flongo 1.8.0 → 2.0.0

package/README.md

@@ -47,6 +47,7 @@ const adults = await users.getAll(
 - 🚀 **TypeScript support** - Full type safety and IntelliSense
 - 📊 **Rich query operations** - Comparisons, arrays, geospatial, text search
 - 🎛️ **Configurable** - Optional event logging, custom error handling
+- 🗂️ **Declarative indexes** - Declare once, ensure idempotently on every boot
 - 🧪 **Battle-tested** - Extracted from production codebase
 - 📦 **Zero config** - Works with existing MongoDB setup
 
@@ -118,6 +119,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
@@ -155,18 +205,172 @@ await collection.batchCreate([user1, user2, user3]);
 ### Configuration
 
 ```typescript
-// Disable event logging
+// Audit logging is OFF by default — opt in per collection
 const collection = new FlongoCollection<User>('users', {
-  enableEventLogging: false
+  enableEventLogging: true
 });
 
-// Custom events collection
+// Opt in with a custom events collection
 const collection = new FlongoCollection<User>('users', {
   enableEventLogging: true,
   eventsCollectionName: 'audit_logs'
 });
 ```
 
+#### Audit logging vs. your own `events` collection
+
+Flongo's built-in audit trail is **opt-in** (`enableEventLogging` defaults to
+`false`). When enabled, it writes to a collection named `events` by default. If
+your application has its own `events` (analytics) collection, redirect Flongo's
+audit trail to a dedicated collection so the two can be indexed and retained
+independently:
+
+```typescript
+const users = new FlongoCollection<User>('users', {
+  enableEventLogging: true,
+  eventsCollectionName: 'audit_events'   // keep audit separate from app analytics
+});
+```
+
+Both `eventsCollectionName` and `enableEventLogging` are per-collection, so you
+control audit behavior for each collection independently.
+
+## Index Management
+
+Declare your indexes once in a central registry and Flongo will ensure them
+**idempotently on every boot**. This keeps indexes colocated, version-controlled,
+and out of ad-hoc scripts against the raw driver. Index management is **purely
+additive** — with no `indexes` registry declared, boot behavior is identical to
+previous versions.
+
+### Declaring indexes
+
+Register indexes at initialization, keyed by collection name. A single central
+registry is the source of truth (rather than per-`FlongoCollection`-construction
+specs), since one physical collection is often constructed in many places.
+
+```typescript
+import { connectFlongo, syncFlongoIndexes } from 'flongo';
+
+await connectFlongo({
+  connectionString: process.env.MONGO_URL!,
+  dbName: 'stays',
+  indexes: {
+    events: [
+      // Compound analytics indexes (order matters — ESR: equality, sort, range)
+      { keys: { name: 1, 'value.stayId': 1, createdAt: 1 } },
+      { keys: { name: 1, identity: 1, createdAt: 1 } }
+    ],
+    users: [
+      { keys: { email: 1 }, options: { unique: true } }
+    ],
+    stays: [
+      { keys: { shortlink: 1 }, options: { unique: true, sparse: true } },
+      { keys: { 'location.coordinates.geoJSON': '2dsphere' } }
+    ]
+  },
+  indexSync: { mode: 'ensure', onError: 'warn', background: false }
+});
+```
+
+`connectFlongo` ensures the declared indexes after connecting. You can also run
+the sync explicitly at any time (e.g. to gate boot on it, or from a migration /
+CI job):
+
+```typescript
+const report = await syncFlongoIndexes();   // idempotent; returns FlongoIndexReport[]
+```
+
+### Index spec
+
+```typescript
+interface FlongoIndexSpec {
+  keys: Record<string, 1 | -1 | '2dsphere' | 'text' | 'hashed'>;
+  options?: {
+    name?: string;                       // custom index name
+    unique?: boolean;
+    sparse?: boolean;
+    partialFilterExpression?: Document;  // partial index (e.g. unique-when-present)
+    expireAfterSeconds?: number;         // TTL — see caveat below
+    collation?: CollationOptions;
+    hidden?: boolean;                    // hide from the planner without dropping
+  };
+}
+```
+
+### Sync semantics
+
+`syncFlongoIndexes()` calls `createIndex(keys, options)` per spec and returns a
+structured report:
+
+```typescript
+interface FlongoIndexReport {
+  collection: string;
+  name: string;                                                   // resolved name
+  status: 'created' | 'exists' | 'conflict' | 'failed' | 'pruned';
+  error?: string;
+}
+```
+
+- **Identical** spec already present → `"exists"` (no-op).
+- **Same keys, different options** → MongoDB throws `IndexOptionsConflict`;
+  Flongo records `"conflict"` and honors `onError` (it never silently
+  drops/recreates).
+- **Creation error** (classic case: a `unique` index over a collection that
+  already contains duplicates) → `"failed"` with a message naming the likely
+  cause. By default this does **not** crash the process.
+
+#### `indexSync` options
+
+| Option        | Values                          | Default    | Behavior |
+|---------------|---------------------------------|------------|----------|
+| `mode`        | `'ensure'` \| `'off'` \| `'strict'` | `'ensure'` | `ensure`: create missing, tolerate problems per `onError`. `off`: register specs but do nothing at boot (call `syncFlongoIndexes()` yourself). `strict`: throw on any conflict/failure (for CI / migration gates). |
+| `onError`     | `'warn'` \| `'throw'`           | `'warn'`   | How non-fatal problems are surfaced. `strict` mode always throws. |
+| `background`  | `boolean`                       | `false`    | When `true`, boot does not block on index builds — the sync runs asynchronously and logs its outcome. `await syncFlongoIndexes()` remains available when you want to await. |
+| `prune`       | `boolean`                       | `false`    | Drop indexes present in Mongo but absent from the registry. See below. |
+| `dryRun`      | `boolean`                       | `false`    | With `prune`, log what *would* be dropped without dropping. |
+
+### Non-destructive by default & pruning
+
+Indexes present in Mongo but absent from the registry are **left untouched** by
+default. Dropping is explicit opt-in and **never** touches the mandatory `_id_`
+index:
+
+```typescript
+// Dry run first — logs out-of-registry indexes without dropping anything
+await syncFlongoIndexes({ prune: true, dryRun: true });
+
+// Then actually prune
+const report = await syncFlongoIndexes({ prune: true });
+```
+
+### Verifying indexes
+
+Two passthroughs help confirm indexes are applied and used:
+
+```typescript
+const users = new FlongoCollection<User>('users');
+
+await users.listIndexes();   // the collection's current index descriptions
+
+// Confirm a query uses an index scan (IXSCAN) rather than a full scan (COLLSCAN)
+const plan = await users.explain(new FlongoQuery().where('email').eq('a@b.com'));
+```
+
+### TTL caveat ⚠️
+
+`expireAfterSeconds` (TTL) requires the indexed field to be a **BSON `Date`**.
+Flongo stamps `createdAt` / `updatedAt` as epoch **numbers** (`Date.now()`), so a
+TTL index on `createdAt` **will not expire anything**. To use TTL, index a
+dedicated `Date`-typed field that you write yourself:
+
+```typescript
+await events.create({ ...data, expiresAt: new Date(Date.now() + 30 * 86400_000) });
+
+// registry
+events: [{ keys: { expiresAt: 1 }, options: { expireAfterSeconds: 0 } }]
+```
+
 ## Examples
 
 ### E-commerce Product Search

package/dist/flongo.d.ts

@@ -1,10 +1,20 @@
 import { Db, MongoClient, MongoClientOptions } from "mongodb";
+import { FlongoIndexRegistry, IndexSyncOptions } from "./indexes";
 export declare let flongoClient: MongoClient;
 export declare let flongoDb: Db;
 export interface FlongoConfig {
     connectionString: string;
     dbName: string;
     clientOptions?: MongoClientOptions;
+    /**
+     * Declarative index registry keyed by collection name. Indexes declared here
+     * are ensured at boot by `connectFlongo` (see `indexSync`) and can be
+     * re-applied any time via `syncFlongoIndexes()`. Omit for identical behavior
+     * to previous versions — index management is purely additive.
+     */
+    indexes?: FlongoIndexRegistry;
+    /** Boot-time index sync behavior (mode, error handling, background, prune). */
+    indexSync?: IndexSyncOptions;
 }
 export declare function initializeFlongo(config: FlongoConfig): void;
 export declare function connectFlongo(config: FlongoConfig): Promise<void>;

package/dist/flongo.js

@@ -4,6 +4,7 @@ exports.flongoDb = exports.flongoClient = void 0;
 exports.initializeFlongo = initializeFlongo;
 exports.connectFlongo = connectFlongo;
 const mongodb_1 = require("mongodb");
+const indexes_1 = require("./indexes");
 const defaultClientOptions = {
     serverSelectionTimeoutMS: 10000,
     heartbeatFrequencyMS: 15000,
@@ -14,9 +15,16 @@ function initializeFlongo(config) {
     const options = { ...defaultClientOptions, ...config.clientOptions };
     exports.flongoClient = new mongodb_1.MongoClient(config.connectionString, options);
     exports.flongoDb = exports.flongoClient.db(config.dbName);
+    // Register declarative index specs so `syncFlongoIndexes()` / boot sync can
+    // find them. Registration is synchronous and connection-independent.
+    (0, indexes_1.registerFlongoIndexes)(config.indexes);
+    (0, indexes_1.setIndexSyncConfig)(config.indexSync);
 }
 async function connectFlongo(config) {
     initializeFlongo(config);
     await exports.flongoClient.connect();
+    // Ensure declared indexes once connected. Honors indexSync.mode/background;
+    // a no-op when no indexes are registered, so existing callers are unaffected.
+    await (0, indexes_1.runBootIndexSync)();
 }
 //# sourceMappingURL=flongo.js.map

package/dist/flongoCollection.d.ts

@@ -1,12 +1,27 @@
 import { FlongoQuery } from "./flongoQuery";
 import { Entity, Event, Pagination, Repository } from "./types";
+import { Document, IndexDescription } 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
  */
 export interface FlongoCollectionOptions {
-    /** Whether to enable automatic event logging for CRUD operations */
+    /**
+     * Whether to enable automatic event logging (audit trail) for CRUD
+     * operations. Defaults to `false` — audit logging is opt-in. Set to `true`
+     * per collection to record an audit trail (into `eventsCollectionName`).
+     */
     enableEventLogging?: boolean;
-    /** Name of the collection to store events in (defaults to "events") */
+    /**
+     * Name of the collection audit events are written to. Defaults to `"events"`.
+     * If your app has its own `events`/analytics collection, redirect Flongo's
+     * audit trail to a dedicated collection (e.g. `"audit_events"`) so audit and
+     * analytics can be indexed and retained independently.
+     */
     eventsCollectionName?: string;
 }
 /**
@@ -76,6 +91,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
@@ -205,6 +243,21 @@ export declare class FlongoCollection<T> {
      * @param clientId - Optional client ID for audit trail
      */
     arrRemove(id: string, key: string, items: any[], clientId?: string): Promise<void>;
+    /**
+     * Lists the indexes currently defined on this collection. A thin passthrough
+     * over the driver's `listIndexes()`, useful for verifying that declared
+     * indexes were applied (pairs with `syncFlongoIndexes()` and `explain()`).
+     * @returns Promise resolving to the collection's index descriptions
+     */
+    listIndexes(): Promise<IndexDescription[]>;
+    /**
+     * Returns the query planner's execution plan for a FlongoQuery. Pairs with
+     * index verification — inspect the winning plan's stage to confirm an
+     * `IXSCAN` (index scan) rather than a `COLLSCAN` (full collection scan).
+     * @param query - The FlongoQuery to explain
+     * @returns Promise resolving to MongoDB's explain output
+     */
+    explain(query: FlongoQuery): Promise<Document>;
     /**
      * Logs an event to the events collection for audit trails
      * Events are only logged if event logging is enabled in options

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.
@@ -44,7 +84,7 @@ class FlongoCollection {
      */
     constructor(collectionName, options = {}) {
         this.collection = flongo_1.flongoDb.collection(collectionName);
-        this.options = { enableEventLogging: true, eventsCollectionName: "events", ...options };
+        this.options = { enableEventLogging: false, eventsCollectionName: "events", ...options };
         // Initialize events collection only if logging is enabled
         this.events = this.options.enableEventLogging
             ? flongo_1.flongoDb.collection(this.options.eventsCollectionName)
@@ -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));
@@ -423,6 +515,30 @@ class FlongoCollection {
         });
     }
     // ===========================================
+    // INDEX INTROSPECTION
+    // ===========================================
+    /**
+     * Lists the indexes currently defined on this collection. A thin passthrough
+     * over the driver's `listIndexes()`, useful for verifying that declared
+     * indexes were applied (pairs with `syncFlongoIndexes()` and `explain()`).
+     * @returns Promise resolving to the collection's index descriptions
+     */
+    async listIndexes() {
+        return (await this.collection.listIndexes().toArray());
+    }
+    /**
+     * Returns the query planner's execution plan for a FlongoQuery. Pairs with
+     * index verification — inspect the winning plan's stage to confirm an
+     * `IXSCAN` (index scan) rather than a `COLLSCAN` (full collection scan).
+     * @param query - The FlongoQuery to explain
+     * @returns Promise resolving to MongoDB's explain output
+     */
+    async explain(query) {
+        const mongodbQuery = query?.build() ?? {};
+        const mongodbOptions = query?.buildOptions() ?? {};
+        return this.collection.find(mongodbQuery, mongodbOptions).explain();
+    }
+    // ===========================================
     // EVENT LOGGING
     // ===========================================
     /**

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/dist/index.d.ts

@@ -2,6 +2,7 @@ export { FlongoCollection, FlongoCollectionOptions } from "./flongoCollection";
 export { FlongoQuery, FlongoQueryBuilder } from "./flongoQuery";
 export { initializeFlongo, connectFlongo, FlongoConfig, flongoClient, flongoDb } from "./flongo";
 export { Error404, Error400 } from "./errors";
+export { syncFlongoIndexes, getFlongoIndexRegistry, defaultIndexName, FlongoIndexSpec, FlongoIndexOptions, FlongoIndexKeyType, FlongoIndexRegistry, FlongoIndexReport, FlongoIndexStatus, IndexSyncOptions, IndexSyncMode, IndexSyncOnError, SyncFlongoIndexesOptions } from "./indexes";
 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.connectFlongo = 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.defaultIndexName = exports.getFlongoIndexRegistry = exports.syncFlongoIndexes = 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");
@@ -15,6 +15,11 @@ Object.defineProperty(exports, "flongoDb", { enumerable: true, get: function ()
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "Error404", { enumerable: true, get: function () { return errors_1.Error404; } });
 Object.defineProperty(exports, "Error400", { enumerable: true, get: function () { return errors_1.Error400; } });
+// Declarative index management
+var indexes_1 = require("./indexes");
+Object.defineProperty(exports, "syncFlongoIndexes", { enumerable: true, get: function () { return indexes_1.syncFlongoIndexes; } });
+Object.defineProperty(exports, "getFlongoIndexRegistry", { enumerable: true, get: function () { return indexes_1.getFlongoIndexRegistry; } });
+Object.defineProperty(exports, "defaultIndexName", { enumerable: true, get: function () { return indexes_1.defaultIndexName; } });
 var types_1 = require("./types");
 Object.defineProperty(exports, "EventName", { enumerable: true, get: function () { return types_1.EventName; } });
 Object.defineProperty(exports, "Logic", { enumerable: true, get: function () { return types_1.Logic; } });

package/dist/indexes.d.ts

@@ -0,0 +1,164 @@
+import { CollationOptions, Document } from "mongodb";
+/**
+ * The value of a single key in an index specification.
+ * - `1` / `-1` — ascending / descending B-tree key.
+ * - `"2dsphere"` — geospatial index (GeoJSON).
+ * - `"text"` — full-text index.
+ * - `"hashed"` — hashed index (e.g. for hashed sharding).
+ */
+export type FlongoIndexKeyType = 1 | -1 | "2dsphere" | "text" | "hashed";
+/**
+ * Options for a declared index. Mirrors the subset of the MongoDB driver's
+ * `CreateIndexesOptions` that Flongo supports declaratively. Any option here is
+ * passed through to `createIndex` verbatim.
+ */
+export interface FlongoIndexOptions {
+    /** Custom index name. Defaults to MongoDB's generated `field_direction` name. */
+    name?: string;
+    /** Enforce uniqueness across the indexed key(s). */
+    unique?: boolean;
+    /** Only index documents that contain the indexed field(s). */
+    sparse?: boolean;
+    /**
+     * Only index documents matching this filter (partial index). Useful for
+     * "unique when present" constraints and for indexing a subset of documents
+     * (e.g. only analytics events).
+     */
+    partialFilterExpression?: Document;
+    /**
+     * TTL: seconds after which a document expires. **Requires the indexed field
+     * to be a BSON `Date`.** Flongo stamps `createdAt`/`updatedAt` as epoch
+     * numbers, so a TTL index on those fields will not expire anything — index a
+     * dedicated `Date`-typed field instead. See the README TTL caveat.
+     */
+    expireAfterSeconds?: number;
+    /** Collation (locale-aware comparison) for the index. */
+    collation?: CollationOptions;
+    /** Hide the index from the query planner without dropping it. */
+    hidden?: boolean;
+}
+/**
+ * A declarative, idempotent index specification. Declared once in the registry
+ * and ensured on every boot via {@link syncFlongoIndexes}.
+ */
+export interface FlongoIndexSpec {
+    /** The index key map. Keys are (dot-path) field names; values are key types. */
+    keys: Record<string, FlongoIndexKeyType>;
+    /** Optional index options (unique, sparse, TTL, collation, etc.). */
+    options?: FlongoIndexOptions;
+}
+/**
+ * The index registry: a map of collection name → declared index specs. A single
+ * central registry (rather than per-`FlongoCollection`-construction specs) is
+ * the source of truth, since one physical collection is frequently constructed
+ * in many places and per-construction specs would duplicate and conflict.
+ */
+export type FlongoIndexRegistry = Record<string, FlongoIndexSpec[]>;
+/**
+ * Boot-time sync behavior.
+ * - `"ensure"` (default) — create missing indexes; tolerate conflicts/failures
+ *   per `onError`.
+ * - `"off"` — register specs but do nothing at boot; the app calls
+ *   {@link syncFlongoIndexes} itself.
+ * - `"strict"` — throw on any conflict or failure (for CI / migration gates).
+ */
+export type IndexSyncMode = "ensure" | "off" | "strict";
+/** How a non-fatal sync problem is surfaced: log and continue, or throw. */
+export type IndexSyncOnError = "warn" | "throw";
+/**
+ * Configuration for boot-time index sync, supplied via `initializeFlongo`'s
+ * `indexSync` field.
+ */
+export interface IndexSyncOptions {
+    /** Sync mode. Defaults to `"ensure"`. */
+    mode?: IndexSyncMode;
+    /** Error handling for non-strict modes. Defaults to `"warn"`. */
+    onError?: IndexSyncOnError;
+    /**
+     * When `true`, boot does not block on index builds — the sync is kicked off
+     * asynchronously and its outcome is logged on completion. `await
+     * syncFlongoIndexes()` remains available when the app wants to await. Defaults
+     * to `false` (await index builds during `connectFlongo`).
+     */
+    background?: boolean;
+    /**
+     * When `true`, drop indexes that exist in Mongo but are absent from the
+     * registry (never `_id_`). Opt-in and off by default. See also `dryRun`.
+     */
+    prune?: boolean;
+    /**
+     * When pruning, log the indexes that *would* be dropped without dropping
+     * them. Off by default.
+     */
+    dryRun?: boolean;
+}
+/** The outcome of ensuring (or pruning) a single index. */
+export type FlongoIndexStatus = "created" | "exists" | "conflict" | "failed" | "pruned";
+/** A structured, per-index result from {@link syncFlongoIndexes}. */
+export interface FlongoIndexReport {
+    /** Collection the index belongs to. */
+    collection: string;
+    /** Resolved index name. */
+    name: string;
+    /** What happened to this index during the sync. */
+    status: FlongoIndexStatus;
+    /** Error/diagnostic message when `status` is `"conflict"` or `"failed"`. */
+    error?: string;
+}
+/** Per-call overrides for {@link syncFlongoIndexes}. */
+export interface SyncFlongoIndexesOptions {
+    /** Override the configured sync mode. */
+    mode?: IndexSyncMode;
+    /** Override the configured error handling. */
+    onError?: IndexSyncOnError;
+    /** Drop out-of-registry indexes (never `_id_`). */
+    prune?: boolean;
+    /** With `prune`, log candidates without dropping. */
+    dryRun?: boolean;
+}
+/**
+ * Registers the declarative index registry. Called by `initializeFlongo`; a
+ * missing registry clears any previously registered specs.
+ */
+export declare function registerFlongoIndexes(registry?: FlongoIndexRegistry): void;
+/** Registers boot-time index sync configuration. Called by `initializeFlongo`. */
+export declare function setIndexSyncConfig(config?: IndexSyncOptions): void;
+/** Returns the currently registered index registry. */
+export declare function getFlongoIndexRegistry(): FlongoIndexRegistry;
+/** Returns the currently registered index sync configuration. */
+export declare function getIndexSyncConfig(): IndexSyncOptions;
+/**
+ * Computes the index name MongoDB would generate for a key map, matching the
+ * driver's `field_direction` join (e.g. `{ a: 1, "b.c": -1 }` → `a_1_b.c_-1`,
+ * `{ loc: "2dsphere" }` → `loc_2dsphere`). Used to resolve report names and to
+ * match declared specs against existing indexes without a round-trip.
+ */
+export declare function defaultIndexName(keys: Record<string, FlongoIndexKeyType>): string;
+/**
+ * Idempotently ensures every index in the registry exists, returning a
+ * structured report. Safe to run on every boot.
+ *
+ * For each spec, calls `createIndex(keys, options)`:
+ * - identical spec already present → `"exists"` (no-op);
+ * - same keys with different options → Mongo throws a conflict, recorded as
+ *   `"conflict"` (never silently dropped/recreated);
+ * - other creation errors (e.g. a unique index over existing duplicates) →
+ *   `"failed"` with a diagnostic message.
+ *
+ * `mode`/`onError` are read from the `indexSync` config unless overridden here.
+ * `strict` mode forces `onError: "throw"`. With `prune`, indexes present in
+ * Mongo but absent from the registry are dropped (never `_id_`); `dryRun` logs
+ * candidates without dropping.
+ *
+ * @param opts - Per-call overrides for mode, onError, prune, and dryRun.
+ * @returns One {@link FlongoIndexReport} per ensured (and pruned) index.
+ */
+export declare function syncFlongoIndexes(opts?: SyncFlongoIndexesOptions): Promise<FlongoIndexReport[]>;
+/**
+ * Boot-time entry point invoked by `connectFlongo` after the connection is
+ * established. Respects `indexSync.mode` (`"off"` does nothing) and
+ * `indexSync.background` (kick off async and log on completion rather than
+ * blocking boot). A no-op when no indexes are registered.
+ */
+export declare function runBootIndexSync(): Promise<void>;
+//# sourceMappingURL=indexes.d.ts.map

package/dist/indexes.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFlongoIndexes = registerFlongoIndexes;
+exports.setIndexSyncConfig = setIndexSyncConfig;
+exports.getFlongoIndexRegistry = getFlongoIndexRegistry;
+exports.getIndexSyncConfig = getIndexSyncConfig;
+exports.defaultIndexName = defaultIndexName;
+exports.syncFlongoIndexes = syncFlongoIndexes;
+exports.runBootIndexSync = runBootIndexSync;
+const flongo_1 = require("./flongo");
+// ===========================================
+// REGISTRY STATE
+// ===========================================
+let indexRegistry = {};
+let indexSyncConfig = {};
+/**
+ * Registers the declarative index registry. Called by `initializeFlongo`; a
+ * missing registry clears any previously registered specs.
+ */
+function registerFlongoIndexes(registry) {
+    indexRegistry = registry ?? {};
+}
+/** Registers boot-time index sync configuration. Called by `initializeFlongo`. */
+function setIndexSyncConfig(config) {
+    indexSyncConfig = config ?? {};
+}
+/** Returns the currently registered index registry. */
+function getFlongoIndexRegistry() {
+    return indexRegistry;
+}
+/** Returns the currently registered index sync configuration. */
+function getIndexSyncConfig() {
+    return indexSyncConfig;
+}
+// ===========================================
+// HELPERS
+// ===========================================
+/**
+ * Computes the index name MongoDB would generate for a key map, matching the
+ * driver's `field_direction` join (e.g. `{ a: 1, "b.c": -1 }` → `a_1_b.c_-1`,
+ * `{ loc: "2dsphere" }` → `loc_2dsphere`). Used to resolve report names and to
+ * match declared specs against existing indexes without a round-trip.
+ */
+function defaultIndexName(keys) {
+    return Object.entries(keys)
+        .map(([field, type]) => `${field}_${type}`)
+        .join("_");
+}
+/** Resolves a spec's effective index name (explicit `name` or the default). */
+function resolveIndexName(spec) {
+    return spec.options?.name ?? defaultIndexName(spec.keys);
+}
+/**
+ * Lists a collection's existing indexes, treating a missing collection (which
+ * has no indexes yet) as an empty list rather than an error.
+ */
+async function fetchExistingIndexes(collection) {
+    try {
+        return await collection.listIndexes().toArray();
+    }
+    catch (err) {
+        // NamespaceNotFound (code 26): the collection doesn't exist yet, so it has
+        // no indexes. Any create below will lazily create the collection.
+        if (err?.code === 26 || /ns does not exist/i.test(err?.message ?? "")) {
+            return [];
+        }
+        throw err;
+    }
+}
+/**
+ * Whether an error from `createIndex` represents an index *conflict* — the same
+ * name or key pattern already exists with different options — as opposed to a
+ * genuine creation failure.
+ */
+function isConflictError(err) {
+    const code = err?.code;
+    const codeName = err?.codeName ?? "";
+    return (code === 85 || // IndexOptionsConflict
+        code === 86 || // IndexKeySpecsConflict
+        codeName === "IndexOptionsConflict" ||
+        codeName === "IndexKeySpecsConflict" ||
+        /already exists with different|different options/i.test(err?.message ?? ""));
+}
+/**
+ * Produces a diagnostic message for a failed index build, naming the likely
+ * cause for the classic case of a unique index over existing duplicates.
+ */
+function describeFailure(err) {
+    const base = err?.message ?? String(err);
+    if (err?.code === 11000 || /duplicate key|E11000/i.test(base)) {
+        return `${base} — likely cause: a unique index cannot be built because the collection already contains duplicate values for the indexed key(s). Resolve the duplicates or drop the \`unique\` option.`;
+    }
+    return base;
+}
+/** Logs a one-line summary of a sync run, grouped by status. */
+function logSummary(reports) {
+    const counts = {};
+    for (const r of reports) {
+        counts[r.status] = (counts[r.status] ?? 0) + 1;
+    }
+    const summary = Object.entries(counts)
+        .map(([status, n]) => `${n} ${status}`)
+        .join(", ");
+    console.log(`[flongo] Index sync complete: ${summary || "no indexes declared"}`);
+}
+// ===========================================
+// SYNC
+// ===========================================
+/**
+ * Idempotently ensures every index in the registry exists, returning a
+ * structured report. Safe to run on every boot.
+ *
+ * For each spec, calls `createIndex(keys, options)`:
+ * - identical spec already present → `"exists"` (no-op);
+ * - same keys with different options → Mongo throws a conflict, recorded as
+ *   `"conflict"` (never silently dropped/recreated);
+ * - other creation errors (e.g. a unique index over existing duplicates) →
+ *   `"failed"` with a diagnostic message.
+ *
+ * `mode`/`onError` are read from the `indexSync` config unless overridden here.
+ * `strict` mode forces `onError: "throw"`. With `prune`, indexes present in
+ * Mongo but absent from the registry are dropped (never `_id_`); `dryRun` logs
+ * candidates without dropping.
+ *
+ * @param opts - Per-call overrides for mode, onError, prune, and dryRun.
+ * @returns One {@link FlongoIndexReport} per ensured (and pruned) index.
+ */
+async function syncFlongoIndexes(opts = {}) {
+    const cfg = getIndexSyncConfig();
+    const mode = opts.mode ?? cfg.mode ?? "ensure";
+    const prune = opts.prune ?? cfg.prune ?? false;
+    const dryRun = opts.dryRun ?? cfg.dryRun ?? false;
+    // Strict mode always throws; otherwise honor the configured/overridden policy.
+    const onError = mode === "strict" ? "throw" : opts.onError ?? cfg.onError ?? "warn";
+    const registry = getFlongoIndexRegistry();
+    const reports = [];
+    const raise = (status, collection, name, message) => {
+        if (onError === "throw") {
+            throw new Error(`[flongo] Index sync ${status} for ${collection}.${name}: ${message}`);
+        }
+        console.warn(`[flongo] Index sync ${status} for ${collection}.${name}: ${message}`);
+    };
+    for (const [collectionName, specs] of Object.entries(registry)) {
+        const collection = flongo_1.flongoDb.collection(collectionName);
+        // Snapshot the pre-existing indexes once: used both to classify
+        // created-vs-exists and to decide pruning (so we never prune what we just
+        // created this run).
+        const existing = await fetchExistingIndexes(collection);
+        const existingNames = new Set(existing.map((i) => i.name));
+        for (const spec of specs) {
+            const resolvedName = resolveIndexName(spec);
+            const preExists = existingNames.has(resolvedName);
+            try {
+                const createdName = await collection.createIndex(spec.keys, (spec.options ?? {}));
+                reports.push({
+                    collection: collectionName,
+                    name: createdName ?? resolvedName,
+                    status: preExists ? "exists" : "created"
+                });
+            }
+            catch (err) {
+                const conflict = isConflictError(err);
+                const status = conflict ? "conflict" : "failed";
+                const message = conflict
+                    ? err?.message ?? "index options conflict"
+                    : describeFailure(err);
+                reports.push({ collection: collectionName, name: resolvedName, status, error: message });
+                raise(status, collectionName, resolvedName, message);
+            }
+        }
+        if (prune) {
+            const declaredNames = new Set(specs.map((s) => resolveIndexName(s)));
+            for (const idx of existing) {
+                const name = idx.name;
+                // Never drop the mandatory _id index, and never drop a declared one.
+                if (name === "_id_" || declaredNames.has(name)) {
+                    continue;
+                }
+                if (dryRun) {
+                    console.warn(`[flongo] [dry-run] would prune index ${collectionName}.${name}`);
+                    continue;
+                }
+                try {
+                    await collection.dropIndex(name);
+                    reports.push({ collection: collectionName, name, status: "pruned" });
+                    console.warn(`[flongo] Pruned out-of-registry index ${collectionName}.${name}`);
+                }
+                catch (err) {
+                    const message = describeFailure(err);
+                    reports.push({ collection: collectionName, name, status: "failed", error: message });
+                    raise("failed", collectionName, name, message);
+                }
+            }
+        }
+    }
+    logSummary(reports);
+    return reports;
+}
+/**
+ * Boot-time entry point invoked by `connectFlongo` after the connection is
+ * established. Respects `indexSync.mode` (`"off"` does nothing) and
+ * `indexSync.background` (kick off async and log on completion rather than
+ * blocking boot). A no-op when no indexes are registered.
+ */
+async function runBootIndexSync() {
+    const cfg = getIndexSyncConfig();
+    const mode = cfg.mode ?? "ensure";
+    if (mode === "off") {
+        return;
+    }
+    if (Object.keys(getFlongoIndexRegistry()).length === 0) {
+        return;
+    }
+    if (cfg.background) {
+        // Don't block boot; report the outcome when the builds finish. Errors are
+        // logged rather than propagated because there is no boot to fail here.
+        void syncFlongoIndexes()
+            .then((reports) => {
+            const failures = reports.filter((r) => r.status === "failed" || r.status === "conflict");
+            if (failures.length) {
+                console.warn(`[flongo] Background index sync finished with ${failures.length} problem(s).`);
+            }
+        })
+            .catch((err) => {
+            console.error("[flongo] Background index sync failed:", err);
+        });
+        return;
+    }
+    await syncFlongoIndexes();
+}
+//# sourceMappingURL=indexes.js.map

package/package.json

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