cry-synced-db-client 0.1.172 → 0.1.174

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

@@ -3012,7 +3012,7 @@ function stripServerManagedFromChanges(changes) {
 }
 
 // src/db/sync/SyncEngine.ts
-var SUPRESS_DB_WARNINGS = false;
+var SUPRESS_DB_WARNINGS = true;
 var _SyncEngine = class _SyncEngine {
   constructor(config) {
     this.tenant = config.tenant;
@@ -3022,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.
@@ -3279,24 +3280,43 @@ var _SyncEngine = class _SyncEngine {
           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: []
         }
       }]);
@@ -4450,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,
@@ -6241,6 +6262,44 @@ var _SyncedDb = class _SyncedDb {
         }
       }
     });
+    const dirty = await this.dexieDb.getDirty(name);
+    if (dirty.length > 0) {
+      const itemById = /* @__PURE__ */ new Map();
+      for (let i = 0; i < allItems.length; i++) {
+        itemById.set(String(allItems[i]._id), allItems[i]);
+      }
+      let orphanCount = 0;
+      for (const dirtyItem of dirty) {
+        const id = dirtyItem._id;
+        if (id == null) continue;
+        const idStr = String(id);
+        const existing = itemById.get(idStr);
+        const diff = {};
+        for (const key of Object.keys(dirtyItem)) {
+          if (key === "_id" || key === "_ts" || key === "_rev") continue;
+          diff[key] = dirtyItem[key];
+        }
+        const merged = _SyncedDb.applyDiffLocally(
+          existing != null ? existing : null,
+          diff,
+          id,
+          name
+        );
+        if (merged._deleted || merged._archived) {
+          itemById.delete(idStr);
+          continue;
+        }
+        if (!existing) orphanCount++;
+        itemById.set(idStr, merged);
+      }
+      if (orphanCount > 0) {
+        console.warn(
+          `[SyncedDb] init(${name}): ${orphanCount} dirty record(s) had no matching Dexie main row \u2014 included in in-mem pending next sync.`
+        );
+      }
+      allItems.length = 0;
+      for (const item of itemById.values()) allItems.push(item);
+    }
     this.inMemManager.initCollection(name, allItems);
     const meta = await this.dexieDb.getSyncMeta(name);
     if (meta) {

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/package.json

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