flongo 1.8.0 → 1.9.0

package/README.md

@@ -118,6 +118,55 @@ const page = await collection.getAll(
 );
 ```
 
+#### 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
 
 ```typescript

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

@@ -24,6 +24,22 @@ export declare class FlongoQuery implements ICollectionQuery {
      * 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`.
@@ -263,6 +279,43 @@ export declare class FlongoQuery implements ICollectionQuery {
      * @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
@@ -287,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

@@ -414,6 +414,49 @@ class FlongoQuery {
         }
         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
     // ===========================================
@@ -552,8 +595,76 @@ class FlongoQuery {
         }
         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/package.json

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