flongo 1.6.0 → 1.8.0

package/README.md

@@ -105,6 +105,17 @@ 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 }
+);
 ```
 
 ### 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/flongo.d.ts

@@ -1,9 +1,11 @@
-import { Db, MongoClient } from "mongodb";
+import { Db, MongoClient, MongoClientOptions } from "mongodb";
 export declare let flongoClient: MongoClient;
 export declare let flongoDb: Db;
 export interface FlongoConfig {
     connectionString: string;
     dbName: string;
+    clientOptions?: MongoClientOptions;
 }
 export declare function initializeFlongo(config: FlongoConfig): void;
+export declare function connectFlongo(config: FlongoConfig): Promise<void>;
 //# sourceMappingURL=flongo.d.ts.map

package/dist/flongo.js

@@ -2,9 +2,21 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.flongoDb = exports.flongoClient = void 0;
 exports.initializeFlongo = initializeFlongo;
+exports.connectFlongo = connectFlongo;
 const mongodb_1 = require("mongodb");
+const defaultClientOptions = {
+    serverSelectionTimeoutMS: 10000,
+    heartbeatFrequencyMS: 15000,
+    socketTimeoutMS: 30000,
+    maxIdleTimeMS: 60000,
+};
 function initializeFlongo(config) {
-    exports.flongoClient = new mongodb_1.MongoClient(config.connectionString);
+    const options = { ...defaultClientOptions, ...config.clientOptions };
+    exports.flongoClient = new mongodb_1.MongoClient(config.connectionString, options);
     exports.flongoDb = exports.flongoClient.db(config.dbName);
 }
+async function connectFlongo(config) {
+    initializeFlongo(config);
+    await exports.flongoClient.connect();
+}
 //# sourceMappingURL=flongo.js.map

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,21 @@ 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[];
+    /**
+     * 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 +235,34 @@ 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 sub-query with AND logic
      * @param query - Sub-query to combine with AND logic

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,14 +371,47 @@ 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;
     }
     // ===========================================
@@ -486,11 +538,17 @@ 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;
     }

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { FlongoCollection, FlongoCollectionOptions } from "./flongoCollection";
 export { FlongoQuery, FlongoQueryBuilder } from "./flongoQuery";
-export { initializeFlongo, FlongoConfig, flongoClient, flongoDb } from "./flongo";
+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/index.js

@@ -1,7 +1,7 @@
 "use strict";
 // Main exports for flongo package
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetGlobalCacheMonitor = exports.getGlobalCacheMonitor = exports.CacheMonitor = exports.CacheStatsCollector = exports.createDevelopmentConfig = exports.createProductionConfig = exports.createDefaultConfig = exports.CacheConfiguration = exports.LRUStrategy = exports.TTLStrategy = exports.CacheInvalidator = exports.InvalidationStrategy = exports.CacheKeyGenerator = exports.MemoryCache = exports.BaseCacheStore = exports.ColExpression = exports.ColRange = exports.SortDirection = exports.Logic = exports.EventName = exports.Error400 = exports.Error404 = exports.flongoDb = exports.flongoClient = exports.initializeFlongo = exports.FlongoQueryBuilder = exports.FlongoQuery = exports.FlongoCollection = void 0;
+exports.resetGlobalCacheMonitor = exports.getGlobalCacheMonitor = exports.CacheMonitor = exports.CacheStatsCollector = exports.createDevelopmentConfig = exports.createProductionConfig = exports.createDefaultConfig = exports.CacheConfiguration = exports.LRUStrategy = exports.TTLStrategy = exports.CacheInvalidator = exports.InvalidationStrategy = exports.CacheKeyGenerator = exports.MemoryCache = exports.BaseCacheStore = exports.ColExpression = exports.ColRange = exports.SortDirection = exports.Logic = exports.EventName = exports.Error400 = exports.Error404 = exports.flongoDb = exports.flongoClient = exports.connectFlongo = exports.initializeFlongo = exports.FlongoQueryBuilder = exports.FlongoQuery = exports.FlongoCollection = void 0;
 var flongoCollection_1 = require("./flongoCollection");
 Object.defineProperty(exports, "FlongoCollection", { enumerable: true, get: function () { return flongoCollection_1.FlongoCollection; } });
 var flongoQuery_1 = require("./flongoQuery");
@@ -9,6 +9,7 @@ Object.defineProperty(exports, "FlongoQuery", { enumerable: true, get: function
 Object.defineProperty(exports, "FlongoQueryBuilder", { enumerable: true, get: function () { return flongoQuery_1.FlongoQueryBuilder; } });
 var flongo_1 = require("./flongo");
 Object.defineProperty(exports, "initializeFlongo", { enumerable: true, get: function () { return flongo_1.initializeFlongo; } });
+Object.defineProperty(exports, "connectFlongo", { enumerable: true, get: function () { return flongo_1.connectFlongo; } });
 Object.defineProperty(exports, "flongoClient", { enumerable: true, get: function () { return flongo_1.flongoClient; } });
 Object.defineProperty(exports, "flongoDb", { enumerable: true, get: function () { return flongo_1.flongoDb; } });
 var errors_1 = require("./errors");

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.6.0",
+  "version": "1.8.0",
   "description": "Firestore-like fluent query API for MongoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",