cry-synced-db-client 0.1.156 → 0.1.158

package/dist/index.js

@@ -2723,16 +2723,32 @@ function isPlainObject4(value) {
 function hasArrayIndexPath(key) {
   return /\.\d+(\.|$)/.test(key);
 }
+function pathTargetsArrayElement(key, arrayPathTokens) {
+  const keyTokens = tokenizePath(key);
+  if (keyTokens.length <= arrayPathTokens.length) return false;
+  for (let i = 0; i < arrayPathTokens.length; i++) {
+    if (keyTokens[i] !== arrayPathTokens[i]) return false;
+  }
+  const next = keyTokens[arrayPathTokens.length];
+  return next.startsWith("[") || /^\d+$/.test(next);
+}
 function fixDotnetArrays(changes, serverRev, baseRev) {
-  if (typeof serverRev !== "number" || typeof baseRev !== "number") {
-    return changes;
-  }
-  if (serverRev <= baseRev) {
-    return changes;
+  const arrayPathTokens = [];
+  for (const [k, v] of Object.entries(changes)) {
+    if (Array.isArray(v)) arrayPathTokens.push(tokenizePath(k));
   }
+  const isStale = typeof serverRev === "number" && typeof baseRev === "number" && serverRev > baseRev;
   const cleaned = {};
   for (const [key, value] of Object.entries(changes)) {
-    if (hasArrayIndexPath(key)) continue;
+    let conflictsWithFullArray = false;
+    for (const tokens of arrayPathTokens) {
+      if (pathTargetsArrayElement(key, tokens)) {
+        conflictsWithFullArray = true;
+        break;
+      }
+    }
+    if (conflictsWithFullArray) continue;
+    if (isStale && hasArrayIndexPath(key)) continue;
     cleaned[key] = value;
   }
   return cleaned;
@@ -2786,6 +2802,42 @@ function translateKey(key, entity) {
   return out.join(".");
 }
 
+// src/utils/stripServerManaged.ts
+var SERVER_MANAGED_KEYS = /* @__PURE__ */ new Set(["_ts", "_rev", "_csq"]);
+function isObjectIdLike2(v) {
+  return !!(v && typeof v === "object" && (v._bsontype === "ObjectId" || v._bsontype === "ObjectID"));
+}
+function isServerManagedPath(key) {
+  for (const part of tokenizePath(key)) {
+    if (part.startsWith("[")) continue;
+    if (SERVER_MANAGED_KEYS.has(part)) return true;
+  }
+  return false;
+}
+function scrubServerManagedDeep(value) {
+  if (value === null || value === void 0) return value;
+  if (Array.isArray(value)) {
+    return value.map((item) => scrubServerManagedDeep(item));
+  }
+  if (typeof value !== "object") return value;
+  if (value instanceof Date) return value;
+  if (isObjectIdLike2(value)) return value;
+  const out = {};
+  for (const k of Object.keys(value)) {
+    if (SERVER_MANAGED_KEYS.has(k)) continue;
+    out[k] = scrubServerManagedDeep(value[k]);
+  }
+  return out;
+}
+function stripServerManagedFromChanges(changes) {
+  const out = {};
+  for (const [key, value] of Object.entries(changes)) {
+    if (isServerManagedPath(key)) continue;
+    out[key] = scrubServerManagedDeep(value);
+  }
+  return out;
+}
+
 // src/db/sync/SyncEngine.ts
 var _SyncEngine = class _SyncEngine {
   constructor(config) {
@@ -2989,6 +3041,7 @@ var _SyncEngine = class _SyncEngine {
         dirtyChangesMap.set(String(dirtyItem._id), dirtyItem);
       }
       const updates = [];
+      const skipped = [];
       const ids = dirtyChanges.map((dc) => dc._id);
       const fullItems = await this.dexieDb.getByIds(collectionName, ids);
       for (let i = 0; i < fullItems.length; i++) {
@@ -2999,6 +3052,8 @@ var _SyncEngine = class _SyncEngine {
           if (delta) {
             const currentServerRev = typeof fullItem._rev === "number" ? fullItem._rev : void 0;
             updates.push({ _id: fullItem._id, delta, currentServerRev, fullItem });
+          } else {
+            skipped.push({ _id: String(fullItem._id), reason: "no-delta-for-fullitem" });
           }
         } else if (id != null) {
           const delta = dirtyChangesMap.get(String(id));
@@ -3006,29 +3061,62 @@ var _SyncEngine = class _SyncEngine {
             const reconstructed = __spreadProps(__spreadValues({}, delta), { _id: id });
             await this.dexieDb.save(collectionName, id, reconstructed);
             updates.push({ _id: id, delta });
+          } else {
+            skipped.push({ _id: String(id), reason: "no-delta-for-orphan" });
           }
+        } else {
+          skipped.push({ _id: "<null>", reason: "no-fullitem-no-id" });
         }
       }
       if (updates.length === 0) {
         console.warn(
-          `uploadDirtyItems: ${collectionName} has ${dirtyChanges.length} dirty entries but 0 resolvable items`
+          `uploadDirtyItems: ${collectionName} has ${dirtyChanges.length} dirty entries but 0 resolvable items`,
+          skipped
         );
+        if (this.callbacks.onUploadSkip) {
+          try {
+            this.callbacks.onUploadSkip({
+              collection: collectionName,
+              reason: "no-resolvable-items",
+              dirtyCount: dirtyChanges.length,
+              skippedIds: skipped.slice(0, 20).map((s) => s._id),
+              skipReasons: skipped.slice(0, 20),
+              calledFrom,
+              timestamp: /* @__PURE__ */ new Date()
+            });
+          } catch (err) {
+            console.error("onUploadSkip callback failed:", err);
+          }
+        }
         continue;
       }
+      if (skipped.length > 0 && this.callbacks.onUploadSkip) {
+        try {
+          this.callbacks.onUploadSkip({
+            collection: collectionName,
+            reason: "no-resolvable-items",
+            dirtyCount: dirtyChanges.length,
+            skippedIds: skipped.slice(0, 20).map((s) => s._id),
+            skipReasons: skipped.slice(0, 20),
+            calledFrom,
+            timestamp: /* @__PURE__ */ new Date()
+          });
+        } catch (err) {
+          console.error("onUploadSkip callback failed:", err);
+        }
+      }
       collectionBatches.push([{
         collection: collectionName,
         batch: {
           updates: updates.map((item) => {
-            const _a2 = item.delta, { _ts, _rev: dirtyBaseRev } = _a2, changes = __objRest(_a2, ["_ts", "_rev"]);
-            const stripped = {};
-            for (const [k, v] of Object.entries(changes)) {
-              if (k.startsWith("_ts.") || k.startsWith("_rev.") || k.startsWith("_csq.")) continue;
-              stripped[k] = v;
-            }
+            const dirtyBaseRev = typeof item.delta._rev === "number" ? item.delta._rev : void 0;
+            const stripped = stripServerManagedFromChanges(
+              item.delta
+            );
             const fixed = fixDotnetArrays(
               stripped,
               item.currentServerRev,
-              typeof dirtyBaseRev === "number" ? dirtyBaseRev : void 0
+              dirtyBaseRev
             );
             const cleanedChanges = translateBracketPathsToIndex(fixed, item.fullItem);
             return {
@@ -3932,6 +4020,8 @@ var _SyncedDb = class _SyncedDb {
     this.onWakeSync = config.onWakeSync;
     this.onEvictionStart = config.onEvictionStart;
     this.onEviction = config.onEviction;
+    this.onSaveIdMismatch = config.onSaveIdMismatch;
+    this.onUploadSkip = config.onUploadSkip;
     this.evictStaleRecordsEveryHrs = (_e = config.evictStaleRecordsEveryHrs) != null ? _e : 0;
     this.scopeExitLookbehindMs = (_f = config.scopeExitLookbehindMs) != null ? _f : 0;
     this.evictOnWake = (_g = config.evictOnWake) != null ? _g : false;
@@ -4068,7 +4158,8 @@ var _SyncedDb = class _SyncedDb {
         onServerWriteRequest: config.onServerWriteRequest,
         onServerWriteResult: config.onServerWriteResult,
         onFindNewerManyCall: config.onFindNewerManyCall,
-        onFindNewerManyResult: config.onFindNewerManyResult
+        onFindNewerManyResult: config.onFindNewerManyResult,
+        onUploadSkip: config.onUploadSkip
       },
       deps: {
         getSyncMetaCache: () => this.syncMetaCache,
@@ -4679,6 +4770,29 @@ var _SyncedDb = class _SyncedDb {
       );
       delete update._id;
     }
+    if ("_id" in update && update._id && String(update._id) !== String(id)) {
+      const updateKeys = Object.keys(update);
+      const stack = (() => {
+        try {
+          return new Error().stack;
+        } catch (e) {
+          return void 0;
+        }
+      })();
+      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(", ")}]`
+      );
+      this.safeCallback(this.onSaveIdMismatch, {
+        collection,
+        id: String(id),
+        updateId: String(update._id),
+        updateKeys,
+        stack,
+        timestamp: /* @__PURE__ */ new Date()
+      });
+      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)) {
@@ -4709,6 +4823,7 @@ 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);
@@ -4722,6 +4837,7 @@ var _SyncedDb = class _SyncedDb {
     var _a;
     this.assertCollection(collection);
     this.ensureId(data, "insert", collection);
+    _SyncedDb.ensureNestedIds(data);
     data = _SyncedDb.stringifyObjectIds(data);
     const id = String(data._id);
     const existing = await this.dexieDb.getById(collection, id);
@@ -5823,6 +5939,48 @@ var _SyncedDb = class _SyncedDb {
   static isObjectIdLike(v) {
     return !!(v && typeof v === "object" && (v._bsontype === "ObjectId" || typeof v.toHexString === "function"));
   }
+  /**
+   * 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

@@ -52,6 +52,8 @@ export declare class SyncedDb implements I_SyncedDb {
     private readonly onWakeSync?;
     private readonly onEvictionStart?;
     private readonly onEviction?;
+    private readonly onSaveIdMismatch?;
+    private readonly onUploadSkip?;
     private readonly evictStaleRecordsEveryHrs;
     private readonly scopeExitLookbehindMs;
     private readonly evictOnWake;
@@ -401,6 +403,27 @@ export declare class SyncedDb implements I_SyncedDb {
      */
     private static stringifyObjectIds;
     private static isObjectIdLike;
+    /**
+     * 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/types/managers.d.ts

@@ -261,6 +261,7 @@ export interface SyncEngineCallbacks {
     onServerWriteResult?: (info: ServerWriteResultInfo) => void;
     onFindNewerManyCall?: (info: FindNewerManyCallInfo) => void;
     onFindNewerManyResult?: (info: FindNewerManyResultInfo) => void;
+    onUploadSkip?: (info: import("../../types/I_SyncedDb").UploadSkipInfo) => void;
 }
 export interface SyncEngineDeps {
     getSyncMetaCache: () => Map<string, SyncMeta>;

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

@@ -35,6 +35,62 @@ export interface InfrastructureErrorInfo {
     /** Timestamp when error occurred */
     timestamp: Date;
 }
+/**
+ * Payload za upload-skip callback. Sproži se, ko `uploadDirtyItems` najde
+ * dirty zapise v Dexie `_dirty_changes`, ampak iz njih ne more zgraditi
+ * resolve-able update batch (npr. fullItem manjka in `id` je null/undefined,
+ * ali `dirtyChangesMap.get` vrne undefined zaradi key mismatch-a).
+ *
+ * Production incident 2026-05-08 (etv/prvak/studenci/tackakp racuni stuck):
+ * 14 dirty zapisov nikoli ne pride na server, brez napake na rdb2/errors,
+ * `lastDirtySyncAt: null` (sentCount=0). Ta callback razkrije za katere
+ * konkretne `_id`-je se to dogaja.
+ */
+export interface UploadSkipInfo {
+    /** Collection kjer je skip nastal */
+    collection: string;
+    /** Razlog za skip */
+    reason: "no-resolvable-items" | "no-batches";
+    /** Število dirty zapisov v Dexie pred skip-om */
+    dirtyCount: number;
+    /** Konkretni _id-ji, ki so šli skozi skip pot (do 20) */
+    skippedIds: string[];
+    /** Razlog za vsak skipped _id (do 20) */
+    skipReasons: {
+        _id: string;
+        reason: "no-fullitem-no-id" | "no-delta-for-fullitem" | "no-delta-for-orphan";
+    }[];
+    /** calledFrom iz sync flow-a */
+    calledFrom?: string;
+    /** Timestamp */
+    timestamp: Date;
+}
+/**
+ * Payload za save() id-mismatch callback. Sproži se, ko caller pokliče
+ * `save(collection, id, update)` z `update._id` ki se NE ujema z `id`.
+ *
+ * Brez popravka bi addDirtyChange shranil entry.id = id, entry.changes._id =
+ * update._id; pri uploadu bi server dobil update._id, vrnil ack pod update._id,
+ * client bi poskušal clear pod id → ne ujema → dirty stuck forever.
+ *
+ * Library v save() avtomatsko strip-a `_id` iz update preden pokliče
+ * addDirtyChange. Callback je samo za telemetry/syslog/alerting — caller bug
+ * mora biti popravljen v aplikaciji.
+ */
+export interface SaveIdMismatchInfo {
+    /** Collection name */
+    collection: string;
+    /** id parameter passed to save() */
+    id: string;
+    /** _id field present in update object (mismatched) */
+    updateId: string;
+    /** Top-level keys of the update object (no values, no PII) */
+    updateKeys: string[];
+    /** Stack trace at the call site */
+    stack?: string;
+    /** Timestamp when mismatch detected */
+    timestamp: Date;
+}
 /**
  * Callback payload for server write requests (before sending)
  */
@@ -462,6 +518,29 @@ export interface SyncedDbConfig {
      * Client code can use this to show warnings, log telemetry, or adjust behavior.
      */
     onInfrastructureError?: (info: InfrastructureErrorInfo) => void;
+    /**
+     * Callback when `uploadDirtyItems` skips dirty entries (silent skip without
+     * sending to server). Used to diagnose stuck-dirty pattern where dirty
+     * exists but `sentCount === 0` (lastDirtySyncAt stays null).
+     *
+     * Production incident 2026-05-08 — 14 stuck racuni/protokoli on prod.
+     * Server has no record, no rdb2 error, dirty stays forever. This callback
+     * reveals which dirty entries hit which skip path.
+     */
+    onUploadSkip?: (info: UploadSkipInfo) => void;
+    /**
+     * Callback when `save(collection, id, update)` is called with `update._id`
+     * that does NOT match `id`. Library auto-strips `_id` from update to prevent
+     * the stuck-dirty bug, but the caller bug should be fixed in the app code.
+     *
+     * Use this callback for telemetry/syslog/alerting — the mismatch is silent
+     * data corruption (dirty stays forever) without observability.
+     *
+     * Production incident 2026-05-08 (zvitorepka, 3 stuck protokoli) was caused
+     * by `pages/protokol.vue` calling `save("protokoli", this._id, this.protokol)`
+     * where `this._id` and `this.protokol._id` had drifted apart.
+     */
+    onSaveIdMismatch?: (info: SaveIdMismatchInfo) => void;
     /**
      * Enable in-memory object metadata feature.
      * When true, collections with hasMetadata=true will have their metadata callbacks invoked

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

@@ -13,6 +13,28 @@
  *   "arr.10"               → true  (multi-digit index)
  */
 export declare function hasArrayIndexPath(key: string): boolean;
+/**
+ * `true` if `key` targets an element of the array at `arrayPath`.
+ *
+ * Both inputs are tokenized via `tokenizePath` (so dot AND bracket-by-_id
+ * segments are normalized). The key targets an element iff:
+ *   1. its first N tokens equal `arrayPath`'s tokens (prefix match), AND
+ *   2. the very next token is a numeric index ("0", "1", …) OR a bracket
+ *      `[<_id>]` segment.
+ *
+ * Examples (with arrayPath = "zaracunaj"):
+ *   "zaracunaj"                      → false (same path, not a child)
+ *   "zaracunaj.0.kolicina"           → true  (child via numeric index)
+ *   "zaracunaj[<_id>].kolicina"      → true  (child via bracket _id)
+ *   "zaracunajX"                     → false (different field)
+ *   "zaracunaj.kolicina"             → false (object field, not element)
+ *
+ * Examples (with arrayPath = "_redundanca.terapije"):
+ *   "_redundanca.terapije[A].postavke[B].x" → true
+ *   "_redundanca.terapije.0.x"              → true
+ *   "_redundanca.terapija"                  → false (different field)
+ */
+export declare function pathTargetsArrayElement(key: string, arrayPathTokens: readonly string[]): boolean;
 /**
  * TEMPORARY mitigation: when server has advanced past client's base _rev
  * (i.e., the dirty was emitted against a stale snapshot of the record),

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

@@ -0,0 +1,33 @@
+/**
+ * `true` if `key` (a dot/bracket-notation path) targets a server-managed
+ * metadata field anywhere along its tokenized path.
+ *
+ * Examples:
+ *   "_ts"                           → true
+ *   "_ts.t"                         → true (token `_ts`)
+ *   "_rev"                          → true
+ *   "field._ts"                     → true
+ *   "arr[<_id>]._rev"               → true
+ *   "_redundanca.terapije[X]._ts.i" → true
+ *   "stranka.gsm"                   → false
+ *   "zaracunaj[<_id>].kolicina"     → false
+ */
+export declare function isServerManagedPath(key: string): boolean;
+/**
+ * Recursively scrub `_ts` / `_rev` / `_csq` from a value tree without
+ * mutating the input. Returns a new tree with the offending keys removed
+ * at every depth, including inside arrays.
+ *
+ * Primitives, Date, and ObjectId-like instances pass through by reference.
+ */
+export declare function scrubServerManagedDeep<T>(value: T): T;
+/**
+ * Strip server-managed metadata from a dirty-changes payload at upload time.
+ *
+ *   1. Drop any path key whose tokenized path includes `_ts`, `_rev`, or `_csq`.
+ *   2. For surviving entries, recursively scrub the value (in case a value is
+ *      a full object/array replace that contains nested `_ts` / `_rev`).
+ *
+ * Returns a new object — input is not mutated.
+ */
+export declare function stripServerManagedFromChanges(changes: Record<string, unknown>): Record<string, unknown>;

package/package.json

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