cry-synced-db-client 0.1.197 → 0.1.200

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Versions
 
+## 0.1.200 (2026-06-14)
+
+### `preprocessDirtyItem` skip/throw zdaj incrementa `numUploadAttempts`
+
+`SyncEngine.uploadDirtyItems`: ko `preprocessDirtyItem` vrne `undefined` ali vrže
+exception, se item ne samo preskoči — zdaj dobi tudi `incrementDirtyUploadAttempts`,
+tako da po 2+ skipih postane stuck in viden prek `getStuckItems()` / `onDirtyItemStuck`.
+
+Prej so skipani itemi tiho ostali v `_dirty_changes` brez metapodatkov in nikoli ne
+bi postali stuck — zdaj se po 3 skipih (vsak sync da 2 incrementa = main + followUp)
+dobijo `stuckSince`.
+
+**Internal:**
+- V `uploadDirtyItems` zbira `preprocessSkippedIds` v obeh poteh, batch-write v
+  `incrementDirtyUploadAttempts` takoj za `for` zanko (en DB write za vse skipane
+  iteme namesto N write-ov)
+
+**Tests:** 5 novih testov v `test/preprocessDirtyItem.test.ts`:
+- `undefined/throw: numUploadAttempts increments across sync cycles, eventually stuck`
+- `undefined/throw: onDirtyItemStuck fires when item becomes stuck`
+- `mixed: stuck item via getStuckItems while non-stuck dirty still active`
+
+876 pass, 0 fail.
+
+## 0.1.198 (2026-06-13)
+
+### Stuck-item tracking (`getStuckItems` / `discardStuckItems` / `onDirtyItemStuck`)
+
+Nov mehanizem za detekcijo dirty itemov, ki jih server vztrajno zavrača.
+
+**Fields na `DirtyChange` / `DirtyMeta`:**
+- `firstUploadAttempt?`, `lastUploadAttempt?`, `numUploadAttempts?`, `stuckSince?`
+- `stuckSince` se nastavi ko `numUploadAttempts > DIRTY_STUCK_AFTER_UPLOAD_ATTEMPTS` (2)
+
+**Nove metode na `SyncedDb`:**
+- `getStuckItems()` — vrne samo stuck dirty iteme po kolekcijah (`Record<collection, DirtyMeta[]>`)
+- `discardStuckItems(calledFrom?)` — zbriše vse stuck dirty iteme, sproži `onBeforeDirtyClearAll` z `reason: "discard-stuck"`
+
+**Nov callback:**
+- `onDirtyItemStuck(info: DirtyItemStuckInfo)` — sproži se ko item prvič postane stuck (po 3. neuspelem uploadu). Vsebuje `collection`, `items: DirtyMeta[]`, `calledFrom`, `timestamp`.
+
+**Internal:**
+- `I_DexieDb.incrementDirtyUploadAttempts(collection, ids)` — nova metoda, vrača `DirtyMeta[]` na novo stuck itemov
+- Vgrajena v `SyncEngine.uploadDirtyItems` in `uploadDirtyItemsForCollection` — per-collection result (errored ids) in catch block (network/timeout)
+- `DexieDb.getDirtyMeta` sedaj vključuje nova polja v izhod
+
+**Tests:** 17 testov v `test/stuckItems.test.ts` — unit testi za increment, integracijski za get/discard, e2e za callback skozi upload pipeline.
+
 ## 0.1.196 (2026-06-10)
 
 ### `refreshImmediately` — blokirni server-fetch z verzijsko primerjavo

package/dist/index.js

@@ -3245,7 +3245,10 @@ var _SyncEngine = class _SyncEngine {
         configMap.set(collectionName, config);
       }
       this.callOnFindNewerManyCall(syncSpecs, calledFrom);
-      this.callbackSafe(this.callbacks.onServerSyncStart, { calledFrom, collectionCount: syncSpecs.length });
+      this.callbackSafe(this.callbacks.onServerSyncStart, {
+        calledFrom,
+        collectionCount: syncSpecs.length
+      });
       const findNewerManyStartTime = Date.now();
       const collectionState = /* @__PURE__ */ new Map();
       for (const [name] of configMap) {
@@ -3276,7 +3279,12 @@ var _SyncEngine = class _SyncEngine {
               if (!config) return;
               const state = collectionState.get(collection);
               state.receivedCount += items.length;
-              const stats = await this.processIncomingServerData(collection, config, items, state.source);
+              const stats = await this.processIncomingServerData(
+                collection,
+                config,
+                items,
+                state.source
+              );
               state.conflicts += stats.conflictsResolved;
               if (stats.maxTs) {
                 if (!state.maxTs || this.compareTimestamps(stats.maxTs, state.maxTs) > 0) {
@@ -3358,12 +3366,16 @@ var _SyncEngine = class _SyncEngine {
       try {
         uploadStats = await this.uploadDirtyItems(calledFrom);
         await this.deps.flushAllPendingChanges();
-        const followUp = await this.uploadDirtyItems(`${calledFrom != null ? calledFrom : "sync"}:followUp`);
+        const followUp = await this.uploadDirtyItems(
+          `${calledFrom != null ? calledFrom : "sync"}:followUp`
+        );
         if (followUp.sentCount > 0) {
           uploadStats.sentCount += followUp.sentCount;
           if (followUp.collectionSentCounts) {
             uploadStats.collectionSentCounts = uploadStats.collectionSentCounts || {};
-            for (const [c, n] of Object.entries(followUp.collectionSentCounts)) {
+            for (const [c, n] of Object.entries(
+              followUp.collectionSentCounts
+            )) {
               uploadStats.collectionSentCounts[c] = (uploadStats.collectionSentCounts[c] || 0) + n;
             }
           }
@@ -3375,7 +3387,9 @@ var _SyncEngine = class _SyncEngine {
         );
       }
       sentCount = uploadStats.sentCount;
-      for (const [collectionName, stats] of Object.entries(uploadStats.collectionSentCounts || {})) {
+      for (const [collectionName, stats] of Object.entries(
+        uploadStats.collectionSentCounts || {}
+      )) {
         if (collectionStats[collectionName]) {
           collectionStats[collectionName].sentCount = stats;
         } else {
@@ -3473,15 +3487,20 @@ var _SyncEngine = class _SyncEngine {
         });
       }
     }
-    if (dexieSave.length > 0) await this.dexieDb.saveMany(collection, dexieSave);
+    if (dexieSave.length > 0)
+      await this.dexieDb.saveMany(collection, dexieSave);
     if (dexieDeleteIds.length > 0) {
       await this.dexieDb.deleteMany(collection, dexieDeleteIds);
     }
     if (memUpsert.length > 0) {
-      this.deps.writeToInMemBatch(collection, memUpsert, "upsert", { source: "incremental" });
+      this.deps.writeToInMemBatch(collection, memUpsert, "upsert", {
+        source: "incremental"
+      });
     }
     if (memDelete.length > 0) {
-      this.deps.writeToInMemBatch(collection, memDelete, "delete", { source: "incremental" });
+      this.deps.writeToInMemBatch(collection, memDelete, "delete", {
+        source: "incremental"
+      });
     }
     if (reAddDirty.length > 0) {
       await this.dexieDb.addDirtyChangesBatch(collection, reAddDirty);
@@ -3508,7 +3527,7 @@ var _SyncEngine = class _SyncEngine {
    * Upload dirty items for all collections.
    */
   async uploadDirtyItems(calledFrom) {
-    var _a;
+    var _a, _b;
     const collectionBatches = [];
     for (const [collectionName] of this.collections) {
       const dirtyChanges = await this.dexieDb.getDirty(collectionName);
@@ -3520,7 +3539,10 @@ var _SyncEngine = class _SyncEngine {
       const updates = [];
       const skipped = [];
       const ids = dirtyChanges.map((dc) => dc._id);
-      const fullItems = await this.dexieDb.getByIds(collectionName, ids);
+      const fullItems = await this.dexieDb.getByIds(
+        collectionName,
+        ids
+      );
       const orphanReconstructed = [];
       for (let i = 0; i < fullItems.length; i++) {
         const fullItem = fullItems[i];
@@ -3531,7 +3553,10 @@ var _SyncEngine = class _SyncEngine {
             const currentServerRev = typeof fullItem._rev === "number" ? fullItem._rev : void 0;
             updates.push({ _id: fullItem._id, delta, currentServerRev });
           } else {
-            skipped.push({ _id: String(fullItem._id), reason: "no-delta-for-fullitem" });
+            skipped.push({
+              _id: String(fullItem._id),
+              reason: "no-delta-for-fullitem"
+            });
           }
         } else if (id != null) {
           const delta = dirtyChangesMap.get(String(id));
@@ -3568,7 +3593,10 @@ var _SyncEngine = class _SyncEngine {
               timestamp: /* @__PURE__ */ new Date()
             });
           } catch (err) {
-            console.error(`[SyncEngine] onUploadSkip callback failed: ${err}`, err);
+            console.error(
+              `[SyncEngine] onUploadSkip callback failed: ${err}`,
+              err
+            );
           }
         }
         continue;
@@ -3585,10 +3613,14 @@ var _SyncEngine = class _SyncEngine {
             timestamp: /* @__PURE__ */ new Date()
           });
         } catch (err) {
-          console.error(`[SyncEngine] onUploadSkip callback failed: ${err}`, err);
+          console.error(
+            `[SyncEngine] onUploadSkip callback failed: ${err}`,
+            err
+          );
         }
       }
       const mappedUpdates = [];
+      const preprocessSkippedIds = [];
       for (const item of updates) {
         const dirtyBaseRev = typeof item.delta._rev === "number" ? item.delta._rev : void 0;
         const stripped = stripServerManagedFromChanges(
@@ -3605,8 +3637,12 @@ var _SyncEngine = class _SyncEngine {
         };
         if (this.preprocessDirtyItem) {
           try {
-            const processed = this.preprocessDirtyItem(candidate, collectionName);
+            const processed = this.preprocessDirtyItem(
+              candidate,
+              collectionName
+            );
             if (processed === void 0) {
+              preprocessSkippedIds.push(item._id);
               continue;
             }
             candidate = processed;
@@ -3615,6 +3651,7 @@ var _SyncEngine = class _SyncEngine {
               `[SyncEngine] preprocessDirtyItem(${collectionName}) failed for _id=${String(item._id)}; keeping dirty for retry:`,
               err
             );
+            preprocessSkippedIds.push(item._id);
             continue;
           }
         }
@@ -3624,14 +3661,23 @@ var _SyncEngine = class _SyncEngine {
           update: candidate.update
         });
       }
+      if (preprocessSkippedIds.length > 0) {
+        const newlyStuck = await this.dexieDb.incrementDirtyUploadAttempts(
+          collectionName,
+          preprocessSkippedIds
+        );
+        this.callOnDirtyItemStuck(collectionName, newlyStuck, calledFrom);
+      }
       if (mappedUpdates.length === 0) continue;
-      collectionBatches.push([{
-        collection: collectionName,
-        batch: {
-          updates: mappedUpdates,
-          deletes: []
+      collectionBatches.push([
+        {
+          collection: collectionName,
+          batch: {
+            updates: mappedUpdates,
+            deletes: []
+          }
         }
-      }]);
+      ]);
     }
     if (collectionBatches.length === 0) {
       return { sentCount: 0 };
@@ -3664,6 +3710,18 @@ var _SyncEngine = class _SyncEngine {
         writeStartedAt,
         calledFrom
       );
+      for (const batch of collectionBatches) {
+        for (const b of batch) {
+          const allIds = [];
+          for (const u of b.batch.updates) allIds.push(u._id);
+          for (const d of b.batch.deletes) allIds.push((_a = d._id) != null ? _a : d);
+          const newlyStuck = await this.dexieDb.incrementDirtyUploadAttempts(
+            b.collection,
+            allIds
+          );
+          this.callOnDirtyItemStuck(b.collection, newlyStuck, calledFrom);
+        }
+      }
       throw err;
     }
     let sentCount = 0;
@@ -3712,13 +3770,38 @@ var _SyncEngine = class _SyncEngine {
           `[SyncEngine] Sync upload [${collection}]: ${ambiguous.length} id(s) appeared in BOTH inserted/updated/deleted AND errors[] \u2014 keeping dirty for safety. _ids: ${ambiguous.join(", ")}`
         );
       }
-      const dirtyBeforeRefresh = mustRefreshIds.size > 0 ? await this.dexieDb.getDirtyChangesBatch(collection, [...mustRefreshIds]) : /* @__PURE__ */ new Map();
+      const dirtyBeforeRefresh = mustRefreshIds.size > 0 ? await this.dexieDb.getDirtyChangesBatch(collection, [
+        ...mustRefreshIds
+      ]) : /* @__PURE__ */ new Map();
       const uploadedByIdRefresh = mustRefreshIds.size > 0 ? this.uploadedSnapshotFor(collectionBatches, collection) : /* @__PURE__ */ new Map();
       if (allSuccessIds.length > 0) {
         await this.dexieDb.clearDirtyChangesBatch(collection, allSuccessIds);
       }
+      const sentIdsForCollection = /* @__PURE__ */ new Set();
+      for (const batch of collectionBatches) {
+        for (const b of batch) {
+          if (b.collection !== collection) continue;
+          for (const u of b.batch.updates)
+            sentIdsForCollection.add(String(u._id));
+          for (const d of b.batch.deletes)
+            sentIdsForCollection.add(String(d._id));
+        }
+      }
+      const retainedIds = [];
+      for (const sid of sentIdsForCollection) {
+        if (!allSuccessIds.find((aid) => String(aid) === sid)) {
+          retainedIds.push(sid);
+        }
+      }
+      if (retainedIds.length > 0) {
+        const newlyStuck = await this.dexieDb.incrementDirtyUploadAttempts(
+          collection,
+          retainedIds
+        );
+        this.callOnDirtyItemStuck(collection, newlyStuck, calledFrom);
+      }
       let collectionSentCount = 0;
-      const isWriteOnly = (_a = this.collections.get(collection)) == null ? void 0 : _a.writeOnly;
+      const isWriteOnly = (_b = this.collections.get(collection)) == null ? void 0 : _b.writeOnly;
       const insertedAndUpdated = inserted.concat(updated);
       if (insertedAndUpdated.length > 0) {
         const idsToCheck = [];
@@ -3726,7 +3809,10 @@ var _SyncEngine = class _SyncEngine {
         if (isWriteOnly) {
           await this.dexieDb.deleteMany(collection, idsToCheck);
         } else {
-          const dexieItems = await this.dexieDb.getByIds(collection, idsToCheck);
+          const dexieItems = await this.dexieDb.getByIds(
+            collection,
+            idsToCheck
+          );
           const dexieSaveBatch = [];
           const inMemUpdateBatch = [];
           const inMemDeleteIds = [];
@@ -3754,7 +3840,12 @@ var _SyncEngine = class _SyncEngine {
             await this.dexieDb.deleteMany(collection, dexieDeleteIds);
           }
           if (inMemUpdateBatch.length > 0) {
-            this.deps.writeToInMemBatch(collection, inMemUpdateBatch, "upsert", { source: "incremental" });
+            this.deps.writeToInMemBatch(
+              collection,
+              inMemUpdateBatch,
+              "upsert",
+              { source: "incremental" }
+            );
           }
           if (inMemDeleteIds.length > 0) {
             this.deps.writeToInMemBatch(
@@ -3777,7 +3868,9 @@ var _SyncEngine = class _SyncEngine {
         }
         await this.dexieDb.deleteMany(collection, deleteIds);
         if (!isWriteOnly) {
-          this.deps.writeToInMemBatch(collection, deleteDbEntities, "delete", { source: "incremental" });
+          this.deps.writeToInMemBatch(collection, deleteDbEntities, "delete", {
+            source: "incremental"
+          });
         }
         sentCount += deleted.length;
         collectionSentCount += deleted.length;
@@ -3793,7 +3886,7 @@ var _SyncEngine = class _SyncEngine {
       if (collectionSentCount > 0) {
         collectionSentCounts[collection] = collectionSentCount;
       }
-      let maxTs = void 0;
+      let maxTs;
       for (const arr of [inserted, updated, deleted]) {
         for (const item of arr) {
           if (item._ts) {
@@ -3857,13 +3950,16 @@ var _SyncEngine = class _SyncEngine {
   /**
    * Upload dirty items for a specific collection.
    */
-  async uploadDirtyItemsForCollection(collection) {
+  async uploadDirtyItemsForCollection(collection, calledFrom) {
     const dirtyItems = await this.dexieDb.getDirty(collection);
     if (dirtyItems.length === 0) {
       return { sentCount: 0 };
     }
     const ids = dirtyItems.map((item) => item._id);
-    const fullItems = await this.dexieDb.getByIds(collection, ids);
+    const fullItems = await this.dexieDb.getByIds(
+      collection,
+      ids
+    );
     const dirtyChangesMap = /* @__PURE__ */ new Map();
     for (const dirtyItem of dirtyItems) {
       dirtyChangesMap.set(String(dirtyItem._id), dirtyItem);
@@ -3879,20 +3975,24 @@ var _SyncEngine = class _SyncEngine {
     if (updates.length === 0) {
       return { sentCount: 0 };
     }
-    const collectionBatches = [[{
-      collection,
-      batch: {
-        updates: updates.map((item) => {
-          const _a = item.delta, { _ts, _rev } = _a, changes = __objRest(_a, ["_ts", "_rev"]);
-          return {
-            _id: item._id,
-            _rev: typeof _rev === "number" ? _rev : 0,
-            update: changes
-          };
-        }),
-        deletes: []
-      }
-    }]];
+    const collectionBatches = [
+      [
+        {
+          collection,
+          batch: {
+            updates: updates.map((item) => {
+              const _a = item.delta, { _ts, _rev } = _a, changes = __objRest(_a, ["_ts", "_rev"]);
+              return {
+                _id: item._id,
+                _rev: typeof _rev === "number" ? _rev : 0,
+                update: changes
+              };
+            }),
+            deletes: []
+          }
+        }
+      ]
+    ];
     const results = await this.deps.withSyncTimeout(
       this.restInterface.updateCollections(collectionBatches),
       "updateCollections"
@@ -3955,6 +4055,29 @@ var _SyncEngine = class _SyncEngine {
       if (allSuccessIds.length > 0) {
         await this.dexieDb.clearDirtyChangesBatch(collection, allSuccessIds);
       }
+      const sentIdsForCollection = /* @__PURE__ */ new Set();
+      for (const batch of collectionBatches) {
+        for (const b of batch) {
+          if (b.collection !== collection) continue;
+          for (const u of b.batch.updates)
+            sentIdsForCollection.add(String(u._id));
+          for (const d of b.batch.deletes)
+            sentIdsForCollection.add(String(d._id));
+        }
+      }
+      const retainedIds = [];
+      for (const sid of sentIdsForCollection) {
+        if (!allSuccessIds.find((aid) => String(aid) === sid)) {
+          retainedIds.push(sid);
+        }
+      }
+      if (retainedIds.length > 0) {
+        const newlyStuck = await this.dexieDb.incrementDirtyUploadAttempts(
+          collection,
+          retainedIds
+        );
+        this.callOnDirtyItemStuck(collection, newlyStuck, calledFrom);
+      }
       if (mustRefresh && mustRefresh.length > 0) {
         await this.adoptMustRefresh(
           collection,
@@ -3980,7 +4103,12 @@ var _SyncEngine = class _SyncEngine {
     const config = this.collections.get(collectionName);
     if (!config) return { updatedIds: [] };
     const source = (_a = opts == null ? void 0 : opts.source) != null ? _a : "incremental";
-    const result = await this.processIncomingServerData(collectionName, config, serverData, source);
+    const result = await this.processIncomingServerData(
+      collectionName,
+      config,
+      serverData,
+      source
+    );
     if (result.updatedIds.length > 0) {
       this.deps.broadcastUpdates({ [collectionName]: result.updatedIds });
     }
@@ -3998,8 +4126,14 @@ var _SyncEngine = class _SyncEngine {
       const chunk = serverData.slice(offset, offset + BATCH);
       const chunkIds = [];
       for (const item of chunk) chunkIds.push(item._id);
-      const localItems = await this.dexieDb.getByIds(collectionName, chunkIds);
-      const dirtyChangesMap = await this.dexieDb.getDirtyChangesBatch(collectionName, chunkIds);
+      const localItems = await this.dexieDb.getByIds(
+        collectionName,
+        chunkIds
+      );
+      const dirtyChangesMap = await this.dexieDb.getDirtyChangesBatch(
+        collectionName,
+        chunkIds
+      );
       const dexieBatch = [];
       const inMemSaveBatch = [];
       const inMemDeleteIds = [];
@@ -4048,7 +4182,9 @@ var _SyncEngine = class _SyncEngine {
         await this.dexieDb.saveMany(collectionName, dexieBatch);
       }
       if (inMemSaveBatch.length > 0) {
-        this.deps.writeToInMemBatch(collectionName, inMemSaveBatch, "upsert", { source });
+        this.deps.writeToInMemBatch(collectionName, inMemSaveBatch, "upsert", {
+          source
+        });
       }
       if (inMemDeleteIds.length > 0) {
         this.deps.writeToInMemBatch(
@@ -4096,7 +4232,10 @@ var _SyncEngine = class _SyncEngine {
           timestamp: /* @__PURE__ */ new Date()
         });
       } catch (err) {
-        console.error(`[SyncEngine] onConflictResolved callback failed: ${err}`, err);
+        console.error(
+          `[SyncEngine] onConflictResolved callback failed: ${err}`,
+          err
+        );
       }
     }
     return resolved;
@@ -4141,7 +4280,10 @@ var _SyncEngine = class _SyncEngine {
           calledFrom
         });
       } catch (err) {
-        console.error(`[SyncEngine] onFindNewerManyCall callback failed: ${err}`, err);
+        console.error(
+          `[SyncEngine] onFindNewerManyCall callback failed: ${err}`,
+          err
+        );
       }
     }
   }
@@ -4160,7 +4302,10 @@ var _SyncEngine = class _SyncEngine {
           ttfbMs: metrics == null ? void 0 : metrics.ttfbMs
         });
       } catch (err) {
-        console.error(`[SyncEngine] onFindNewerManyResult callback failed: ${err}`, err);
+        console.error(
+          `[SyncEngine] onFindNewerManyResult callback failed: ${err}`,
+          err
+        );
       }
     }
   }
@@ -4173,7 +4318,10 @@ var _SyncEngine = class _SyncEngine {
           calledFrom
         });
       } catch (err) {
-        console.error(`[SyncEngine] onServerWriteRequest callback failed: ${err}`, err);
+        console.error(
+          `[SyncEngine] onServerWriteRequest callback failed: ${err}`,
+          err
+        );
       }
     }
   }
@@ -4188,10 +4336,29 @@ var _SyncEngine = class _SyncEngine {
           calledFrom
         });
       } catch (err) {
-        console.error(`[SyncEngine] onServerWriteResult callback failed: ${err}`, err);
+        console.error(
+          `[SyncEngine] onServerWriteResult callback failed: ${err}`,
+          err
+        );
       }
     }
   }
+  callOnDirtyItemStuck(collection, stuckMetas, calledFrom) {
+    if (!this.callbacks.onDirtyItemStuck || stuckMetas.length === 0) return;
+    try {
+      this.callbacks.onDirtyItemStuck({
+        collection,
+        items: stuckMetas,
+        calledFrom,
+        timestamp: /* @__PURE__ */ new Date()
+      });
+    } catch (err) {
+      console.error(
+        `[SyncEngine] onDirtyItemStuck callback failed: ${err}`,
+        err
+      );
+    }
+  }
   callOnServerSyncWrite(request, response, error, startTime, timestamp, calledFrom) {
     if (!this.callbacks.onServerSyncWrite) return;
     try {
@@ -4209,7 +4376,10 @@ var _SyncEngine = class _SyncEngine {
         timestamp
       });
     } catch (err) {
-      console.error(`[SyncEngine] onServerSyncWrite callback failed: ${err}`, err);
+      console.error(
+        `[SyncEngine] onServerSyncWrite callback failed: ${err}`,
+        err
+      );
     }
   }
 };
@@ -4867,7 +5037,8 @@ var _SyncedDb = class _SyncedDb {
         onServerSyncWrite: config.onServerSyncWrite,
         onFindNewerManyCall: config.onFindNewerManyCall,
         onFindNewerManyResult: config.onFindNewerManyResult,
-        onUploadSkip: config.onUploadSkip
+        onUploadSkip: config.onUploadSkip,
+        onDirtyItemStuck: config.onDirtyItemStuck
       },
       deps: {
         getSyncMetaCache: () => this.syncMetaCache,
@@ -6330,6 +6501,59 @@ var _SyncedDb = class _SyncedDb {
     await this.dexieDb.clearDirtyChanges(collection);
     return metas;
   }
+  /**
+   * Return dirty entries whose `stuckSince` is set across all collections.
+   * A stuck entry has exceeded `DIRTY_STUCK_AFTER_UPLOAD_ATTEMPTS` upload
+   * attempts without success — typically a server-side error that prevents
+   * the record from being accepted.
+   *
+   * Same shape as `getDirtyMeta()` but filtered to stuck items only.
+   * Collections with no stuck items are omitted from the result.
+   */
+  async getStuckItems() {
+    const result = {};
+    for (const [collectionName] of this.collections) {
+      const metas = await this.dexieDb.getDirtyMeta(collectionName);
+      const stuck = metas.filter((m) => m.stuckSince !== void 0);
+      if (stuck.length > 0) {
+        result[collectionName] = stuck;
+      }
+    }
+    return result;
+  }
+  /**
+   * Discard all stuck dirty entries across ALL collections without touching
+   * the main row data. A stuck entry is one where `stuckSince` is set
+   * (exceeded `DIRTY_STUCK_AFTER_UPLOAD_ATTEMPTS` upload attempts).
+   *
+   * Fires `onBeforeDirtyClearAll` once per collection that has stuck items,
+   * with `reason: "discard-stuck"`. Returns the `DirtyMeta[]` of every
+   * entry that was removed.
+   *
+   * Does NOT await in-flight uploads — call `flushToServer()` first if a
+   * last-chance upload is desired.
+   *
+   * @param calledFrom Diagnostic tag threaded through to the callback.
+   */
+  async discardStuckItems(calledFrom) {
+    const cleared = [];
+    for (const [collectionName] of this.collections) {
+      const metas = await this.dexieDb.getDirtyMeta(collectionName);
+      const stuck = metas.filter((m) => m.stuckSince !== void 0);
+      if (stuck.length === 0) continue;
+      this.safeCallback(this.onBeforeDirtyClearAll, {
+        reason: "discard-stuck",
+        collection: collectionName,
+        items: stuck,
+        calledFrom,
+        timestamp: /* @__PURE__ */ new Date()
+      });
+      const ids = stuck.map((m) => m.id);
+      await this.dexieDb.clearDirtyChangesBatch(collectionName, ids);
+      for (const m of stuck) cleared.push(m);
+    }
+    return cleared;
+  }
   // ==================== Data Deletion ====================
   async dropCollection(collection, force = false) {
     this.assertCollection(collection);
@@ -7359,6 +7583,9 @@ var SyncedDb = _SyncedDb;
 // src/db/DexieDb.ts
 import Dexie from "dexie";
 
+// src/types/I_DexieDb.ts
+var DIRTY_STUCK_AFTER_UPLOAD_ATTEMPTS = 2;
+
 // src/utils/computeDiff.ts
 function isDescendantOrEqual(path, candidate) {
   if (path === candidate) return true;
@@ -7645,7 +7872,11 @@ var DexieDb = class extends Dexie {
         baseTs: entry.baseTs,
         baseRev: entry.baseRev,
         createdAt: entry.createdAt,
-        updatedAt: entry.updatedAt
+        updatedAt: entry.updatedAt,
+        firstUploadAttempt: entry.firstUploadAttempt,
+        lastUploadAttempt: entry.lastUploadAttempt,
+        numUploadAttempts: entry.numUploadAttempts,
+        stuckSince: entry.stuckSince
       });
     }
     return result;
@@ -7723,6 +7954,45 @@ var DexieDb = class extends Dexie {
     }
     return result;
   }
+  async incrementDirtyUploadAttempts(collection, ids) {
+    var _a;
+    if (ids.length === 0) return [];
+    const keys = [];
+    for (const id of ids) keys.push([collection, this.idToString(id)]);
+    const entries = await this.dirtyChanges.bulkGet(keys);
+    const now = Date.now();
+    const toUpdate = [];
+    const newlyStuck = [];
+    for (let i = 0; i < entries.length; i++) {
+      const entry = entries[i];
+      if (!entry) continue;
+      entry.numUploadAttempts = ((_a = entry.numUploadAttempts) != null ? _a : 0) + 1;
+      if (entry.firstUploadAttempt === void 0) {
+        entry.firstUploadAttempt = now;
+      }
+      entry.lastUploadAttempt = now;
+      if (entry.numUploadAttempts > DIRTY_STUCK_AFTER_UPLOAD_ATTEMPTS && entry.stuckSince === void 0) {
+        entry.stuckSince = now;
+        newlyStuck.push({
+          collection: entry.collection,
+          id: entry.id,
+          baseTs: entry.baseTs,
+          baseRev: entry.baseRev,
+          createdAt: entry.createdAt,
+          updatedAt: entry.updatedAt,
+          firstUploadAttempt: entry.firstUploadAttempt,
+          lastUploadAttempt: entry.lastUploadAttempt,
+          numUploadAttempts: entry.numUploadAttempts,
+          stuckSince: entry.stuckSince
+        });
+      }
+      toUpdate.push(entry);
+    }
+    if (toUpdate.length > 0) {
+      await this.dirtyChanges.bulkPut(toUpdate);
+    }
+    return newlyStuck;
+  }
   async clearDirtyChange(collection, id) {
     const stringId = this.idToString(id);
     await this.dirtyChanges.delete([collection, stringId]);
@@ -8231,6 +8501,7 @@ function createStructureReader(structure, firstId) {
         inlineObjectReadThreshold = Infinity;
         return readObject();
       }
+      structure.read0 = optimizedReadObject;
       if (structure.highByte === 0)
         structure.read = createSecondByteReader(firstId, structure.read);
       return optimizedReadObject();
@@ -8247,6 +8518,7 @@ function createStructureReader(structure, firstId) {
     return object;
   }
   readObject.count = 0;
+  structure.read0 = readObject;
   if (structure.highByte === 0) {
     return createSecondByteReader(firstId, readObject);
   }
@@ -8646,7 +8918,7 @@ var recordDefinition = (id, highByte) => {
   }
   currentStructures[id] = structure;
   structure.read = createStructureReader(structure, firstByte);
-  return structure.read();
+  return (structure.read0 || structure.read)();
 };
 currentExtensions[0] = () => {
 };
@@ -9024,6 +9296,7 @@ var Packr = class extends Unpackr {
             let newSharedData = (packr3._prepareStructures || prepareStructures)(structures, packr3);
             if (!encodingError) {
               if (packr3.saveStructures(newSharedData, newSharedData.isCompatible) === false) {
+                structures.uninitialized = true;
                 return packr3.pack(value, encodeOptions);
               }
               packr3.lastNamedStructuresLength = sharedLength;

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

@@ -46,6 +46,7 @@ export declare class DexieDb extends Dexie implements I_DexieDb {
     }>): Promise<void>;
     getDirtyChange(collection: string, id: Id): Promise<DirtyChange | undefined>;
     getDirtyChangesBatch(collection: string, ids: Id[]): Promise<Map<string, DirtyChange>>;
+    incrementDirtyUploadAttempts(collection: string, ids: Id[]): Promise<DirtyMeta[]>;
     clearDirtyChange(collection: string, id: Id): Promise<void>;
     clearDirtyChangesBatch(collection: string, ids: Id[]): Promise<void>;
     clearDirtyChanges(collection: string): Promise<void>;

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

@@ -333,6 +333,31 @@ export declare class SyncedDb implements I_SyncedDb {
      * upload is desired.
      */
     clearDirty(collection?: string, ids?: Id[], calledFrom?: string): Promise<DirtyMeta[]>;
+    /**
+     * Return dirty entries whose `stuckSince` is set across all collections.
+     * A stuck entry has exceeded `DIRTY_STUCK_AFTER_UPLOAD_ATTEMPTS` upload
+     * attempts without success — typically a server-side error that prevents
+     * the record from being accepted.
+     *
+     * Same shape as `getDirtyMeta()` but filtered to stuck items only.
+     * Collections with no stuck items are omitted from the result.
+     */
+    getStuckItems(): Promise<Readonly<Record<string, readonly DirtyMeta[]>>>;
+    /**
+     * Discard all stuck dirty entries across ALL collections without touching
+     * the main row data. A stuck entry is one where `stuckSince` is set
+     * (exceeded `DIRTY_STUCK_AFTER_UPLOAD_ATTEMPTS` upload attempts).
+     *
+     * Fires `onBeforeDirtyClearAll` once per collection that has stuck items,
+     * with `reason: "discard-stuck"`. Returns the `DirtyMeta[]` of every
+     * entry that was removed.
+     *
+     * Does NOT await in-flight uploads — call `flushToServer()` first if a
+     * last-chance upload is desired.
+     *
+     * @param calledFrom Diagnostic tag threaded through to the callback.
+     */
+    discardStuckItems(calledFrom?: string): Promise<DirtyMeta[]>;
     dropCollection(collection: string, force?: boolean): Promise<void>;
     dropDatabase(force?: boolean): Promise<void>;
     /**

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

@@ -62,7 +62,7 @@ export declare class SyncEngine implements I_SyncEngine {
     /**
      * Upload dirty items for a specific collection.
      */
-    uploadDirtyItemsForCollection(collection: string): Promise<UploadResult>;
+    uploadDirtyItemsForCollection(collection: string, calledFrom?: string): Promise<UploadResult>;
     /**
      * Process incoming server data for a single collection.
      * Used by referToServer to process findNewer results.
@@ -89,5 +89,6 @@ export declare class SyncEngine implements I_SyncEngine {
     private callOnFindNewerManyResult;
     private callOnServerWriteRequest;
     private callOnServerWriteResult;
+    private callOnDirtyItemStuck;
     private callOnServerSyncWrite;
 }

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

@@ -267,6 +267,7 @@ export interface SyncEngineCallbacks {
     onFindNewerManyCall?: (info: FindNewerManyCallInfo) => void;
     onFindNewerManyResult?: (info: FindNewerManyResultInfo) => void;
     onUploadSkip?: (info: import("../../types/I_SyncedDb").UploadSkipInfo) => void;
+    onDirtyItemStuck?: (info: import("../../types/I_SyncedDb").DirtyItemStuckInfo) => void;
 }
 export interface SyncEngineDeps {
     getSyncMetaCache: () => Map<string, SyncMeta>;
@@ -326,7 +327,7 @@ export interface I_SyncEngine {
     /** Upload dirty items for all collections. */
     uploadDirtyItems(calledFrom?: string): Promise<UploadResult>;
     /** Upload dirty items for a specific collection. */
-    uploadDirtyItemsForCollection(collection: string): Promise<UploadResult>;
+    uploadDirtyItemsForCollection(collection: string, calledFrom?: string): Promise<UploadResult>;
     /** Process incoming server data for a single collection (used by referToServer). */
     processCollectionServerData(collectionName: string, serverData: import("../../types/DbEntity").LocalDbEntity[], opts?: {
         source?: SyncSource;

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

@@ -7,6 +7,11 @@ export interface SyncMeta {
     collection: string;
     lastSyncTs?: any;
 }
+/**
+ * After this many upload attempts without success, the item is considered
+ * stuck and `stuckSince` is set on the DirtyChange entry.
+ */
+export declare const DIRTY_STUCK_AFTER_UPLOAD_ATTEMPTS = 2;
 /**
  * Dirty change entry - tracks accumulated changes for a record
  * Stored in _dirty_changes table with composite key [collection, id]
@@ -26,6 +31,14 @@ export interface DirtyChange {
     createdAt: number;
     /** When last change was accumulated */
     updatedAt: number;
+    /** When this dirty entry was first attempted for upload (ms timestamp) */
+    firstUploadAttempt?: number;
+    /** When this dirty entry was last attempted for upload (ms timestamp) */
+    lastUploadAttempt?: number;
+    /** How many upload attempts have been made so far */
+    numUploadAttempts?: number;
+    /** Set when numUploadAttempts > DIRTY_STUCK_AFTER_UPLOAD_ATTEMPTS (ms timestamp) */
+    stuckSince?: number;
 }
 /**
  * Meta fields of a DirtyChange entry, without the `changes` payload.
@@ -110,6 +123,8 @@ export interface I_DexieDb {
     getDirtyChange(collection: string, id: Id): Promise<DirtyChange | undefined>;
     /** Get dirty change entries for multiple records (batch) */
     getDirtyChangesBatch(collection: string, ids: Id[]): Promise<Map<string, DirtyChange>>;
+    /** Increment upload attempt counters for retained dirty entries. Returns newly stuck DirtyMeta[]. */
+    incrementDirtyUploadAttempts(collection: string, ids: Id[]): Promise<DirtyMeta[]>;
     /** Clear dirty change for a record (after successful sync) */
     clearDirtyChange(collection: string, id: Id): Promise<void>;
     /** Clear dirty changes for multiple records (batch) */

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

@@ -91,6 +91,21 @@ export interface SaveIdMismatchInfo {
     /** Timestamp when mismatch detected */
     timestamp: Date;
 }
+/**
+ * Payload za `onDirtyItemStuck` callback. Sproži se, ko `incrementDirtyUploadAttempts`
+ * nastavi `stuckSince` na DirtyChange entry-ju — pomeni, da je item presegel
+ * `DIRTY_STUCK_AFTER_UPLOAD_ATTEMPTS` neuspelih nalaganj.
+ */
+export interface DirtyItemStuckInfo {
+    /** Collection name */
+    collection: string;
+    /** Meta podatki stuck itemov (vsebujejo `stuckSince`, `numUploadAttempts`, itd.) */
+    items: import("./I_DexieDb").DirtyMeta[];
+    /** Optional caller tag */
+    calledFrom?: string;
+    /** Timestamp when stuck was detected */
+    timestamp: Date;
+}
 /**
  * Callback payload fired by `clearDirty()` when called WITHOUT a
  * `collection` argument (clear-all path). One invocation per
@@ -741,6 +756,19 @@ export interface SyncedDbConfig {
      * reveals which dirty entries hit which skip path.
      */
     onUploadSkip?: (info: UploadSkipInfo) => void;
+    /**
+     * Fired when a dirty item exceeds `DIRTY_STUCK_AFTER_UPLOAD_ATTEMPTS`
+     * upload attempts without server acknowledgement. The item's `stuckSince`
+     * is set and it will remain dirty until manually cleared via
+     * `discardStuckItems()` or `clearDirty()`, or until a future upload
+     * succeeds (which clears the dirty entry normally).
+     *
+     * Fires once per collection per `uploadDirtyItems` cycle, with ALL items
+     * that newly became stuck in that cycle (not previously stuck items).
+     *
+     * Use for alerting / syslog / automatic recovery flows.
+     */
+    onDirtyItemStuck?: (info: DirtyItemStuckInfo) => 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
@@ -1228,6 +1256,20 @@ export interface I_SyncedDb {
      * ki imajo vsaj en dirty zapis. Kolekcije brez dirty vnosov niso vključene.
      */
     getDirtyMeta(): Promise<Readonly<Record<string, readonly DirtyMeta[]>>>;
+    /**
+     * Return dirty entries whose `stuckSince` is set across all collections.
+     * A stuck entry has exceeded `DIRTY_STUCK_AFTER_UPLOAD_ATTEMPTS` upload
+     * attempts without success. Collections with no stuck items are omitted.
+     */
+    getStuckItems(): Promise<Readonly<Record<string, readonly DirtyMeta[]>>>;
+    /**
+     * Discard all stuck dirty entries across ALL collections without touching
+     * the main row data. Fires `onBeforeDirtyClearAll` per collection with
+     * `reason: "discard-stuck"`. Returns the `DirtyMeta[]` of removed entries.
+     *
+     * @param calledFrom Diagnostic tag threaded through to the callback.
+     */
+    discardStuckItems(calledFrom?: string): Promise<DirtyMeta[]>;
     /**
      * Drops a collection, ensuring no data loss.
      * - Throws if offline or forcedOffline (unless force=true)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cry-synced-db-client",
-  "version": "0.1.197",
+  "version": "0.1.200",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -30,16 +30,16 @@
     "@types/bun": "latest",
     "bson": "^7.2.0",
     "cry-ebus-proxy": "^2.0.0",
-    "dexie": "^4.4.2",
-    "esbuild": "^0.28.0",
+    "dexie": "^4.4.3",
+    "esbuild": "^0.28.1",
     "fake-indexeddb": "^6.2.5",
     "typescript": "^6",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.8"
   },
   "dependencies": {
     "cry-db": "^2.5.0",
-    "cry-helpers": "^2.1.194",
-    "msgpackr": "^2.0.1",
+    "cry-helpers": "^2.1.205",
+    "msgpackr": "^2.0.4",
     "superjson": "^2.2.6"
   },
   "peerDependencies": {