Skip to content

DbFindOpts (Post-Retrieval Processing)

Description

The dbFindOpts parameter provides options for post-processing data after it has been retrieved from the database but before it is returned to the client. These options control:

  1. Ordering - Sort results by a field
  2. Pagination - Skip and limit the number of returned entries
  3. Direction - Reverse the order of results
  4. Aggregation - Group, count, min, max, and average over fields

This allows for efficient data manipulation without requiring additional processing on the client side.

Options

reverse

Reverses the order of the results.

// Query
{
    dbFindOpts: {
        reverse: true
    }
}

// If original results are: [1, 2, 3, 4, 5]
// Final results will be: [5, 4, 3, 2, 1]

Note: When sortBy is not specified, reverse is applied immediately during file iteration. When sortBy is used, the final sort order is determined by sortAsc.

offset

Skips a specified number of entries from the beginning of the results.

// Query
{
    dbFindOpts: {
        offset: 10
    }
}

// Skips the first 10 entries and returns the rest

Default: 0

limit

Limits the number of returned entries.

// Query
{
    dbFindOpts: {
        limit: 20
    }
}

// Returns only the first 20 entries (after offset is applied)

Default: -1 (no limit)

sortBy

Sorts results by a specified field name, randomly, or by multiple fields.

// Sort by a field
{
    dbFindOpts: {
        sortBy: "age"
    }
}

// Random sort
{
    dbFindOpts: {
        sortBy: "random()"
    }
}

// Multi-field sort
{
    dbFindOpts: {
        sortBy: [
            { field: "lastName", asc: true },
            { field: "age", asc: false }
        ]
    }
}

Special value: "random()" - Shuffles results randomly using Math.random().

Multi-field sort: Pass an array of { field, asc? } objects. Each field is sorted in order; subsequent fields break ties from previous comparisons. asc defaults to true.

Default: undefined (no sorting, uses data order)

sortAsc

Determines the sort direction when sortBy is specified.

// Ascending order (default)
{
    dbFindOpts: {
        sortBy: "age",
        sortAsc: true
    }
}

// Descending order
{
    dbFindOpts: {
        sortBy: "age",
        sortAsc: false
    }
}

Default: true

groupBy

Groups results by one or more fields. When specified alongside aggregation operators (min, max, avg, count), computations are performed per group.

// Group by a single field
{
    dbFindOpts: {
        groupBy: "category",
        count: { total: "id" }
    }
}

// Group by multiple fields
{
    dbFindOpts: {
        groupBy: ["category", "status"],
        count: { total: "id" }
    }
}

Type: string | string[]

Default: undefined (no grouping, single aggregate over all data)

count

Counts non-null, non-undefined values per field. Maps output keys to source fields.

// Count total entries
{
    dbFindOpts: {
        count: { total: "id" }
    }
}

// Count with grouping
{
    dbFindOpts: {
        groupBy: "category",
        count: { total: "id", activeUsers: "status" }
    }
}

Type: Record<string, string> - { outputKey: sourceField }

Default: undefined

min

Computes the minimum numeric value of a field. Maps output keys to source fields.

// Youngest age across all entries
{
    dbFindOpts: {
        min: { youngest: "age" }
    }
}

// Min with grouping
{
    dbFindOpts: {
        groupBy: "category",
        min: { cheapest: "price" }
    }
}

Type: Record<string, string> - { outputKey: sourceField }

Default: undefined

max

Computes the maximum numeric value of a field. Maps output keys to source fields.

// Oldest age across all entries
{
    dbFindOpts: {
        max: { oldest: "age" }
    }
}

// Max with grouping
{
    dbFindOpts: {
        groupBy: "category",
        max: { mostExpensive: "price" }
    }
}

Type: Record<string, string> - { outputKey: sourceField }

Default: undefined

avg

Computes the average (mean) numeric value of a field. Maps output keys to source fields.

// Average age across all entries
{
    dbFindOpts: {
        avg: { averageAge: "age" }
    }
}

// Average with grouping
{
    dbFindOpts: {
        groupBy: "category",
        avg: { averagePrice: "price" }
    }
}

Type: Record<string, string> - { outputKey: sourceField }

Default: undefined

sum

Computes the sum of numeric values of a field. Maps output keys to source fields.

// Total revenue across all entries
{
    dbFindOpts: {
        sum: { totalRevenue: "amount" }
    }
}

// Sum with grouping
{
    dbFindOpts: {
        groupBy: "category",
        sum: { totalSales: "price" }
    }
}

Type: Record<string, string> - { outputKey: sourceField }

Default: undefined

distinct

Removes duplicate entries based on the value of a specified field. Only the first occurrence of each unique value is kept.

// Get unique categories
{
    dbFindOpts: {
        distinct: "category"
    }
}

// Distinct with other options
{
    dbFindOpts: {
        distinct: "email",
        limit: 100
    }
}

Type: string - The field name to deduplicate by.

Default: undefined (no deduplication)

Execution Flow

limit: Infinity is treated as "no limit" (-1).

Without Aggregation (min/max/avg/sum/groupBy/count), sortBy, or distinct

  1. Iterate through files
  2. Apply reverse during iteration (if specified)
  3. Apply offset (skip entries)
  4. Apply limit (truncate results)

With Aggregation (min/max/avg/sum/groupBy/count)

  1. Collect all entries from all files
  2. Group entries by groupBy fields (if specified)
  3. Per group, compute min, max, avg, sum, count (if specified)
  4. Apply distinct (if specified)
  5. If sortBy is specified, sort the aggregated rows:
  6. If sortBy === "random()": shuffle randomly
  7. If sortBy is an array: sort by multiple fields in order
  8. Otherwise: sort by field value using compareSafe()
  9. Apply offset and limit to aggregated results

With sortBy or distinct (no aggregation)

  1. Collect all entries from all files
  2. Apply distinct (if specified)
  3. Sort entries:
  4. If sortBy === "random()": shuffle randomly
  5. If sortBy is an array: sort by multiple fields in order
  6. Otherwise: sort by field value using compareSafe()
  7. Apply offset and limit to sorted results

Examples

Basic Pagination

// Get page 2 with 10 items per page
{
    dbFindOpts: {
        offset: 10,
        limit: 10
    }
}

Sort by Field Descending

// Get users sorted by age (oldest first)
{
    dbFindOpts: {
        sortBy: "age",
        sortAsc: false,
        limit: 50
    }
}

Random Sample

// Get 10 random entries
{
    dbFindOpts: {
        sortBy: "random()",
        limit: 10
    }
}

Reverse Order

// Get results in reverse file order
{
    dbFindOpts: {
        reverse: true,
        offset: 0,
        limit: 100
    }
}

Combined Options

// Complex query with sorting and pagination
{
    dbFindOpts: {
        sortBy: "createdAt",
        sortAsc: false,  // Newest first
        offset: 0,
        limit: 20
    }
}

Aggregate per Group

// Get count, min, max, avg price per category
{
    dbFindOpts: {
        groupBy: "category",
        count: { itemCount: "id" },
        min: { minPrice: "price" },
        max: { maxPrice: "price" },
        avg: { avgPrice: "price" }
    }
}

Global Aggregation (no grouping)

// Stats across all entries
{
    dbFindOpts: {
        count: { total: "id" },
        min: { youngest: "age" },
        max: { oldest: "age" },
        avg: { averageAge: "age" },
        sum: { totalAge: "age" }
    }
}

Multi-Field Sort

// Sort by last name ascending, then by age descending
{
    dbFindOpts: {
        sortBy: [
            { field: "lastName", asc: true },
            { field: "age", asc: false }
        ]
    }
}

Distinct Values

// Get unique categories (first document per category)
{
    dbFindOpts: {
        distinct: "category"
    }
}

Note: when distinct is combined with aggregations, it is applied to the aggregated rows, not the raw documents. To count entries per category, use groupBy:

// One row per category with the number of entries
{
    dbFindOpts: {
        groupBy: "category",
        count: { total: "_id" }
    }
}