flongo 2.2.0 → 2.3.0

package/dist/flongoCollection.d.ts

@@ -92,12 +92,13 @@ export declare class FlongoCollection<T> {
      */
     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.
+     * Executes a query carrying computed sort keys (`orderByRandom` and/or
+     * `orderByExpr`) via an aggregation pipeline. For random sorts, verifies the
+     * server supports `$toHashedIndexKey` (MongoDB >= 8.0) first so callers get an
+     * actionable error rather than a raw driver failure.
      * @private
      */
-    private getAllRandom;
+    private getAllViaPipeline;
     /**
      * Retrieves only the `_id`s of matching documents, as strings (the same
      * normalization `toEntity` applies). Uses a server-side projection so full

package/dist/flongoCollection.js

@@ -128,10 +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);
+        // Seeded random and expression sorts can't be expressed with find().sort() —
+        // they sort by computed per-document values, so they route through an
+        // aggregation pipeline.
+        if (query?.needsPipeline()) {
+            return this.getAllViaPipeline(query, pagination);
         }
         const mongodbQuery = query?.build() ?? {};
         const mongodbOptions = query?.buildOptions(pagination) ?? new flongoQuery_1.FlongoQuery().buildOptions(pagination);
@@ -144,13 +145,16 @@ class FlongoCollection {
         }
     }
     /**
-     * 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.
+     * Executes a query carrying computed sort keys (`orderByRandom` and/or
+     * `orderByExpr`) via an aggregation pipeline. For random sorts, 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();
+    async getAllViaPipeline(query, pagination) {
+        if (query.hasRandomSort()) {
+            await this.assertRandomSortSupported();
+        }
         const pipeline = query.buildPipeline(pagination);
         const res = await this.collection.aggregate(pipeline).toArray();
         return res.map((d) => this.toEntity(d));
@@ -181,10 +185,12 @@ class FlongoCollection {
      * @returns Promise resolving to the matching document ids as strings
      */
     async getIds(query, pagination) {
-        // Mirror getAll: a seeded random sort must execute via the aggregation
+        // Mirror getAll: computed sort keys must execute via the aggregation
         // pipeline. Only the id column is materialized on either path.
-        if (query?.hasRandomSort()) {
-            await this.assertRandomSortSupported();
+        if (query?.needsPipeline()) {
+            if (query.hasRandomSort()) {
+                await this.assertRandomSortSupported();
+            }
             const pipeline = query.buildPipeline(pagination);
             pipeline.push({ $project: { _id: 1 } });
             const res = await this.collection.aggregate(pipeline).toArray();
@@ -237,9 +243,9 @@ 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);
+        // Mirror getAll: computed sort keys route through the aggregation path.
+        if (query?.needsPipeline()) {
+            return this.getAllViaPipeline(query, pagination);
         }
         const mongodbQuery = query?.build();
         const mongodbOptions = query?.buildOptions(pagination);

package/dist/flongoQuery.d.ts

@@ -40,6 +40,8 @@ export declare class FlongoQuery implements ICollectionQuery {
     randomSortPosition?: number;
     /** Internal computed field used to carry the per-document shuffle hash. */
     static readonly SHUFFLE_FIELD = "__flongoShuffle";
+    /** Prefix of internal computed fields backing expression sort keys. */
+    static readonly EXPR_FIELD_PREFIX = "__flongoSortExpr";
     /**
      * Primary sort field, derived from `sorts[0]`.
      * @deprecated Retained for backward compatibility; use `sorts`.
@@ -279,6 +281,48 @@ export declare class FlongoQuery implements ICollectionQuery {
      * @returns This query instance for chaining
      */
     thenBy(field?: string, direction?: SortDirection): FlongoQuery;
+    /**
+     * Sets the primary sort to a computed aggregation expression, resetting any
+     * previously configured sort keys (the expression analog of `orderBy`).
+     *
+     * The expression is materialized into an internal field via `$addFields`, so a
+     * query carrying an expression sort executes via an aggregation pipeline
+     * instead of `find` (same execution path as `orderByRandom`, but with no
+     * server-version requirement). The internal field never leaks to callers.
+     *
+     * The canonical use is normalizing a field before sorting on it. MongoDB's
+     * BSON type order ranks Boolean above Null/missing, so
+     * `orderBy('featured', Descending)` puts an explicit `featured: false` *above*
+     * documents missing the field entirely. Normalizing fixes that:
+     *
+     * @example
+     * // Pin featured docs on top; explicit false and missing tie.
+     * new FlongoQuery()
+     *   .orderByExpr({ $eq: ['$featured', true] }, SortDirection.Descending)
+     *   .thenBy('_id', SortDirection.Ascending);
+     *
+     * Composes with `thenBy`/`orderByRandom` exactly like a field sort key: keys
+     * apply in call order.
+     *
+     * @param expr - MongoDB aggregation expression to sort by
+     * @param direction - Sort direction (ascending or descending)
+     * @returns This query instance for chaining
+     */
+    orderByExpr(expr: Document, direction: SortDirection): FlongoQuery;
+    /**
+     * Appends a computed aggregation expression as a tiebreaker sort key (the
+     * expression analog of `thenBy`). See `orderByExpr` for semantics.
+     *
+     * @param expr - MongoDB aggregation expression to sort by
+     * @param direction - Sort direction (ascending or descending)
+     * @returns This query instance for chaining
+     */
+    thenByExpr(expr: Document, direction: SortDirection): FlongoQuery;
+    /**
+     * Whether this query carries any expression sort keys (`orderByExpr`/
+     * `thenByExpr`) and must therefore execute via an aggregation pipeline.
+     */
+    hasExprSort(): boolean;
     /**
      * Adds a deterministic, seeded random sort. Given the same seed the produced
      * order is identical on every call, so `$skip`/`$limit` pagination stays
@@ -316,6 +360,12 @@ export declare class FlongoQuery implements ICollectionQuery {
      * pipeline (`buildPipeline`) rather than the normal `find` path.
      */
     hasRandomSort(): boolean;
+    /**
+     * Whether this query must execute via an aggregation pipeline
+     * (`buildPipeline`) rather than the normal `find` path — true when it carries
+     * a random sort and/or any expression sort keys.
+     */
+    needsPipeline(): boolean;
     /**
      * Adds a sub-query with AND logic
      * @param query - Sub-query to combine with AND logic
@@ -343,20 +393,22 @@ export declare class FlongoQuery implements ICollectionQuery {
     /**
      * 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.
+     * sort keys (expression keys sort by their computed internal field) and always
+     * appending `_id` as a final tiebreaker. Only used on the pipeline path.
      * @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.
+     * results as `find` would, but ordered by computed sort values — the
+     * deterministic per-document shuffle (`orderByRandom`) and/or expression sort
+     * keys (`orderByExpr`/`thenByExpr`). 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`).
+     * **A random sort requires MongoDB server >= 8.0** (uses `$toHashedIndexKey`);
+     * expression sorts have no version requirement.
      *
      * @param pagination - Optional pagination settings
      * @returns MongoDB aggregation pipeline stages

package/dist/flongoQuery.js

@@ -414,6 +414,57 @@ class FlongoQuery {
         }
         return this;
     }
+    /**
+     * Sets the primary sort to a computed aggregation expression, resetting any
+     * previously configured sort keys (the expression analog of `orderBy`).
+     *
+     * The expression is materialized into an internal field via `$addFields`, so a
+     * query carrying an expression sort executes via an aggregation pipeline
+     * instead of `find` (same execution path as `orderByRandom`, but with no
+     * server-version requirement). The internal field never leaks to callers.
+     *
+     * The canonical use is normalizing a field before sorting on it. MongoDB's
+     * BSON type order ranks Boolean above Null/missing, so
+     * `orderBy('featured', Descending)` puts an explicit `featured: false` *above*
+     * documents missing the field entirely. Normalizing fixes that:
+     *
+     * @example
+     * // Pin featured docs on top; explicit false and missing tie.
+     * new FlongoQuery()
+     *   .orderByExpr({ $eq: ['$featured', true] }, SortDirection.Descending)
+     *   .thenBy('_id', SortDirection.Ascending);
+     *
+     * Composes with `thenBy`/`orderByRandom` exactly like a field sort key: keys
+     * apply in call order.
+     *
+     * @param expr - MongoDB aggregation expression to sort by
+     * @param direction - Sort direction (ascending or descending)
+     * @returns This query instance for chaining
+     */
+    orderByExpr(expr, direction) {
+        this.sorts = [];
+        return this.thenByExpr(expr, direction);
+    }
+    /**
+     * Appends a computed aggregation expression as a tiebreaker sort key (the
+     * expression analog of `thenBy`). See `orderByExpr` for semantics.
+     *
+     * @param expr - MongoDB aggregation expression to sort by
+     * @param direction - Sort direction (ascending or descending)
+     * @returns This query instance for chaining
+     */
+    thenByExpr(expr, direction) {
+        const index = this.sorts.filter((s) => s.expr !== undefined).length;
+        this.sorts.push({ field: `${FlongoQuery.EXPR_FIELD_PREFIX}${index}`, direction, expr });
+        return this;
+    }
+    /**
+     * Whether this query carries any expression sort keys (`orderByExpr`/
+     * `thenByExpr`) and must therefore execute via an aggregation pipeline.
+     */
+    hasExprSort() {
+        return this.sorts.some((s) => s.expr !== undefined);
+    }
     /**
      * Adds a deterministic, seeded random sort. Given the same seed the produced
      * order is identical on every call, so `$skip`/`$limit` pagination stays
@@ -457,6 +508,14 @@ class FlongoQuery {
     hasRandomSort() {
         return this.randomSeed !== undefined;
     }
+    /**
+     * Whether this query must execute via an aggregation pipeline
+     * (`buildPipeline`) rather than the normal `find` path — true when it carries
+     * a random sort and/or any expression sort keys.
+     */
+    needsPipeline() {
+        return this.hasRandomSort() || this.hasExprSort();
+    }
     // ===========================================
     // LOGICAL OPERATORS
     // ===========================================
@@ -587,8 +646,10 @@ class FlongoQuery {
         // 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);
+        // behavior where a field set with no direction produced no sort. Expression
+        // keys are computed fields that only exist on the pipeline path, so they are
+        // excluded here rather than sorting on a field no document has.
+        const sortKeys = this.sorts.filter((s) => s.field && s.direction && s.expr === undefined);
         if (sortKeys.length) {
             const sort = {};
             for (const s of sortKeys) {
@@ -601,8 +662,8 @@ class FlongoQuery {
     /**
      * 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.
+     * sort keys (expression keys sort by their computed internal field) and always
+     * appending `_id` as a final tiebreaker. Only used on the pipeline path.
      * @private
      */
     buildAggregationSort() {
@@ -632,42 +693,60 @@ class FlongoQuery {
     }
     /**
      * 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.
+     * results as `find` would, but ordered by computed sort values — the
+     * deterministic per-document shuffle (`orderByRandom`) and/or expression sort
+     * keys (`orderByExpr`/`thenByExpr`). 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`).
+     * **A random sort requires MongoDB server >= 8.0** (uses `$toHashedIndexKey`);
+     * expression sorts have no version requirement.
      *
      * @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] }
-                }
+        // Materialize every computed sort value in one $addFields stage.
+        const computed = {};
+        for (const s of this.sorts) {
+            if (s.expr !== undefined) {
+                computed[s.field] = s.expr;
             }
-        });
+        }
+        if (this.randomSeed !== undefined) {
+            // 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.
+            computed[FlongoQuery.SHUFFLE_FIELD] = {
+                $toHashedIndexKey: { $concat: [{ $toString: "$_id" }, ":", this.randomSeed] }
+            };
+        }
+        if (Object.keys(computed).length > 0) {
+            pipeline.push({ $addFields: computed });
+        }
         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 } });
+        // Don't leak the internal computed fields to callers.
+        if (Object.keys(computed).length > 0) {
+            const exclusions = {};
+            for (const field of Object.keys(computed)) {
+                exclusions[field] = 0;
+            }
+            pipeline.push({ $project: exclusions });
+        }
         return pipeline;
     }
 }
 exports.FlongoQuery = FlongoQuery;
 /** Internal computed field used to carry the per-document shuffle hash. */
 FlongoQuery.SHUFFLE_FIELD = "__flongoShuffle";
+/** Prefix of internal computed fields backing expression sort keys. */
+FlongoQuery.EXPR_FIELD_PREFIX = "__flongoSortExpr";
 /**
  * FlongoQueryBuilder provides a builder pattern wrapper around FlongoQuery
  * This can be useful for more complex query construction scenarios

package/dist/types.d.ts

@@ -62,6 +62,12 @@ export declare class ColExpression {
 export interface Sort {
     field: string;
     direction?: SortDirection;
+    /**
+     * Aggregation expression this sort key is computed from (set by
+     * `orderByExpr`/`thenByExpr`). When present, `field` is an internal
+     * generated name materialized via `$addFields` on the pipeline path.
+     */
+    expr?: unknown;
 }
 export type ICollectionQuery = {
     expressions: ColExpression[];

package/package.json

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