cry-synced-db-client 0.1.124 → 0.1.126

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Versions
 
+## 0.1.126 (2026-04-08)
+
+- Eviction: remove out-of-scope records from Dexie and in-mem cache
+  - `evictOutOfScopeRecords(collection)` — evict records not matching `syncConfig.query`
+  - `evictOutOfScopeRecordsAll()` — evict across all collections, fires `onEviction` callback
+  - `evictStaleRecordsEveryHrs` config — auto-eviction after sync when interval elapsed
+  - `onEviction` callback with `EvictionInfo` (total, duration, trigger, per-collection breakdown)
+  - Dirty records always preserved; deleted/archived evicted; cross-tab reload broadcast emitted
+  - `dropDatabase()` clears `__lastEviction` timestamp
+
+## 0.1.125 (2026-04-08)
+
+- Detect stringified falsy `_id` values (`"undefined"`, `"null"`, `"0"`, `"false"`, `""`) across all DB operations
+
 ## 0.1.124 (2026-04-08)
 
 - Fix `ensureId` not generating `_id` when key is absent (caused `"undefined"` string ids)

package/dist/index.js

@@ -3416,7 +3416,7 @@ var NetworkStatusManager = class {
 };
 
 // src/db/SyncedDb.ts
-var SyncedDb = class _SyncedDb {
+var _SyncedDb = class _SyncedDb {
   constructor(config) {
     this.collections = /* @__PURE__ */ new Map();
     // State
@@ -3428,7 +3428,7 @@ var SyncedDb = class _SyncedDb {
     this.syncOnlyCollections = null;
     // Sync metadata cache
     this.syncMetaCache = /* @__PURE__ */ new Map();
-    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n;
     this.tenant = config.tenant;
     this.dexieDb = config.dexieDb;
     this.inMemDb = config.inMemDb;
@@ -3452,13 +3452,15 @@ var SyncedDb = class _SyncedDb {
     this.onWsNotification = config.onWsNotification;
     this.onCrossTabSync = config.onCrossTabSync;
     this.onWakeSync = config.onWakeSync;
+    this.onEviction = config.onEviction;
+    this.evictStaleRecordsEveryHrs = (_e = config.evictStaleRecordsEveryHrs) != null ? _e : 0;
     for (const col of config.collections) {
       this.collections.set(col.name, col);
     }
     this.inMemManager = new InMemManager({
       inMemDb: this.inMemDb,
       collections: this.collections,
-      useObjectMetadata: (_e = config.useObjectMetadata) != null ? _e : false
+      useObjectMetadata: (_f = config.useObjectMetadata) != null ? _f : false
     });
     this.leaderElection = new LeaderElectionManager({
       tenant: this.tenant,
@@ -3480,7 +3482,7 @@ var SyncedDb = class _SyncedDb {
       tenant: this.tenant,
       instanceId: this.syncedDbInstanceId,
       windowId,
-      debounceMs: (_f = config.crossTabSyncDebounceMs) != null ? _f : 100,
+      debounceMs: (_g = config.crossTabSyncDebounceMs) != null ? _g : 100,
       callbacks: {
         onCrossTabSync: config.onCrossTabSync,
         onInfrastructureError: config.onInfrastructureError ? (type, message, error) => {
@@ -3506,8 +3508,8 @@ var SyncedDb = class _SyncedDb {
     });
     this.connectionManager = new ConnectionManager({
       restInterface: this.restInterface,
-      restTimeoutMs: (_g = config.restTimeoutMs) != null ? _g : 9e4,
-      syncTimeoutMs: (_h = config.syncTimeoutMs) != null ? _h : 12e4,
+      restTimeoutMs: (_h = config.restTimeoutMs) != null ? _h : 9e4,
+      syncTimeoutMs: (_i = config.syncTimeoutMs) != null ? _i : 12e4,
       autoSyncIntervalMs: config.autoSyncIntervalMs,
       callbacks: {
         onOnlineStatusChange: config.onOnlineStatusChange,
@@ -3533,8 +3535,8 @@ var SyncedDb = class _SyncedDb {
     });
     this.pendingChanges = new PendingChangesManager({
       tenant: this.tenant,
-      debounceDexieWritesMs: (_i = config.debounceDexieWritesMs) != null ? _i : 500,
-      debounceRestWritesMs: (_j = config.debounceRestWritesMs) != null ? _j : 100,
+      debounceDexieWritesMs: (_j = config.debounceDexieWritesMs) != null ? _j : 500,
+      debounceRestWritesMs: (_k = config.debounceRestWritesMs) != null ? _k : 100,
       callbacks: {
         onDexieWriteRequest: config.onDexieWriteRequest,
         onDexieWriteResult: config.onDexieWriteResult,
@@ -3611,8 +3613,8 @@ var SyncedDb = class _SyncedDb {
     });
     if (config.wakeSyncEnabled) {
       this.wakeSync = new WakeSyncManager({
-        gapThresholdMs: (_k = config.wakeSyncGapThresholdMs) != null ? _k : 1e4,
-        debounceMs: (_l = config.wakeSyncDebounceMs) != null ? _l : 2e3,
+        gapThresholdMs: (_l = config.wakeSyncGapThresholdMs) != null ? _l : 1e4,
+        debounceMs: (_m = config.wakeSyncDebounceMs) != null ? _m : 2e3,
         callbacks: {
           onWakeSync: config.onWakeSync
         },
@@ -3627,7 +3629,7 @@ var SyncedDb = class _SyncedDb {
     }
     if (config.networkStatusEnabled) {
       this.networkStatus = new NetworkStatusManager({
-        debounceMs: (_m = config.networkStatusDebounceMs) != null ? _m : 100,
+        debounceMs: (_n = config.networkStatusDebounceMs) != null ? _n : 100,
         callbacks: {
           onBrowserNetworkChange: config.onBrowserNetworkChange,
           onBrowserOnline: config.onBrowserOnline,
@@ -4360,6 +4362,11 @@ var SyncedDb = class _SyncedDb {
       this.syncLock = false;
       this.crossTabSync.endServerSync();
       await this.processQueuedWsUpdates();
+      try {
+        await this.maybeAutoEvict();
+      } catch (err) {
+        console.error("Auto-eviction failed:", err);
+      }
     }
   }
   async processQueuedWsUpdates() {
@@ -4500,6 +4507,8 @@ var SyncedDb = class _SyncedDb {
     }
     this.syncMetaCache.clear();
     this._clearLastFullSync();
+    this._lastEvictionDate = void 0;
+    await this.dexieDb.deleteSyncMeta("__lastEviction");
   }
   /**
    * Clear all collection data and sync metadata, then re-download
@@ -4526,6 +4535,108 @@ var SyncedDb = class _SyncedDb {
     this.syncMetaCache.clear();
     this._clearLastFullSync();
   }
+  // ==================== Eviction ====================
+  /**
+   * Remove records from Dexie and in-mem that no longer match the
+   * collection's current syncConfig.query. Does NOT delete from server.
+   * Skips records with dirty changes (pending local writes).
+   */
+  async evictOutOfScopeRecords(collection) {
+    var _a;
+    this.assertCollection(collection);
+    const config = this.collections.get(collection);
+    const syncQuery = (_a = config.syncConfig) == null ? void 0 : _a.query;
+    const query = typeof syncQuery === "function" ? syncQuery() : syncQuery;
+    if (!query) {
+      return { collection, evictedCount: 0, dirtySkipped: 0, scannedCount: 0 };
+    }
+    await this.pendingChanges.flushForCollection(collection);
+    const dirtyItems = await this.dexieDb.getDirty(collection);
+    const dirtyIds = new Set(dirtyItems.map((d) => String(d._id)));
+    let scannedCount = 0;
+    let dirtySkipped = 0;
+    const evictIds = [];
+    await this.dexieDb.forEachBatch(
+      collection,
+      2e3,
+      async (items) => {
+        for (const item of items) {
+          scannedCount++;
+          const id = String(item._id);
+          if (dirtyIds.has(id)) {
+            dirtySkipped++;
+            continue;
+          }
+          if (!matchesQuery(item, query)) {
+            evictIds.push(id);
+          }
+        }
+      }
+    );
+    if (evictIds.length > 0) {
+      await this.dexieDb.deleteMany(collection, evictIds);
+      if (!config.writeOnly) {
+        this.inMemManager.writeBatch(
+          collection,
+          evictIds.map((id) => ({ _id: id })),
+          "delete"
+        );
+      }
+      this.crossTabSync.broadcastReload([collection]);
+    }
+    return { collection, evictedCount: evictIds.length, dirtySkipped, scannedCount };
+  }
+  /**
+   * Evict out-of-scope records for all collections.
+   * Skips writeOnly and collections without syncConfig.query.
+   * Fires onEviction callback.
+   */
+  async evictOutOfScopeRecordsAll(trigger = "manual") {
+    var _a;
+    const startTime = Date.now();
+    const collectionResults = [];
+    let totalEvicted = 0;
+    for (const [name, config] of this.collections) {
+      if (config.writeOnly) continue;
+      const syncQuery = (_a = config.syncConfig) == null ? void 0 : _a.query;
+      const query = typeof syncQuery === "function" ? syncQuery() : syncQuery;
+      if (!query) continue;
+      const result = await this.evictOutOfScopeRecords(name);
+      collectionResults.push(result);
+      totalEvicted += result.evictedCount;
+    }
+    const info = {
+      totalEvicted,
+      durationMs: Date.now() - startTime,
+      trigger,
+      collections: collectionResults
+    };
+    this.safeCallback(this.onEviction, info);
+    return info;
+  }
+  /**
+   * Check if auto-eviction should run and execute if interval has elapsed.
+   * Called after sync() and at end of init().
+   */
+  async maybeAutoEvict() {
+    if (this.evictStaleRecordsEveryHrs <= 0) return;
+    const intervalMs = this.evictStaleRecordsEveryHrs * 36e5;
+    if (!this._lastEvictionDate) {
+      const meta = await this.dexieDb.getSyncMeta("__lastEviction");
+      if (meta == null ? void 0 : meta.lastSyncTs) {
+        this._lastEvictionDate = new Date(meta.lastSyncTs);
+      }
+    }
+    if (this._lastEvictionDate && Date.now() - this._lastEvictionDate.getTime() < intervalMs) {
+      return;
+    }
+    await this.evictOutOfScopeRecordsAll("auto");
+    this._lastEvictionDate = /* @__PURE__ */ new Date();
+    await this.dexieDb.setSyncMeta(
+      "__lastEviction",
+      this._lastEvictionDate.toISOString()
+    );
+  }
   // ==================== Object Metadata ====================
   getObjectMetadata(collection, _id) {
     return this.inMemManager.getObjectMetadata(collection, _id);
@@ -4669,6 +4780,11 @@ var SyncedDb = class _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.`
       );
     }
+    if (typeof id === "string" && _SyncedDb.STRINGIFIED_FALSY.has(id)) {
+      console.error(
+        `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.`
+      );
+    }
     return typeof id === "object" && id !== null ? String(id) : id;
   }
   /**
@@ -4681,6 +4797,11 @@ var SyncedDb = class _SyncedDb {
         `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(", ")}]`
       );
     }
+    if ("_id" in data && typeof data._id === "string" && _SyncedDb.STRINGIFIED_FALSY.has(data._id)) {
+      console.error(
+        `SyncedDb.${method}("${collection}"): _id is a stringified falsy value ("${data._id}"). This is a bug \u2014 a falsy value was coerced to string before being passed as _id. Data keys: [${Object.keys(data).join(", ")}]`
+      );
+    }
   }
   /**
    * Ensure `_id` on a data object is never falsy or absent.
@@ -4689,6 +4810,12 @@ var SyncedDb = class _SyncedDb {
    * @mutates — modifies the object in-place and returns it.
    */
   ensureId(data, method, collection) {
+    if (typeof data._id === "string" && _SyncedDb.STRINGIFIED_FALSY.has(data._id)) {
+      console.error(
+        `SyncedDb.${method}("${collection}"): _id is a stringified falsy value ("${data._id}"). This is a bug \u2014 a falsy value was coerced to string before being passed as _id. Data keys: [${Object.keys(data).join(", ")}]`
+      );
+      data._id = null;
+    }
     if (!data._id) {
       const newId = new ObjectId2().toHexString();
       if ("_id" in data) {
@@ -4765,6 +4892,14 @@ var SyncedDb = class _SyncedDb {
     );
   }
 };
+_SyncedDb.STRINGIFIED_FALSY = /* @__PURE__ */ new Set([
+  "undefined",
+  "null",
+  "0",
+  "false",
+  ""
+]);
+var SyncedDb = _SyncedDb;
 
 // src/db/DexieDb.ts
 import Dexie from "dexie";

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

@@ -1,5 +1,5 @@
 import type { AggregateOptions } from "mongodb";
-import type { I_SyncedDb, SyncedDbConfig, WsNotificationInfo } from "../types/I_SyncedDb";
+import type { I_SyncedDb, SyncedDbConfig, WsNotificationInfo, EvictionInfo, EvictionCollectionInfo } from "../types/I_SyncedDb";
 import type { MetaUpdateBroadcast } from "../types/I_DexieDb";
 import type { QuerySpec, QueryOpts, UpdateSpec, InsertSpec, BatchSpec } from "../types/I_RestInterface";
 import type { Id, DbEntity } from "../types/DbEntity";
@@ -50,6 +50,9 @@ export declare class SyncedDb implements I_SyncedDb {
     private readonly onWsNotification?;
     private readonly onCrossTabSync?;
     private readonly onWakeSync?;
+    private readonly onEviction?;
+    private readonly evictStaleRecordsEveryHrs;
+    private _lastEvictionDate?;
     constructor(config: SyncedDbConfig);
     getInstanceId(): string;
     getCrossTabSyncDebounceMs(): number;
@@ -167,6 +170,23 @@ export declare class SyncedDb implements I_SyncedDb {
      * The sync will also upload any remaining dirty items.
      */
     refreshDatabaseFromServer(): Promise<void>;
+    /**
+     * Remove records from Dexie and in-mem that no longer match the
+     * collection's current syncConfig.query. Does NOT delete from server.
+     * Skips records with dirty changes (pending local writes).
+     */
+    evictOutOfScopeRecords(collection: string): Promise<EvictionCollectionInfo>;
+    /**
+     * Evict out-of-scope records for all collections.
+     * Skips writeOnly and collections without syncConfig.query.
+     * Fires onEviction callback.
+     */
+    evictOutOfScopeRecordsAll(trigger?: "auto" | "manual"): Promise<EvictionInfo>;
+    /**
+     * Check if auto-eviction should run and execute if interval has elapsed.
+     * Called after sync() and at end of init().
+     */
+    private maybeAutoEvict;
     getObjectMetadata<M>(collection: string, _id: Id): M | undefined;
     getObjectsMetadata<M>(collection: string, _ids: Id[]): (M | undefined)[];
     setObjectMetadata<M>(collection: string, _id: Id, metadata: M): void;
@@ -208,6 +228,7 @@ export declare class SyncedDb implements I_SyncedDb {
     private loadCollectionsToInMem;
     private loadCollectionToInMem;
     private assertCollection;
+    private static readonly STRINGIFIED_FALSY;
     /** Stringify an Id parameter (ObjectId → hex string). */
     private normalizeId;
     /**

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

@@ -62,6 +62,6 @@ export declare class CrossTabSyncManager implements I_CrossTabSyncManager {
     private handleCrossTabMetaUpdate;
     private handleReloadBroadcast;
     private handleDeltaBroadcast;
-    private broadcastReload;
+    broadcastReload(collections: string[]): void;
     private callOnInfrastructureError;
 }

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

@@ -82,6 +82,8 @@ export interface I_CrossTabSyncManager {
      * Emits a single reload broadcast for all collections touched during the sync.
      */
     endServerSync(): void;
+    /** Emit a reload broadcast for the given collections. */
+    broadcastReload(collections: string[]): void;
     /** Cleanup resources. */
     dispose(): void;
     /** Handle external broadcast (for testing). */

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

@@ -228,6 +228,32 @@ export interface SyncInfo {
     /** Per-collection sync statistics (collection name -> stats) */
     collections?: Record<string, CollectionSyncStats>;
 }
+/** Per-collection eviction statistics. */
+export interface EvictionCollectionInfo {
+    /** Collection name. */
+    collection: string;
+    /** Records removed from Dexie + in-mem. */
+    evictedCount: number;
+    /** Records skipped because they have pending dirty changes. */
+    dirtySkipped: number;
+    /** Total records scanned in this collection. */
+    scannedCount: number;
+}
+/** Eviction result reported to the onEviction callback. */
+export interface EvictionInfo {
+    /** Total records evicted across all collections. */
+    totalEvicted: number;
+    /** Wall-clock duration of the eviction operation in ms. */
+    durationMs: number;
+    /** Whether this was triggered automatically or by manual call. */
+    trigger: "auto" | "manual";
+    /**
+     * Per-collection breakdown.
+     * Only collections with syncConfig.query are included.
+     * Collections where evictedCount === 0 ARE included.
+     */
+    collections: EvictionCollectionInfo[];
+}
 /**
  * Configuration for collection sync behavior (used in sync() method only, not uploadDirtyItems)
  */
@@ -469,6 +495,15 @@ export interface SyncedDbConfig {
      * Note: This is different from onOnlineStatusChange which fires after SyncedDb processes the change.
      */
     onBrowserOffline?: () => void;
+    /**
+     * Auto-eviction interval in hours. When set (> 0), eviction runs
+     * automatically after init and each sync cycle if the interval has elapsed.
+     * Stores last eviction timestamp in Dexie via syncMeta key `__lastEviction`.
+     * Default: 0 (disabled).
+     */
+    evictStaleRecordsEveryHrs?: number;
+    /** Callback fired after each eviction run (manual or auto). Errors are swallowed. */
+    onEviction?: (info: EvictionInfo) => void;
 }
 /**
  * Glavna logika za sinhronizirano bazo podatkov
@@ -670,6 +705,19 @@ export interface I_SyncedDb {
      * Unlike dropDatabase(), this never discards unsynchronized edits.
      */
     refreshDatabaseFromServer(): Promise<void>;
+    /**
+     * Remove records from Dexie and in-mem that no longer match the
+     * collection's current syncConfig.query. Does NOT delete from server.
+     * Skips records with dirty changes (pending local writes).
+     * Returns per-collection eviction stats.
+     */
+    evictOutOfScopeRecords(collection: string): Promise<EvictionCollectionInfo>;
+    /**
+     * Same as evictOutOfScopeRecords but for all configured collections.
+     * Skips writeOnly collections and collections without syncConfig.query.
+     * Fires onEviction callback with full stats.
+     */
+    evictOutOfScopeRecordsAll(): Promise<EvictionInfo>;
     /**
      * Check if this instance is the leader tab.
      * Only the leader processes server notifications and writes to Dexie from server updates.

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

@@ -4,7 +4,7 @@ export type { Obj, QuerySpec, Projection, QueryOpts, KeyOf, InsertKeyOf, InsertS
 export type { I_InMemDb as InMemDb } from "./I_InMemDb";
 export type { I_DexieDb as DexieDb, SyncMeta } from "./I_DexieDb";
 export type { I_ServerUpdateNotifier as ServerUpdateNotifier, ServerUpdateCallback, ServerUpdateNotifierCallbacks } from "./I_ServerUpdateNotifier";
-export type { I_SyncedDb as SyncedDb, SyncedDbConfig, CollectionConfig, CollectionSyncConfig, SyncInfo, ServerWriteRequestInfo, ServerWriteResultInfo, FindNewerManyCallInfo, FindNewerManyResultInfo, DexieWriteRequestInfo, DexieWriteResultInfo, LocalstorageWriteResultInfo, WsNotificationInfo, InfrastructureErrorType, InfrastructureErrorInfo, ConflictSource, ConflictResolutionReport, CrossTabSyncInfo, } from "./I_SyncedDb";
+export type { I_SyncedDb as SyncedDb, SyncedDbConfig, CollectionConfig, CollectionSyncConfig, SyncInfo, ServerWriteRequestInfo, ServerWriteResultInfo, FindNewerManyCallInfo, FindNewerManyResultInfo, DexieWriteRequestInfo, DexieWriteResultInfo, LocalstorageWriteResultInfo, WsNotificationInfo, InfrastructureErrorType, InfrastructureErrorInfo, ConflictSource, ConflictResolutionReport, CrossTabSyncInfo, EvictionInfo, EvictionCollectionInfo, } from "./I_SyncedDb";
 export type { NetworkStatusChangeInfo } from "../db/types/managers";
 export type { CollectionConfig as CollectionConfigFull, CollectionSyncConfig as CollectionSyncConfigFull } from "./CollectionConfig";
 export type { Rdb2CallMap, Rdb2Operation } from "./Rdb2CallMap";

package/package.json

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