flongo 1.9.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
 
@@ -204,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,6 +1,6 @@
 import { FlongoQuery } from "./flongoQuery";
 import { Entity, Event, Pagination, Repository } from "./types";
-import { Document } from "mongodb";
+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.
@@ -10,9 +10,18 @@ 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;
 }
 /**
@@ -234,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

@@ -84,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)
@@ -515,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/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.9.0",
+  "version": "2.0.0",
   "description": "Firestore-like fluent query API for MongoDB",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",