flongo 2.0.0 → 2.1.0

package/README.md

@@ -307,7 +307,7 @@ structured report:
 interface FlongoIndexReport {
   collection: string;
   name: string;                                                   // resolved name
-  status: 'created' | 'exists' | 'conflict' | 'failed' | 'pruned';
+  status: 'created' | 'exists' | 'conflict' | 'failed' | 'pruned' | 'reconciled';
   error?: string;
 }
 ```
@@ -315,7 +315,8 @@ interface FlongoIndexReport {
 - **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).
+  drops/recreates). With the `reconcile` opt-in, the existing index is instead
+  dropped and rebuilt from the declared spec → `"reconciled"` (see below).
 - **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.
@@ -328,7 +329,8 @@ interface FlongoIndexReport {
 | `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. |
+| `reconcile`   | `boolean`                       | `false`    | Drop + rebuild conflicting indexes from their declared specs. See below. |
+| `dryRun`      | `boolean`                       | `false`    | With `prune`/`reconcile`, log what *would* be dropped (or dropped and rebuilt) without touching anything. |
 
 ### Non-destructive by default & pruning
 
@@ -344,6 +346,39 @@ await syncFlongoIndexes({ prune: true, dryRun: true });
 const report = await syncFlongoIndexes({ prune: true });
 ```
 
+### Reconciling option changes
+
+Changing a declared index's **options** (e.g. adding `unique`, changing a
+partial filter) makes MongoDB reject the `createIndex` with a conflict, since
+an index's options are immutable. By default Flongo reports `"conflict"` and
+leaves the resolution to you. With the `reconcile` opt-in, Flongo evolves the
+index for you: it drops the existing index and rebuilds it from the declared
+spec.
+
+```typescript
+// Dry run first — logs which indexes would be dropped and rebuilt
+await syncFlongoIndexes({ reconcile: true, dryRun: true });
+
+// Then actually reconcile
+const report = await syncFlongoIndexes({ reconcile: true });
+// → [{ collection: 'users', name: 'email_1', status: 'reconciled' }]
+```
+
+Safety properties:
+
+- **Rollback on failure** — if the rebuild fails (e.g. you added `unique` and
+  the collection contains duplicates), the original index is restored from the
+  pre-sync snapshot and the report is `"failed"` with the cause. The collection
+  is never left without the index.
+- **Drops the real index** — the drop targets the server-side index that
+  conflicts (matched by name, or by key pattern if your spec renames it), never
+  a guessed name, and never `_id_`.
+
+⚠️ **Rebuild window**: between the drop and the completed rebuild, queries
+can't use the index and `unique` is not enforced. For large collections or
+strict uniqueness requirements, prefer running reconcile during a maintenance
+window rather than on every boot.
+
 ### Verifying indexes
 
 Two passthroughs help confirm indexes are applied and used:

package/dist/indexes.d.ts

@@ -87,13 +87,23 @@ export interface IndexSyncOptions {
      */
     prune?: boolean;
     /**
-     * When pruning, log the indexes that *would* be dropped without dropping
-     * them. Off by default.
+     * When `true`, resolve index conflicts (an index with the same identity
+     * already exists with different options or keys) by dropping the existing
+     * index and rebuilding it from the declared spec. If the rebuild fails, the
+     * original index is restored from the pre-sync snapshot so the collection is
+     * never left without it. Note the rebuild window: while the index is being
+     * rebuilt, queries can't use it and `unique` is not enforced. Opt-in and off
+     * by default; never touches `_id_`. See also `dryRun`.
+     */
+    reconcile?: boolean;
+    /**
+     * When pruning or reconciling, log the indexes that *would* be dropped (or
+     * dropped and rebuilt) without touching them. Off by default.
      */
     dryRun?: boolean;
 }
-/** The outcome of ensuring (or pruning) a single index. */
-export type FlongoIndexStatus = "created" | "exists" | "conflict" | "failed" | "pruned";
+/** The outcome of ensuring (or pruning/reconciling) a single index. */
+export type FlongoIndexStatus = "created" | "exists" | "conflict" | "failed" | "pruned" | "reconciled";
 /** A structured, per-index result from {@link syncFlongoIndexes}. */
 export interface FlongoIndexReport {
     /** Collection the index belongs to. */
@@ -113,7 +123,9 @@ export interface SyncFlongoIndexesOptions {
     onError?: IndexSyncOnError;
     /** Drop out-of-registry indexes (never `_id_`). */
     prune?: boolean;
-    /** With `prune`, log candidates without dropping. */
+    /** Drop + rebuild conflicting indexes from their declared specs (never `_id_`). */
+    reconcile?: boolean;
+    /** With `prune`/`reconcile`, log candidates without dropping. */
     dryRun?: boolean;
 }
 /**
@@ -141,16 +153,18 @@ export declare function defaultIndexName(keys: Record<string, FlongoIndexKeyType
  * 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);
+ *   `"conflict"` (never silently dropped/recreated) — unless `reconcile` is on,
+ *   in which case the existing index is dropped and rebuilt from the spec
+ *   (`"reconciled"`), with the original restored if the rebuild fails;
  * - 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.
+ * prune/reconcile candidates without dropping.
  *
- * @param opts - Per-call overrides for mode, onError, prune, and dryRun.
+ * @param opts - Per-call overrides for mode, onError, prune, reconcile, and dryRun.
  * @returns One {@link FlongoIndexReport} per ensured (and pruned) index.
  */
 export declare function syncFlongoIndexes(opts?: SyncFlongoIndexesOptions): Promise<FlongoIndexReport[]>;

package/dist/indexes.js

@@ -92,6 +92,99 @@ function describeFailure(err) {
     }
     return base;
 }
+/** Order-sensitive equality between an existing index's key doc and a spec's keys. */
+function sameKeyPattern(existingKey, specKeys) {
+    const a = Object.entries(existingKey ?? {});
+    const b = Object.entries(specKeys);
+    return a.length === b.length && a.every(([field, type], i) => b[i][0] === field && b[i][1] === type);
+}
+/**
+ * Finds the existing index a conflicting spec collides with: same resolved
+ * name, or (for an explicitly renamed spec) the same key pattern under another
+ * name. The server-side index is the identity that must be dropped to
+ * reconcile — not the spec's resolved name, which may not exist yet.
+ */
+function findConflictingIndex(existing, spec) {
+    const name = resolveIndexName(spec);
+    return (existing.find((i) => i.name === name) ??
+        existing.find((i) => sameKeyPattern(i.key, spec.keys)));
+}
+/**
+ * Rebuilds `createIndex` options from a `listIndexes` document so a dropped
+ * index can be restored verbatim, minus the server-managed fields that
+ * `createIndex` does not accept back.
+ */
+function restoreOptionsFromIndexDoc(doc) {
+    const options = {};
+    for (const [field, value] of Object.entries(doc)) {
+        if (field !== "v" && field !== "key" && field !== "ns" && field !== "background") {
+            options[field] = value;
+        }
+    }
+    return options;
+}
+/**
+ * Attempts to reconcile a conflicting spec by dropping the existing index and
+ * rebuilding it from the declaration. If the rebuild fails, the original index
+ * is restored from the pre-sync snapshot so the collection is never left
+ * without it. Returns the report for the attempt, or `undefined` when there is
+ * no safely identifiable drop target (or the target is `_id_`, or this is a
+ * dry run), in which case the caller falls back to plain conflict handling.
+ */
+async function reconcileIndex(collection, collectionName, spec, existing, dryRun) {
+    const target = findConflictingIndex(existing, spec);
+    if (!target || target.name === "_id_") {
+        return undefined;
+    }
+    const targetName = target.name;
+    const resolvedName = resolveIndexName(spec);
+    if (dryRun) {
+        console.warn(`[flongo] [dry-run] would reconcile index ${collectionName}.${targetName} (drop + rebuild as ${resolvedName})`);
+        return undefined;
+    }
+    try {
+        await collection.dropIndex(targetName);
+    }
+    catch (err) {
+        return {
+            collection: collectionName,
+            name: targetName,
+            status: "failed",
+            error: `reconcile could not drop existing index: ${err?.message ?? String(err)}`
+        };
+    }
+    try {
+        const createdName = await collection.createIndex(spec.keys, (spec.options ?? {}));
+        console.warn(`[flongo] Reconciled index ${collectionName}.${createdName ?? resolvedName} (dropped ${targetName}, rebuilt with declared options)`);
+        return {
+            collection: collectionName,
+            name: createdName ?? resolvedName,
+            status: "reconciled"
+        };
+    }
+    catch (err) {
+        const rebuildFailure = describeFailure(err);
+        // The old index is already gone; restore it rather than leaving the
+        // collection with no index at all.
+        try {
+            await collection.createIndex(target.key, restoreOptionsFromIndexDoc(target));
+            return {
+                collection: collectionName,
+                name: resolvedName,
+                status: "failed",
+                error: `reconcile rebuild failed; original index ${targetName} was restored — ${rebuildFailure}`
+            };
+        }
+        catch (restoreErr) {
+            return {
+                collection: collectionName,
+                name: resolvedName,
+                status: "failed",
+                error: `reconcile rebuild failed and restoring ${targetName} also failed — the collection is currently missing this index. Rebuild: ${rebuildFailure}; restore: ${restoreErr?.message ?? String(restoreErr)}`
+            };
+        }
+    }
+}
 /** Logs a one-line summary of a sync run, grouped by status. */
 function logSummary(reports) {
     const counts = {};
@@ -113,22 +206,25 @@ function logSummary(reports) {
  * 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);
+ *   `"conflict"` (never silently dropped/recreated) — unless `reconcile` is on,
+ *   in which case the existing index is dropped and rebuilt from the spec
+ *   (`"reconciled"`), with the original restored if the rebuild fails;
  * - 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.
+ * prune/reconcile candidates without dropping.
  *
- * @param opts - Per-call overrides for mode, onError, prune, and dryRun.
+ * @param opts - Per-call overrides for mode, onError, prune, reconcile, 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 reconcile = opts.reconcile ?? cfg.reconcile ?? 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";
@@ -160,6 +256,17 @@ async function syncFlongoIndexes(opts = {}) {
             }
             catch (err) {
                 const conflict = isConflictError(err);
+                if (conflict && reconcile) {
+                    const report = await reconcileIndex(collection, collectionName, spec, existing, dryRun);
+                    if (report) {
+                        reports.push(report);
+                        if (report.status === "failed") {
+                            raise("failed", collectionName, report.name, report.error ?? "reconcile failed");
+                        }
+                        continue;
+                    }
+                    // No safe drop target (or dry run): fall through to plain conflict handling.
+                }
                 const status = conflict ? "conflict" : "failed";
                 const message = conflict
                     ? err?.message ?? "index options conflict"

package/package.json

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