cry-synced-db-client 0.1.162 → 0.1.164

package/CHANGELOG.md

@@ -1,5 +1,192 @@
 # Versions
 
+## Unreleased
+
+### `onServerSyncWrite` callback
+
+Single-shot callback that fires once per `restInterface.updateCollections`
+round-trip with both the request payload and either the server response
+or a thrown error in one payload. Convenience over correlating
+`onServerWriteRequest` + `onServerWriteResult`:
+
+```typescript
+const syncedDb = new SyncedDb({
+  // ...
+  onServerSyncWrite: (info) => {
+    if (info.error) {
+      console.error('upload failed', info.error.message, info.error.stack);
+    } else {
+      logToSyslog({ request: info.request, response: info.response });
+    }
+  },
+});
+```
+
+`ServerSyncWriteInfo`: `{ request, response?, error?, durationMs, calledFrom?, timestamp }`.
+`response` is `undefined` on transport / timeout / network failure;
+`error` is `{message, name?, stack?}` (serialized — safe for logging).
+
+### Local Dexie write uses diff-applied merged row (parity fix)
+
+`SyncedDb.save()` now schedules the **mongo-symmetric `merged` row** to
+Dexie via `pendingChanges`, not the raw partial `update`. Without this,
+`Dexie.table.update(key, partialUpdate)` would replace top-level array
+fields wholesale (postavke, koraki, etc.) and drop element sub-fields
+the caller didn't mention — same data-loss class the in-mem path
+already protected against. New regression test
+`test/node-only/insertUpdateRacunPostavke.test.ts` (real cry-db) verifies
+parity across **mongo + Dexie + in-mem** simultaneously after a partial
+`save({ postavke: [{_id: "P1", kolicina: 2}] })` over an existing
+`postavke[0] = {_id: "P1", opis: "postavka 1", kolicina: 1}`.
+
+## 0.1.162
+
+### Bracket-by-_id paths flow through server unchanged
+
+`SyncEngine.uploadDirtyItems` no longer calls `translateBracketPathsToIndex`.
+Bracket paths (`arr[<_id>].field`) leave the client as-is; cry-db ≥ 2.4.33
+translates them server-side to mongo `arr.$[<filterId>].field` +
+`arrayFilters` atomically against the **live document**.
+
+This eliminates the race window where another writer's
+reorder/insert/delete shifted the targeted index between the client's
+read and the server's apply. Translation against a stale Dexie snapshot
+(client-side) is replaced by atomic resolution against mongo's current
+state (server-side).
+
+### `undefined` value = delete the field (cry-db `$unset` convention)
+
+App code now signals "delete this field" by setting the value to
+`undefined` in `update`. End-to-end behavior:
+
+- `computeDiff` preserves `undefined` in the emitted diff (no longer
+  normalizes to `null`)
+- Dirty change in Dexie carries `undefined` (Dexie's structured clone
+  preserves it)
+- REST upload via `msgpackr` (`structuredClone: true`) preserves
+  `undefined` in the binary frame
+- Server cry-db `_processUpdateObject` routes `key: undefined` to
+  `$unset[key] = true`; mongo physically removes the field
+- Local in-mem and Dexie: `applyDiffLocally` detects `undefined`
+  values in the diff and uses `deleteByPath` (mongo-symmetric)
+
+Caller convention: read with strict `racun.field === undefined` is
+now safe (the field is genuinely absent, not stored as `null`).
+
+```typescript
+// remove `navodilo` from the racun
+await syncedDb.save("racuni", id, { navodilo: undefined });
+```
+
+### Diff-aware local apply (`applyDiffLocally`)
+
+`SyncedDb.save()` no longer uses shallow `{ ...currentMem, ...update }`
+spread that would replace top-level array/object fields wholesale and
+drop nested fields the caller's `update` didn't mention.
+
+Replaced with `applyDiffLocally(base, diff, id)`:
+1. Deep-clone `base` (currentMem ?? existing) via `safeDeepClone`
+   (handles Date and `ObjectId`-like values; avoids `structuredClone`
+   throwing on bson class instances)
+2. For each `(path, value)` in `diff`: `setByPath` if value is
+   defined, `deleteByPath` if value is `undefined`
+3. Result matches what server-side `$set` + `$unset` would produce
+
+`deleteByPath` is now a sibling export of `setByPath` in `computeDiff.ts`.
+
+## 0.1.161
+
+### Don't auto-stamp `_id` on bracket-array elements
+
+Reverted automatic `_id` stamping for objects appearing as array elements.
+If an array of objects lacks `_id`, the caller's element shape is now
+preserved. This allows callers to mix:
+- Whole-element bracket replace: `update.postavke = [{...}]`
+- Bracket-by-_id sub-field path: `update["postavke[<id>].field"] = value`
+in the same payload without the client mutating element identity.
+
+## 0.1.160
+
+### Composition changes emit precise paths (not full-array replace)
+
+`computeArrayDiff` strategy matrix is expanded:
+
+| Composition | Strategy |
+|---|---|
+| Empty → empty | no diff |
+| Same `_id` set, same order | element-wise: `arr[<id>].field` |
+| Same `_id` set, different order | full replace `arr` |
+| Different `_id` set | mixed: `$pull` + `$push` + sub-field |
+
+For composition changes, `computeDiff` now emits:
+- **Removed `_id`**: `arr[<id>] = undefined` (server: `$pull`)
+- **Added `_id`**: `arr[<id>] = [element]` (server: `$concatArrays + $filter`)
+- **Retained `_id`**: element-wise sub-field via `arr[<id>].field`
+
+Pre-fix, composition change emitted full-array replace at `basePath`,
+which `mergeDirtyPath` Case 2 then dropped pending sub-field paths on
+the same parent — race-y data-loss strip pattern visible in production.
+
+## 0.1.159
+
+### Self-echo WS suppression for `_rev <= local._rev`
+
+`ServerUpdateHandler` now ignores its own WS notifications when
+`_lastUpdaterId === self.updaterId AND _rev <= local._rev`. Three sub-cases:
+
+| `_rev` relation | Action |
+|---|---|
+| `=== local._rev + 1` | Bump meta to match server, clear dirty (existing loopback case) |
+| `=== local._rev` | WS arrived AFTER post-upload writeback. Local is already at server's rev — drop the WS payload entirely. |
+| `< local._rev` | Stale duplicate / out-of-order delivery. Never downgrade local. |
+
+In B and C, `mergeLocalWithDelta` and `writeToInMemBatch` are skipped
+entirely. Production data-loss case (2026-05-09): page re-mount loaded
+older snapshot because a self-echo WS arrived after writeback and
+overwrote in-mem with the server's `$set`-iterated copy of postavke
+(missing freshly-set `pop` and `navodilo` fields). Now in-mem is preserved.
+
+## 0.1.158
+
+Internal version bump consolidating 0.1.157 fixes for production publish.
+
+## 0.1.157
+
+### Recursive server-managed metadata strip at upload boundary
+
+`stripServerManagedFromChanges(changes)` walks dirty payload paths AND
+values, removing every `_ts` / `_rev` / `_csq` at every depth (including
+inside nested arrays and objects). Replaces SyncEngine's prefix-only
+filter (`startsWith('_ts.')`) which missed deep paths like
+`_redundanca.terapije[<id>]._rev` and silent-rejected uploads on the
+server.
+
+### `fixDotnetArrays` recognizes bracket-by-_id paths and nested top-level array keys
+
+When a top-level full array key (e.g. `zaracunaj` or
+`_redundanca.terapije`) coexists with element paths (`arr[<id>].field`
+or `arr.0.field`), the element paths are dropped to prevent mongo
+"path conflict" rejection (`Updating the path 'X' would create a
+conflict at 'Y'`). Now also catches dot-key array names like
+`_redundanca.terapije` and bracket-by-_id paths.
+
+### Auto-stamp `_id` on every plain object inside arrays (`SyncedDb.ensureNestedIds`)
+
+Write operations (save / upsert / insert) recursively walk the data
+tree and stamp `_id = new ObjectId().toHexString()` on every plain
+object that appears as an array element but lacks one. This keeps
+every save on the element-wise bracket-by-_id path
+(`computeDiff`'s `allElementsHaveId` check).
+
+(Note: 0.1.161 reverted this — see entry above.)
+
+### Production stuck-dirty regression test
+
+`test/stuckDirtyDirectInject.test.ts` injects an exact production
+stuck-dirty payload (mixing top-level full arrays with bracket paths)
+into Dexie's `_dirty_changes` and asserts upload succeeds without
+mongo path-conflict errors via a `MongoFaithfulRestInterface` mock.
+
 ## 0.1.156
 
 Three related fixes targeting **dirty-payload metadata leak** and

package/dist/index.js

@@ -3218,6 +3218,7 @@ var _SyncEngine = class _SyncEngine {
     }
     this.callOnServerWriteRequest(collectionBatches, calledFrom);
     const writeStartTime = Date.now();
+    const writeStartedAt = /* @__PURE__ */ new Date();
     let results;
     try {
       results = await this.deps.withSyncTimeout(
@@ -3225,8 +3226,24 @@ var _SyncEngine = class _SyncEngine {
         "updateCollections"
       );
       this.callOnServerWriteResult(results, writeStartTime, true, calledFrom);
+      this.callOnServerSyncWrite(
+        collectionBatches,
+        results,
+        void 0,
+        writeStartTime,
+        writeStartedAt,
+        calledFrom
+      );
     } catch (err) {
       this.callOnServerWriteResult([], writeStartTime, false, calledFrom, err);
+      this.callOnServerSyncWrite(
+        collectionBatches,
+        void 0,
+        err,
+        writeStartTime,
+        writeStartedAt,
+        calledFrom
+      );
       throw err;
     }
     let sentCount = 0;
@@ -3628,6 +3645,26 @@ var _SyncEngine = class _SyncEngine {
       }
     }
   }
+  callOnServerSyncWrite(request, response, error, startTime, timestamp, calledFrom) {
+    if (!this.callbacks.onServerSyncWrite) return;
+    try {
+      const errInfo = error ? {
+        message: error instanceof Error ? error.message : String(error),
+        name: error instanceof Error ? error.name : void 0,
+        stack: error instanceof Error ? error.stack : void 0
+      } : void 0;
+      this.callbacks.onServerSyncWrite({
+        request,
+        response,
+        error: errInfo,
+        durationMs: Date.now() - startTime,
+        calledFrom,
+        timestamp
+      });
+    } catch (err) {
+      console.error("onServerSyncWrite callback failed:", err);
+    }
+  }
 };
 // ============================================================
 // Private: Process Incoming Data
@@ -4248,6 +4285,7 @@ var _SyncedDb = class _SyncedDb {
         onConflictResolved: config.onConflictResolved,
         onServerWriteRequest: config.onServerWriteRequest,
         onServerWriteResult: config.onServerWriteResult,
+        onServerSyncWrite: config.onServerSyncWrite,
         onFindNewerManyCall: config.onFindNewerManyCall,
         onFindNewerManyResult: config.onFindNewerManyResult,
         onUploadSkip: config.onUploadSkip
@@ -4883,7 +4921,6 @@ var _SyncedDb = class _SyncedDb {
       });
       delete update._id;
     }
-    _SyncedDb.ensureNestedIds(update);
     update = _SyncedDb.stringifyObjectIds(update);
     const existing = await this.dexieDb.getById(collection, id);
     if (!existing && !((_a = this.collections.get(collection)) == null ? void 0 : _a.writeOnly)) {
@@ -4899,10 +4936,6 @@ var _SyncedDb = class _SyncedDb {
       diff,
       { _ts: existing == null ? void 0 : existing._ts, _rev: existing == null ? void 0 : existing._rev }
     );
-    const newData = __spreadProps(__spreadValues({}, update), {
-      _lastUpdaterId: this.updaterId
-    });
-    this.pendingChanges.schedule(collection, id, newData, 0, "save");
     const isWriteOnly = (_b = this.collections.get(collection)) == null ? void 0 : _b.writeOnly;
     const currentMem = isWriteOnly ? null : this.inMemDb.getById(collection, id);
     const merged = _SyncedDb.applyDiffLocally(
@@ -4910,6 +4943,7 @@ var _SyncedDb = class _SyncedDb {
       diff,
       id
     );
+    this.pendingChanges.schedule(collection, id, merged, 0, "save");
     if (!isWriteOnly && !(existing == null ? void 0 : existing._deleted) && !(existing == null ? void 0 : existing._archived)) {
       this.inMemManager.writeBatch(collection, [merged], "upsert", { source: "incremental" });
     }
@@ -4918,7 +4952,6 @@ var _SyncedDb = class _SyncedDb {
   async upsert(collection, query, update) {
     this.assertCollection(collection);
     this.ensureId(update, "upsert", collection);
-    _SyncedDb.ensureNestedIds(update);
     query = _SyncedDb.stringifyObjectIds(query);
     update = _SyncedDb.stringifyObjectIds(update);
     const existing = await this.findOne(collection, query);
@@ -4932,7 +4965,6 @@ var _SyncedDb = class _SyncedDb {
     var _a;
     this.assertCollection(collection);
     this.ensureId(data, "insert", collection);
-    _SyncedDb.ensureNestedIds(data);
     data = _SyncedDb.stringifyObjectIds(data);
     const unsetPaths = collectUnsetPaths(data);
     const id = String(data._id);
@@ -6094,48 +6126,6 @@ var _SyncedDb = class _SyncedDb {
     }
     return out;
   }
-  /**
-   * Recursively walk `value` and ensure every plain object that appears
-   * as an element of an array carries an `_id`. Missing `_id`s are
-   * generated as `new ObjectId().toHexString()` (string, not BSON instance).
-   *
-   * Mutates the input tree in place — caller sees the freshly-assigned ids
-   * (matches the pattern of `ensureId`).
-   *
-   * Why: `computeDiff` falls back to a full-array replace whenever any
-   * element of an array of objects lacks `_id` (see `allElementsHaveId`).
-   * That defeats element-wise `arr[<_id>].field` paths and re-introduces
-   * the stale-array-overwrite bug. Stamping ids upfront keeps every save
-   * on the per-element bracket path.
-   *
-   * Skipped:
-   *   - primitives (numbers, strings, booleans, null, undefined)
-   *   - `Date`, `ObjectId`-like values
-   *   - top-level objects (only ARRAY ELEMENTS get an auto-id; the entity
-   *     itself is handled by `ensureId`)
-   */
-  static ensureNestedIds(value) {
-    if (value === null || value === void 0) return;
-    if (typeof value !== "object") return;
-    if (value instanceof Date) return;
-    if (_SyncedDb.isObjectIdLike(value)) return;
-    if (Array.isArray(value)) {
-      for (const element of value) {
-        if (element !== null && typeof element === "object" && !Array.isArray(element) && !(element instanceof Date) && !_SyncedDb.isObjectIdLike(element)) {
-          if (element._id == null || element._id === "") {
-            element._id = new ObjectId2().toHexString();
-          } else if (_SyncedDb.isObjectIdLike(element._id)) {
-            element._id = String(element._id);
-          }
-        }
-        _SyncedDb.ensureNestedIds(element);
-      }
-      return;
-    }
-    for (const key of Object.keys(value)) {
-      _SyncedDb.ensureNestedIds(value[key]);
-    }
-  }
   /**
    * Asserts write-only collection has online connectivity for reads.
    * @throws Error if offline

package/dist/src/db/SyncedDb.d.ts

@@ -427,27 +427,6 @@ export declare class SyncedDb implements I_SyncedDb {
      * instances like bson `ObjectId`.
      */
     private static safeDeepClone;
-    /**
-     * Recursively walk `value` and ensure every plain object that appears
-     * as an element of an array carries an `_id`. Missing `_id`s are
-     * generated as `new ObjectId().toHexString()` (string, not BSON instance).
-     *
-     * Mutates the input tree in place — caller sees the freshly-assigned ids
-     * (matches the pattern of `ensureId`).
-     *
-     * Why: `computeDiff` falls back to a full-array replace whenever any
-     * element of an array of objects lacks `_id` (see `allElementsHaveId`).
-     * That defeats element-wise `arr[<_id>].field` paths and re-introduces
-     * the stale-array-overwrite bug. Stamping ids upfront keeps every save
-     * on the per-element bracket path.
-     *
-     * Skipped:
-     *   - primitives (numbers, strings, booleans, null, undefined)
-     *   - `Date`, `ObjectId`-like values
-     *   - top-level objects (only ARRAY ELEMENTS get an auto-id; the entity
-     *     itself is handled by `ensureId`)
-     */
-    private static ensureNestedIds;
     /**
      * Asserts write-only collection has online connectivity for reads.
      * @throws Error if offline

package/dist/src/db/sync/SyncEngine.d.ts

@@ -63,4 +63,5 @@ export declare class SyncEngine implements I_SyncEngine {
     private callOnFindNewerManyResult;
     private callOnServerWriteRequest;
     private callOnServerWriteResult;
+    private callOnServerSyncWrite;
 }

package/dist/src/db/types/managers.d.ts

@@ -7,7 +7,7 @@ import type { I_DexieDb, SyncMeta, MetaUpdateBroadcast } from "../../types/I_Dex
 import type { I_InMemDb, SyncSource } from "../../types/I_InMemDb";
 import type { I_RestInterface } from "../../types/I_RestInterface";
 import type { PublishDataPayload } from "../../types/PublishRevsPayload";
-import type { CollectionConfig, SyncInfo, ConflictResolutionReport, ServerWriteRequestInfo, ServerWriteResultInfo, FindNewerManyCallInfo, FindNewerManyResultInfo, DexieWriteRequestInfo, DexieWriteResultInfo, LocalstorageWriteResultInfo, WsNotificationInfo, CrossTabSyncInfo } from "../../types/I_SyncedDb";
+import type { CollectionConfig, SyncInfo, ConflictResolutionReport, ServerWriteRequestInfo, ServerWriteResultInfo, ServerSyncWriteInfo, FindNewerManyCallInfo, FindNewerManyResultInfo, DexieWriteRequestInfo, DexieWriteResultInfo, LocalstorageWriteResultInfo, WsNotificationInfo, CrossTabSyncInfo } from "../../types/I_SyncedDb";
 import type { PendingChange, UploadResult } from "./internal";
 export interface LeaderElectionCallbacks {
     onBecameLeader?: () => void;
@@ -259,6 +259,7 @@ export interface SyncEngineCallbacks {
     onConflictResolved?: (report: ConflictResolutionReport) => void;
     onServerWriteRequest?: (info: ServerWriteRequestInfo) => void;
     onServerWriteResult?: (info: ServerWriteResultInfo) => void;
+    onServerSyncWrite?: (info: ServerSyncWriteInfo) => void;
     onFindNewerManyCall?: (info: FindNewerManyCallInfo) => void;
     onFindNewerManyResult?: (info: FindNewerManyResultInfo) => void;
     onUploadSkip?: (info: import("../../types/I_SyncedDb").UploadSkipInfo) => void;

package/dist/src/types/I_SyncedDb.d.ts

@@ -117,6 +117,41 @@ export interface ServerWriteResultInfo {
     /** Where sync was called from (for debugging) */
     calledFrom?: string;
 }
+/**
+ * Callback payload for a single `updateCollections` round-trip — fires
+ * once per call with both the request and either the response OR the
+ * error description in a single payload.
+ *
+ * Convenience over `onServerWriteRequest` + `onServerWriteResult`: lets
+ * consumers route the entire request/response pair (or a thrown error)
+ * to syslog / observability with a single hook, without correlating
+ * across the two events.
+ */
+export interface ServerSyncWriteInfo {
+    /** Batches sent to the server (the request payload). */
+    request: CollectionUpdateRequest<any>[];
+    /**
+     * Per-collection results from the server — present when the call
+     * succeeded (no transport / timeout / network error). Individual
+     * items inside the result may still report per-record `errors`.
+     */
+    response?: CollectionUpdateResult[];
+    /**
+     * Populated when `restInterface.updateCollections` threw or timed
+     * out. `response` is `undefined` in that case.
+     */
+    error?: {
+        message: string;
+        name?: string;
+        stack?: string;
+    };
+    /** Round-trip duration in ms. */
+    durationMs: number;
+    /** Where sync was called from (for debugging). */
+    calledFrom?: string;
+    /** Wall-clock time when the round-trip started. */
+    timestamp: Date;
+}
 /**
  * Callback payload for findNewerMany calls
  */
@@ -459,6 +494,14 @@ export interface SyncedDbConfig {
     onServerWriteRequest?: (info: ServerWriteRequestInfo) => void;
     /** Callback after receiving result from server (updateCollections) */
     onServerWriteResult?: (info: ServerWriteResultInfo) => void;
+    /**
+     * Single-shot callback for each `updateCollections` round-trip — fires
+     * once with both the request payload AND either the server response or
+     * the thrown error (`error.message`/`name`/`stack`). Convenient when a
+     * consumer wants to log the full request/response pair (e.g. to syslog)
+     * without correlating across `onServerWriteRequest` + `onServerWriteResult`.
+     */
+    onServerSyncWrite?: (info: ServerSyncWriteInfo) => void;
     /** Callback when findNewerMany is called */
     onFindNewerManyCall?: (info: FindNewerManyCallInfo) => void;
     /** Callback when findNewerMany completes */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cry-synced-db-client",
-  "version": "0.1.162",
+  "version": "0.1.164",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",