cry-synced-db-client 0.1.122 → 0.1.124

package/{VERSIONS.md → CHANGELOG.md}

@@ -1,10 +1,16 @@
 # Versions
 
-## 0.1.122 (2026-04-08)
+## 0.1.124 (2026-04-08)
 
-- Ensure `_id` is never falsy (undefined/null/0/"") in `upsert`, `insert`, and `save`
-  - `upsert`/`insert`: falsy `_id` replaced with new ObjectId before any operation
+- Fix `ensureId` not generating `_id` when key is absent (caused `"undefined"` string ids)
+
+## 0.1.123 (2026-04-08)
+
+- Falsy `_id` guard on all public DB operations with detailed `console.error` messages
+  - `insert`/`upsert`: falsy `_id` replaced with new ObjectId before any operation
   - `save`: falsy `_id` stripped from update partial to prevent overwriting valid id
+  - `findById`/`findByIds`/`deleteOne`/`hardDeleteOne`: warn on falsy `id` parameter
+  - `findOne`/`find`/`deleteMany`/`hardDelete`: warn on falsy `_id` in query object
 
 ## 0.1.120 (2026-04-08)
 

package/dist/index.js

@@ -3877,7 +3877,7 @@ var SyncedDb = class _SyncedDb {
   async findById(collection, id, opts) {
     var _a;
     this.assertCollection(collection);
-    id = this.normalizeId(id);
+    id = this.normalizeId(id, "findById", collection);
     opts = this.resolveOpts(opts);
     if ((_a = this.collections.get(collection)) == null ? void 0 : _a.writeOnly) {
       return this.writeOnlyFindById(collection, id);
@@ -3922,7 +3922,7 @@ var SyncedDb = class _SyncedDb {
   async findByIds(collection, ids, opts) {
     var _a;
     this.assertCollection(collection);
-    ids = ids.map((id) => this.normalizeId(id));
+    ids = ids.map((id) => this.normalizeId(id, "findByIds", collection));
     opts = this.resolveOpts(opts);
     if ((_a = this.collections.get(collection)) == null ? void 0 : _a.writeOnly) {
       return this.writeOnlyFindByIds(collection, ids);
@@ -3964,6 +3964,7 @@ var SyncedDb = class _SyncedDb {
   async findOne(collection, query, opts) {
     var _a, _b;
     this.assertCollection(collection);
+    if (query) this.warnFalsyQueryId(query, "findOne", collection);
     query = _SyncedDb.stringifyObjectIds(query);
     opts = this.resolveOpts(opts);
     if ((_a = this.collections.get(collection)) == null ? void 0 : _a.writeOnly) {
@@ -4010,6 +4011,7 @@ var SyncedDb = class _SyncedDb {
   async find(collection, query, opts) {
     var _a;
     this.assertCollection(collection);
+    if (query) this.warnFalsyQueryId(query, "find", collection);
     if (query) query = _SyncedDb.stringifyObjectIds(query);
     opts = this.resolveOpts(opts);
     if ((_a = this.collections.get(collection)) == null ? void 0 : _a.writeOnly) {
@@ -4126,8 +4128,11 @@ var SyncedDb = class _SyncedDb {
   async save(collection, id, update) {
     var _a, _b;
     this.assertCollection(collection);
-    id = this.normalizeId(id);
+    id = this.normalizeId(id, "save", collection);
     if ("_id" in update && !update._id) {
+      console.error(
+        `SyncedDb.save("${collection}", "${String(id)}"): update._id is present but falsy (${JSON.stringify(update._id)}). Stripped from update to prevent overwriting valid id. This is a bug \u2014 the caller should not pass falsy _id in update. Data keys: [${Object.keys(update).join(", ")}]`
+      );
       delete update._id;
     }
     update = _SyncedDb.stringifyObjectIds(update);
@@ -4157,7 +4162,7 @@ var SyncedDb = class _SyncedDb {
   }
   async upsert(collection, query, update) {
     this.assertCollection(collection);
-    this.ensureId(update);
+    this.ensureId(update, "upsert", collection);
     query = _SyncedDb.stringifyObjectIds(query);
     update = _SyncedDb.stringifyObjectIds(update);
     const existing = await this.findOne(collection, query);
@@ -4170,7 +4175,7 @@ var SyncedDb = class _SyncedDb {
   async insert(collection, data) {
     var _a;
     this.assertCollection(collection);
-    this.ensureId(data);
+    this.ensureId(data, "insert", collection);
     data = _SyncedDb.stringifyObjectIds(data);
     const id = String(data._id);
     const existing = await this.dexieDb.getById(collection, id);
@@ -4198,7 +4203,7 @@ var SyncedDb = class _SyncedDb {
   async deleteOne(collection, id) {
     var _a;
     this.assertCollection(collection);
-    id = this.normalizeId(id);
+    id = this.normalizeId(id, "deleteOne", collection);
     const existing = await this.dexieDb.getById(collection, id);
     if (!existing || existing._deleted) {
       return null;
@@ -4221,6 +4226,7 @@ var SyncedDb = class _SyncedDb {
   }
   async deleteMany(collection, query) {
     this.assertCollection(collection);
+    if (query) this.warnFalsyQueryId(query, "deleteMany", collection);
     const items = await this.find(collection, query);
     if (items.length === 0) return 0;
     const ids = items.map((item) => item._id);
@@ -4259,7 +4265,7 @@ var SyncedDb = class _SyncedDb {
   // ==================== Hard Delete Operations (online only) ====================
   async hardDeleteOne(collection, id) {
     this.assertCollection(collection);
-    id = this.normalizeId(id);
+    id = this.normalizeId(id, "hardDeleteOne", collection);
     if (!this.isOnline()) {
       throw new Error("hardDeleteOne requires online connection");
     }
@@ -4277,6 +4283,7 @@ var SyncedDb = class _SyncedDb {
   }
   async hardDelete(collection, query) {
     this.assertCollection(collection);
+    if (query) this.warnFalsyQueryId(query, "hardDelete", collection);
     if (!this.isOnline()) {
       throw new Error("hardDelete requires online connection");
     }
@@ -4656,17 +4663,40 @@ var SyncedDb = class _SyncedDb {
     }
   }
   /** Stringify an Id parameter (ObjectId → hex string). */
-  normalizeId(id) {
+  normalizeId(id, method, collection) {
+    if (!id && id !== void 0) {
+      console.error(
+        `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.`
+      );
+    }
     return typeof id === "object" && id !== null ? String(id) : id;
   }
   /**
-   * Ensure `_id` on a data object is never falsy.
-   * Replaces undefined / null / 0 / "" with a new ObjectId hex string.
+   * Warn if a query/data object has `_id` present but falsy.
+   * Does NOT mutate — only logs.
+   */
+  warnFalsyQueryId(data, method, collection) {
+    if ("_id" in data && !data._id) {
+      console.error(
+        `SyncedDb.${method}("${collection}"): _id is present in query/data but falsy (${JSON.stringify(data._id)}). This is a bug \u2014 _id must be valid when specified. Data keys: [${Object.keys(data).join(", ")}]`
+      );
+    }
+  }
+  /**
+   * Ensure `_id` on a data object is never falsy or absent.
+   * Replaces undefined / null / 0 / "" / missing with a new ObjectId hex string.
+   * Logs console.error only when `_id` key is present but falsy (caller bug).
    * @mutates — modifies the object in-place and returns it.
    */
-  ensureId(data) {
+  ensureId(data, method, collection) {
     if (!data._id) {
-      data._id = new ObjectId2().toHexString();
+      const newId = new ObjectId2().toHexString();
+      if ("_id" in data) {
+        console.error(
+          `SyncedDb.${method}("${collection}"): _id is present but falsy (${JSON.stringify(data._id)}). Replaced with "${newId}". This is a bug \u2014 the caller should provide a valid _id. Data keys: [${Object.keys(data).join(", ")}]`
+        );
+      }
+      data._id = newId;
     }
     return data;
   }

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

@@ -211,8 +211,14 @@ export declare class SyncedDb implements I_SyncedDb {
     /** Stringify an Id parameter (ObjectId → hex string). */
     private normalizeId;
     /**
-     * Ensure `_id` on a data object is never falsy.
-     * Replaces undefined / null / 0 / "" with a new ObjectId hex string.
+     * Warn if a query/data object has `_id` present but falsy.
+     * Does NOT mutate — only logs.
+     */
+    private warnFalsyQueryId;
+    /**
+     * Ensure `_id` on a data object is never falsy or absent.
+     * Replaces undefined / null / 0 / "" / missing with a new ObjectId hex string.
+     * Logs console.error only when `_id` key is present but falsy (caller bug).
      * @mutates — modifies the object in-place and returns it.
      */
     private ensureId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cry-synced-db-client",
-  "version": "0.1.122",
+  "version": "0.1.124",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -13,7 +13,7 @@
   },
   "files": [
     "dist",
-    "VERSIONS.md"
+    "CHANGELOG.md"
   ],
   "scripts": {
     "clean": "rm -rf dist",