cry-synced-db-client 0.1.216 → 0.1.218

package/dist/index.js

@@ -7684,17 +7684,30 @@ var _SyncedDb = class _SyncedDb {
       }
     }
   }
-  /** Stringify an Id parameter (ObjectId → hex string). */
+  /**
+   * Stringify an Id parameter (ObjectId → hex string).
+   *
+   * Throws when `id` is falsy (null, undefined, 0, "", false) or is a
+   * stringified-falsy value ("undefined", "null", "0", "false", "").
+   * Passing a garbage _id creates a stuck dirty item that can never be
+   * uploaded (server rejects it) and can never be auto-healed (library
+   * doesn't know the correct _id). Fail-fast prevents silent data loss.
+   */
   normalizeId(id, method, collection) {
     if (!id && id !== void 0) {
-      console.error(
-        `[SyncedDb] SyncedDb.${method != null ? method : "?"}("${collection != null ? collection : "?"}"): id parameter is falsy (${JSON.stringify(id)}). This is a bug \u2014 the caller must provide a valid _id.`
-      );
+      const msg = `[SyncedDb] SyncedDb.${method != null ? method : "?"}("${collection != null ? collection : "?"}"): id parameter is falsy (${JSON.stringify(id)}). This is a bug \u2014 the caller must provide a valid _id.`;
+      console.error(msg);
+      throw new Error(msg);
     }
     if (typeof id === "string" && _SyncedDb.STRINGIFIED_FALSY.has(id)) {
-      console.error(
-        `[SyncedDb] SyncedDb.${method != null ? method : "?"}("${collection != null ? collection : "?"}"): id is a stringified falsy value ("${id}"). This is a bug \u2014 a falsy value was coerced to string before being passed as _id.`
-      );
+      const msg = `[SyncedDb] SyncedDb.${method != null ? method : "?"}("${collection != null ? collection : "?"}"): id is a stringified falsy value ("${id}"). This is a bug \u2014 a falsy value was coerced to string before being passed as _id.`;
+      console.error(msg);
+      throw new Error(msg);
+    }
+    if (id === void 0) {
+      const msg = `[SyncedDb] SyncedDb.${method != null ? method : "?"}("${collection != null ? collection : "?"}"): id parameter is undefined. This is a bug \u2014 the caller must provide a valid _id.`;
+      console.error(msg);
+      throw new Error(msg);
     }
     return typeof id === "object" && id !== null ? String(id) : id;
   }
@@ -7976,7 +7989,30 @@ var DexieDb = class extends Dexie {
     }
     return table;
   }
-  idToString(id) {
+  /**
+   * Convert an Id to its string representation for IndexedDB key storage.
+   * Throws on falsy values to prevent stuck-dirty items with garbage
+   * _id values like "undefined" / "null" that can never be uploaded.
+   */
+  idToString(id, debugContext) {
+    if (!id && id !== void 0) {
+      console.error(
+        `[DexieDb.idToString] id is falsy (${JSON.stringify(id)}, type ${typeof id}). `,
+        debugContext
+      );
+    }
+    if (id === void 0) {
+      console.error(
+        `[DexieDb.idToString] id is undefined. `,
+        debugContext
+      );
+    }
+    if (typeof id === "string" && (id === "undefined" || id === "null" || id === "0" || id === "false" || id === "")) {
+      console.error(
+        `[DexieDb.idToString] id is a stringified falsy value ("${id}"). `,
+        debugContext
+      );
+    }
     return String(id);
   }
   /** Ensure _id is a primitive string. IndexedDB rejects ObjectId objects as keys. */
@@ -7987,7 +8023,7 @@ var DexieDb = class extends Dexie {
   }
   async save(collection, id, data) {
     const table = this.getTable(collection);
-    const key = this.idToString(id);
+    const key = this.idToString(id, { collection, id, data, calledFrom: "DexieDb/save" });
     const existing = await table.get(key);
     if (existing) {
       await table.update(key, data);
@@ -8032,14 +8068,14 @@ var DexieDb = class extends Dexie {
   }
   async deleteOne(collection, id) {
     const table = this.getTable(collection);
-    const key = this.idToString(id);
+    const key = this.idToString(id, { collection, id, calledFrom: "DexieDb/deleteOne" });
     await table.delete(key);
   }
   async deleteMany(collection, ids) {
     if (ids.length === 0) return;
     const table = this.getTable(collection);
     const keys = [];
-    for (const id of ids) keys.push(this.idToString(id));
+    for (const id of ids) keys.push(this.idToString(id, { collection, id, ids, calledFrom: "DexieDb/deleteMany" }));
     await table.bulkDelete(keys);
   }
   async saveCollection(collection, data) {
@@ -8056,14 +8092,14 @@ var DexieDb = class extends Dexie {
   }
   async getById(collection, id) {
     const table = this.getTable(collection);
-    const key = this.idToString(id);
+    const key = this.idToString(id, { collection, id, calledFrom: "DexieDb/getById" });
     return await table.get(key);
   }
   async getByIds(collection, ids) {
     if (ids.length === 0) return [];
     const table = this.getTable(collection);
     const keys = [];
-    for (const id of ids) keys.push(this.idToString(id));
+    for (const id of ids) keys.push(this.idToString(id, { collection, ids, calledFrom: "DexieDb/getByIds" }));
     return await table.bulkGet(keys);
   }
   async getAll(collection) {
@@ -8116,7 +8152,7 @@ var DexieDb = class extends Dexie {
   }
   async addDirtyChange(collection, id, changes, baseMeta) {
     if (isMetaOnlyChanges(changes)) return;
-    const stringId = this.idToString(id);
+    const stringId = this.idToString(id, { collection, id, changes, baseMeta, calledFrom: "DexieDb/addDirtyChange" });
     const existing = await this.dirtyChanges.get([collection, stringId]);
     const now = Date.now();
     if (existing) {
@@ -8143,12 +8179,12 @@ var DexieDb = class extends Dexie {
     if (filtered.length === 0) return;
     const now = Date.now();
     const keys = [];
-    for (const c of filtered) keys.push([collection, this.idToString(c.id)]);
+    for (const c of filtered) keys.push([collection, this.idToString(c.id, { collection, changesList, c, calledFrom: "DexieDb/addDirtyChangesBatch" })]);
     const existingEntries = await this.dirtyChanges.bulkGet(keys);
     const toWrite = [];
     for (let i = 0; i < filtered.length; i++) {
       const changeItem = filtered[i];
-      const stringId = this.idToString(changeItem.id);
+      const stringId = this.idToString(changeItem.id, { collection, changesList, changeItem, calledFrom: "DexieDb/addDirtyChangesBatch" });
       const existing = existingEntries[i];
       if (existing) {
         rebaseDirtyOnServerAdvance(existing, changeItem.changes, changeItem.baseMeta);
@@ -8170,19 +8206,19 @@ var DexieDb = class extends Dexie {
     await this.dirtyChanges.bulkPut(toWrite);
   }
   async getDirtyChange(collection, id) {
-    const stringId = this.idToString(id);
+    const stringId = this.idToString(id, { collection, id, calledFrom: "DexieDb/getDirtyChange" });
     return this.dirtyChanges.get([collection, stringId]);
   }
   async getDirtyChangesBatch(collection, ids) {
     const result = /* @__PURE__ */ new Map();
     if (ids.length === 0) return result;
     const keys = [];
-    for (const id of ids) keys.push([collection, this.idToString(id)]);
+    for (const id of ids) keys.push([collection, this.idToString(id, { collection, ids, id, calledFrom: "DexieDb/getDirtyChangesBatch" })]);
     const entries = await this.dirtyChanges.bulkGet(keys);
     for (let i = 0; i < ids.length; i++) {
       const entry = entries[i];
       if (entry) {
-        result.set(this.idToString(ids[i]), entry);
+        result.set(this.idToString(ids[i], { collection, ids, entry, calledFrom: "DexieDb/getDirtyChangesBatch" }), entry);
       }
     }
     return result;
@@ -8191,7 +8227,7 @@ var DexieDb = class extends Dexie {
     var _a;
     if (ids.length === 0) return [];
     const keys = [];
-    for (const id of ids) keys.push([collection, this.idToString(id)]);
+    for (const id of ids) keys.push([collection, this.idToString(id, { collection, id, ids, calledFrom: "DexieDb/incrementDirtyUploadAttempts" })]);
     const entries = await this.dirtyChanges.bulkGet(keys);
     const now = Date.now();
     const toUpdate = [];
@@ -8227,7 +8263,7 @@ var DexieDb = class extends Dexie {
     return newlyStuck;
   }
   async clearDirtyChange(collection, id) {
-    const stringId = this.idToString(id);
+    const stringId = this.idToString(id, { collection, id, calledFrom: "DexieDb/clearDirtyChange" });
     await this.dirtyChanges.delete([collection, stringId]);
   }
   async clearDirtyChangesBatch(collection, ids) {
@@ -8235,7 +8271,7 @@ var DexieDb = class extends Dexie {
     const promises = [];
     for (const id of ids) {
       promises.push(
-        this.dirtyChanges.delete([collection, this.idToString(id)])
+        this.dirtyChanges.delete([collection, this.idToString(id, { collection, id, ids, calledFrom: "DexieDb/clearDirtyChangesBatch" })])
       );
     }
     await Promise.all(promises);

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

@@ -15,6 +15,11 @@ export declare class DexieDb extends Dexie implements I_DexieDb {
     private _isNewDatabase;
     constructor(tenant: string, collectionConfigs: CollectionConfig<any>[]);
     private getTable;
+    /**
+     * Convert an Id to its string representation for IndexedDB key storage.
+     * Throws on falsy values to prevent stuck-dirty items with garbage
+     * _id values like "undefined" / "null" that can never be uploaded.
+     */
     private idToString;
     /** Ensure _id is a primitive string. IndexedDB rejects ObjectId objects as keys. */
     private ensureStringId;

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

@@ -617,7 +617,15 @@ export declare class SyncedDb implements I_SyncedDb {
      */
     private _autoRegisterTemporaryForFind;
     private static readonly STRINGIFIED_FALSY;
-    /** Stringify an Id parameter (ObjectId → hex string). */
+    /**
+     * Stringify an Id parameter (ObjectId → hex string).
+     *
+     * Throws when `id` is falsy (null, undefined, 0, "", false) or is a
+     * stringified-falsy value ("undefined", "null", "0", "false", "").
+     * Passing a garbage _id creates a stuck dirty item that can never be
+     * uploaded (server rejects it) and can never be auto-healed (library
+     * doesn't know the correct _id). Fail-fast prevents silent data loss.
+     */
     private normalizeId;
     /**
      * Warn if a query/data object has `_id` present but falsy.

package/package.json

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