cry-synced-db-client 0.1.197 → 0.1.199

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Versions
 
+## 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

@@ -3508,7 +3508,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);
@@ -3664,6 +3664,15 @@ 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;
@@ -3717,8 +3726,26 @@ 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);
+      }
       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 = [];
@@ -3857,7 +3884,7 @@ 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 };
@@ -3955,6 +3982,24 @@ 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,
@@ -4192,6 +4237,19 @@ var _SyncEngine = class _SyncEngine {
       }
     }
   }
+  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 {
@@ -4867,7 +4925,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 +6389,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 +7471,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 +7760,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 +7842,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 +8389,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 +8406,7 @@ function createStructureReader(structure, firstId) {
     return object;
   }
   readObject.count = 0;
+  structure.read0 = readObject;
   if (structure.highByte === 0) {
     return createSecondByteReader(firstId, readObject);
   }
@@ -8646,7 +8806,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 +9184,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.199",
   "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": {