flongo 1.7.0 → 1.9.0

package/README.md

@@ -105,6 +105,66 @@ const results = await collection.getAll(
   query.orderBy('createdAt', SortDirection.Descending),
   { offset: 0, count: 20 }
 );
+
+// Compound (multi-field) sort with a unique tiebreaker.
+// Appending `_id` makes skip/limit pagination deterministic, so pages never
+// overlap or skip documents when the primary sort key has ties.
+const page = await collection.getAll(
+  new FlongoQuery()
+    .where('status').eq('accepted')
+    .orderBy('featured', SortDirection.Descending)
+    .thenBy('_id', SortDirection.Ascending), // => sort: { featured: -1, _id: 1 }
+  { offset: 0, count: 24 }
+);
+```
+
+#### Seeded random sort (`orderByRandom`)
+
+`orderByRandom(seed)` adds a **deterministic, seeded shuffle** for fair, rotating
+list/browse orderings (e.g. a public directory with no meaningful ranking yet).
+Given the same seed it produces the **same order on every call**, so `$skip`/`$limit`
+pagination stays gapless and non-overlapping across pages; change the seed and the
+whole set reshuffles.
+
+```typescript
+const DAY_MS = 24 * 60 * 60 * 1000;
+// Caller owns the rotation policy. Here: a new shuffle each day. Pin the seed for
+// a browsing session (capture on first load, echo back per page) so paging is stable
+// and rotation only affects new sessions.
+const seed = sessionSeed ?? Math.floor(Date.now() / DAY_MS);
+
+const query = new FlongoQuery()
+  .where('enable').eq(true)
+  .orderBy('featured', SortDirection.Descending) // pinned groups stay on top
+  .orderByRandom(seed);                          // shuffle within each featured tier
+
+const page = await stays.getAll(query, { offset: 0, count: 24 }); // stable, fair
+```
+
+- **Composable** with `orderBy`/`thenBy`: sort keys apply in call order and the
+  shuffle slots in at *its* call position. `_id` is always appended as a final
+  tiebreaker, so pages are gapless even under hash collisions.
+- **Seed is caller-owned** — Flongo does not decide rotation cadence. Pass a
+  time-bucketed seed for rotation, optionally mixed with a session/user id. Number
+  and string seeds are normalized to a string, so `1` and `'1'` are equivalent.
+- **Execution**: a query carrying `orderByRandom` runs via an aggregation pipeline
+  (using `$toHashedIndexKey`) instead of `find` — the `getAll`/`getSome` signatures
+  and return types are unchanged. **Requires MongoDB server ≥ 8.0**; on older
+  servers `orderByRandom` fails fast with an actionable error.
+
+#### Raw aggregation escape hatch
+
+For computed-field sorts/rankings the fluent builder doesn't cover yet,
+`FlongoCollection.aggregate(pipeline)` runs a raw MongoDB aggregation pipeline and
+returns documents in Entity form (`_id` normalized to a string):
+
+```typescript
+const topRated = await products.aggregate([
+  { $match: { inStock: true } },
+  { $addFields: { score: { $multiply: ['$rating', '$reviewCount'] } } },
+  { $sort: { score: -1 } },
+  { $limit: 10 }
+]);
 ```
 
 ### Collection Operations

package/dist/cache/cacheKeyGenerator.js

@@ -72,6 +72,16 @@ class CacheKeyGenerator {
                 direction: query.orderDirection || types_1.SortDirection.Ascending
             };
         }
+        // Include the full ordered sort list only when tiebreakers are present, so
+        // queries differing only by a tiebreaker (e.g. `{ featured: -1 }` vs
+        // `{ featured: -1, _id: 1 }`) hash to distinct keys. Single-sort queries
+        // keep their previous key shape (just `order`) for cache continuity.
+        if (query.sorts && query.sorts.length > 1) {
+            normalized.sorts = query.sorts.map(sort => ({
+                field: sort.field,
+                direction: sort.direction || types_1.SortDirection.Ascending
+            }));
+        }
         if (query.orQueries && query.orQueries.length > 0) {
             normalized.or = query.orQueries
                 .map(q => this.normalizeQuery(q))

package/dist/flongoCollection.d.ts

@@ -1,5 +1,11 @@
 import { FlongoQuery } from "./flongoQuery";
 import { Entity, Event, Pagination, Repository } from "./types";
+import { Document } from "mongodb";
+/**
+ * Clears the memoized per-connection server-version check. Exported for tests;
+ * production code relies on the connection-keyed cache invalidating itself.
+ */
+export declare function __resetServerVersionCache(): void;
 /**
  * Configuration options for FlongoCollection instances
  */
@@ -76,6 +82,29 @@ export declare class FlongoCollection<T> {
      * @returns Promise resolving to array of documents
      */
     getAll(query?: FlongoQuery, pagination?: Pagination): Promise<(Entity & T)[]>;
+    /**
+     * Executes a query carrying an `orderByRandom` via an aggregation pipeline.
+     * Verifies the server supports `$toHashedIndexKey` (MongoDB >= 8.0) first so
+     * callers get an actionable error rather than a raw driver failure.
+     * @private
+     */
+    private getAllRandom;
+    /**
+     * Runs a raw aggregation pipeline against this collection and returns the
+     * documents with their `_id` normalized to a string (Entity form). A low-level
+     * escape hatch for computed-field sorts/rankings that the fluent builder does
+     * not yet cover; `orderByRandom` is built on the same execution path.
+     * @param pipeline - MongoDB aggregation pipeline stages
+     * @returns Promise resolving to the aggregated documents in Entity form
+     */
+    aggregate(pipeline: Document[]): Promise<(Entity & T)[]>;
+    /**
+     * Throws a clear, actionable error when the connected MongoDB server predates
+     * the `$toHashedIndexKey` operator that `orderByRandom` relies on (added in
+     * 8.0), instead of letting an unrecognized-operator driver error surface.
+     * @private
+     */
+    private assertRandomSortSupported;
     /**
      * Retrieves a subset of documents with required query and pagination
      * Similar to getAll but requires both query and pagination parameters

package/dist/flongoCollection.js

@@ -1,11 +1,51 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlongoCollection = void 0;
+exports.__resetServerVersionCache = __resetServerVersionCache;
 const flongo_1 = require("./flongo");
 const flongoQuery_1 = require("./flongoQuery");
 const types_1 = require("./types");
 const mongodb_1 = require("mongodb");
 const errors_1 = require("./errors");
+/**
+ * Memoized MongoDB major version for the active `flongoDb` connection. Keyed by
+ * the `flongoDb` reference so a reconnect (which replaces `flongoDb`) misses the
+ * cache and transparently re-checks; shared across all FlongoCollection
+ * instances on the same connection so `orderByRandom` costs at most one
+ * `buildInfo` round-trip per connection.
+ */
+let cachedServerMajor;
+/**
+ * Resolves the connected server's major version, memoized per connection.
+ * Concurrent callers share a single in-flight `buildInfo`; a failed check is not
+ * cached so the next call retries.
+ */
+function getServerMajorVersion() {
+    if (cachedServerMajor && cachedServerMajor.db === flongo_1.flongoDb) {
+        return cachedServerMajor.promise;
+    }
+    const promise = (async () => {
+        const info = await flongo_1.flongoDb.command({ buildInfo: 1 });
+        return Array.isArray(info.versionArray)
+            ? Number(info.versionArray[0])
+            : parseInt(String(info.version), 10);
+    })();
+    // Don't cache a transient failure — allow the next call to retry.
+    promise.catch(() => {
+        if (cachedServerMajor?.promise === promise) {
+            cachedServerMajor = undefined;
+        }
+    });
+    cachedServerMajor = { db: flongo_1.flongoDb, promise };
+    return promise;
+}
+/**
+ * Clears the memoized per-connection server-version check. Exported for tests;
+ * production code relies on the connection-keyed cache invalidating itself.
+ */
+function __resetServerVersionCache() {
+    cachedServerMajor = undefined;
+}
 /**
  * FlongoCollection provides a high-level interface for MongoDB collection operations
  * with automatic entity management, event logging, and fluent query support.
@@ -88,6 +128,11 @@ class FlongoCollection {
      * @returns Promise resolving to array of documents
      */
     async getAll(query, pagination) {
+        // A seeded random sort can't be expressed with find().sort() — it sorts by a
+        // computed per-document value, so it routes through an aggregation pipeline.
+        if (query?.hasRandomSort()) {
+            return this.getAllRandom(query, pagination);
+        }
         const mongodbQuery = query?.build() ?? {};
         const mongodbOptions = query?.buildOptions(pagination) ?? new flongoQuery_1.FlongoQuery().buildOptions(pagination);
         try {
@@ -98,6 +143,49 @@ class FlongoCollection {
             throw err;
         }
     }
+    /**
+     * Executes a query carrying an `orderByRandom` via an aggregation pipeline.
+     * Verifies the server supports `$toHashedIndexKey` (MongoDB >= 8.0) first so
+     * callers get an actionable error rather than a raw driver failure.
+     * @private
+     */
+    async getAllRandom(query, pagination) {
+        await this.assertRandomSortSupported();
+        const pipeline = query.buildPipeline(pagination);
+        const res = await this.collection.aggregate(pipeline).toArray();
+        return res.map((d) => this.toEntity(d));
+    }
+    /**
+     * Runs a raw aggregation pipeline against this collection and returns the
+     * documents with their `_id` normalized to a string (Entity form). A low-level
+     * escape hatch for computed-field sorts/rankings that the fluent builder does
+     * not yet cover; `orderByRandom` is built on the same execution path.
+     * @param pipeline - MongoDB aggregation pipeline stages
+     * @returns Promise resolving to the aggregated documents in Entity form
+     */
+    async aggregate(pipeline) {
+        const res = await this.collection.aggregate(pipeline).toArray();
+        return res.map((d) => this.toEntity(d));
+    }
+    /**
+     * Throws a clear, actionable error when the connected MongoDB server predates
+     * the `$toHashedIndexKey` operator that `orderByRandom` relies on (added in
+     * 8.0), instead of letting an unrecognized-operator driver error surface.
+     * @private
+     */
+    async assertRandomSortSupported() {
+        let major;
+        try {
+            major = await getServerMajorVersion();
+        }
+        catch (err) {
+            console.error("Failed to verify MongoDB server version for orderByRandom: ", err);
+            throw new errors_1.Error400("orderByRandom() could not verify the MongoDB server version. It requires MongoDB server >= 8.0 (uses $toHashedIndexKey).");
+        }
+        if (!(major >= 8)) {
+            throw new errors_1.Error400(`orderByRandom() requires MongoDB server >= 8.0 (uses $toHashedIndexKey), but the connected server is ${major}.x.`);
+        }
+    }
     /**
      * Retrieves a subset of documents with required query and pagination
      * Similar to getAll but requires both query and pagination parameters
@@ -106,6 +194,10 @@ class FlongoCollection {
      * @returns Promise resolving to array of documents
      */
     async getSome(query, pagination) {
+        // Mirror getAll: a seeded random sort routes through the aggregation path.
+        if (query?.hasRandomSort()) {
+            return this.getAllRandom(query, pagination);
+        }
         const mongodbQuery = query?.build();
         const mongodbOptions = query?.buildOptions(pagination);
         return (await this.collection.find(mongodbQuery, mongodbOptions).toArray()).map((d) => this.toEntity(d));

package/dist/flongoQuery.d.ts

@@ -1,4 +1,4 @@
-import { Bounds, Coordinates, Pagination, ColExpression, ColRange, ICollectionQuery, Logic, SortDirection } from "./types";
+import { Bounds, Coordinates, Pagination, ColExpression, ColRange, ICollectionQuery, Logic, Sort, SortDirection } from "./types";
 import { Document, Filter, FindOptions } from "mongodb";
 /**
  * FlongoQuery provides a fluent, chainable interface for building MongoDB queries
@@ -19,10 +19,37 @@ export declare class FlongoQuery implements ICollectionQuery {
     expressions: ColExpression[];
     /** Array of range queries (currently unused but reserved for future features) */
     ranges: ColRange[];
-    /** Field to sort results by */
-    orderField?: string;
-    /** Direction for sorting (ascending or descending) */
-    orderDirection?: SortDirection;
+    /**
+     * Ordered list of sort keys. The first entry is the primary sort, subsequent
+     * entries act as tiebreakers (in order). Populated by `orderBy()`/`thenBy()`.
+     */
+    sorts: Sort[];
+    /**
+     * Normalized seed for a deterministic random sort, set by `orderByRandom()`.
+     * `undefined` means the query has no random sort and executes via the normal
+     * `find` path. When present, the query must execute via an aggregation
+     * pipeline (see `buildPipeline`). Requires MongoDB server >= 8.0.
+     */
+    randomSeed?: string;
+    /**
+     * The position of the random sort within the sort-key order, captured as
+     * `sorts.length` at the time `orderByRandom()` was called. Explicit sort keys
+     * added before this index sort ahead of the shuffle; those added at/after it
+     * sort behind it. `undefined` when there is no random sort.
+     */
+    randomSortPosition?: number;
+    /** Internal computed field used to carry the per-document shuffle hash. */
+    static readonly SHUFFLE_FIELD = "__flongoShuffle";
+    /**
+     * Primary sort field, derived from `sorts[0]`.
+     * @deprecated Retained for backward compatibility; use `sorts`.
+     */
+    get orderField(): string | undefined;
+    /**
+     * Primary sort direction, derived from `sorts[0]`.
+     * @deprecated Retained for backward compatibility; use `sorts`.
+     */
+    get orderDirection(): SortDirection | undefined;
     /** Array of queries to be combined with OR logic */
     orQueries: FlongoQuery[];
     /** Array of queries to be combined with AND logic */
@@ -224,12 +251,71 @@ export declare class FlongoQuery implements ICollectionQuery {
      */
     near(center: Coordinates, maxDistanceMeters: number): FlongoQuery;
     /**
-     * Sets the field and direction for sorting results
+     * Sets the primary sort field and direction, resetting any previously
+     * configured sort keys (including tiebreakers added via `thenBy`).
      * @param field - Field name to sort by
      * @param direction - Sort direction (ascending or descending)
      * @returns This query instance for chaining
      */
     orderBy(field?: string, direction?: SortDirection): FlongoQuery;
+    /**
+     * Appends a secondary (tertiary, …) sort key used as a tiebreaker after the
+     * primary `orderBy` field. Sort keys are applied in the order they are added,
+     * which is what makes deterministic pagination possible (e.g. appending a
+     * unique `_id` tiebreaker so `skip`/`limit` pages don't overlap).
+     *
+     * If called before any `orderBy`, the field becomes the primary sort.
+     * If the same field is added more than once, the latest direction wins
+     * (the field keeps its original position in the sort order).
+     *
+     * @example
+     * new FlongoQuery()
+     *   .orderBy('featured', SortDirection.Descending)
+     *   .thenBy('_id', SortDirection.Ascending);
+     * // => sort: { featured: -1, _id: 1 }
+     *
+     * @param field - Field name to sort by
+     * @param direction - Sort direction (ascending or descending)
+     * @returns This query instance for chaining
+     */
+    thenBy(field?: string, direction?: SortDirection): FlongoQuery;
+    /**
+     * Adds a deterministic, seeded random sort. Given the same seed the produced
+     * order is identical on every call, so `$skip`/`$limit` pagination stays
+     * gapless and non-overlapping across pages; change the seed and the whole set
+     * reshuffles. This is what enables fair, rotating list/browse orderings.
+     *
+     * Composes with `orderBy`/`thenBy`: sort keys apply in call order and the
+     * shuffle slots in at the position of *this* call, so
+     * `orderBy('featured', Descending).orderByRandom(seed)` pins featured docs to
+     * the top and shuffles within each tier. `_id` is always appended as a final
+     * tiebreaker so a total order (and therefore stable paging) is guaranteed even
+     * under hash collisions. Calling this alone shuffles the whole result set.
+     *
+     * The seed is caller-owned — Flongo does not decide rotation policy. Pass e.g.
+     * `Math.floor(Date.now() / DAY_MS)` for daily rotation, optionally mixed with a
+     * session/user id. Number and string seeds are normalized to a string, so `1`
+     * and `'1'` produce the same order.
+     *
+     * Implemented natively via the `$toHashedIndexKey` aggregation operator, so a
+     * query carrying a random sort executes via an aggregation pipeline instead of
+     * `find`. **Requires MongoDB server >= 8.0.**
+     *
+     * @example
+     * new FlongoQuery()
+     *   .where('enable').eq(true)
+     *   .orderBy('featured', SortDirection.Descending)
+     *   .orderByRandom(seed);
+     *
+     * @param seed - Seed controlling the shuffle (number or string)
+     * @returns This query instance for chaining
+     */
+    orderByRandom(seed: number | string): FlongoQuery;
+    /**
+     * Whether this query carries a random sort and must execute via an aggregation
+     * pipeline (`buildPipeline`) rather than the normal `find` path.
+     */
+    hasRandomSort(): boolean;
     /**
      * Adds a sub-query with AND logic
      * @param query - Sub-query to combine with AND logic
@@ -254,6 +340,28 @@ export declare class FlongoQuery implements ICollectionQuery {
      * @returns MongoDB FindOptions object
      */
     buildOptions<T extends Document>(pagination?: Pagination): FindOptions<T>;
+    /**
+     * Builds the ordered `$sort` specification for the aggregation path, weaving
+     * the internal shuffle field in at its call position amongst the explicit
+     * sort keys and always appending `_id` as a final tiebreaker. Only used when
+     * a random sort is present.
+     * @private
+     */
+    private buildAggregationSort;
+    /**
+     * Compiles this query into an aggregation pipeline that materializes the same
+     * results as `find` would, but ordered by a deterministic per-document shuffle
+     * (see `orderByRandom`). The `$match` stage is exactly what `find` receives
+     * today (`build()`), so all filter logic and indexes carry over unchanged;
+     * `$skip`/`$limit` are applied *after* the deterministic sort, which is what
+     * makes paging stable.
+     *
+     * **Requires MongoDB server >= 8.0** (uses `$toHashedIndexKey`).
+     *
+     * @param pagination - Optional pagination settings
+     * @returns MongoDB aggregation pipeline stages
+     */
+    buildPipeline<T>(pagination?: Pagination): Document[];
 }
 /**
  * FlongoQueryBuilder provides a builder pattern wrapper around FlongoQuery

package/dist/flongoQuery.js

@@ -26,11 +26,30 @@ class FlongoQuery {
         this.expressions = [];
         /** Array of range queries (currently unused but reserved for future features) */
         this.ranges = [];
+        /**
+         * Ordered list of sort keys. The first entry is the primary sort, subsequent
+         * entries act as tiebreakers (in order). Populated by `orderBy()`/`thenBy()`.
+         */
+        this.sorts = [];
         /** Array of queries to be combined with OR logic */
         this.orQueries = [];
         /** Array of queries to be combined with AND logic */
         this.andQueries = [];
     }
+    /**
+     * Primary sort field, derived from `sorts[0]`.
+     * @deprecated Retained for backward compatibility; use `sorts`.
+     */
+    get orderField() {
+        return this.sorts[0]?.field;
+    }
+    /**
+     * Primary sort direction, derived from `sorts[0]`.
+     * @deprecated Retained for backward compatibility; use `sorts`.
+     */
+    get orderDirection() {
+        return this.sorts[0]?.direction;
+    }
     /**
      * Gets the most recently added expression for method chaining
      * @private
@@ -352,16 +371,92 @@ class FlongoQuery {
     // SORTING
     // ===========================================
     /**
-     * Sets the field and direction for sorting results
+     * Sets the primary sort field and direction, resetting any previously
+     * configured sort keys (including tiebreakers added via `thenBy`).
      * @param field - Field name to sort by
      * @param direction - Sort direction (ascending or descending)
      * @returns This query instance for chaining
      */
     orderBy(field, direction) {
-        this.orderField = field;
-        this.orderDirection = direction;
+        this.sorts = field ? [{ field, direction }] : [];
         return this;
     }
+    /**
+     * Appends a secondary (tertiary, …) sort key used as a tiebreaker after the
+     * primary `orderBy` field. Sort keys are applied in the order they are added,
+     * which is what makes deterministic pagination possible (e.g. appending a
+     * unique `_id` tiebreaker so `skip`/`limit` pages don't overlap).
+     *
+     * If called before any `orderBy`, the field becomes the primary sort.
+     * If the same field is added more than once, the latest direction wins
+     * (the field keeps its original position in the sort order).
+     *
+     * @example
+     * new FlongoQuery()
+     *   .orderBy('featured', SortDirection.Descending)
+     *   .thenBy('_id', SortDirection.Ascending);
+     * // => sort: { featured: -1, _id: 1 }
+     *
+     * @param field - Field name to sort by
+     * @param direction - Sort direction (ascending or descending)
+     * @returns This query instance for chaining
+     */
+    thenBy(field, direction) {
+        if (!field) {
+            return this;
+        }
+        const existing = this.sorts.find((s) => s.field === field);
+        if (existing) {
+            existing.direction = direction;
+        }
+        else {
+            this.sorts.push({ field, direction });
+        }
+        return this;
+    }
+    /**
+     * Adds a deterministic, seeded random sort. Given the same seed the produced
+     * order is identical on every call, so `$skip`/`$limit` pagination stays
+     * gapless and non-overlapping across pages; change the seed and the whole set
+     * reshuffles. This is what enables fair, rotating list/browse orderings.
+     *
+     * Composes with `orderBy`/`thenBy`: sort keys apply in call order and the
+     * shuffle slots in at the position of *this* call, so
+     * `orderBy('featured', Descending).orderByRandom(seed)` pins featured docs to
+     * the top and shuffles within each tier. `_id` is always appended as a final
+     * tiebreaker so a total order (and therefore stable paging) is guaranteed even
+     * under hash collisions. Calling this alone shuffles the whole result set.
+     *
+     * The seed is caller-owned — Flongo does not decide rotation policy. Pass e.g.
+     * `Math.floor(Date.now() / DAY_MS)` for daily rotation, optionally mixed with a
+     * session/user id. Number and string seeds are normalized to a string, so `1`
+     * and `'1'` produce the same order.
+     *
+     * Implemented natively via the `$toHashedIndexKey` aggregation operator, so a
+     * query carrying a random sort executes via an aggregation pipeline instead of
+     * `find`. **Requires MongoDB server >= 8.0.**
+     *
+     * @example
+     * new FlongoQuery()
+     *   .where('enable').eq(true)
+     *   .orderBy('featured', SortDirection.Descending)
+     *   .orderByRandom(seed);
+     *
+     * @param seed - Seed controlling the shuffle (number or string)
+     * @returns This query instance for chaining
+     */
+    orderByRandom(seed) {
+        this.randomSeed = String(seed);
+        this.randomSortPosition = this.sorts.length;
+        return this;
+    }
+    /**
+     * Whether this query carries a random sort and must execute via an aggregation
+     * pipeline (`buildPipeline`) rather than the normal `find` path.
+     */
+    hasRandomSort() {
+        return this.randomSeed !== undefined;
+    }
     // ===========================================
     // LOGICAL OPERATORS
     // ===========================================
@@ -486,16 +581,90 @@ class FlongoQuery {
             mongodbOptions.skip = pagination.offset;
             mongodbOptions.limit = pagination.count;
         }
-        // Add sorting if specified
-        if (this.orderField && this.orderDirection) {
-            mongodbOptions.sort = {
-                [this.orderField]: this.orderDirection === types_1.SortDirection.Ascending ? 1 : -1
-            };
+        // Add sorting if specified. Iterate sort keys in order so MongoDB honors the
+        // insertion order of the resulting `sort` object's keys (primary first, then
+        // tiebreakers). Entries without a direction are skipped, preserving the prior
+        // behavior where a field set with no direction produced no sort.
+        const sortKeys = this.sorts.filter((s) => s.field && s.direction);
+        if (sortKeys.length) {
+            const sort = {};
+            for (const s of sortKeys) {
+                sort[s.field] = s.direction === types_1.SortDirection.Ascending ? 1 : -1;
+            }
+            mongodbOptions.sort = sort;
         }
         return mongodbOptions;
     }
+    /**
+     * Builds the ordered `$sort` specification for the aggregation path, weaving
+     * the internal shuffle field in at its call position amongst the explicit
+     * sort keys and always appending `_id` as a final tiebreaker. Only used when
+     * a random sort is present.
+     * @private
+     */
+    buildAggregationSort() {
+        const sort = {};
+        const addShuffle = () => {
+            sort[FlongoQuery.SHUFFLE_FIELD] = 1;
+        };
+        // Iterate the raw sort keys so the random slot lands at the exact index it
+        // was declared at (positions are captured against the unfiltered array).
+        this.sorts.forEach((s, i) => {
+            if (i === this.randomSortPosition) {
+                addShuffle();
+            }
+            if (s.field && s.direction) {
+                sort[s.field] = s.direction === types_1.SortDirection.Ascending ? 1 : -1;
+            }
+        });
+        // Random sort declared at or after the last explicit key.
+        if (this.randomSortPosition !== undefined && this.randomSortPosition >= this.sorts.length) {
+            addShuffle();
+        }
+        // Final tiebreaker guarantees a total order (gapless pages under collisions).
+        if (!("_id" in sort)) {
+            sort["_id"] = 1;
+        }
+        return sort;
+    }
+    /**
+     * Compiles this query into an aggregation pipeline that materializes the same
+     * results as `find` would, but ordered by a deterministic per-document shuffle
+     * (see `orderByRandom`). The `$match` stage is exactly what `find` receives
+     * today (`build()`), so all filter logic and indexes carry over unchanged;
+     * `$skip`/`$limit` are applied *after* the deterministic sort, which is what
+     * makes paging stable.
+     *
+     * **Requires MongoDB server >= 8.0** (uses `$toHashedIndexKey`).
+     *
+     * @param pagination - Optional pagination settings
+     * @returns MongoDB aggregation pipeline stages
+     */
+    buildPipeline(pagination) {
+        const pipeline = [{ $match: this.build() }];
+        // Hash the full `_id` string mixed with the seed. Hashing the whole _id
+        // decorrelates the order from the ObjectId timestamp prefix, so newer docs
+        // aren't biased toward one end of the shuffle.
+        pipeline.push({
+            $addFields: {
+                [FlongoQuery.SHUFFLE_FIELD]: {
+                    $toHashedIndexKey: { $concat: [{ $toString: "$_id" }, ":", this.randomSeed] }
+                }
+            }
+        });
+        pipeline.push({ $sort: this.buildAggregationSort() });
+        if (pagination) {
+            pipeline.push({ $skip: pagination.offset });
+            pipeline.push({ $limit: pagination.count });
+        }
+        // Don't leak the internal shuffle field to callers.
+        pipeline.push({ $project: { [FlongoQuery.SHUFFLE_FIELD]: 0 } });
+        return pipeline;
+    }
 }
 exports.FlongoQuery = FlongoQuery;
+/** Internal computed field used to carry the per-document shuffle hash. */
+FlongoQuery.SHUFFLE_FIELD = "__flongoShuffle";
 /**
  * FlongoQueryBuilder provides a builder pattern wrapper around FlongoQuery
  * This can be useful for more complex query construction scenarios

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export { FlongoCollection, FlongoCollectionOptions } from "./flongoCollection";
 export { FlongoQuery, FlongoQueryBuilder } from "./flongoQuery";
 export { initializeFlongo, connectFlongo, FlongoConfig, flongoClient, flongoDb } from "./flongo";
 export { Error404, Error400 } from "./errors";
-export { Entity, DbRecord, Pagination, Coordinates, Bounds, Event, EventName, EventRecord, Logic, SortDirection, ColRange, ColExpression, ICollectionQuery, ICollection, Repository, CacheOptions, CachedCollectionOptions } from "./types";
+export { Entity, DbRecord, Pagination, Coordinates, Bounds, Event, EventName, EventRecord, Logic, SortDirection, Sort, ColRange, ColExpression, ICollectionQuery, ICollection, Repository, CacheOptions, CachedCollectionOptions } from "./types";
 export { CacheStore, CacheEntry, CacheStats, CacheStoreOptions, BaseCacheStore, MemoryCache, MemoryCacheOptions, CacheKeyGenerator, CacheKeyOptions, InvalidationStrategy, InvalidationRule, InvalidationOptions, CacheInvalidator, TTLStrategy, LRUStrategy, CacheConfig, CacheProviderConfig, CacheConfiguration, createDefaultConfig, createProductionConfig, createDevelopmentConfig, DetailedCacheStats, CacheMetrics, CacheStatsCollector, CacheMonitor, getGlobalCacheMonitor, resetGlobalCacheMonitor } from "./cache";
 //# sourceMappingURL=index.d.ts.map

package/dist/types.d.ts

@@ -58,10 +58,19 @@ export declare class ColExpression {
     val: any;
     constructor(key: string);
 }
+/** A single sort key: a field paired with a direction. */
+export interface Sort {
+    field: string;
+    direction?: SortDirection;
+}
 export type ICollectionQuery = {
     expressions: ColExpression[];
     ranges: ColRange[];
+    /** Ordered list of sort keys. The first entry is the primary sort. */
+    sorts?: Sort[];
+    /** @deprecated Primary sort field; derived from `sorts[0]`. Use `sorts`. */
     orderField?: string;
+    /** @deprecated Primary sort direction; derived from `sorts[0]`. Use `sorts`. */
     orderDirection?: SortDirection;
     orQueries: ICollectionQuery[];
     andQueries: ICollectionQuery[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flongo",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Firestore-like fluent query API for MongoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",