flongo 2.0.0 → 2.2.0

package/README.md

@@ -168,6 +168,32 @@ const topRated = await products.aggregate([
 ]);
 ```
 
+#### Id projection & semi-joins (`getIds`)
+
+When you only need to know **which** documents match — not their contents —
+`getIds(query, pagination?)` returns matching `_id`s as strings. It uses a
+server-side projection, so full documents never leave the server. This is the
+natural fit for a semi-join: "of these N candidate ids, which pass this filter?"
+
+```typescript
+// Of these candidate stayIds, which are publicly visible?
+const visibleIds = await stays.getIds(
+  new FlongoQuery()
+    .where('_id').in(candidateStayIds)
+    .and('status').eq('Accepted')
+    .and('enable').eq(true)
+);
+```
+
+`getIds` honors the same query and pagination semantics as `getAll`, including
+sort clauses — ordered ids are useful for id-first pagination.
+
+> **Note (2.2.0):** inline `_id` clauses now compose with other field clauses,
+> as the example above relies on. Previously an `_id` clause caused every other
+> clause in the same clause list to be silently dropped, and filters had to be
+> attached via `.andQuery(new FlongoQuery().where('_id').in(ids))` — that
+> pattern still works unchanged.
+
 ### Collection Operations
 
 ```typescript
@@ -184,6 +210,7 @@ const user = await collection.create({
 // Read
 const user = await collection.get('user123');
 const users = await collection.getAll(query);
+const ids = await collection.getIds(query);   // matching _ids only (server-side projection)
 const first = await collection.getFirst(query);
 const count = await collection.count(query);
 const exists = await collection.exists(query);
@@ -307,7 +334,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 +342,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 +356,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 +373,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:
@@ -467,6 +529,25 @@ const users = await collection.getAll(
 );
 ```
 
+## Changelog
+
+### 2.2.0
+
+- **`FlongoCollection.getIds(query?, pagination?)`** — returns matching `_id`s
+  as strings via a server-side projection (`{_id: 1}` on `find`, `$project` on
+  the aggregation path), so full documents never cross the wire. Honors the
+  same query, sort, and pagination semantics as `getAll`.
+- **Inline `_id` clauses now compose in `build()`.** Previously an `_id`
+  expression in the main clause list short-circuited the build and silently
+  discarded every other clause; combining `_id` with other filters required the
+  `.andQuery(new FlongoQuery().where('_id').in(ids))` workaround. Now `_id`
+  composes like any other field (string → ObjectId conversion is preserved for
+  both single values and `$in` arrays). Queries with **only** an `_id` clause
+  build identical output to before, and the `andQuery` pattern still works.
+  *Behavior note:* if a query combined `_id` with other clauses **and** relied
+  on those other clauses being ignored, it now returns only documents matching
+  all clauses — i.e., what the query literally says.
+
 ## License
 
 MIT

package/dist/flongoCollection.d.ts

@@ -98,6 +98,32 @@ export declare class FlongoCollection<T> {
      * @private
      */
     private getAllRandom;
+    /**
+     * Retrieves only the `_id`s of matching documents, as strings (the same
+     * normalization `toEntity` applies). Uses a server-side projection so full
+     * documents never leave the server — ideal for semi-joins ("which of these N
+     * ids match this filter?") and other membership checks where hydrating whole
+     * documents is wasted work.
+     *
+     * Honors the same query and pagination semantics as `getAll`, including sort
+     * clauses (ordered ids are useful for id-first pagination).
+     *
+     * Example usage:
+     * ```typescript
+     * // Semi-join: of these candidate stayIds, which are publicly visible?
+     * const visibleIds = await stays.getIds(
+     *   new FlongoQuery()
+     *     .where('_id').in(candidateStayIds)
+     *     .and('status').eq('Accepted')
+     *     .and('enable').eq(true)
+     * );
+     * ```
+     *
+     * @param query - Optional FlongoQuery for filtering
+     * @param pagination - Optional pagination settings
+     * @returns Promise resolving to the matching document ids as strings
+     */
+    getIds(query?: FlongoQuery, pagination?: Pagination): Promise<string[]>;
     /**
      * Runs a raw aggregation pipeline against this collection and returns the
      * documents with their `_id` normalized to a string (Entity form). A low-level

package/dist/flongoCollection.js

@@ -155,6 +155,49 @@ class FlongoCollection {
         const res = await this.collection.aggregate(pipeline).toArray();
         return res.map((d) => this.toEntity(d));
     }
+    /**
+     * Retrieves only the `_id`s of matching documents, as strings (the same
+     * normalization `toEntity` applies). Uses a server-side projection so full
+     * documents never leave the server — ideal for semi-joins ("which of these N
+     * ids match this filter?") and other membership checks where hydrating whole
+     * documents is wasted work.
+     *
+     * Honors the same query and pagination semantics as `getAll`, including sort
+     * clauses (ordered ids are useful for id-first pagination).
+     *
+     * Example usage:
+     * ```typescript
+     * // Semi-join: of these candidate stayIds, which are publicly visible?
+     * const visibleIds = await stays.getIds(
+     *   new FlongoQuery()
+     *     .where('_id').in(candidateStayIds)
+     *     .and('status').eq('Accepted')
+     *     .and('enable').eq(true)
+     * );
+     * ```
+     *
+     * @param query - Optional FlongoQuery for filtering
+     * @param pagination - Optional pagination settings
+     * @returns Promise resolving to the matching document ids as strings
+     */
+    async getIds(query, pagination) {
+        // Mirror getAll: a seeded random sort must execute via the aggregation
+        // pipeline. Only the id column is materialized on either path.
+        if (query?.hasRandomSort()) {
+            await this.assertRandomSortSupported();
+            const pipeline = query.buildPipeline(pagination);
+            pipeline.push({ $project: { _id: 1 } });
+            const res = await this.collection.aggregate(pipeline).toArray();
+            return res.map((d) => String(d._id));
+        }
+        const mongodbQuery = query?.build() ?? {};
+        const mongodbOptions = {
+            ...(query?.buildOptions(pagination) ?? new flongoQuery_1.FlongoQuery().buildOptions(pagination)),
+            projection: { _id: 1 }
+        };
+        const res = await this.collection.find(mongodbQuery, mongodbOptions).toArray();
+        return res.map((d) => String(d._id));
+    }
     /**
      * Runs a raw aggregation pipeline against this collection and returns the
      * documents with their `_id` normalized to a string (Entity form). A low-level

package/dist/flongoQuery.js

@@ -492,25 +492,24 @@ class FlongoQuery {
             // Process main expressions
             if (this.expressions) {
                 for (const expression of this.expressions) {
-                    // Special handling for _id field - convert strings to ObjectIds
+                    // Build query object for this clause
+                    let fieldValue;
                     if (expression.key === "_id") {
+                        // _id keeps its string -> ObjectId conversion but composes with the
+                        // other clauses like any field (it used to short-circuit the build,
+                        // silently discarding every co-existing clause).
                         if (Array.isArray(expression.val)) {
                             // Multiple IDs: {_id: {$in: [ObjectId(...), ObjectId(...)]}}
-                            mongodbQuery = {
-                                _id: {
-                                    [expression.op ?? "$in"]: expression.val.map((element) => new mongodb_1.ObjectId(element))
-                                }
+                            fieldValue = {
+                                [expression.op ?? "$in"]: expression.val.map((element) => new mongodb_1.ObjectId(element))
                             };
                         }
                         else {
                             // Single ID: {_id: ObjectId(...)}
-                            mongodbQuery = { _id: new mongodb_1.ObjectId(expression.val) };
+                            fieldValue = new mongodb_1.ObjectId(expression.val);
                         }
-                        break; // _id queries are typically exclusive
                     }
-                    // Build query object for non-_id fields
-                    let fieldValue;
-                    if (!expression.op) {
+                    else if (!expression.op) {
                         // Direct value assignment for simple equality (arrContains)
                         fieldValue = expression.val;
                     }
@@ -528,10 +527,14 @@ class FlongoQuery {
                         // Standard operator
                         fieldValue = { [expression.op]: expression.val };
                     }
-                    // Merge operators for the same field (e.g., range queries)
+                    // Merge operators for the same field (e.g., range queries).
+                    // ObjectId instances are direct values, not operator maps — spreading
+                    // one would destroy it, so they always assign.
                     if (mongodbQuery[expression.key] &&
                         typeof mongodbQuery[expression.key] === "object" &&
-                        typeof fieldValue === "object") {
+                        !(mongodbQuery[expression.key] instanceof mongodb_1.ObjectId) &&
+                        typeof fieldValue === "object" &&
+                        !(fieldValue instanceof mongodb_1.ObjectId)) {
                         mongodbQuery[expression.key] = { ...mongodbQuery[expression.key], ...fieldValue };
                     }
                     else {

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