cry-db 2.4.48 → 2.5.0

package/dist/utils.mjs

@@ -0,0 +1,807 @@
+// AI created: 2026-05-21
+// AI modified: 2026-05-21 (rename computeDiff → computeObjDiff, applyDiffLocally → applyObjDiff)
+//
+// Diff utilities extracted from cry-synced-db-client
+// (`src/utils/computeDiff.ts` + `SyncedDb.applyDiffLocally`). These are the
+// server-symmetric counterparts of the client diff machinery: `computeObjDiff`
+// produces minimal MongoDB-style dot/bracket paths between two documents, and
+// `applyObjDiff` replays such a path-set onto a base document the same way
+// a server-side `$set` + `$unset` would. Pure functions, no mongo dependency.
+// ── ObjectId / plain-object detection ──────────────────────────────────────
+/** Duck-type ObjectId detection (avoids a bson dependency). */
+function isObjectIdLike(v) {
+    return !!(v &&
+        typeof v === "object" &&
+        (v._bsontype === "ObjectId" || v._bsontype === "ObjectID") &&
+        typeof v.toString === "function");
+}
+function isPlainObject(v) {
+    if (v === null || typeof v !== "object")
+        return false;
+    if (Array.isArray(v))
+        return false;
+    if (v instanceof Date)
+        return false;
+    if (isObjectIdLike(v))
+        return false;
+    // Filter out other class instances (Map, Set, RegExp, etc.)
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+}
+/** Deep equality for values that may include Date, ObjectId, plain objects, arrays. */
+export function deepEquals(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (a === undefined || b === undefined)
+        return false;
+    if (a instanceof Date && b instanceof Date) {
+        return a.getTime() === b.getTime();
+    }
+    if (isObjectIdLike(a) && isObjectIdLike(b)) {
+        return String(a) === String(b);
+    }
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== "object")
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a)) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (!deepEquals(a[i], b[i]))
+                return false;
+        }
+        return true;
+    }
+    // Plain object comparison
+    const ak = Object.keys(a);
+    const bk = Object.keys(b);
+    if (ak.length !== bk.length)
+        return false;
+    for (const k of ak) {
+        if (!Object.prototype.hasOwnProperty.call(b, k))
+            return false;
+        if (!deepEquals(a[k], b[k]))
+            return false;
+    }
+    return true;
+}
+// ── computeObjDiff ─────────────────────────────────────────────────────────
+/**
+ * Check if every element in array has a non-null _id field.
+ * Required for element-wise diff strategy.
+ */
+function allElementsHaveId(arr) {
+    if (arr.length === 0)
+        return false;
+    for (const e of arr) {
+        if (!e || typeof e !== "object")
+            return false;
+        if (e._id == null)
+            return false;
+    }
+    return true;
+}
+/**
+ * Check if two arrays have the same _id composition in the same order.
+ * Returns false if reordering, additions, or removals are detected.
+ */
+function sameIdSequence(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (String(a[i]._id) !== String(b[i]._id))
+            return false;
+    }
+    return true;
+}
+/**
+ * True if `value` contains (anywhere in its tree) a non-empty array whose
+ * every element has an `_id` — i.e. recursing into `value` could emit
+ * another bracket-by-id path segment.
+ *
+ * Used to guard against multi-bracket diff paths: when an element-wise diff
+ * would otherwise recurse into a child element that itself contains an
+ * `_id`-array, we LIFT the diff — emit the parent element as a single
+ * `arr[<id>] = <full element>` replacement at the first bracket level.
+ */
+function containsIdArrayDescendant(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    if (value instanceof Date || isObjectIdLike(value))
+        return false;
+    if (Array.isArray(value)) {
+        if (value.length > 0 && allElementsHaveId(value))
+            return true;
+        for (const v of value) {
+            if (containsIdArrayDescendant(v))
+                return true;
+        }
+        return false;
+    }
+    if (!isPlainObject(value))
+        return false;
+    for (const key of Object.keys(value)) {
+        if (containsIdArrayDescendant(value[key]))
+            return true;
+    }
+    return false;
+}
+/**
+ * Compute diff between two array values at a given path.
+ *
+ * Strategy (when both arrays have `_id` on every element):
+ *   1. Same `_id` set, same order  → element-wise sub-field diff via `arr[<id>].field`
+ *   2. Same `_id` set, different order → full replace (no good per-element repr for reorder)
+ *   3. Different `_id` set (added/removed) → emit PRECISE paths:
+ *       - removed:  `arr[<id>] = undefined`            (server: `$pull`)
+ *       - added:    `arr[<id>] = [element]`            (server: `$concatArrays + $filter`)
+ *       - retained: element-wise sub-field via `arr[<id>].field`
+ *
+ * Falls back to full-replace when elements lack `_id` (no id to use for bracket).
+ */
+function computeArrayDiff(existingArr, updateArr, basePath, diff) {
+    // Both empty → no diff.
+    if (existingArr.length === 0 && updateArr.length === 0)
+        return;
+    // Element-wise diff requires `_id` on every element in BOTH arrays. If either
+    // is missing, fall back to full replace (no bracket-id to anchor paths).
+    // Empty existing is OK — we just emit insert paths for every update element.
+    if (!allElementsHaveId(updateArr) ||
+        (existingArr.length > 0 && !allElementsHaveId(existingArr))) {
+        if (!deepEquals(existingArr, updateArr)) {
+            diff[basePath] = updateArr;
+        }
+        return;
+    }
+    // Build _id sets for composition diff.
+    const existingIds = new Set();
+    for (const e of existingArr)
+        existingIds.add(String(e._id));
+    const updateIds = new Set();
+    for (const u of updateArr)
+        updateIds.add(String(u._id));
+    // Same _id set?
+    let sameSet = existingIds.size === updateIds.size;
+    if (sameSet) {
+        for (const id of existingIds) {
+            if (!updateIds.has(id)) {
+                sameSet = false;
+                break;
+            }
+        }
+    }
+    if (sameSet) {
+        if (sameIdSequence(existingArr, updateArr)) {
+            // Same composition, same order → per-element sub-field diff.
+            // No-multi-bracket invariant: if recursing into the element would
+            // produce ANOTHER bracket segment (the element contains a nested
+            // `_id`-array), LIFT instead — emit the full element at `arr[<id>]`.
+            for (let i = 0; i < updateArr.length; i++) {
+                const elementId = String(updateArr[i]._id);
+                const elementPath = `${basePath}[${elementId}]`;
+                if (containsIdArrayDescendant(updateArr[i])) {
+                    if (!deepEquals(existingArr[i], updateArr[i])) {
+                        diff[elementPath] = updateArr[i];
+                    }
+                }
+                else {
+                    computeDiffInto(existingArr[i], updateArr[i], elementPath, diff);
+                }
+            }
+        }
+        else {
+            // Same composition, different order → full replace. No clean per-element
+            // representation for reorder (mongo arrays are positional; bracket paths
+            // target by id, not position).
+            diff[basePath] = updateArr;
+        }
+        return;
+    }
+    // Composition changed. Emit precise insert/remove/sub-field paths.
+    // 1. REMOVED _ids → terminal bracket with `undefined` value.
+    for (const id of existingIds) {
+        if (!updateIds.has(id)) {
+            diff[`${basePath}[${id}]`] = undefined;
+        }
+    }
+    // 2. ADDED _ids → terminal bracket with `[element]` array value.
+    for (const updateEl of updateArr) {
+        const id = String(updateEl._id);
+        if (!existingIds.has(id)) {
+            diff[`${basePath}[${id}]`] = [updateEl];
+        }
+    }
+    // 3. RETAINED _ids → element-wise sub-field diff OR full-element lift.
+    if (existingArr.length > 0) {
+        const existingById = new Map();
+        for (const e of existingArr)
+            existingById.set(String(e._id), e);
+        for (const updateEl of updateArr) {
+            const id = String(updateEl._id);
+            if (existingIds.has(id)) {
+                const elementPath = `${basePath}[${id}]`;
+                if (containsIdArrayDescendant(updateEl)) {
+                    if (!deepEquals(existingById.get(id), updateEl)) {
+                        diff[elementPath] = updateEl;
+                    }
+                }
+                else {
+                    computeDiffInto(existingById.get(id), updateEl, elementPath, diff);
+                }
+            }
+        }
+    }
+}
+/**
+ * Recursive diff accumulator. Mutates `diff` in place.
+ * Public API uses computeObjDiff() which returns a fresh object.
+ */
+function computeDiffInto(existing, update, basePath, diff) {
+    // No-op cases
+    if (deepEquals(existing, update))
+        return;
+    // Type mismatch or update is non-object → full replace at basePath
+    if (update === null ||
+        update === undefined ||
+        typeof update !== "object" ||
+        update instanceof Date ||
+        isObjectIdLike(update)) {
+        diff[basePath] = update;
+        return;
+    }
+    // existing is missing or non-object → emit update as-is at basePath
+    if (existing === null ||
+        existing === undefined ||
+        typeof existing !== "object" ||
+        existing instanceof Date ||
+        isObjectIdLike(existing)) {
+        diff[basePath] = update;
+        return;
+    }
+    // Array vs object mismatch → full replace
+    if (Array.isArray(update) !== Array.isArray(existing)) {
+        diff[basePath] = update;
+        return;
+    }
+    if (Array.isArray(update)) {
+        computeArrayDiff(existing, update, basePath, diff);
+        return;
+    }
+    // Plain object → recurse on each key in update
+    if (!isPlainObject(update) || !isPlainObject(existing)) {
+        // Class instance edge case → full replace
+        diff[basePath] = update;
+        return;
+    }
+    // Empty-object full-replace: when `update` is `{}` but `existing` has
+    // children, the caller's intent is "clear all children". Symmetric with
+    // `field: []` (array replace) and `field: undefined` (delete the field).
+    if (Object.keys(update).length === 0 && Object.keys(existing).length > 0) {
+        diff[basePath] = update;
+        return;
+    }
+    for (const key of Object.keys(update)) {
+        const childPath = basePath ? `${basePath}.${key}` : key;
+        computeDiffInto(existing[key], update[key], childPath, diff);
+    }
+}
+/**
+ * Server-managed metadata fields that must NEVER appear in a diff. These are
+ * populated by mongo via `$currentDate` (`_ts`) and `$inc` (`_rev`); recursing
+ * into them would otherwise emit dot-notation entries (e.g. `_ts.t`, `_ts.i`,
+ * `_rev`) that conflict with mongo's atomic operators on the same path.
+ */
+const SERVER_MANAGED_METADATA_KEYS = new Set(["_ts", "_rev", "_csq"]);
+/**
+ * Compute the minimal set of MongoDB dot-notation $set paths that transform
+ * `existing` into `update` (only for keys present in `update`).
+ *
+ * @returns Record where keys are dot-notation paths and values are new values.
+ *   Empty object means no changes.
+ *
+ * @example
+ * existing = { koraki: [{ _id: "k1", diag: "old", ter: "x" }] }
+ * update   = { koraki: [{ _id: "k1", diag: "new", ter: "x" }] }
+ * → { "koraki[k1].diag": "new" }
+ */
+export function computeObjDiff(existing, update) {
+    const diff = {};
+    if (!update || typeof update !== "object")
+        return diff;
+    // No existing → full update is the diff (still strip server metadata).
+    if (existing === null || existing === undefined) {
+        const cleaned = {};
+        for (const k of Object.keys(update)) {
+            if (SERVER_MANAGED_METADATA_KEYS.has(k))
+                continue;
+            cleaned[k] = update[k];
+        }
+        return cleaned;
+    }
+    for (const key of Object.keys(update)) {
+        // Skip server-managed metadata at the top level so we never recurse into
+        // BSON Timestamp `{t,i}` sub-fields (which would emit `_ts.t`/`_ts.i`).
+        if (SERVER_MANAGED_METADATA_KEYS.has(key))
+            continue;
+        computeDiffInto(existing[key], update[key], key, diff);
+    }
+    return diff;
+}
+// ── path tokenization + set/delete by path ─────────────────────────────────
+/**
+ * Tokenize a dot-notation path that may contain bracket-id segments.
+ *
+ * "postavke[A].kolicina"   → ["postavke", "[A]", "kolicina"]
+ * "koraki.0.diag"          → ["koraki", "0", "diag"]
+ * "arr[A].sub[B].field"    → ["arr", "[A]", "sub", "[B]", "field"]
+ */
+export function 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)); // includes [ and ]
+            i = close;
+        }
+        else {
+            buf += ch;
+        }
+    }
+    if (buf)
+        out.push(buf);
+    return out;
+}
+/**
+ * Plain-object container check: a `{}` literal or `Object.create(null)`.
+ * Host types (Date, ObjectId, RegExp, Map, Set) and arrays return false.
+ */
+function isPlainObjectContainer(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value !== "object")
+        return false;
+    if (Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** Navigate one step into `current` by segment; returns child or undefined. */
+function navigateSegment(current, part) {
+    if (current === null || current === undefined)
+        return undefined;
+    if (part.startsWith("[") && part.endsWith("]")) {
+        const idStr = part.slice(1, -1);
+        if (!Array.isArray(current))
+            return undefined;
+        return current.find((item) => item && String(item._id) === idStr);
+    }
+    if (/^\d+$/.test(part) && Array.isArray(current)) {
+        return current[Number(part)];
+    }
+    if (typeof current === "object") {
+        return current[part];
+    }
+    return undefined;
+}
+/**
+ * Set the last segment on `current` (mutates in place). Returns success.
+ *
+ * Terminal bracket-by-_id (`[<id>]`) on an array supports the insert/replace
+ * wire form (`arr[<id>] = [<el>]`):
+ *   - Match found in array → replace at that index
+ *   - No match found → PUSH the unwrapped element (composition-change INSERT)
+ */
+function setSegment(current, part, value) {
+    if (current === null || current === undefined)
+        return false;
+    if (part.startsWith("[") && part.endsWith("]")) {
+        const idStr = part.slice(1, -1);
+        if (!Array.isArray(current))
+            return false;
+        const idx = current.findIndex((item) => item && String(item._id) === idStr);
+        // INSERT/REPLACE wire form: `[<el>]` wrapper with `el._id === idStr`.
+        // Unwrap and push (no match) or replace (match) — never produces dupes.
+        if (Array.isArray(value) &&
+            value.length === 1 &&
+            value[0] &&
+            typeof value[0] === "object" &&
+            String(value[0]._id) === idStr) {
+            if (idx >= 0)
+                current[idx] = value[0];
+            else
+                current.push(value[0]);
+            return true;
+        }
+        if (idx < 0)
+            return false;
+        current[idx] = value;
+        return true;
+    }
+    if (/^\d+$/.test(part) && Array.isArray(current)) {
+        current[Number(part)] = value;
+        return true;
+    }
+    if (typeof current === "object") {
+        current[part] = value;
+        return true;
+    }
+    return false;
+}
+/**
+ * Set a value at a path within a nested target. Supports three segment forms:
+ *   - Numeric ("0", "1") → array index
+ *   - Bracket ("[<_id>]") → array element matched by `_id` field
+ *   - Plain ("field") → object key
+ *
+ * Auto-creation policy (when `opts.autoCreate !== false`, the default):
+ *   - PLAIN segment whose intermediate is `undefined`/`null` AND whose parent
+ *     is a plain object → materialize `{}` in place and continue.
+ *   - PLAIN segment whose intermediate is a primitive → REFUSE (return false).
+ *   - NUMERIC / BRACKET segment → unchanged (cannot safely synthesize an array
+ *     slot or element without committing to the array shape). The dedicated
+ *     `materializeBracketPath` helper handles those.
+ *
+ * @returns true if the value was set, false if traversal failed for a reason
+ *          that cannot be auto-corrected.
+ */
+export function setByPath(target, path, value, opts) {
+    if (target === null || target === undefined)
+        return false;
+    const autoCreate = (opts === null || opts === void 0 ? void 0 : opts.autoCreate) !== false;
+    const parts = tokenizePath(path);
+    // Auto-create gate: refuse if ANY segment requires array shape
+    // (bracket-by-id or numeric index). Plain-object intermediates `{}` are the
+    // only thing we can synthesize without external shape info.
+    const pathHasArrayShape = parts.some((p) => (p.startsWith("[") && p.endsWith("]")) || /^\d+$/.test(p));
+    const canAutoCreate = autoCreate && !pathHasArrayShape;
+    let current = target;
+    // Track keys we created on each container, so we can roll back if the final
+    // `setSegment` fails — leaves no orphan `{}` intermediates in the target.
+    const created = [];
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        let next = navigateSegment(current, part);
+        // Treat null exactly like undefined for auto-create eligibility.
+        const isMissing = next === undefined || next === null;
+        if (isMissing && canAutoCreate) {
+            // pathHasArrayShape is false here, so all segments are plain.
+            if (isPlainObjectContainer(current)) {
+                current[part] = {};
+                created.push({ container: current, key: part });
+                next = current[part];
+            }
+            else {
+                return false;
+            }
+        }
+        else if (isMissing) {
+            return false;
+        }
+        else if (autoCreate &&
+            !pathHasArrayShape &&
+            !isPlainObjectContainer(next) &&
+            !Array.isArray(next)) {
+            // All-plain path + existing intermediate is a HOST object (Date,
+            // ObjectId, RegExp, …). Drilling further would silently mutate the host
+            // instance. Refuse; caller can take its own recovery branch.
+            return false;
+        }
+        current = next;
+    }
+    const last = parts[parts.length - 1];
+    const ok = setSegment(current, last, value);
+    if (!ok && created.length > 0) {
+        // Roll back auto-created intermediates so the target is unchanged on failure.
+        for (let i = created.length - 1; i >= 0; i--) {
+            const { container, key } = created[i];
+            delete container[key];
+        }
+    }
+    return ok;
+}
+/** Delete the last segment on `current` (mutates in place). Returns success. */
+function deleteSegment(current, part) {
+    if (current === null || current === undefined)
+        return false;
+    if (part.startsWith("[") && part.endsWith("]")) {
+        const idStr = part.slice(1, -1);
+        if (!Array.isArray(current))
+            return false;
+        const idx = current.findIndex((item) => item && String(item._id) === idStr);
+        if (idx < 0)
+            return false;
+        current.splice(idx, 1);
+        return true;
+    }
+    if (/^\d+$/.test(part) && Array.isArray(current)) {
+        const idx = Number(part);
+        if (idx < 0 || idx >= current.length)
+            return false;
+        current.splice(idx, 1);
+        return true;
+    }
+    if (typeof current === "object") {
+        if (!Object.prototype.hasOwnProperty.call(current, part))
+            return false;
+        delete current[part];
+        return true;
+    }
+    return false;
+}
+/**
+ * Delete the value at `path` within `target`. Sibling of `setByPath` —
+ * navigates the same tokenized path forms (numeric, bracket-by-_id, plain),
+ * but the final segment removes the property/element instead of setting it.
+ *
+ * Honors the convention that an `undefined` value in a diff means "delete this
+ * field". Returns `true` if a delete actually occurred.
+ */
+export function deleteByPath(target, path) {
+    if (target === null || target === undefined)
+        return false;
+    const parts = tokenizePath(path);
+    if (parts.length === 0)
+        return false;
+    let current = target;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const next = navigateSegment(current, parts[i]);
+        if (next === undefined || next === null)
+            return false;
+        current = next;
+    }
+    const last = parts[parts.length - 1];
+    return deleteSegment(current, last);
+}
+// ── applyObjDiff ───────────────────────────────────────────────────────────
+/**
+ * Deep clone for `applyObjDiff`. Recurses into plain objects and arrays;
+ * preserves `Date` (cloned to avoid shared reference) and `ObjectId`-like
+ * values by reference. Other class instances pass through by reference. Avoids
+ * `structuredClone` because it throws on class instances like bson `ObjectId`.
+ */
+function safeDeepClone(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value !== "object")
+        return value;
+    if (value instanceof Date)
+        return new Date(value.getTime());
+    if (isObjectIdLike(value))
+        return value;
+    if (Array.isArray(value)) {
+        const out = new Array(value.length);
+        for (let i = 0; i < value.length; i++)
+            out[i] = safeDeepClone(value[i]);
+        return out;
+    }
+    // Skip class instances other than plain objects (return by reference).
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return value;
+    const out = {};
+    for (const key of Object.keys(value)) {
+        out[key] = safeDeepClone(value[key]);
+    }
+    return out;
+}
+/**
+ * Fallback for `setByPath` failures inside `applyObjDiff`. Materializes
+ * missing array containers AND missing intermediate plain objects so the diff
+ * entry can land instead of being dropped.
+ *
+ * Supported path shape (tokenizes to `[…plain prefix, [<id>], …plain suffix]`):
+ *   - `polje[<id>] = <obj>`              → seed.polje = [<obj>]
+ *   - `polje[<id>].field = <v>`          → seed.polje = [{_id, field: <v>}]
+ *   - `outer.inner.polje[<id>].a.b = <v>`→ seed.outer = {inner: {polje: [{_id, a:{b:<v>}}]}}
+ *   - existing matching `_id`            → walk into element, set leaf (no dupe)
+ *
+ * Dropped: multi-bracket paths (need shape knowledge we can't reconstruct) and
+ * existing non-plain intermediates. Drops on `_`-prefixed roots are SILENT
+ * (server-mirrored fields — next sync hydrates the canonical state); other
+ * drops log a `console.error` so real data loss is surfaced.
+ */
+function materializeBracketPath(seed, path, value, collection, id) {
+    const tokens = tokenizePath(path);
+    const firstToken = tokens[0];
+    // Internal/redundancy fields (name starts with `_`) are server-mirrored —
+    // dropping such paths locally without logging is acceptable: next sync brings
+    // the materialized structure back. Other field names are user-authored, so a
+    // drop is real data loss we want to surface.
+    const dropSilently = typeof firstToken === "string" && firstToken.startsWith("_");
+    const drop = (reason) => {
+        if (dropSilently)
+            return;
+        console.error(`[cry-db] applyObjDiff: dropping bracket-path diff entry (${reason})`, { collection, _id: String(id), path, value });
+    };
+    if (tokens.length < 2) {
+        drop(`unsupported token count ${tokens.length}`);
+        return;
+    }
+    if (firstToken === undefined || firstToken.startsWith("[")) {
+        drop("first segment is not a plain field");
+        return;
+    }
+    // Locate the first bracket token. Everything before it is the plain prefix;
+    // the bracket itself is the element selector; everything after is the plain
+    // suffix walked into the matched element.
+    let bracketIdx = -1;
+    for (let i = 1; i < tokens.length; i++) {
+        if (tokens[i].startsWith("[")) {
+            bracketIdx = i;
+            break;
+        }
+    }
+    if (bracketIdx < 0) {
+        drop("no bracket segment found");
+        return;
+    }
+    // No additional brackets allowed — multi-bracket paths need shape knowledge
+    // we don't carry.
+    for (let i = bracketIdx + 1; i < tokens.length; i++) {
+        if (tokens[i].startsWith("[")) {
+            drop("nested bracket path");
+            return;
+        }
+    }
+    // `_`-prefixed roots only materialize for the single-segment-prefix shape.
+    // Multi-segment prefix under `_` stays a silent drop.
+    if (dropSilently && bracketIdx > 1) {
+        return;
+    }
+    const prefixTokens = tokens.slice(0, bracketIdx);
+    const bracketToken = tokens[bracketIdx];
+    const suffixTokens = tokens.slice(bracketIdx + 1);
+    const bracketId = bracketToken.slice(1, -1);
+    if (bracketId.length === 0) {
+        drop("empty bracket id");
+        return;
+    }
+    // Navigate (and create as needed) the plain prefix down to the parent of the
+    // target array. Refuse to overwrite an existing non-plain-object intermediate.
+    let parent = seed;
+    for (let i = 0; i < prefixTokens.length - 1; i++) {
+        const seg = prefixTokens[i];
+        const cur = parent[seg];
+        if (cur === undefined || cur === null) {
+            parent[seg] = {};
+        }
+        else if (typeof cur !== "object" ||
+            Array.isArray(cur) ||
+            cur instanceof Date) {
+            drop(`existing intermediate "${prefixTokens
+                .slice(0, i + 1)
+                .join(".")}" is not a plain object`);
+            return;
+        }
+        parent = parent[seg];
+    }
+    const lastPrefixSeg = prefixTokens[prefixTokens.length - 1];
+    let arr = parent[lastPrefixSeg];
+    if (arr != null && !Array.isArray(arr)) {
+        drop(`existing "${prefixTokens.join(".")}" is not an array`);
+        return;
+    }
+    if (arr == null) {
+        arr = [];
+        parent[lastPrefixSeg] = arr;
+    }
+    // ---------- Suffix length 0: terminal-bracket whole-element op ----------
+    if (suffixTokens.length === 0) {
+        // `polje[<id>] = <obj>` — unwrap INSERT wire form `[<el>]` if it matches,
+        // otherwise treat `value` as the bare element. Stamp `_id` when missing.
+        let element = value;
+        if (Array.isArray(value) &&
+            value.length === 1 &&
+            value[0] != null &&
+            typeof value[0] === "object") {
+            element = value[0];
+        }
+        if (element == null ||
+            typeof element !== "object" ||
+            Array.isArray(element)) {
+            drop("value is not a single element or wire-form wrapper");
+            return;
+        }
+        if (element._id == null) {
+            element._id = bracketId;
+        }
+        // Replace an existing element with the same `_id` to avoid duplicates.
+        const replaceIdx = arr.findIndex((it) => it != null && typeof it === "object" && String(it._id) === bracketId);
+        if (replaceIdx >= 0) {
+            arr[replaceIdx] = element;
+        }
+        else {
+            arr.push(element);
+        }
+        return;
+    }
+    // ---------- Suffix length ≥ 1: sub-field path into the element ----------
+    const buildNestedSubTree = (segs, leaf) => {
+        let acc = leaf;
+        for (let i = segs.length - 1; i >= 0; i--) {
+            acc = { [segs[i]]: acc };
+        }
+        return acc;
+    };
+    const existingIdx = arr.findIndex((it) => it != null && typeof it === "object" && String(it._id) === bracketId);
+    if (existingIdx >= 0) {
+        // Walk into the matching element, create missing intermediates, set the leaf.
+        let cur = arr[existingIdx];
+        for (let i = 0; i < suffixTokens.length - 1; i++) {
+            const seg = suffixTokens[i];
+            const next = cur[seg];
+            if (next == null || typeof next !== "object" || Array.isArray(next)) {
+                cur[seg] = {};
+            }
+            cur = cur[seg];
+        }
+        cur[suffixTokens[suffixTokens.length - 1]] = value;
+    }
+    else {
+        const subTree = buildNestedSubTree(suffixTokens, value);
+        arr.push({ _id: bracketId, ...subTree });
+    }
+}
+/**
+ * Mongo-symmetric local apply: starting from a safe deep clone of `base`, walk
+ * each `(path, value)` entry of `diff`:
+ *
+ *   - `value === undefined`  →  `deleteByPath`  (mongo `$unset` symmetric)
+ *   - otherwise              →  `setByPath`     (mongo `$set` symmetric)
+ *
+ * Bracket-path entries whose parent array doesn't exist yet fall back to
+ * `materializeBracketPath`. The result is what an equivalent server-side
+ * `$set` + `$unset` would have produced.
+ *
+ * @param base - source document (cloned, never mutated)
+ * @param diff - dot/bracket path → value map (as produced by {@link computeObjDiff})
+ * @param fallbackId - `_id` to seed when `base` is null/has no `_id`
+ * @param collection - collection name, used only for drop-log context
+ * @returns a new object (cloned-and-mutated)
+ */
+export function applyObjDiff(base, diff, fallbackId, collection) {
+    const seed = base ? safeDeepClone(base) : { _id: fallbackId };
+    if (seed._id == null)
+        seed._id = fallbackId;
+    for (const path of Object.keys(diff)) {
+        const value = diff[path];
+        if (value === undefined) {
+            // `$unset` symmetric: physically remove the field at this path. Failure
+            // (path can't reach target) is fine — the field already wasn't there.
+            deleteByPath(seed, path);
+            continue;
+        }
+        // `$set` symmetric. Top-level keys without `.` or `[` go directly.
+        if (!path.includes(".") && !path.includes("[")) {
+            seed[path] = value;
+            continue;
+        }
+        const ok = setByPath(seed, path, value);
+        if (ok)
+            continue;
+        materializeBracketPath(seed, path, value, collection, fallbackId);
+    }
+    return seed;
+}
+//# sourceMappingURL=utils.mjs.map