cry-db 2.4.32 → 2.4.33

package/dist/mongo.mjs

@@ -1,3 +1,5 @@
+// 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 +37,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 +635,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 +675,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 +717,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 +762,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 +866,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 +1050,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 +1070,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 +2406,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 +2443,443 @@ 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 and AUTO-FILLS element `_id` for terminal
+     * bracket-id paths in `$set` whose value is an object (replace) or array of
+     * objects (insert).
+     *
+     * Three rules enforced:
+     *   1) `_id` in brackets must be non-empty            (empty → throw via `_unquoteBracketId`)
+     *   2) `_id` in brackets must equal element's `_id`   (mismatch → throw, prevents data corruption)
+     *   3) element `_id` may be omitted                   (auto-fill from bracket id)
+     *
+     * Mutates element objects in place (auto-fill). Throws on rule 1/2 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 validated/filled element `_id`.
+     */
+    _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) {
+                    el._id = bracketId; // auto-fill rule 3
+                }
+                else 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}". Either omit element _id (auto-filled from bracket) or align both.`);
+                }
+            };
+            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 }));
+    }
+    /**
+     * Combined bracket-path processing: extracts inserts (`arr[id]: [els]`),
+     * removes (`arr[id]: undefined` → `$unset`), and arrayFilters (`arr[id].field = X`).
+     * 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 with unified `$filter + $concatArrays`
+     *                              per parent field; arrayFilters NOT allowed (throws)
+     *
+     * The unified pipeline stage atomically filters out elements matching any of
+     * the (removeIds ∪ insertIds), then appends new elements. This makes inserts
+     * idempotent (re-inserting same _id no-ops) and combines remove+insert without
+     * race window.
+     */
+    _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);
+        const arrayFilters = this._extractArrayFilters(update);
+        if (!inserts && !removes) {
+            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;
+            return arrayFilters ? { update, arrayFilters } : { update };
+        }
+        // Inserts present (± removes) → pipeline form.
+        if (arrayFilters) {
+            throw new Error('cry-db: cannot combine bracket-by-_id sub-field updates (e.g. `arr[id].field`) with terminal-bracket array inserts (e.g. `arr[id]: [<elements>]`) in the same update. Pipeline form does not support arrayFilters. Split into two separate updateOne/save calls.');
+        }
+        // Group inserts AND removes per parent field — they share one filter+concat stage.
+        // Insert elements implicitly remove existing same-_id entries first (idempotency).
+        const fieldOps = new Map();
+        if (inserts) {
+            for (const ins of inserts) {
+                if (!fieldOps.has(ins.field))
+                    fieldOps.set(ins.field, { removeIds: [], insertElements: [] });
+                const ops = fieldOps.get(ins.field);
+                ops.removeIds.push(...ins.ids);
+                ops.insertElements.push(...ins.elements);
+            }
+        }
+        if (removes) {
+            for (const rm of removes) {
+                if (!fieldOps.has(rm.field))
+                    fieldOps.set(rm.field, { removeIds: [], insertElements: [] });
+                const ops = fieldOps.get(rm.field);
+                ops.removeIds.push(...rm.ids);
+            }
+        }
+        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) });
+        }
+        for (const [field, ops] of fieldOps.entries()) {
+            const dedupedRemoveIds = Array.from(new Set(ops.removeIds));
+            pipeline.push({
+                $set: {
+                    [field]: {
+                        $concatArrays: [
+                            {
+                                $filter: {
+                                    input: { $ifNull: [`$${field}`, []] },
+                                    as: 'el',
+                                    cond: { $not: { $in: ['$$el._id', dedupedRemoveIds] } },
+                                },
+                            },
+                            ops.insertElements,
+                        ],
+                    },
+                },
+            });
+        }
+        return { update: pipeline };
+    }
     async _processHashedKeys(obj) {
         const hashedKeys = Object.keys(obj).filter(startsWithHashedPrefix);
         await Promise.all(hashedKeys.map(async (key) => {