cry-db 2.4.32 → 2.4.34

package/dist/mongo.mjs

@@ -1,3 +1,7 @@
+// AI modified: 2026-05-10 (drop auto-fill `_id` iz bracket id — če element nima `_id`, se zdaj vrže napaka. Avto-zapolnitev je skrivala odjemalske napake; klient mora `_id` vedno nastaviti eksplicitno.)
+// AI modified: 2026-05-09 (kombiniran update: `arr[id].field` sub-field updates + `arr[id]: [els]` terminal-bracket inserts v isti operaciji — sub-field paths se zdaj prevedejo v pipeline `$map` + `$mergeObjects`, namesto da bi se metala napaka. Tudi `$inc`/`$currentDate` (npr. `_rev`/`_ts` pri useRevisions) se zdaj ohranjata v pipeline obliki.)
+// AI modified: 2026-05-09 (terminal bracket-id `arr[<id>]: undefined` → $pull (regular doc, lahko z arrayFilters); kombiniran z insert v unified $filter+$concatArrays pipeline stage per field)
+// AI modified: 2026-05-09 (terminal bracket-id `arr[<id>]` z array vrednostjo → idempotent insert preko aggregation pipeline ($concatArrays + $filter); quoted bracket id `['p0']`/`["p0"]` zdaj enak unquoted `[p0]`)
 // AI modified: 2026-04-25 (GetNewerSpec.specId — disambiguate duplicate-collection specs in findNewerMany / findNewerManyStream)
 // AI modified: 2026-04-21
 import * as bcrypt from 'bcrypt';
@@ -35,6 +39,7 @@ const parseFieldList = (fields) => (typeof fields === 'string' ? fields.split(',
 // String helper functions (faster than RegExp)
 const startsWithDollar = (s) => s.length > 0 && s[0] === '$';
 const startsWithDoubleUnderscore = (s) => s.length > 1 && s[0] === '_' && s[1] === '_';
+const isServerReserved = (s) => s === "_rev" || s === "_ts";
 const startsWithHashedPrefix = (s) => s.length > 10 && s.startsWith(HASHED_PREFIX);
 const isHex24 = (s) => {
     if (s.length !== 24)
@@ -632,21 +637,29 @@ export class Mongo extends Db {
         if (this._hasHashedKeys(update))
             await this._processHashedKeys(update);
         update = this._processUpdateObject(update);
+        const processed = this._applyBracketProcessing(update);
+        if (processed.arrayFilters)
+            opts.arrayFilters = processed.arrayFilters;
+        const isPipeline = Array.isArray(processed.update);
+        // For pipeline form, sequence-keys auto-injection cannot recurse into array of stages.
+        // Skip the `update.$set` normalization and seqKeys path entirely when pipeline.
+        let seqKeys = isPipeline ? undefined : this._findSequenceKeys(update.$set);
         fjLog.debug('updateOne called', collection, query, update);
-        let seqKeys = this._findSequenceKeys(update.$set);
         let obj = await this.executeTransactionally(collection, async (conn, client) => {
-            update.$set = update.$set || {};
-            if (seqKeys)
-                await this._processSequenceField(client, dbName, collection, update.$set, seqKeys);
-            if (update.$set === undefined || Object.keys(update.$set).length === 0)
-                delete update.$set;
-            let res = await conn.findOneAndUpdate(query, update, opts);
+            if (!isPipeline) {
+                update.$set = update.$set || {};
+                if (seqKeys)
+                    await this._processSequenceField(client, dbName, collection, update.$set, seqKeys);
+                if (update.$set === undefined || Object.keys(update.$set).length === 0)
+                    delete update.$set;
+            }
+            let res = await conn.findOneAndUpdate(query, processed.update, opts);
             if (!res)
                 return null;
-            let resObj = this._removeUnchanged(res, update, !!(options === null || options === void 0 ? void 0 : options.returnFullObject));
+            let resObj = isPipeline ? res : this._removeUnchanged(res, update, !!(options === null || options === void 0 ? void 0 : options.returnFullObject));
             await this._publishAndAudit('update', dbName, collection, resObj);
             return resObj;
-        }, !!seqKeys, { operation: "updateOne", collection, query, update, options });
+        }, !!seqKeys, { operation: "updateOne", collection, query, update: processed.update, options });
         fjLog.debug('updateOne returns', obj);
         return this._processReturnedObject(await obj);
     }
@@ -664,21 +677,27 @@ export class Mongo extends Db {
         if (this._hasHashedKeys(update))
             await this._processHashedKeys(update);
         update = this._processUpdateObject(update);
+        const processed = this._applyBracketProcessing(update);
+        if (processed.arrayFilters)
+            opts.arrayFilters = processed.arrayFilters;
+        const isPipeline = Array.isArray(processed.update);
         fjLog.debug('save called', collection, id, update);
-        let seqKeys = this._findSequenceKeys(update.$set);
+        let seqKeys = isPipeline ? undefined : this._findSequenceKeys(update.$set);
         let obj = await this.executeTransactionally(collection, async (conn, client) => {
-            update.$set = update.$set || {};
-            if (seqKeys)
-                await this._processSequenceField(client, dbName, collection, update.$set, seqKeys);
-            if (update.$set === undefined || Object.keys(update.$set).length === 0)
-                delete update.$set;
-            let res = await conn.findOneAndUpdate({ _id }, update, opts);
+            if (!isPipeline) {
+                update.$set = update.$set || {};
+                if (seqKeys)
+                    await this._processSequenceField(client, dbName, collection, update.$set, seqKeys);
+                if (update.$set === undefined || Object.keys(update.$set).length === 0)
+                    delete update.$set;
+            }
+            let res = await conn.findOneAndUpdate({ _id }, processed.update, opts);
             if (!res)
                 return null;
-            let resObj = this._removeUnchanged(res, update, !!(options === null || options === void 0 ? void 0 : options.returnFullObject));
+            let resObj = isPipeline ? res : this._removeUnchanged(res, update, !!(options === null || options === void 0 ? void 0 : options.returnFullObject));
             await this._publishAndAudit('update', dbName, collection, resObj);
             return resObj;
-        }, !!seqKeys, { operation: "save", collection, _id, update, options });
+        }, !!seqKeys, { operation: "save", collection, _id, update: processed.update, options });
         fjLog.debug('save returns', obj);
         return this._processReturnedObject(await obj);
     }
@@ -700,23 +719,29 @@ export class Mongo extends Db {
         if (this._hasHashedKeys(update))
             await this._processHashedKeys(update);
         update = this._processUpdateObject(update);
+        const processed = this._applyBracketProcessing(update);
+        if (processed.arrayFilters)
+            opts.arrayFilters = processed.arrayFilters;
+        const isPipeline = Array.isArray(processed.update);
         fjLog.debug('update called', collection, query, update);
-        let seqKeys = this._findSequenceKeys(update.$set);
+        let seqKeys = isPipeline ? undefined : this._findSequenceKeys(update.$set);
         let obj = await this.executeTransactionally(collection, async (conn, client) => {
-            update.$set = update.$set || {};
-            if (seqKeys)
-                await this._processSequenceField(client, dbName, collection, update.$set, seqKeys);
-            if (update.$set === undefined || Object.keys(update.$set).length === 0)
-                delete update.$set;
+            if (!isPipeline) {
+                update.$set = update.$set || {};
+                if (seqKeys)
+                    await this._processSequenceField(client, dbName, collection, update.$set, seqKeys);
+                if (update.$set === undefined || Object.keys(update.$set).length === 0)
+                    delete update.$set;
+            }
             fjLog.debug('update called', collection, query, update);
-            let res = await conn.updateMany(query, update, opts);
+            let res = await conn.updateMany(query, processed.update, opts);
             let resObj = {
                 n: res.modifiedCount,
                 ok: !!res.acknowledged
             };
             await this._publishAndAudit('updateMany', dbName, collection, resObj);
             return resObj;
-        }, !!seqKeys, { operation: "update", collection, query, update });
+        }, !!seqKeys, { operation: "update", collection, query, update: processed.update });
         fjLog.debug('update returns', obj);
         return await obj;
     }
@@ -739,17 +764,23 @@ export class Mongo extends Db {
         if (this._hasHashedKeys(update))
             await this._processHashedKeys(update);
         update = this._processUpdateObject(update);
-        let seqKeys = this._findSequenceKeys(update.$set);
+        const processed = this._applyBracketProcessing(update);
+        if (processed.arrayFilters)
+            opts.arrayFilters = processed.arrayFilters;
+        const isPipeline = Array.isArray(processed.update);
+        let seqKeys = isPipeline ? undefined : this._findSequenceKeys(update.$set);
         fjLog.debug('upsert processed', collection, query, update);
         if (Object.keys(query).length === 0)
             query._id = Mongo.newid();
         let ret = await this.executeTransactionally(collection, async (conn, client) => {
-            update.$set = update.$set || {};
-            if (seqKeys)
-                await this._processSequenceField(client, dbName, collection, update.$set, seqKeys);
-            if (update.$set === undefined || Object.keys(update.$set).length === 0)
-                delete update.$set;
-            let ret = await conn.findOneAndUpdate(query, update, opts);
+            if (!isPipeline) {
+                update.$set = update.$set || {};
+                if (seqKeys)
+                    await this._processSequenceField(client, dbName, collection, update.$set, seqKeys);
+                if (update.$set === undefined || Object.keys(update.$set).length === 0)
+                    delete update.$set;
+            }
+            let ret = await conn.findOneAndUpdate(query, processed.update, opts);
             if (ret) {
                 // Detect if this was an insert or update by checking _rev
                 const isInsert = this.revisions && ret._rev === 1;
@@ -837,23 +868,28 @@ export class Mongo extends Db {
                             update = this.replaceIds(update);
                             if (this._hasHashedKeys(update))
                                 await this._processHashedKeys(update);
-                            const processedUpdate = this._processUpdateObject({ ...update });
+                            const processedBase = this._processUpdateObject({ ...update });
+                            const processed = this._applyBracketProcessing(processedBase);
+                            const isPipeline = Array.isArray(processed.update);
                             const opts = {
                                 upsert: true,
                                 returnDocument: "after",
                                 includeResultMetadata: true,
+                                ...(processed.arrayFilters ? { arrayFilters: processed.arrayFilters } : {}),
                                 ...this._sessionOpt()
                             };
                             const res = await conn
                                 .db(dbName)
                                 .collection(collection)
-                                .findOneAndUpdate({ _id: objectId }, processedUpdate, opts);
+                                .findOneAndUpdate({ _id: objectId }, processed.update, opts);
                             if (res === null || res === void 0 ? void 0 : res.value) {
                                 // Determine if this was an insert or update based on lastErrorObject
                                 const wasInsert = !((_a = res.lastErrorObject) === null || _a === void 0 ? void 0 : _a.updatedExisting);
                                 const operation = wasInsert ? 'insert' : 'update';
-                                // For inserts, return full object; for updates, remove unchanged fields
-                                const retObj = wasInsert ? res.value : this._removeUnchanged(res.value, processedUpdate, false);
+                                // For inserts (or pipeline updates) return full object; for regular
+                                // updates, strip fields that didn't change. _removeUnchanged expects
+                                // doc-form update — skip for pipeline.
+                                const retObj = (wasInsert || isPipeline) ? res.value : this._removeUnchanged(res.value, processedBase, false);
                                 this._processReturnedObject(retObj);
                                 return { success: true, _id, data: retObj, operation, wasInsert };
                             }
@@ -1016,8 +1052,12 @@ export class Mongo extends Db {
                 };
                 if (this._hasHashedKeys(update))
                     await this._processHashedKeys(update);
-                const processedUpdate = this._processUpdateObject({ ...update });
-                const result = await conn.findOneAndUpdate(query, processedUpdate, options);
+                const processedBase = this._processUpdateObject({ ...update });
+                const processed = this._applyBracketProcessing(processedBase);
+                if (processed.arrayFilters)
+                    options.arrayFilters = processed.arrayFilters;
+                const isPipeline = Array.isArray(processed.update);
+                const result = await conn.findOneAndUpdate(query, processed.update, options);
                 if (!((_a = result === null || result === void 0 ? void 0 : result.value) === null || _a === void 0 ? void 0 : _a._id))
                     return null;
                 const ret = result.value;
@@ -1032,7 +1072,7 @@ export class Mongo extends Db {
                 else {
                     oper = "insert";
                 }
-                const retObj = oper === "insert" ? ret : this._removeUnchanged(ret, processedUpdate, !!(opts === null || opts === void 0 ? void 0 : opts.returnFullObject));
+                const retObj = oper === "insert" ? ret : (isPipeline ? ret : this._removeUnchanged(ret, processedBase, !!(opts === null || opts === void 0 ? void 0 : opts.returnFullObject)));
                 this._processReturnedObject(retObj);
                 return { operation: oper, data: retObj };
             });
@@ -2368,6 +2408,10 @@ export class Mongo extends Db {
                 delete update[key];
                 continue;
             }
+            if (isServerReserved(keyStr) && !keyStr.startsWith(HASHED_PREFIX)) {
+                delete update[key];
+                continue;
+            }
             if (key === '' || key === null || key === undefined) {
                 delete update[key];
                 continue;
@@ -2401,6 +2445,723 @@ export class Mongo extends Db {
         }
         return update;
     }
+    /**
+     * Translate `arr[<_id>].field` bracket-by-_id segments inside `$set`
+     * and `$unset` paths to mongo positional `$[<filterId>]` placeholders,
+     * generating matching `arrayFilters` entries.
+     *
+     * Lets clients identify array elements by their `_id` instead of by
+     * position. Mongo evaluates the filter against the live document at
+     * write time, so the operation is atomic — no race window exists where
+     * a concurrent reorder/insert/delete by another writer could shift the
+     * targeted index between client read and server write.
+     *
+     * Path token forms (matches `cry-synced-db-client` `tokenizePath`):
+     *   - plain `field`        → kept as-is
+     *   - numeric `<n>`        → kept as-is (legacy positional index path)
+     *   - bracket `[<_id>]`    → translated to `$[fN]`, filter `{fN._id: <_id>}` emitted
+     *
+     * Filters are deduplicated by (parentPath, _id) so multiple paths into
+     * the same array element share one filter (mongo requires every filter
+     * identifier to be referenced).
+     *
+     * Mutates `update.$set` / `update.$unset` in place. Returns the
+     * arrayFilters array (or `undefined` when no bracket paths present).
+     */
+    _extractArrayFilters(update) {
+        const filters = [];
+        const memo = new Map();
+        let counter = 0;
+        const translatePath = (path) => {
+            const tokens = Mongo._tokenizePath(path);
+            const out = [];
+            let parentKey = '';
+            for (const t of tokens) {
+                if (t.length >= 2 && t.charCodeAt(0) === 91 /* [ */ && t.charCodeAt(t.length - 1) === 93 /* ] */) {
+                    const idStr = Mongo._unquoteBracketId(t, path);
+                    const memoKey = `${parentKey}|${idStr}`;
+                    let filterName = memo.get(memoKey);
+                    if (filterName === undefined) {
+                        filterName = `f${counter++}`;
+                        memo.set(memoKey, filterName);
+                        filters.push({ [`${filterName}._id`]: idStr });
+                    }
+                    out.push(`$[${filterName}]`);
+                    parentKey = parentKey ? `${parentKey}.$[${filterName}]` : `$[${filterName}]`;
+                }
+                else {
+                    out.push(t);
+                    parentKey = parentKey ? `${parentKey}.${t}` : t;
+                }
+            }
+            return out.join('.');
+        };
+        const translateOp = (opName) => {
+            const op = update[opName];
+            if (!op || typeof op !== 'object')
+                return;
+            // Fast path: skip rebuild if no bracket present.
+            let hasBracket = false;
+            for (const k of Object.keys(op)) {
+                if (k.indexOf('[') >= 0) {
+                    hasBracket = true;
+                    break;
+                }
+            }
+            if (!hasBracket)
+                return;
+            const translated = {};
+            for (const k of Object.keys(op)) {
+                translated[translatePath(k)] = op[k];
+            }
+            update[opName] = translated;
+        };
+        translateOp('$set');
+        translateOp('$unset');
+        return filters.length > 0 ? filters : undefined;
+    }
+    /**
+     * Tokenize a dot-notation path that may contain `[<_id>]` bracket
+     * segments. Mirrors the client-side `cry-synced-db-client/utils/computeDiff#tokenizePath`.
+     *
+     *   "postavke[A].kolicina"   → ["postavke", "[A]", "kolicina"]
+     *   "koraki.0.diag"          → ["koraki", "0", "diag"]
+     *   "stranka.gsm"            → ["stranka", "gsm"]
+     *   "arr[A].sub[B].field"    → ["arr", "[A]", "sub", "[B]", "field"]
+     */
+    static _tokenizePath(path) {
+        const out = [];
+        let buf = '';
+        for (let i = 0; i < path.length; i++) {
+            const ch = path[i];
+            if (ch === '.') {
+                if (buf) {
+                    out.push(buf);
+                    buf = '';
+                }
+            }
+            else if (ch === '[') {
+                if (buf) {
+                    out.push(buf);
+                    buf = '';
+                }
+                const close = path.indexOf(']', i);
+                if (close < 0) {
+                    buf += ch;
+                    continue;
+                }
+                out.push(path.substring(i, close + 1));
+                i = close;
+            }
+            else {
+                buf += ch;
+            }
+        }
+        if (buf)
+            out.push(buf);
+        return out;
+    }
+    /**
+     * Strip `[ ]` wrapper and surrounding `'…'` / `"…"` quotes from a bracket-id token.
+     * Convention: `[p2]`, `['p2']`, `["p2"]` all denote element with `_id === "p2"`.
+     * Quoted form is preferred when id contains characters that could conflict with
+     * dot-notation (rare, but defensive).
+     *
+     * Throws on empty id (`[]`, `['']`, `[""]`) — empty bracket has no semantic meaning
+     * (no element to target) and almost certainly indicates a caller bug. Optional
+     * `path` argument is included in the error message for easier debugging.
+     */
+    static _unquoteBracketId(bracketToken, path) {
+        let id = bracketToken.slice(1, -1);
+        const len = id.length;
+        if (len >= 2) {
+            const first = id.charCodeAt(0);
+            const last = id.charCodeAt(len - 1);
+            if ((first === 39 /* ' */ && last === 39) || (first === 34 /* " */ && last === 34)) {
+                id = id.slice(1, -1);
+            }
+        }
+        if (id.length === 0) {
+            throw new Error(`cry-db: empty bracket id in ${path ? `path "${path}"` : `token "${bracketToken}"`} — bracket-by-_id syntax requires non-empty id (e.g. "arr[<id>]" or "arr['<id>']").`);
+        }
+        return id;
+    }
+    /**
+     * Pre-processing pass that VALIDATES element `_id` for terminal bracket-id
+     * paths in `$set` whose value is an object (replace) or array of objects
+     * (insert).
+     *
+     * Two rules enforced:
+     *   1) `_id` in brackets must be non-empty            (empty → throw via `_unquoteBracketId`)
+     *   2) every element MUST carry an `_id` that equals the bracket id
+     *      (missing or mismatched → throw, prevents data corruption / silent renaming)
+     *
+     * Throws on violation. Skips primitive values (caller knows what they're
+     * doing) and `null` (rare, not a typical insert/replace shape).
+     *
+     * Called BEFORE `_extractArrayInserts`/`_extractArrayRemoves`/`_extractArrayFilters`
+     * so downstream code can assume every element has an `_id`.
+     *
+     * Note: auto-fill of missing `_id` from the bracket id was previously supported
+     * but was removed because it hid client bugs (e.g. constructing an insert with
+     * the wrong field name and silently writing an element identified by the bracket).
+     * Always set `_id` explicitly on the client.
+     */
+    _validateAndAutoFillTerminalBracketValues(update) {
+        const $set = update.$set;
+        if (!$set || typeof $set !== 'object')
+            return;
+        let hasBracket = false;
+        for (const k of Object.keys($set)) {
+            if (k.indexOf('[') >= 0) {
+                hasBracket = true;
+                break;
+            }
+        }
+        if (!hasBracket)
+            return;
+        for (const path of Object.keys($set)) {
+            const tokens = Mongo._tokenizePath(path);
+            const lastToken = tokens[tokens.length - 1];
+            const isTerminalBracket = !!(lastToken
+                && lastToken.length >= 2
+                && lastToken.charCodeAt(0) === 91 /* [ */
+                && lastToken.charCodeAt(lastToken.length - 1) === 93 /* ] */);
+            if (!isTerminalBracket)
+                continue;
+            const bracketId = Mongo._unquoteBracketId(lastToken, path); // throws on empty
+            const value = $set[path];
+            const validateElement = (el, locator) => {
+                if (el == null || typeof el !== 'object') {
+                    throw new Error(`cry-db: bracket-id terminal at "${path}"${locator} — value must be an object with _id matching bracket id "${bracketId}" (got ${el === null ? 'null' : typeof el}).`);
+                }
+                if (el._id == null) {
+                    throw new Error(`cry-db: bracket-id terminal at "${path}"${locator} — element is missing _id. Set it explicitly to "${bracketId}" (auto-fill is no longer supported).`);
+                }
+                if (String(el._id) !== bracketId) {
+                    throw new Error(`cry-db: bracket-id terminal at "${path}"${locator} — element _id "${el._id}" does not match bracket id "${bracketId}".`);
+                }
+            };
+            if (Array.isArray(value)) {
+                for (let i = 0; i < value.length; i++)
+                    validateElement(value[i], ` [${i}]`);
+            }
+            else if (value !== null && value !== undefined && typeof value === 'object') {
+                validateElement(value, '');
+            }
+            // Primitives (string/number/boolean) — pass through to existing arrayFilters
+            // path. Mongo would set the array element to the primitive, which is unusual
+            // but not strictly invalid.
+        }
+    }
+    /**
+     * Detect "terminal-bracket-id with array value" paths in `$set` — these are the
+     * INSERT operations: client wants to add array elements identified by `_id`,
+     * not update an existing element's sub-fields.
+     *
+     * Convention:
+     *   - Path ends with `[<id>]` (terminal bracket, no `.<subfield>` after) AND
+     *   - Value is an array AND
+     *   - Every element in the array has `_id` (required for idempotency check)
+     *
+     * Mutates `update.$set` (removes matched paths). Returns extracted insert specs,
+     * or `undefined` if no inserts present.
+     *
+     * Each spec carries:
+     *   - `field`:    parent array field path (e.g. `"postavke"`)
+     *   - `ids`:      `_id`s of all elements to insert (used to dedupe existing)
+     *   - `elements`: the new elements to push
+     *
+     * Note: parent paths with NESTED brackets (e.g. `terapije[t1].postavke[<new>]`)
+     * are NOT supported here — left in `$set` for the existing arrayFilters path
+     * (which would silently no-op for non-existent ids; future enhancement).
+     */
+    _extractArrayInserts(update) {
+        const $set = update.$set;
+        if (!$set || typeof $set !== 'object')
+            return undefined;
+        // Fast path: no bracket present in any key.
+        let hasBracket = false;
+        for (const k of Object.keys($set)) {
+            if (k.indexOf('[') >= 0) {
+                hasBracket = true;
+                break;
+            }
+        }
+        if (!hasBracket)
+            return undefined;
+        const inserts = [];
+        const remaining = {};
+        for (const path of Object.keys($set)) {
+            const value = $set[path];
+            const tokens = Mongo._tokenizePath(path);
+            const lastToken = tokens[tokens.length - 1];
+            const isTerminalBracket = !!(lastToken
+                && lastToken.length >= 2
+                && lastToken.charCodeAt(0) === 91 /* [ */
+                && lastToken.charCodeAt(lastToken.length - 1) === 93 /* ] */);
+            if (isTerminalBracket && Array.isArray(value)) {
+                const parentTokens = tokens.slice(0, -1);
+                // Reject nested-bracket parent paths — combining $push semantics with
+                // arrayFilters-targeted parent is not cleanly expressible in mongo.
+                const parentHasBracket = parentTokens.some((t) => t.length > 0 && t.charCodeAt(0) === 91);
+                // Every element must have `_id` (required so we can dedupe before push).
+                const allElementsHaveId = value.every((e) => e && typeof e === 'object' && e._id != null);
+                if (!parentHasBracket && allElementsHaveId && parentTokens.length > 0) {
+                    const fieldPath = parentTokens.join('.');
+                    const ids = value.map((e) => String(e._id));
+                    inserts.push({ field: fieldPath, ids, elements: value });
+                    continue;
+                }
+            }
+            remaining[path] = value;
+        }
+        if (inserts.length === 0)
+            return undefined;
+        update.$set = remaining;
+        if (Object.keys(remaining).length === 0)
+            delete update.$set;
+        return inserts;
+    }
+    /**
+     * Detect "terminal-bracket-id with no value" paths in `$unset` — these are the
+     * REMOVE operations: client wants to drop array elements identified by `_id`.
+     *
+     * Convention:
+     *   - Path ends with `[<id>]` (terminal bracket, no `.<subfield>` after) AND
+     *   - Was sent as `undefined` in the original update (became `$unset` after
+     *     `_processUpdateObject` normalization).
+     *
+     * Mongo's `$unset` on `arr.$[fN]` would set the element to `null` in place
+     * (not remove from array). For real removal we use `$pull` instead — or, when
+     * combined with terminal-bracket inserts, the unified `$filter + $concatArrays`
+     * aggregation stage in `_applyBracketProcessing`.
+     *
+     * Mutates `update.$unset` (removes matched paths). Returns extracted remove
+     * specs (one per parent field, ids merged), or `undefined` if no removes present.
+     *
+     * Note: parent paths with NESTED brackets are not supported here (left in `$unset`
+     * for the existing arrayFilters fallback).
+     */
+    _extractArrayRemoves(update) {
+        const $unset = update.$unset;
+        if (!$unset || typeof $unset !== 'object')
+            return undefined;
+        let hasBracket = false;
+        for (const k of Object.keys($unset)) {
+            if (k.indexOf('[') >= 0) {
+                hasBracket = true;
+                break;
+            }
+        }
+        if (!hasBracket)
+            return undefined;
+        const removesByField = new Map();
+        const remaining = {};
+        for (const path of Object.keys($unset)) {
+            const tokens = Mongo._tokenizePath(path);
+            const lastToken = tokens[tokens.length - 1];
+            const isTerminalBracket = !!(lastToken
+                && lastToken.length >= 2
+                && lastToken.charCodeAt(0) === 91 /* [ */
+                && lastToken.charCodeAt(lastToken.length - 1) === 93 /* ] */);
+            if (isTerminalBracket) {
+                const parentTokens = tokens.slice(0, -1);
+                const parentHasBracket = parentTokens.some((t) => t.length > 0 && t.charCodeAt(0) === 91);
+                if (!parentHasBracket && parentTokens.length > 0) {
+                    const fieldPath = parentTokens.join('.');
+                    const id = Mongo._unquoteBracketId(lastToken, path);
+                    if (!removesByField.has(fieldPath))
+                        removesByField.set(fieldPath, []);
+                    removesByField.get(fieldPath).push(id);
+                    continue;
+                }
+            }
+            remaining[path] = $unset[path];
+        }
+        if (removesByField.size === 0)
+            return undefined;
+        update.$unset = remaining;
+        if (Object.keys(remaining).length === 0)
+            delete update.$unset;
+        return Array.from(removesByField.entries()).map(([field, ids]) => ({ field, ids }));
+    }
+    /**
+     * Extracts SINGLE-bracket bracket-by-_id paths from `$set`/`$unset`, grouped
+     * by `(parentArrayField, elementId)`. Used when pipeline form is needed
+     * (because terminal-bracket inserts/removes are present) — these paths must
+     * be expressed as `$map` + `$mergeObjects` stages, since mongo does not
+     * allow `arrayFilters` to coexist with aggregation pipelines.
+     *
+     * Path forms detected (mutated out of `$set`/`$unset`):
+     *   - `$set` `arr[id].field`           → sets["field"] = value     (sub-field set)
+     *   - `$set` `arr[id].sub.field`       → sets["sub.field"] = value (deep sub-field set)
+     *   - `$set` `arr[id]` (object value)  → replace = value           (whole-element replace)
+     *   - `$unset` `arr[id].field`         → unsets.push("field")      (sub-field unset)
+     *
+     * NOT detected (left in `$set`/`$unset` for caller to handle):
+     *   - paths with NESTED brackets (e.g. `arr[A].sub[B].field`) — caller must
+     *     reject these when in pipeline mode (still unsupported).
+     *   - terminal `arr[id]` already removed by `_extractArrayInserts`/`_extractArrayRemoves`.
+     *
+     * Mutates `update.$set` and `update.$unset`. Returns the grouped ops, or
+     * `undefined` if no extractable paths were present.
+     */
+    _extractArraySubFieldUpdates(update) {
+        const result = new Map();
+        let extractedAny = false;
+        const ensureEntry = (parentField, id) => {
+            if (!result.has(parentField))
+                result.set(parentField, new Map());
+            const idMap = result.get(parentField);
+            if (!idMap.has(id))
+                idMap.set(id, { sets: {}, unsets: [] });
+            return idMap.get(id);
+        };
+        const processOp = (opName) => {
+            const op = update[opName];
+            if (!op || typeof op !== 'object')
+                return;
+            let hasBracket = false;
+            for (const k of Object.keys(op)) {
+                if (k.indexOf('[') >= 0) {
+                    hasBracket = true;
+                    break;
+                }
+            }
+            if (!hasBracket)
+                return;
+            const remaining = {};
+            let mutated = false;
+            for (const path of Object.keys(op)) {
+                const tokens = Mongo._tokenizePath(path);
+                let bracketCount = 0;
+                let bracketIdx = -1;
+                for (let i = 0; i < tokens.length; i++) {
+                    const t = tokens[i];
+                    if (t.length >= 2 && t.charCodeAt(0) === 91 /* [ */ && t.charCodeAt(t.length - 1) === 93 /* ] */) {
+                        bracketCount++;
+                        bracketIdx = i;
+                    }
+                }
+                if (bracketCount === 1 && bracketIdx > 0) {
+                    const parentField = tokens.slice(0, bracketIdx).join('.');
+                    const id = Mongo._unquoteBracketId(tokens[bracketIdx], path);
+                    const restPath = tokens.slice(bracketIdx + 1).join('.');
+                    const elOps = ensureEntry(parentField, id);
+                    if (opName === '$set') {
+                        if (restPath === '') {
+                            // `arr[id]: <obj>` — whole-element replace.
+                            elOps.replace = op[path];
+                        }
+                        else {
+                            elOps.sets[restPath] = op[path];
+                        }
+                    }
+                    else {
+                        // `$unset arr[id].field` — sub-field unset. Terminal `$unset arr[id]`
+                        // is already extracted by `_extractArrayRemoves`.
+                        if (restPath === '') {
+                            remaining[path] = op[path];
+                            continue;
+                        }
+                        elOps.unsets.push(restPath);
+                    }
+                    mutated = true;
+                    extractedAny = true;
+                    continue;
+                }
+                remaining[path] = op[path];
+            }
+            if (mutated) {
+                update[opName] = remaining;
+                if (Object.keys(remaining).length === 0)
+                    delete update[opName];
+            }
+        };
+        processOp('$set');
+        processOp('$unset');
+        return extractedAny ? result : undefined;
+    }
+    /**
+     * Build an aggregation expression that produces a transformed copy of an
+     * element, applying the given sets/unsets and (optionally) a whole-element
+     * replacement.
+     *
+     * - `replace`: when set, becomes the new base (full element replacement).
+     * - `sets`: dot-paths within element → values; deep-merged via recursive
+     *   `$mergeObjects`/`$ifNull` so nested updates preserve sibling fields.
+     * - `unsets`: dot-paths within element to remove. Implemented via
+     *   `$arrayToObject($filter($objectToArray(merged), kv.k notIn unsets))` —
+     *   `$$REMOVE` inside `$mergeObjects` does NOT drop the field (mongo treats
+     *   it as a missing value and falls through to the previous operand), so
+     *   the explicit kv-filter is required.
+     *
+     * The returned expression is suitable as the `in:` argument of `$map`.
+     */
+    static _buildElementMergeExpr(baseExpr, ops) {
+        const hasSets = Object.keys(ops.sets).length > 0;
+        const hasUnsets = ops.unsets.length > 0;
+        const hasReplace = ops.replace !== undefined;
+        if (!hasSets && !hasUnsets && !hasReplace)
+            return baseExpr;
+        if (!hasSets && !hasUnsets) {
+            // Pure replace — embed as literal so client-supplied field names like
+            // "_id" don't get interpreted as field paths.
+            return { $literal: ops.replace };
+        }
+        const root = { directs: {}, nested: {}, unsets: [] };
+        const walkInsert = (path, isUnset, value) => {
+            const parts = path.split('.');
+            let node = root;
+            for (let i = 0; i < parts.length - 1; i++) {
+                const key = parts[i];
+                if (!node.nested[key])
+                    node.nested[key] = { directs: {}, nested: {}, unsets: [] };
+                node = node.nested[key];
+            }
+            const leaf = parts[parts.length - 1];
+            if (isUnset)
+                node.unsets.push(leaf);
+            else
+                node.directs[leaf] = value;
+        };
+        for (const [p, v] of Object.entries(ops.sets))
+            walkInsert(p, false, v);
+        for (const p of ops.unsets)
+            walkInsert(p, true);
+        // Recursively build merge expression. `basePath` is a string field path
+        // (e.g. "$$el", "$$el.sub") used to read the existing nested value.
+        const buildOverlay = (node, basePath) => {
+            const overlay = {};
+            for (const [k, v] of Object.entries(node.directs))
+                overlay[k] = v;
+            for (const [k, sub] of Object.entries(node.nested)) {
+                const subPath = `${basePath}.${k}`;
+                overlay[k] = buildOverlay(sub, subPath);
+            }
+            // Merge sets/nested onto the existing object (or {} if absent).
+            let merged = { $mergeObjects: [{ $ifNull: [basePath, {}] }, overlay] };
+            // Drop unset top-level keys at this level via kv-filter.
+            if (node.unsets.length > 0) {
+                merged = {
+                    $arrayToObject: {
+                        $filter: {
+                            input: { $objectToArray: merged },
+                            as: 'kv',
+                            cond: { $not: { $in: ['$$kv.k', node.unsets] } },
+                        },
+                    },
+                };
+            }
+            return merged;
+        };
+        // If a replace is also requested, treat replacement as the new base.
+        // Wrap with `$let` since a literal object isn't addressable by string field path.
+        if (hasReplace) {
+            const overlayExpr = buildOverlay(root, '$$replaced');
+            return {
+                $let: {
+                    vars: { replaced: { $literal: ops.replace } },
+                    in: overlayExpr,
+                },
+            };
+        }
+        return buildOverlay(root, baseExpr);
+    }
+    /**
+     * Translate an update doc's `$inc` and `$currentDate` operators into
+     * pipeline-stage equivalents, so revisions (`_rev` increment, `_ts` timestamp)
+     * still fire when the rest of the update goes through aggregation pipeline.
+     *
+     *   - `$inc: { f: n }`               → `{ $set: { f: { $add: [{ $ifNull: ['$f', 0] }, n] } } }`
+     *   - `$currentDate: { f: true }`    → `{ $set: { f: '$$NOW' } }`              (Date)
+     *   - `$currentDate: { f: { $type: 'date' } }`      → same as above
+     *   - `$currentDate: { f: { $type: 'timestamp' } }` → `{ $set: { f: '$$CLUSTER_TIME' } }` (Timestamp)
+     *
+     * Mutates `update` (deletes `$inc` and `$currentDate`). Returns 0..2 pipeline stages.
+     */
+    static _drainIncAndCurrentDateToPipelineStages(update) {
+        const stages = [];
+        const inc = update.$inc;
+        if (inc && typeof inc === 'object') {
+            const setObj = {};
+            for (const [k, v] of Object.entries(inc)) {
+                setObj[k] = { $add: [{ $ifNull: [`$${k}`, 0] }, v] };
+            }
+            if (Object.keys(setObj).length > 0)
+                stages.push({ $set: setObj });
+            delete update.$inc;
+        }
+        const cd = update.$currentDate;
+        if (cd && typeof cd === 'object') {
+            const setObj = {};
+            for (const [k, spec] of Object.entries(cd)) {
+                let isTimestamp = false;
+                if (spec && typeof spec === 'object' && spec.$type === 'timestamp')
+                    isTimestamp = true;
+                setObj[k] = isTimestamp ? '$$CLUSTER_TIME' : '$$NOW';
+            }
+            if (Object.keys(setObj).length > 0)
+                stages.push({ $set: setObj });
+            delete update.$currentDate;
+        }
+        return stages;
+    }
+    /**
+     * Combined bracket-path processing: extracts inserts (`arr[id]: [els]`),
+     * removes (`arr[id]: undefined` → `$unset`), sub-field updates
+     * (`arr[id].field`, `arr[id].sub.field`, `arr[id]: <obj>`) and arrayFilters.
+     * Decides whether mongo update should be sent as a regular doc or as an
+     * aggregation pipeline.
+     *
+     * Returns `{ update, arrayFilters? }`:
+     *   - `update` is the original update doc OR an aggregation pipeline.
+     *   - `arrayFilters` is set when sub-field bracket paths needed translation; only
+     *     valid when `update` is the doc form (mongo doesn't support arrayFilters on pipelines).
+     *
+     * Strategy matrix:
+     *   - no inserts, no removes → existing arrayFilters path (or pure update doc)
+     *   - removes only           → adds `$pull` to update doc; arrayFilters allowed
+     *   - inserts (± removes)    → pipeline form; SINGLE-bracket sub-field paths
+     *                              are also translated to pipeline `$map` + `$mergeObjects`
+     *                              so they coexist with the inserts. NESTED-bracket paths
+     *                              (e.g. `arr[A].sub[B].field`) combined with inserts still
+     *                              throw — caller must split into two operations.
+     *
+     * The unified per-parent-field pipeline stage atomically filters out elements
+     * matching any of (removeIds ∪ insertIds), maps remaining elements through the
+     * sub-field merge expression, then appends new elements. Inserts remain
+     * idempotent (re-inserting same `_id` no-ops). `$inc` and `$currentDate` are
+     * also translated to pipeline stages so revisions (`_rev`/`_ts`) still fire.
+     */
+    _applyBracketProcessing(update) {
+        // Pre-pass: validate bracket-id ↔ element-_id consistency, auto-fill missing _id.
+        // Throws on empty bracket id or _id mismatch. Mutates element objects in $set.
+        this._validateAndAutoFillTerminalBracketValues(update);
+        const inserts = this._extractArrayInserts(update);
+        const removes = this._extractArrayRemoves(update);
+        // Pure sub-field updates only (no inserts, no removes) — keep on legacy
+        // arrayFilters path (faster, smaller payload, doesn't fight $inc/$currentDate).
+        if (!inserts && !removes) {
+            const arrayFilters = this._extractArrayFilters(update);
+            return arrayFilters ? { update, arrayFilters } : { update };
+        }
+        // Removes-only path: `$pull` on update doc. Coexists fine with `$set` + arrayFilters.
+        if (removes && !inserts) {
+            const pullOp = (update.$pull || {});
+            for (const rm of removes) {
+                const existing = pullOp[rm.field];
+                if (existing && existing._id && Array.isArray(existing._id.$in)) {
+                    const merged = new Set([...existing._id.$in, ...rm.ids]);
+                    pullOp[rm.field] = { _id: { $in: Array.from(merged) } };
+                }
+                else {
+                    pullOp[rm.field] = { _id: { $in: [...rm.ids] } };
+                }
+            }
+            update.$pull = pullOp;
+            const arrayFilters = this._extractArrayFilters(update);
+            return arrayFilters ? { update, arrayFilters } : { update };
+        }
+        // Inserts present (± removes) → pipeline form.
+        // Extract single-bracket sub-field paths so we can express them as pipeline
+        // stages instead of arrayFilters (mongo forbids arrayFilters on pipelines).
+        const subFieldOps = this._extractArraySubFieldUpdates(update);
+        // Any bracket paths still in $set/$unset must be NESTED-bracket
+        // (e.g. `arr[A].sub[B].field`) — those aren't expressible without arrayFilters,
+        // so combining them with inserts is still unsupported.
+        const hasNestedBracket = (op) => {
+            if (!op)
+                return false;
+            for (const k of Object.keys(op))
+                if (k.indexOf('[') >= 0)
+                    return true;
+            return false;
+        };
+        if (hasNestedBracket(update.$set) || hasNestedBracket(update.$unset)) {
+            throw new Error('cry-db: cannot combine NESTED-bracket sub-field paths (e.g. `arr[A].sub[B].field`) with terminal-bracket array inserts (e.g. `arr[id]: [<elements>]`) in the same update. Split into two separate updateOne/save calls.');
+        }
+        const fieldOps = new Map();
+        const ensureField = (field) => {
+            if (!fieldOps.has(field))
+                fieldOps.set(field, { removeIds: [], insertElements: [], elementOps: new Map() });
+            return fieldOps.get(field);
+        };
+        if (inserts) {
+            for (const ins of inserts) {
+                const ops = ensureField(ins.field);
+                ops.removeIds.push(...ins.ids);
+                ops.insertElements.push(...ins.elements);
+            }
+        }
+        if (removes) {
+            for (const rm of removes) {
+                const ops = ensureField(rm.field);
+                ops.removeIds.push(...rm.ids);
+            }
+        }
+        if (subFieldOps) {
+            for (const [field, idMap] of subFieldOps.entries()) {
+                const ops = ensureField(field);
+                for (const [id, elOps] of idMap.entries()) {
+                    // If an insert with the same id is also queued, the insert wins
+                    // (insertElements are already extracted; element merge would only
+                    // affect "existing" rows that survive the filter — but the insert
+                    // id is in removeIds, so it's filtered out anyway). Keep the
+                    // sub-field update so callers that mix these get predictable
+                    // behavior on existing data; it's a no-op if id ends up filtered.
+                    ops.elementOps.set(id, elOps);
+                }
+            }
+        }
+        const pipeline = [];
+        if (update.$set && Object.keys(update.$set).length > 0) {
+            pipeline.push({ $set: update.$set });
+        }
+        if (update.$unset && Object.keys(update.$unset).length > 0) {
+            pipeline.push({ $unset: Object.keys(update.$unset) });
+        }
+        // Translate $inc / $currentDate so revisions (_rev/_ts) still update in pipeline form.
+        for (const stage of Mongo._drainIncAndCurrentDateToPipelineStages(update))
+            pipeline.push(stage);
+        for (const [field, ops] of fieldOps.entries()) {
+            const dedupedRemoveIds = Array.from(new Set(ops.removeIds));
+            const filteredInput = {
+                $filter: {
+                    input: { $ifNull: [`$${field}`, []] },
+                    as: 'el',
+                    cond: { $not: { $in: ['$$el._id', dedupedRemoveIds] } },
+                },
+            };
+            let mappedExisting = filteredInput;
+            if (ops.elementOps.size > 0) {
+                // Build $switch with one branch per (id → merged element).
+                const branches = [];
+                for (const [id, elOps] of ops.elementOps.entries()) {
+                    branches.push({
+                        case: { $eq: ['$$el._id', id] },
+                        then: Mongo._buildElementMergeExpr('$$el', elOps),
+                    });
+                }
+                mappedExisting = {
+                    $map: {
+                        input: filteredInput,
+                        as: 'el',
+                        in: { $switch: { branches, default: '$$el' } },
+                    },
+                };
+            }
+            pipeline.push({
+                $set: {
+                    [field]: {
+                        $concatArrays: [mappedExisting, ops.insertElements],
+                    },
+                },
+            });
+        }
+        return { update: pipeline };
+    }
     async _processHashedKeys(obj) {
         const hashedKeys = Object.keys(obj).filter(startsWithHashedPrefix);
         await Promise.all(hashedKeys.map(async (key) => {