cry-synced-db-client 0.1.171 → 0.1.173

package/CHANGELOG.md

@@ -2,6 +2,80 @@
 
 ## Unreleased
 
+### `preprocessDirtyItem` callback — per-item filter / transform before upload
+
+New optional config callback fired for **every** dirty item just before it
+becomes part of an `updateCollections` batch. Runs after `_ts`/`_rev` strip
+and legacy-path fixup, so `item.update` already reflects the wire-shape
+that would normally be uploaded.
+
+Return values:
+
+| Return | Result |
+|---|---|
+| same or modified `{_id, update}` | uploaded for this cycle |
+| `undefined` | SKIP upload this cycle — dirty record **left untouched** |
+| throw | SKIP upload + `console.error` — dirty record **left untouched** |
+
+Both skip paths leave the underlying dirty change as-is so the next sync
+cycle re-runs preprocessing. Use the regular `save`/`insert` API to
+overwrite locally or `hardDeleteOne` to permanently remove.
+
+```typescript
+new SyncedDb({
+  // ...
+  preprocessDirtyItem: (item, collection) => {
+    // e.g. skip uploads during a specific business window
+    if (collection === "logs" && now() < businessStart) return undefined;
+
+    // or transform: strip a field that another tab will recompute
+    const { ephemeral, ...rest } = item.update as any;
+    return { _id: item._id, update: rest };
+  },
+});
+```
+
+Useful for: per-tenant data sanitization, conditional upload gating,
+audit-trail injection.
+
+### Nested-bracket terminal layering in `mergeDirtyPath` Case 2
+
+When a new terminal-bracket whole-element write arrives AFTER pending
+sub-field edits on the same element (e.g. existing `postavke[p1].kolicina
+= 99`, new `postavke[p1] = [{_id:p1, opis:"fresh"}]`), the pending
+sub-field values are now LAYERED into the new element value before the
+descendant entries are dropped — producing one canonical
+`postavke[p1] = [{_id:p1, opis:"fresh", kolicina:99}]` entry rather than
+silently losing the prior sub-field write.
+
+Applies only to terminal-bracket new paths whose value is element-shaped
+(`[<el>]` insert wire form or plain object). Plain non-bracket ancestors
+(`koraki = [...]` whole-array replace) and REMOVE markers (`undefined`)
+keep the original "drop descendants" behavior.
+
+Pairs with cry-db Unreleased's nested-bracket pipeline support — works
+both with and without the lift (`containsIdArrayDescendant`) in
+`computeArrayDiff`.
+
+### Module-prefixed console logs
+
+All `console.error` / `warn` / `log` / `info` / `debug` calls in
+`src/db/**`, `src/utils/**`, and `src/types/**` are now tagged with a
+module-scoped prefix (`[SyncedDb]`, `[SyncEngine]`, `[LeaderElection]`,
+`[PendingChanges]`, `[Connection]`, `[CrossTabSync]`, `[InMem]`,
+`[NetworkStatus]`, `[WakeSync]`, `[Ebus2ProxyNotifier]`, `[DexieDb]`,
+`[CrashRecovery]`). Consumer log aggregators can now filter or
+namespace-route library output by prefix.
+
+### `DB-WARNING` tag for cry-db per-item warnings + `SUPRESS_DB_WARNINGS` kill-switch
+
+Per-item `warnings` returned by `updateCollections` are now surfaced on
+`console.error` with a `DB-WARNING [<collection>] _id=…:` prefix
+(previously `console.warn` with a generic message), so they show up
+alongside actual upload errors in observability pipelines.
+`SUPRESS_DB_WARNINGS` constant in `SyncEngine.ts` silences them when
+needed (e.g. during noisy migrations).
+
 ### Runtime collection registration (`addCollectionToSync`, `replaceSyncCollection`)
 
 Two methods to install / replace collection configs at runtime; both load the

package/dist/index.js

@@ -600,6 +600,17 @@ function canExpandArrayToBrackets(value) {
   }
   return true;
 }
+function pickLayerTarget(newPath, newValue) {
+  if (!isTerminalBracketKey(newPath)) return null;
+  if (newValue === void 0) return null;
+  if (Array.isArray(newValue) && newValue.length === 1 && newValue[0] && typeof newValue[0] === "object") {
+    return newValue[0];
+  }
+  if (newValue && typeof newValue === "object" && !Array.isArray(newValue)) {
+    return newValue;
+  }
+  return null;
+}
 function mergeDirtyPath(accumulated, newPath, newValue) {
   for (const existingKey of Object.keys(accumulated)) {
     if (existingKey === newPath) continue;
@@ -628,14 +639,27 @@ function mergeDirtyPath(accumulated, newPath, newValue) {
       break;
     }
   }
-  const toDelete = [];
+  const descendants = [];
   for (const existingKey of Object.keys(accumulated)) {
     if (existingKey === newPath) continue;
     if (isDescendantOrEqual(existingKey, newPath)) {
-      toDelete.push(existingKey);
+      descendants.push(existingKey);
+    }
+  }
+  const layerInto = pickLayerTarget(newPath, newValue);
+  if (layerInto && descendants.length > 0) {
+    for (const desc of descendants) {
+      const sepChar = desc[newPath.length];
+      const relativePath = sepChar === "[" ? desc.substring(newPath.length) : desc.substring(newPath.length + 1);
+      const descValue = accumulated[desc];
+      if (descValue === void 0) {
+        deleteByPath(layerInto, relativePath);
+      } else {
+        setByPath(layerInto, relativePath, descValue);
+      }
     }
   }
-  for (const k of toDelete) delete accumulated[k];
+  for (const k of descendants) delete accumulated[k];
   accumulated[newPath] = newValue;
 }
 function mergeDirtyChanges(accumulated, newChanges) {
@@ -722,14 +746,14 @@ var InMemManager = class {
           try {
             metadatas = config.onObjectsUpdated(items);
           } catch (err) {
-            console.error("onObjectsUpdated callback failed:", err);
+            console.error("[InMem] onObjectsUpdated callback failed:", err);
             return;
           }
         } else if (config.onObjectUpdated) {
           try {
             metadatas = items.map((item) => config.onObjectUpdated(item));
           } catch (err) {
-            console.error("onObjectUpdated callback failed:", err);
+            console.error("[InMem] onObjectUpdated callback failed:", err);
             return;
           }
         } else {
@@ -762,14 +786,14 @@ var InMemManager = class {
           try {
             metadatas = config.onObjectsUpdated(items);
           } catch (err) {
-            console.error("onObjectsUpdated callback failed:", err);
+            console.error("[InMem] onObjectsUpdated callback failed:", err);
             return;
           }
         } else if (config.onObjectUpdated) {
           try {
             metadatas = items.map((item) => config.onObjectUpdated(item));
           } catch (err) {
-            console.error("onObjectUpdated callback failed:", err);
+            console.error("[InMem] onObjectUpdated callback failed:", err);
             return;
           }
         } else {
@@ -1035,7 +1059,7 @@ var LeaderElectionManager = class {
       try {
         this.leaderReelectionChannel.postMessage({ type: "reelect-leader" });
       } catch (err) {
-        console.error("Failed to broadcast leader reelection:", err);
+        console.error("[LeaderElection] Failed to broadcast leader reelection:", err);
       }
     }
   }
@@ -1046,7 +1070,7 @@ var LeaderElectionManager = class {
       try {
         this.callbacks.onBecameLeader();
       } catch (err) {
-        console.error("onBecameLeader callback failed:", err);
+        console.error("[LeaderElection] onBecameLeader callback failed:", err);
       }
     }
   }
@@ -1057,7 +1081,7 @@ var LeaderElectionManager = class {
       try {
         this.callbacks.onLostLeadership();
       } catch (err) {
-        console.error("onLostLeadership callback failed:", err);
+        console.error("[LeaderElection] onLostLeadership callback failed:", err);
       }
     }
   }
@@ -1066,7 +1090,7 @@ var LeaderElectionManager = class {
       try {
         this.callbacks.onInfrastructureError(type, message, error);
       } catch (err) {
-        console.error("onInfrastructureError callback failed:", err);
+        console.error("[LeaderElection] onInfrastructureError callback failed:", err);
       }
     }
   }
@@ -1191,7 +1215,7 @@ var CrossTabSyncManager = class {
       try {
         this.metaUpdateChannel.postMessage(payload);
       } catch (err) {
-        console.error("Failed to broadcast meta update:", err);
+        console.error("[CrossTabSync] Failed to broadcast meta update:", err);
       }
     }
     this.pendingBroadcasts.clear();
@@ -1237,7 +1261,7 @@ var CrossTabSyncManager = class {
       try {
         await this.deps.reloadCollectionFromDexie(collection);
       } catch (err) {
-        console.error(`Error reloading collection ${collection} from Dexie:`, err);
+        console.error(`[CrossTabSync] Error reloading collection ${collection} from Dexie:`, err);
       }
     }
   }
@@ -1285,11 +1309,11 @@ var CrossTabSyncManager = class {
             };
             this.callbacks.onCrossTabSync(info);
           } catch (err) {
-            console.error("onCrossTabSync callback failed:", err);
+            console.error("[CrossTabSync] onCrossTabSync callback failed:", err);
           }
         }
       } catch (err) {
-        console.error(`Error handling cross-tab delta update for ${collection}:`, err);
+        console.error(`[CrossTabSync] Error handling cross-tab delta update for ${collection}:`, err);
       }
     }
   }
@@ -1305,7 +1329,7 @@ var CrossTabSyncManager = class {
     try {
       this.metaUpdateChannel.postMessage(payload);
     } catch (err) {
-      console.error("Failed to broadcast reload:", err);
+      console.error("[CrossTabSync] Failed to broadcast reload:", err);
     }
   }
   callOnInfrastructureError(type, message, error) {
@@ -1313,7 +1337,7 @@ var CrossTabSyncManager = class {
       try {
         this.callbacks.onInfrastructureError(type, message, error);
       } catch (err) {
-        console.error("onInfrastructureError callback failed:", err);
+        console.error("[CrossTabSync] onInfrastructureError callback failed:", err);
       }
     }
   }
@@ -1379,7 +1403,7 @@ var ConnectionManager = class {
     } else {
       this.deps.tryBecomeLeader();
       this.tryGoOnline().catch((err) => {
-        console.error("Failed to go online after forceOffline release:", err);
+        console.error("[Connection] Failed to go online after forceOffline release:", err);
       });
     }
   }
@@ -1403,13 +1427,13 @@ var ConnectionManager = class {
             "ping"
           );
         } catch (err) {
-          console.warn("tryGoOnline: ping failed:", err);
+          console.warn("[Connection] tryGoOnline: ping failed:", err);
           this.online = false;
           return;
         }
         if (!pingResult) {
           const url = (_a = this.restInterface.endpoint) != null ? _a : "unknown";
-          console.warn(`Ping to ${url} failed - staying offline`);
+          console.warn(`[Connection] Ping to ${url} failed - staying offline`);
           return;
         }
         this.online = true;
@@ -1421,7 +1445,7 @@ var ConnectionManager = class {
       try {
         await this.deps.sync("INITIAL SYNC");
       } catch (err) {
-        console.warn("INITIAL SYNC after tryGoOnline failed (stays online):", err);
+        console.warn("[Connection] INITIAL SYNC after tryGoOnline failed (stays online):", err);
       }
     } finally {
       this.tryGoOnlineInFlight = false;
@@ -1437,7 +1461,7 @@ var ConnectionManager = class {
       this.autoSyncTimer = setInterval(() => {
         if (this.forcedOffline || !this.online) return;
         this.deps.sync(`interval ${intervalMs}ms`).catch((err) => {
-          console.error("Auto-sync failed:", err);
+          console.error("[Connection] Auto-sync failed:", err);
         });
       }, intervalMs);
     }
@@ -1446,7 +1470,7 @@ var ConnectionManager = class {
       this.reconnectTimer = setInterval(() => {
         if (this.forcedOffline || this.online || this.tryGoOnlineInFlight) return;
         this.tryGoOnline().catch((err) => {
-          console.error("Reconnect tryGoOnline failed:", err);
+          console.error("[Connection] Reconnect tryGoOnline failed:", err);
         });
       }, retryMs);
     }
@@ -1530,7 +1554,7 @@ var ConnectionManager = class {
       try {
         this.callbacks.onInfrastructureError(type, message, error);
       } catch (err) {
-        console.error("onInfrastructureError callback failed:", err);
+        console.error("[Connection] onInfrastructureError callback failed:", err);
       }
     }
   }
@@ -1543,7 +1567,7 @@ var ConnectionManager = class {
       try {
         this.callbacks.onSyncFailed(reason);
       } catch (err) {
-        console.error("onSyncFailed callback failed:", err);
+        console.error("[Connection] onSyncFailed callback failed:", err);
       }
     }
   }
@@ -1555,7 +1579,7 @@ var ConnectionManager = class {
       try {
         this.callbacks.onWsConnect();
       } catch (err) {
-        console.error("onWsConnect callback failed:", err);
+        console.error("[Connection] onWsConnect callback failed:", err);
       }
     }
   }
@@ -1567,7 +1591,7 @@ var ConnectionManager = class {
       try {
         this.callbacks.onWsDisconnect(reason);
       } catch (err) {
-        console.error("onWsDisconnect callback failed:", err);
+        console.error("[Connection] onWsDisconnect callback failed:", err);
       }
     }
     this.reportInfrastructureError(
@@ -1583,7 +1607,7 @@ var ConnectionManager = class {
       try {
         this.callbacks.onWsReconnect(attempt);
       } catch (err) {
-        console.error("onWsReconnect callback failed:", err);
+        console.error("[Connection] onWsReconnect callback failed:", err);
       }
     }
   }
@@ -2450,7 +2474,7 @@ function savePendingWrite(tenant, collection, id, delta) {
     }
     localStorage.setItem(key, dist_default.stringify(pending));
   } catch (e) {
-    console.warn("Failed to save pending write to localStorage");
+    console.warn("[CrashRecovery] Failed to save pending write to localStorage");
   }
 }
 function clearPendingWrite(tenant, collection, id) {
@@ -2632,7 +2656,7 @@ var PendingChangesManager = class {
           clearPendingWrite(this.tenant, write.collection, write.id);
         }
       } catch (err) {
-        console.error(`Failed to recover pending writes for ${collection}:`, err);
+        console.error(`[PendingChanges] Failed to recover pending writes for ${collection}:`, err);
       }
     }
   }
@@ -2682,7 +2706,7 @@ var PendingChangesManager = class {
             calledFrom: pending.calledFrom
           });
         } catch (err) {
-          console.error("onDexieWriteRequest callback failed:", err);
+          console.error("[PendingChanges] onDexieWriteRequest callback failed:", err);
         }
       }
       if (existing) {
@@ -2697,7 +2721,7 @@ var PendingChangesManager = class {
           // ensure _id is after spread
         });
         if (typeof insertData._id === "object") {
-          console.error(`Dexie: _id is object type in ${pending.collection}:`, typeof insertData._id, insertData._id);
+          console.error(`[PendingChanges] Dexie: _id is object type in ${pending.collection}:`, typeof insertData._id, insertData._id);
         }
         await this.deps.dexieDb.insert(pending.collection, insertData);
       }
@@ -2711,7 +2735,7 @@ var PendingChangesManager = class {
             calledFrom: pending.calledFrom
           });
         } catch (err) {
-          console.error("onDexieWriteResult callback failed:", err);
+          console.error("[PendingChanges] onDexieWriteResult callback failed:", err);
         }
       }
       clearPendingWrite(this.tenant, pending.collection, pending.id);
@@ -2725,12 +2749,12 @@ var PendingChangesManager = class {
             calledFrom: pending.calledFrom
           });
         } catch (err) {
-          console.error("onLocalstorageWriteResult callback failed:", err);
+          console.error("[PendingChanges] onLocalstorageWriteResult callback failed:", err);
         }
       }
       this.scheduleRestUpload();
     } catch (err) {
-      console.error("Failed to write to Dexie:", err);
+      console.error("[PendingChanges] Failed to write to Dexie:", err);
       if (this.callbacks.onDexieWriteResult) {
         try {
           this.callbacks.onDexieWriteResult({
@@ -2742,13 +2766,13 @@ var PendingChangesManager = class {
             calledFrom: pending.calledFrom
           });
         } catch (callbackErr) {
-          console.error("onDexieWriteResult callback failed:", callbackErr);
+          console.error("[PendingChanges] onDexieWriteResult callback failed:", callbackErr);
         }
       }
       const newRetryCount = pending.retryCount + 1;
       if (newRetryCount >= MAX_RETRY_COUNT) {
         console.error(
-          `Max retry count (${MAX_RETRY_COUNT}) reached for pending change ${key}. Data remains in localStorage for crash recovery.`
+          `[PendingChanges] Max retry count (${MAX_RETRY_COUNT}) reached for pending change ${key}. Data remains in localStorage for crash recovery.`
         );
         return;
       }
@@ -2784,7 +2808,7 @@ var PendingChangesManager = class {
     try {
       await this.deps.uploadDirtyItems();
     } catch (err) {
-      console.error("REST upload failed:", err);
+      console.error("[PendingChanges] REST upload failed:", err);
     } finally {
       this.isUploadingToRest = false;
       resolveUpload();
@@ -2861,10 +2885,6 @@ function mergeObjectArrays(local, external, parentServerWins = false) {
   }
   if (objectItemsMissingId.length > 0) {
     for (const item of objectItemsMissingId) {
-      console.error(
-        "[mergeObjectArrays] array element without _id \u2014 falling back to whole-array replace by higher _rev:",
-        item
-      );
     }
     return parentServerWins ? external.slice() : local.slice();
   }
@@ -2992,6 +3012,7 @@ function stripServerManagedFromChanges(changes) {
 }
 
 // src/db/sync/SyncEngine.ts
+var SUPRESS_DB_WARNINGS = true;
 var _SyncEngine = class _SyncEngine {
   constructor(config) {
     this.tenant = config.tenant;
@@ -3001,6 +3022,7 @@ var _SyncEngine = class _SyncEngine {
     this.restInterface = config.restInterface;
     this.callbacks = config.callbacks;
     this.deps = config.deps;
+    this.preprocessDirtyItem = config.preprocessDirtyItem;
   }
   /**
    * Execute full sync cycle.
@@ -3139,7 +3161,7 @@ var _SyncEngine = class _SyncEngine {
         }
       } catch (err) {
         console.error(
-          "uploadDirtyItems failed (download succeeded, staying online):",
+          "[SyncEngine] uploadDirtyItems failed (download succeeded, staying online):",
           err
         );
       }
@@ -3165,7 +3187,7 @@ var _SyncEngine = class _SyncEngine {
       });
     } catch (err) {
       const reason = err instanceof Error ? err.message : String(err);
-      console.error("Sync failed:", err);
+      console.error("[SyncEngine] Sync failed:", err);
       this.deps.onSyncFailed(`Sync failed: ${reason}`);
       this.callOnSyncEnd({
         durationMs: Date.now() - startTime,
@@ -3223,7 +3245,7 @@ var _SyncEngine = class _SyncEngine {
       }
       if (updates.length === 0) {
         console.warn(
-          `uploadDirtyItems: ${collectionName} has ${dirtyChanges.length} dirty entries but 0 resolvable items`,
+          `[SyncEngine] uploadDirtyItems: ${collectionName} has ${dirtyChanges.length} dirty entries but 0 resolvable items`,
           skipped
         );
         if (this.callbacks.onUploadSkip) {
@@ -3238,7 +3260,7 @@ var _SyncEngine = class _SyncEngine {
               timestamp: /* @__PURE__ */ new Date()
             });
           } catch (err) {
-            console.error("onUploadSkip callback failed:", err);
+            console.error("[SyncEngine] onUploadSkip callback failed:", err);
           }
         }
         continue;
@@ -3255,27 +3277,46 @@ var _SyncEngine = class _SyncEngine {
             timestamp: /* @__PURE__ */ new Date()
           });
         } catch (err) {
-          console.error("onUploadSkip callback failed:", err);
+          console.error("[SyncEngine] onUploadSkip callback failed:", err);
+        }
+      }
+      const mappedUpdates = [];
+      for (const item of updates) {
+        const dirtyBaseRev = typeof item.delta._rev === "number" ? item.delta._rev : void 0;
+        const stripped = stripServerManagedFromChanges(
+          item.delta
+        );
+        const fixed = fixDotnetArrays(
+          stripped,
+          item.currentServerRev,
+          dirtyBaseRev
+        );
+        let candidate = {
+          _id: item._id,
+          update: fixed
+        };
+        if (this.preprocessDirtyItem) {
+          try {
+            const processed = this.preprocessDirtyItem(candidate, collectionName);
+            if (processed === void 0) {
+              continue;
+            }
+            candidate = processed;
+          } catch (err) {
+            console.error(
+              `[SyncEngine] preprocessDirtyItem(${collectionName}) failed for _id=${String(item._id)}; keeping dirty for retry:`,
+              err
+            );
+            continue;
+          }
         }
+        mappedUpdates.push(candidate);
       }
+      if (mappedUpdates.length === 0) continue;
       collectionBatches.push([{
         collection: collectionName,
         batch: {
-          updates: updates.map((item) => {
-            const dirtyBaseRev = typeof item.delta._rev === "number" ? item.delta._rev : void 0;
-            const stripped = stripServerManagedFromChanges(
-              item.delta
-            );
-            const fixed = fixDotnetArrays(
-              stripped,
-              item.currentServerRev,
-              dirtyBaseRev
-            );
-            return {
-              _id: item._id,
-              update: fixed
-            };
-          }),
+          updates: mappedUpdates,
           deletes: []
         }
       }]);
@@ -3352,7 +3393,7 @@ var _SyncEngine = class _SyncEngine {
       }
       if (ambiguous.length > 0) {
         console.error(
-          `Sync upload [${collection}]: ${ambiguous.length} id(s) appeared in BOTH inserted/updated/deleted AND errors[] \u2014 keeping dirty for safety. _ids: ${ambiguous.join(", ")}`
+          `[SyncEngine] Sync upload [${collection}]: ${ambiguous.length} id(s) appeared in BOTH inserted/updated/deleted AND errors[] \u2014 keeping dirty for safety. _ids: ${ambiguous.join(", ")}`
         );
       }
       if (allSuccessIds.length > 0) {
@@ -3450,14 +3491,14 @@ var _SyncEngine = class _SyncEngine {
       if (errors2 && errors2.length > 0) {
         for (const e of errors2) {
           console.error(
-            `Sync upload error [${collection}] _id=${e._id}: ${e.error} \u2014 dirty entry will persist until retry`
+            `[SyncEngine] Sync upload error [${collection}] _id=${e._id}: ${e.error} \u2014 dirty entry will persist until retry`
           );
         }
       }
-      if (warnings && warnings.length > 0) {
+      if (warnings && warnings.length > 0 && !SUPRESS_DB_WARNINGS) {
         for (const w of warnings) {
-          console.warn(
-            `Sync upload warning [${collection}] _id=${w._id}: ${w.error}`
+          console.error(
+            `[SyncEngine] DB-WARNING [${collection}] _id=${w._id}: ${w.error}`
           );
         }
       }
@@ -3471,7 +3512,7 @@ var _SyncEngine = class _SyncEngine {
       const unacked = [...sentIds].filter((id) => !ackIds.has(id));
       if (unacked.length > 0) {
         console.warn(
-          `uploadDirtyItems: ${collection}: ${unacked.length} items sent but not acknowledged:`,
+          `[SyncEngine] uploadDirtyItems: ${collection}: ${unacked.length} items sent but not acknowledged:`,
           unacked
         );
       }
@@ -3527,14 +3568,14 @@ var _SyncEngine = class _SyncEngine {
         for (const e of errors2) {
           erroredIds.add(String(e._id));
           console.error(
-            `Sync upload error [${collection}] _id=${e._id}: ${e.error} \u2014 dirty entry will persist until retry`
+            `[SyncEngine] Sync upload error [${collection}] _id=${e._id}: ${e.error} \u2014 dirty entry will persist until retry`
           );
         }
       }
-      if (warnings && warnings.length > 0) {
+      if (warnings && warnings.length > 0 && !SUPRESS_DB_WARNINGS) {
         for (const w of warnings) {
-          console.warn(
-            `Sync upload warning [${collection}] _id=${w._id}: ${w.error}`
+          console.error(
+            `[SyncEngine] DB-WARNING [${collection}] _id=${w._id}: ${w.error}`
           );
         }
       }
@@ -3566,7 +3607,7 @@ var _SyncEngine = class _SyncEngine {
       }
       if (ambiguous.length > 0) {
         console.error(
-          `Sync upload [${collection}]: ${ambiguous.length} id(s) appeared in BOTH inserted/updated/deleted AND errors[] \u2014 keeping dirty for safety. _ids: ${ambiguous.join(", ")}`
+          `[SyncEngine] Sync upload [${collection}]: ${ambiguous.length} id(s) appeared in BOTH inserted/updated/deleted AND errors[] \u2014 keeping dirty for safety. _ids: ${ambiguous.join(", ")}`
         );
       }
       if (allSuccessIds.length > 0) {
@@ -3705,7 +3746,7 @@ var _SyncEngine = class _SyncEngine {
           timestamp: /* @__PURE__ */ new Date()
         });
       } catch (err) {
-        console.error("onConflictResolved callback failed:", err);
+        console.error("[SyncEngine] onConflictResolved callback failed:", err);
       }
     }
     return resolved;
@@ -3719,7 +3760,7 @@ var _SyncEngine = class _SyncEngine {
       try {
         fn(info);
       } catch (err) {
-        console.error("Callback failed:", err);
+        console.error("[SyncEngine] Callback failed:", err);
       }
     }
   }
@@ -3728,7 +3769,7 @@ var _SyncEngine = class _SyncEngine {
       try {
         this.callbacks.onSyncStart(info);
       } catch (err) {
-        console.error("onSyncStart callback failed:", err);
+        console.error("[SyncEngine] onSyncStart callback failed:", err);
       }
     }
   }
@@ -3737,7 +3778,7 @@ var _SyncEngine = class _SyncEngine {
       try {
         this.callbacks.onSyncEnd(info);
       } catch (err) {
-        console.error("onSyncEnd callback failed:", err);
+        console.error("[SyncEngine] onSyncEnd callback failed:", err);
       }
     }
   }
@@ -3750,7 +3791,7 @@ var _SyncEngine = class _SyncEngine {
           calledFrom
         });
       } catch (err) {
-        console.error("onFindNewerManyCall callback failed:", err);
+        console.error("[SyncEngine] onFindNewerManyCall callback failed:", err);
       }
     }
   }
@@ -3766,7 +3807,7 @@ var _SyncEngine = class _SyncEngine {
           calledFrom
         });
       } catch (err) {
-        console.error("onFindNewerManyResult callback failed:", err);
+        console.error("[SyncEngine] onFindNewerManyResult callback failed:", err);
       }
     }
   }
@@ -3779,7 +3820,7 @@ var _SyncEngine = class _SyncEngine {
           calledFrom
         });
       } catch (err) {
-        console.error("onServerWriteRequest callback failed:", err);
+        console.error("[SyncEngine] onServerWriteRequest callback failed:", err);
       }
     }
   }
@@ -3794,7 +3835,7 @@ var _SyncEngine = class _SyncEngine {
           calledFrom
         });
       } catch (err) {
-        console.error("onServerWriteResult callback failed:", err);
+        console.error("[SyncEngine] onServerWriteResult callback failed:", err);
       }
     }
   }
@@ -3815,7 +3856,7 @@ var _SyncEngine = class _SyncEngine {
         timestamp
       });
     } catch (err) {
-      console.error("onServerSyncWrite callback failed:", err);
+      console.error("[SyncEngine] onServerSyncWrite callback failed:", err);
     }
   }
 };
@@ -4080,7 +4121,7 @@ var ServerUpdateHandler = class {
           timestamp: /* @__PURE__ */ new Date()
         });
       } catch (err) {
-        console.error("onWsNotification callback failed:", err);
+        console.error("[ServerUpdateHandler] onWsNotification callback failed:", err);
       }
     }
   }
@@ -4162,11 +4203,11 @@ var WakeSyncManager = class {
             timestamp: /* @__PURE__ */ new Date()
           });
         } catch (err) {
-          console.error("onWakeSync callback failed:", err);
+          console.error("[WakeSync] onWakeSync callback failed:", err);
         }
       }
       this.deps.sync(`wake-sync:${trigger}`).catch((err) => {
-        console.error(`Wake sync (${trigger}) failed:`, err);
+        console.error(`[WakeSync] Wake sync (${trigger}) failed:`, err);
       });
     }, this.debounceMs);
   }
@@ -4235,7 +4276,7 @@ var NetworkStatusManager = class {
         try {
           this.callbacks.onBrowserNetworkChange(info);
         } catch (err) {
-          console.error("onBrowserNetworkChange callback failed:", err);
+          console.error("[NetworkStatus] onBrowserNetworkChange callback failed:", err);
         }
       }
       if (finalOnlineState) {
@@ -4243,7 +4284,7 @@ var NetworkStatusManager = class {
           try {
             this.callbacks.onBrowserOnline();
           } catch (err) {
-            console.error("onBrowserOnline callback failed:", err);
+            console.error("[NetworkStatus] onBrowserOnline callback failed:", err);
           }
         }
       } else {
@@ -4251,12 +4292,12 @@ var NetworkStatusManager = class {
           try {
             this.callbacks.onBrowserOffline();
           } catch (err) {
-            console.error("onBrowserOffline callback failed:", err);
+            console.error("[NetworkStatus] onBrowserOffline callback failed:", err);
           }
         }
       }
       this.deps.setOnline(finalOnlineState).catch((err) => {
-        console.error("Failed to set online status:", err);
+        console.error("[NetworkStatus] Failed to set online status:", err);
       });
     }, this.debounceMs);
   }
@@ -4321,14 +4362,14 @@ var _SyncedDb = class _SyncedDb {
         onBecameLeader: () => {
           if (this.initialized && !this.connectionManager.isOnline() && !this.connectionManager.isForcedOffline()) {
             this.connectionManager.tryGoOnline().catch((err) => {
-              console.error("tryGoOnline on becameLeader failed:", err);
+              console.error("[SyncedDb] tryGoOnline on becameLeader failed:", err);
             });
           }
           if (config.onBecameLeader) {
             try {
               config.onBecameLeader();
             } catch (err) {
-              console.error("onBecameLeader callback failed:", err);
+              console.error("[SyncedDb] onBecameLeader callback failed:", err);
             }
           }
         },
@@ -4429,6 +4470,7 @@ var _SyncedDb = class _SyncedDb {
       collections: this.collections,
       dexieDb: this.dexieDb,
       restInterface: this.restInterface,
+      preprocessDirtyItem: config.preprocessDirtyItem,
       callbacks: {
         onSyncStart: config.onSyncStart ? (info) => config.onSyncStart(__spreadProps(__spreadValues({}, info), { initialSync: !this._lastFullSyncDate })) : void 0,
         onSyncEnd: config.onSyncEnd,
@@ -4631,7 +4673,7 @@ var _SyncedDb = class _SyncedDb {
       try {
         this.onDatabaseCreated();
       } catch (err) {
-        console.error("onDatabaseCreated callback failed:", err);
+        console.error("[SyncedDb] onDatabaseCreated callback failed:", err);
       }
     }
     await this.pendingChanges.recoverPendingWrites();
@@ -4664,10 +4706,10 @@ var _SyncedDb = class _SyncedDb {
       try {
         await this.serverUpdateNotifier.connect();
         const ep = (_c = this.serverUpdateNotifier.endpoint) != null ? _c : "unknown";
-        console.log(`SyncedDb: ebus-proxy connected to ${ep}`);
+        console.log(`[SyncedDb] SyncedDb: ebus-proxy connected to ${ep}`);
       } catch (err) {
         const ep = (_d = this.serverUpdateNotifier.endpoint) != null ? _d : "unknown";
-        console.warn(`SyncedDb: ebus-proxy connection to ${ep} failed`);
+        console.warn(`[SyncedDb] SyncedDb: ebus-proxy connection to ${ep} failed`);
         this.connectionManager.reportInfrastructureError(
           "WEBSOCKET_CONNECTION_FAILED",
           `WebSocket connection to ${ep} failed during initialization`,
@@ -4679,7 +4721,7 @@ var _SyncedDb = class _SyncedDb {
       this.beforeUnloadHandler = () => {
         if (this.initialized && this.pendingChanges.hasPendingChanges()) {
           console.warn(
-            `SyncedDb: pending changes not flushed. Call close() before page unload.`
+            `[SyncedDb] SyncedDb: pending changes not flushed. Call close() before page unload.`
           );
         }
       };
@@ -4689,7 +4731,7 @@ var _SyncedDb = class _SyncedDb {
       this.visibilityFlushHandler = () => {
         if (document.visibilityState !== "hidden") return;
         this.flushToServer("visibility-hidden").catch((err) => {
-          console.warn("flushToServer on visibility-hidden failed:", err == null ? void 0 : err.message);
+          console.warn("[SyncedDb] flushToServer on visibility-hidden failed:", err == null ? void 0 : err.message);
         });
       };
       document.addEventListener("visibilitychange", this.visibilityFlushHandler);
@@ -4830,6 +4872,11 @@ var _SyncedDb = class _SyncedDb {
   async findById(collection, id, opts) {
     var _a;
     this.assertCollection(collection);
+    if (!id) {
+      const err = new Error(`[SyncedDb] findById ${collection} no id ${id}`);
+      console.error(err);
+      return null;
+    }
     id = this.normalizeId(id, "findById", collection);
     opts = this.resolveOpts(opts);
     if ((_a = this.collections.get(collection)) == null ? void 0 : _a.writeOnly) {
@@ -5062,7 +5109,7 @@ var _SyncedDb = class _SyncedDb {
         await this.syncEngine.processCollectionServerData(collection, serverData, { source: "refresh" });
       }
     }).catch((err) => {
-      console.error(`referToServer failed for ${collection}:`, err);
+      console.error(`[SyncedDb] referToServer failed for ${collection}:`, err);
     });
   }
   /**
@@ -5083,7 +5130,7 @@ var _SyncedDb = class _SyncedDb {
       if (!serverItems || serverItems.length === 0) return;
       await this.syncEngine.processCollectionServerData(collection, serverItems, { source: "incremental" });
     }).catch((err) => {
-      console.error(`refreshInBackground failed for ${collection}:`, err);
+      console.error(`[SyncedDb] refreshInBackground failed for ${collection}:`, err);
     });
   }
   async ensureItemsAreLoaded(collection, ids, withDeleted) {
@@ -5129,7 +5176,7 @@ var _SyncedDb = class _SyncedDb {
     id = this.normalizeId(id, "save", collection);
     if ("_id" in update && !update._id) {
       console.error(
-        `SyncedDb.save("${collection}", "${String(id)}"): update._id is present but falsy (${JSON.stringify(update._id)}). Stripped from update to prevent overwriting valid id. This is a bug \u2014 the caller should not pass falsy _id in update. Data keys: [${Object.keys(update).join(", ")}]`
+        `[SyncedDb] SyncedDb.save("${collection}", "${String(id)}"): update._id is present but falsy (${JSON.stringify(update._id)}). Stripped from update to prevent overwriting valid id. This is a bug \u2014 the caller should not pass falsy _id in update. Data keys: [${Object.keys(update).join(", ")}]`
       );
       delete update._id;
     }
@@ -5143,7 +5190,7 @@ var _SyncedDb = class _SyncedDb {
         }
       })();
       console.error(
-        `SyncedDb.save("${collection}", "${String(id)}"): update._id (${JSON.stringify(update._id)}) does NOT match id (${JSON.stringify(String(id))}). Stripped from update to prevent stuck-dirty bug. The caller likely passed a stale this._id while building update from a freshly-generated record. Data keys: [${updateKeys.join(", ")}]`
+        `[SyncedDb] SyncedDb.save("${collection}", "${String(id)}"): update._id (${JSON.stringify(update._id)}) does NOT match id (${JSON.stringify(String(id))}). Stripped from update to prevent stuck-dirty bug. The caller likely passed a stale this._id while building update from a freshly-generated record. Data keys: [${updateKeys.join(", ")}]`
       );
       this.safeCallback(this.onSaveIdMismatch, {
         collection,
@@ -5159,7 +5206,7 @@ var _SyncedDb = class _SyncedDb {
     const existing = await this.dexieDb.getById(collection, id);
     if (!existing && !((_a = this.collections.get(collection)) == null ? void 0 : _a.writeOnly)) {
       console.warn(
-        `SyncedDb.save: Object ${String(id)} not found in ${collection}, creating new`
+        `[SyncedDb] SyncedDb.save: Object ${String(id)} not found in ${collection}, creating new`
       );
     }
     const fullChanges = __spreadProps(__spreadValues({}, update), { _lastUpdaterId: this.updaterId });
@@ -5209,7 +5256,7 @@ var _SyncedDb = class _SyncedDb {
     const existing = await this.dexieDb.getById(collection, id);
     if (existing && !existing._deleted && !existing._archived) {
       console.warn(
-        `SyncedDb.insert: Object ${String(id)} already exists in ${collection}, overwriting`
+        `[SyncedDb] SyncedDb.insert: Object ${String(id)} already exists in ${collection}, overwriting`
       );
     }
     const insertChanges = __spreadProps(__spreadValues({}, data), { _lastUpdaterId: this.updaterId });
@@ -5348,7 +5395,7 @@ var _SyncedDb = class _SyncedDb {
             this.inMemManager.writeBatch(collection, [{ _id: item.id }], "delete", { source: "incremental" });
             results.push(true);
           } catch (err) {
-            console.error(`Failed to hard delete ${String(item.id)}:`, err);
+            console.error(`[SyncedDb] Failed to hard delete ${String(item.id)}:`, err);
             results.push(false);
           }
         }
@@ -5383,7 +5430,7 @@ var _SyncedDb = class _SyncedDb {
           evictionPlan = await this._collectScopeExitPlan("auto");
         } catch (err) {
           console.error(
-            "[evict] phase 1 failed (skipping bundled eviction):",
+            "[SyncedDb] [evict] phase 1 failed (skipping bundled eviction):",
             err
           );
         }
@@ -5400,11 +5447,11 @@ var _SyncedDb = class _SyncedDb {
           const now = /* @__PURE__ */ new Date();
           if (!this._lastFullSyncDate) {
             this._setLastInitialSync(now).catch((err) => {
-              console.error("Failed to persist lastInitialSync:", err);
+              console.error("[SyncedDb] Failed to persist lastInitialSync:", err);
             });
           }
           this._setLastFullSync(now).catch((err) => {
-            console.error("Failed to persist lastFullSync:", err);
+            console.error("[SyncedDb] Failed to persist lastFullSync:", err);
           });
         }
       } catch (err) {
@@ -5423,7 +5470,7 @@ var _SyncedDb = class _SyncedDb {
             );
             await this._persistEvictionTimestamp();
           } catch (err) {
-            console.error("[evict] phase 3 failed:", err);
+            console.error("[SyncedDb] [evict] phase 3 failed:", err);
           }
         }
       }
@@ -5730,7 +5777,7 @@ var _SyncedDb = class _SyncedDb {
         serverEvictedCount = serverExits.length;
       } catch (err) {
         console.error(
-          `[evict] server-assisted pass failed for ${collection} (proceeding with local-only):`,
+          `[SyncedDb] [evict] server-assisted pass failed for ${collection} (proceeding with local-only):`,
           err
         );
       }
@@ -5847,7 +5894,7 @@ var _SyncedDb = class _SyncedDb {
       } catch (err) {
         serverFailed = true;
         console.error(
-          "[evict] server-assisted batch failed (proceeding with local-only):",
+          "[SyncedDb] [evict] server-assisted batch failed (proceeding with local-only):",
           err
         );
       }
@@ -6159,7 +6206,7 @@ var _SyncedDb = class _SyncedDb {
       try {
         fn(info);
       } catch (err) {
-        console.error("Callback failed:", err);
+        console.error("[SyncedDb] Callback failed:", err);
       }
     }
   }
@@ -6250,12 +6297,12 @@ var _SyncedDb = class _SyncedDb {
   normalizeId(id, method, collection) {
     if (!id && id !== void 0) {
       console.error(
-        `SyncedDb.${method != null ? method : "?"}("${collection != null ? collection : "?"}"): id parameter is falsy (${JSON.stringify(id)}). This is a bug \u2014 the caller must provide a valid _id.`
+        `[SyncedDb] SyncedDb.${method != null ? method : "?"}("${collection != null ? collection : "?"}"): id parameter is falsy (${JSON.stringify(id)}). This is a bug \u2014 the caller must provide a valid _id.`
       );
     }
     if (typeof id === "string" && _SyncedDb.STRINGIFIED_FALSY.has(id)) {
       console.error(
-        `SyncedDb.${method != null ? method : "?"}("${collection != null ? collection : "?"}"): id is a stringified falsy value ("${id}"). This is a bug \u2014 a falsy value was coerced to string before being passed as _id.`
+        `[SyncedDb] SyncedDb.${method != null ? method : "?"}("${collection != null ? collection : "?"}"): id is a stringified falsy value ("${id}"). This is a bug \u2014 a falsy value was coerced to string before being passed as _id.`
       );
     }
     return typeof id === "object" && id !== null ? String(id) : id;
@@ -6267,12 +6314,12 @@ var _SyncedDb = class _SyncedDb {
   warnFalsyQueryId(data, method, collection) {
     if ("_id" in data && !data._id) {
       console.error(
-        `SyncedDb.${method}("${collection}"): _id is present in query/data but falsy (${JSON.stringify(data._id)}). This is a bug \u2014 _id must be valid when specified. Data keys: [${Object.keys(data).join(", ")}]`
+        `[SyncedDb] SyncedDb.${method}("${collection}"): _id is present in query/data but falsy (${JSON.stringify(data._id)}). This is a bug \u2014 _id must be valid when specified. Data keys: [${Object.keys(data).join(", ")}]`
       );
     }
     if ("_id" in data && typeof data._id === "string" && _SyncedDb.STRINGIFIED_FALSY.has(data._id)) {
       console.error(
-        `SyncedDb.${method}("${collection}"): _id is a stringified falsy value ("${data._id}"). This is a bug \u2014 a falsy value was coerced to string before being passed as _id. Data keys: [${Object.keys(data).join(", ")}]`
+        `[SyncedDb] SyncedDb.${method}("${collection}"): _id is a stringified falsy value ("${data._id}"). This is a bug \u2014 a falsy value was coerced to string before being passed as _id. Data keys: [${Object.keys(data).join(", ")}]`
       );
     }
   }
@@ -6285,7 +6332,7 @@ var _SyncedDb = class _SyncedDb {
   ensureId(data, method, collection) {
     if (typeof data._id === "string" && _SyncedDb.STRINGIFIED_FALSY.has(data._id)) {
       console.error(
-        `SyncedDb.${method}("${collection}"): _id is a stringified falsy value ("${data._id}"). This is a bug \u2014 a falsy value was coerced to string before being passed as _id. Data keys: [${Object.keys(data).join(", ")}]`
+        `[SyncedDb] SyncedDb.${method}("${collection}"): _id is a stringified falsy value ("${data._id}"). This is a bug \u2014 a falsy value was coerced to string before being passed as _id. Data keys: [${Object.keys(data).join(", ")}]`
       );
       data._id = null;
     }
@@ -6293,7 +6340,7 @@ var _SyncedDb = class _SyncedDb {
       const newId = new ObjectId2().toHexString();
       if ("_id" in data) {
         console.error(
-          `SyncedDb.${method}("${collection}"): _id is present but falsy (${JSON.stringify(data._id)}). Replaced with "${newId}". This is a bug \u2014 the caller should provide a valid _id. Data keys: [${Object.keys(data).join(", ")}]`
+          `[SyncedDb] SyncedDb.${method}("${collection}"): _id is present but falsy (${JSON.stringify(data._id)}). Replaced with "${newId}". This is a bug \u2014 the caller should provide a valid _id. Data keys: [${Object.keys(data).join(", ")}]`
         );
       }
       data._id = newId;
@@ -6383,7 +6430,7 @@ var _SyncedDb = class _SyncedDb {
     const drop = (reason) => {
       if (dropSilently) return;
       console.error(
-        `SyncedDb.applyDiffLocally: dropping bracket-path diff entry (${reason})`,
+        `[SyncedDb] applyDiffLocally: dropping bracket-path diff entry (${reason})`,
         { collection, _id: String(id), path, value }
       );
     };
@@ -6599,7 +6646,7 @@ var DexieDb = class extends Dexie {
       this.ensureStringId(item);
       if (typeof item._id !== "string" || item._id.length === 0) {
         console.error(
-          `DexieDb.saveMany: skipping item with invalid _id in "${collection}"`,
+          `[DexieDb] DexieDb.saveMany: skipping item with invalid _id in "${collection}"`,
           { _id: item._id, _idType: typeof item._id, item }
         );
         continue;
@@ -6612,7 +6659,7 @@ var DexieDb = class extends Dexie {
     } catch (err) {
       const ids = valid.map((it) => String(it._id));
       console.error(
-        `DexieDb.saveMany: bulkPut failed for "${collection}" (${valid.length} items):`,
+        `[DexieDb] DexieDb.saveMany: bulkPut failed for "${collection}" (${valid.length} items):`,
         err,
         "_ids:",
         ids
@@ -9567,7 +9614,7 @@ var Ebus2ProxyServerUpdateNotifier = class {
     this.reconnectAttempt = 0;
     this.currentReconnectDelay = this.reconnectDelayMs;
     console.log(
-      `Ebus2Proxy connected to ${this.wsUrl} (db: ${this.dbName})`
+      `[Ebus2ProxyNotifier] Ebus2Proxy connected to ${this.wsUrl} (db: ${this.dbName})`
     );
     this.sendSubscribe(`db/${this.dbName}`);
     if (this.subscribeServices) {
@@ -9578,7 +9625,7 @@ var Ebus2ProxyServerUpdateNotifier = class {
       try {
         callback();
       } catch (err) {
-        console.error("onWsConnect callback failed:", err);
+        console.error("[Ebus2ProxyNotifier] onWsConnect callback failed:", err);
       }
     }
   }
@@ -9593,7 +9640,7 @@ var Ebus2ProxyServerUpdateNotifier = class {
         try {
           callback(reason);
         } catch (err) {
-          console.error("onWsDisconnect callback failed:", err);
+          console.error("[Ebus2ProxyNotifier] onWsDisconnect callback failed:", err);
         }
       }
     }
@@ -9602,7 +9649,7 @@ var Ebus2ProxyServerUpdateNotifier = class {
     }
   }
   handleError(event) {
-    console.error("WebSocket error:", event);
+    console.error("[Ebus2ProxyNotifier] WebSocket error:", event);
   }
   handleMessage(event) {
     try {
@@ -9624,11 +9671,11 @@ var Ebus2ProxyServerUpdateNotifier = class {
           this.handlePong();
           break;
         case "error":
-          console.error("WebSocket server error:", message.error);
+          console.error("[Ebus2ProxyNotifier] WebSocket server error:", message.error);
           break;
       }
     } catch (err) {
-      console.error("Failed to parse WebSocket message:", err);
+      console.error("[Ebus2ProxyNotifier] Failed to parse WebSocket message:", err);
     }
   }
   handleChannelMessage(message) {
@@ -9636,7 +9683,7 @@ var Ebus2ProxyServerUpdateNotifier = class {
       try {
         this.onServicesChange(message.data);
       } catch (err) {
-        console.error("onServicesChange callback failed:", err);
+        console.error("[Ebus2ProxyNotifier] onServicesChange callback failed:", err);
       }
       return;
     }
@@ -9653,14 +9700,14 @@ var Ebus2ProxyServerUpdateNotifier = class {
       try {
         this.onWsNotification(payload);
       } catch (err) {
-        console.error("onWsNotification callback failed:", err);
+        console.error("[Ebus2ProxyNotifier] onWsNotification callback failed:", err);
       }
     }
     for (const callback of this.callbacks) {
       try {
         callback(payload);
       } catch (err) {
-        console.error("ServerUpdateCallback failed:", err);
+        console.error("[Ebus2ProxyNotifier] ServerUpdateCallback failed:", err);
       }
     }
   }
@@ -9679,14 +9726,14 @@ var Ebus2ProxyServerUpdateNotifier = class {
       try {
         callback(this.reconnectAttempt);
       } catch (err) {
-        console.error("onWsReconnect callback failed:", err);
+        console.error("[Ebus2ProxyNotifier] onWsReconnect callback failed:", err);
       }
     }
     this.reconnectTimer = setTimeout(() => {
       this.reconnectTimer = void 0;
       if (this.shouldReconnect && !this.forcedOffline) {
         this.createWebSocket().catch((err) => {
-          console.error("Reconnection failed:", err);
+          console.error("[Ebus2ProxyNotifier] Reconnection failed:", err);
           this.currentReconnectDelay = Math.min(
             this.currentReconnectDelay * 2,
             this.maxReconnectDelayMs
@@ -9709,7 +9756,7 @@ var Ebus2ProxyServerUpdateNotifier = class {
     const pingMsg = { type: "ping", id: `ping-${Date.now()}` };
     this.ws.send(packr2.pack(preprocessForPack2(pingMsg)));
     this.pongTimer = setTimeout(() => {
-      console.warn("Pong timeout - closing WebSocket");
+      console.warn("[Ebus2ProxyNotifier] Pong timeout - closing WebSocket");
       if (this.ws) {
         this.ws.close(4e3, "Pong timeout");
       }

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

@@ -18,6 +18,7 @@ export declare class SyncEngine implements I_SyncEngine {
     private readonly restInterface;
     private readonly callbacks;
     private readonly deps;
+    private readonly preprocessDirtyItem?;
     constructor(config: SyncEngineConfig);
     /**
      * Execute full sync cycle.

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

@@ -292,6 +292,11 @@ export interface SyncEngineConfig {
     collections: Map<string, CollectionConfig>;
     dexieDb: I_DexieDb;
     restInterface: I_RestInterface;
+    /**
+     * Optional per-item filter / transform applied before upload. See
+     * `SyncedDbConfig.preprocessDirtyItem` for full semantics.
+     */
+    preprocessDirtyItem?: (item: import("../../types/I_SyncedDb").PreprocessDirtyItem, collection: string) => import("../../types/I_SyncedDb").PreprocessDirtyItem | undefined;
     callbacks: SyncEngineCallbacks;
     deps: SyncEngineDeps;
 }

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

@@ -117,6 +117,16 @@ export interface ServerWriteResultInfo {
     /** Where sync was called from (for debugging) */
     calledFrom?: string;
 }
+/**
+ * Item handed to `preprocessDirtyItem` immediately before it would be sent
+ * to the server. Carries the per-record `_id` and the wire-form `update`
+ * payload (paths → values, with `_ts` / `_rev` already stripped and
+ * legacy `arr.0.field` paths fixed).
+ */
+export interface PreprocessDirtyItem {
+    _id: Id;
+    update: Partial<LocalDbEntity>;
+}
 /**
  * Callback payload for a single `updateCollections` round-trip — fires
  * once per call with both the request and either the response OR the
@@ -440,6 +450,33 @@ export interface SyncedDbConfig {
     debounceDexieWritesMs?: number;
     /** Debounce čas za pošiljanje na REST v ms (default: 1000) - po uspešnem zapisu v Dexie */
     debounceRestWritesMs?: number;
+    /**
+     * Per-item filter / transform applied to each dirty payload just before it
+     * is sent to the server. Runs after `_ts`/`_rev` strip and legacy-path
+     * fixup, so `item.update` already reflects the wire-shape that would
+     * normally be uploaded.
+     *
+     * Return values:
+     *   - the same or a modified `{ _id, update }` → use it for upload
+     *   - `undefined` → SKIP upload of this item for the current cycle; the
+     *     dirty change is **left untouched** so the next sync cycle
+     *     re-runs preprocessing
+     *   - throw → log `console.error` and SKIP upload for this item; the
+     *     dirty change is **left untouched** as well (same as `undefined`,
+     *     just additionally surfaced as an error)
+     *
+     * Neither return path clears or modifies the underlying dirty change —
+     * use the regular `save` / `insert` / `upsert` API to overwrite or
+     * `hardDeleteOne` to remove records.
+     *
+     * Items that survive are batched into a single `updateCollections` call
+     * per collection.
+     *
+     * @param item   The candidate payload (id + wire-form update)
+     * @param collection The collection name the item belongs to
+     * @returns Modified item, the same item, or `undefined` to skip this cycle
+     */
+    preprocessDirtyItem?: (item: PreprocessDirtyItem, collection: string) => PreprocessDirtyItem | undefined;
     /**
      * Callback fired on each sync failure. Unlike the removed `onForcedOffline`,
      * this does NOT mutate online state — the library keeps trying on the next

package/dist/src/utils/computeDiff.d.ts

@@ -84,9 +84,15 @@ export declare function deleteByPath(target: any, path: string): boolean;
  *         wrapped element[0], not into the array itself. The pending insert
  *         absorbs the sub-field edit.
  *
- * 2. New path is an ANCESTOR of existing keys (e.g. existing has "koraki.0.diag",
- *    new is "koraki" with full array): remove the now-redundant descendants and
- *    set the parent path. The new full value supersedes any field-level deltas.
+ * 2. New path is an ANCESTOR of existing keys.
+ *    - Plain ancestor (e.g. existing "koraki.0.diag", new "koraki" with full
+ *      array): drop the descendants; the new full value supersedes any
+ *      field-level deltas.
+ *    - TERMINAL-bracket ancestor whose `newValue` is element-shaped
+ *      (`arr[a].sub[b]` with `[<el>]` or plain object): LAYER pending
+ *      descendant sub-field edits INTO `newValue` before dropping them,
+ *      so the element-level write absorbs the prior sub-field-level
+ *      writes instead of silently overwriting them.
  *
  * 3. New path is ORTHOGONAL to existing keys: simple set (Object.assign-equivalent).
  *

package/package.json

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