cry-synced-db-client 0.1.187 → 0.1.188

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Versions
 
+## 0.1.188 (2026-05-15)
+
+### `clearDirty()` — manual dirty drain + `onBeforeDirtyClearAll` callback
+
+Public counterpart to `getDirty` / `getDirtyMeta` for the "stuck dirty
+drain" recovery flow. Use case: a known-bad dirty entry can't upload
+(e.g. pre-fix `sestevki` parent+descendant producing repeated 500-loops
+on klikvet tabs running pre-0.1.185 bundles) and the operator wants to
+forfeit the pending local intent in favor of server state — without
+calling the heavier `dropCollection` / `dropDatabase` which also wipes
+the main row data.
+
+```typescript
+clearDirty(
+  collection?: string,
+  ids?: Id[],
+  calledFrom?: string,
+): Promise<DirtyMeta[]>
+```
+
+Returns the `DirtyMeta[]` of every entry that was actually removed, so
+the caller can archive what was lost.
+
+| Call shape | Effect | Fires `onBeforeDirtyClearAll` |
+|---|---|---|
+| `clearDirty()` / `clearDirty(undefined)` | Clear ALL dirty in EVERY collection | ✅ once per collection that has dirty |
+| `clearDirty(coll)` | Clear all dirty in one collection | ❌ |
+| `clearDirty(coll, ids)` | Clear specific ids in that collection | ❌ |
+| `clearDirty(undefined, ids)` | Throws — ambiguous | — |
+
+The new config callback:
+
+```typescript
+onBeforeDirtyClearAll?: (info: BeforeDirtyClearAllInfo) => void;
+
+interface BeforeDirtyClearAllInfo {
+  reason: string;             // `calledFrom` if provided, else "manual"
+  collection: string;
+  items: DirtyMeta[];         // every entry in that collection (no `changes` payload)
+  calledFrom?: string;        // passthrough of the third arg
+  timestamp: Date;
+}
+```
+
+Fires **only** on the clear-all path, **before** the Dexie delete runs,
+**once per collection** with dirty. Use to archive the dirty state to
+syslog / audit trail before it disappears. Per-collection /
+per-id `clearDirty` calls are intentionally silent — the caller already
+knows what they're touching.
+
+```typescript
+new SyncedDb({
+  // ...
+  onBeforeDirtyClearAll: (info) => {
+    syslog.warn("dirty cleared", {
+      collection: info.collection,
+      count: info.items.length,
+      reason: info.reason,
+      ids: info.items.map((m) => m.id),
+    });
+  },
+});
+
+// Nuke everything across collections, tagged for the audit log.
+const cleared = await syncedDb.clearDirty(undefined, undefined, "stuck-drain");
+
+// Targeted: drop two known-bad rows in `obiski` (silent — no callback).
+await syncedDb.clearDirty("obiski", ["6a032a59...", "6a05a1ba..."]);
+
+// Inspect first, then decide.
+const meta = await syncedDb.getDirtyMeta();
+for (const [coll, items] of Object.entries(meta)) {
+  if (items.length > 100) {
+    await syncedDb.clearDirty(coll, undefined, `over-threshold:${items.length}`);
+  }
+}
+```
+
+`clearDirty` does NOT await in-flight uploads — call `flushToServer()`
+first if a last-chance upload is desired. It also does not touch the
+main row data; in-mem and Dexie rows are preserved at whatever state
+they're at (typically: the server's view if WS-push has landed
+recently, otherwise the pre-rollback local intent).
+
 ## 0.1.187 (2026-05-16)
 
 ### Fix: `setByPath` auto-creates plain-object intermediates (root cause of `sestevki` parent+child conflict)

package/dist/index.js

@@ -4484,6 +4484,7 @@ var _SyncedDb = class _SyncedDb {
     this.onEviction = config.onEviction;
     this.onSaveIdMismatch = config.onSaveIdMismatch;
     this.onUploadSkip = config.onUploadSkip;
+    this.onBeforeDirtyClearAll = config.onBeforeDirtyClearAll;
     this.evictStaleRecordsEveryHrs = (_e = config.evictStaleRecordsEveryHrs) != null ? _e : 0;
     this.scopeExitLookbehindMs = (_f = config.scopeExitLookbehindMs) != null ? _f : 0;
     this.evictOnWake = (_g = config.evictOnWake) != null ? _g : false;
@@ -5759,6 +5760,68 @@ var _SyncedDb = class _SyncedDb {
     }
     return result;
   }
+  /**
+   * Manually clear pending dirty changes WITHOUT touching the main
+   * row data. Counterpart to `getDirty` / `getDirtyMeta` for the
+   * "stuck dirty drain" recovery flow — when a known-bad dirty entry
+   * can't be uploaded (e.g. pre-fix sestevki parent+descendant
+   * conflict producing repeated 500s) and the operator wants to
+   * forfeit the pending local intent in favor of server state.
+   *
+   * Three call shapes:
+   *
+   * | Call | Effect |
+   * |---|---|
+   * | `clearDirty()` / `clearDirty(undefined)` | Clear ALL dirty in EVERY collection. Fires `onBeforeDirtyClearAll` once per collection that has dirty (BEFORE the Dexie delete). |
+   * | `clearDirty(coll)` | Clear all dirty in one collection. No callback. |
+   * | `clearDirty(coll, ids)` | Clear specific ids in that collection. No callback. |
+   * | `clearDirty(undefined, ids)` | Throws — ambiguous (which collection do the ids belong to?). |
+   *
+   * Returns the `DirtyMeta[]` of every entry that was actually
+   * removed so the caller can log / archive what was lost.
+   *
+   * Pairs naturally with `getDirtyMeta()` for the inspect-then-clear
+   * pattern. Doesn't await in-flight uploads — caller's
+   * responsibility to call `flushToServer()` first if a last-chance
+   * upload is desired.
+   */
+  async clearDirty(collection, ids, calledFrom) {
+    if (!collection && ids && ids.length > 0) {
+      throw new Error(
+        `[SyncedDb] clearDirty: 'ids' requires a 'collection' \u2014 ids alone are ambiguous across collections.`
+      );
+    }
+    const cleared = [];
+    if (!collection) {
+      for (const [name] of this.collections) {
+        const metas2 = await this.dexieDb.getDirtyMeta(name);
+        if (metas2.length === 0) continue;
+        this.safeCallback(this.onBeforeDirtyClearAll, {
+          reason: calledFrom != null ? calledFrom : "manual",
+          collection: name,
+          items: metas2,
+          calledFrom,
+          timestamp: /* @__PURE__ */ new Date()
+        });
+        await this.dexieDb.clearDirtyChanges(name);
+        for (const m of metas2) cleared.push(m);
+      }
+      return cleared;
+    }
+    this.assertCollection(collection);
+    if (ids && ids.length > 0) {
+      const idStrings = new Set(ids.map((id) => String(id)));
+      const allMetas = await this.dexieDb.getDirtyMeta(collection);
+      for (const m of allMetas) {
+        if (idStrings.has(String(m.id))) cleared.push(m);
+      }
+      await this.dexieDb.clearDirtyChangesBatch(collection, ids);
+      return cleared;
+    }
+    const metas = await this.dexieDb.getDirtyMeta(collection);
+    await this.dexieDb.clearDirtyChanges(collection);
+    return metas;
+  }
   // ==================== Data Deletion ====================
   async dropCollection(collection, force = false) {
     this.assertCollection(collection);

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

@@ -56,6 +56,7 @@ export declare class SyncedDb implements I_SyncedDb {
     private readonly onEviction?;
     private readonly onSaveIdMismatch?;
     private readonly onUploadSkip?;
+    private readonly onBeforeDirtyClearAll?;
     private readonly evictStaleRecordsEveryHrs;
     private readonly scopeExitLookbehindMs;
     private readonly evictOnWake;
@@ -238,6 +239,32 @@ export declare class SyncedDb implements I_SyncedDb {
     getOnWakeSync(): ((info: import("./types/managers").WakeSyncInfo) => void) | undefined;
     getDirty<T extends DbEntity>(): Promise<Readonly<Record<string, readonly T[]>>>;
     getDirtyMeta(): Promise<Readonly<Record<string, readonly DirtyMeta[]>>>;
+    /**
+     * Manually clear pending dirty changes WITHOUT touching the main
+     * row data. Counterpart to `getDirty` / `getDirtyMeta` for the
+     * "stuck dirty drain" recovery flow — when a known-bad dirty entry
+     * can't be uploaded (e.g. pre-fix sestevki parent+descendant
+     * conflict producing repeated 500s) and the operator wants to
+     * forfeit the pending local intent in favor of server state.
+     *
+     * Three call shapes:
+     *
+     * | Call | Effect |
+     * |---|---|
+     * | `clearDirty()` / `clearDirty(undefined)` | Clear ALL dirty in EVERY collection. Fires `onBeforeDirtyClearAll` once per collection that has dirty (BEFORE the Dexie delete). |
+     * | `clearDirty(coll)` | Clear all dirty in one collection. No callback. |
+     * | `clearDirty(coll, ids)` | Clear specific ids in that collection. No callback. |
+     * | `clearDirty(undefined, ids)` | Throws — ambiguous (which collection do the ids belong to?). |
+     *
+     * Returns the `DirtyMeta[]` of every entry that was actually
+     * removed so the caller can log / archive what was lost.
+     *
+     * Pairs naturally with `getDirtyMeta()` for the inspect-then-clear
+     * pattern. Doesn't await in-flight uploads — caller's
+     * responsibility to call `flushToServer()` first if a last-chance
+     * upload is desired.
+     */
+    clearDirty(collection?: string, ids?: Id[], calledFrom?: string): Promise<DirtyMeta[]>;
     dropCollection(collection: string, force?: boolean): Promise<void>;
     dropDatabase(force?: boolean): Promise<void>;
     /**

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

@@ -91,6 +91,28 @@ export interface SaveIdMismatchInfo {
     /** Timestamp when mismatch detected */
     timestamp: Date;
 }
+/**
+ * Callback payload fired by `clearDirty()` when called WITHOUT a
+ * `collection` argument (clear-all path). One invocation per
+ * collection that has ≥1 dirty entry, fired BEFORE the underlying
+ * Dexie delete runs — caller can archive/inspect the records.
+ *
+ * Per-collection `clearDirty(coll, ...)` calls do NOT fire this
+ * callback (targeted operation; caller already knows what they're
+ * touching).
+ */
+export interface BeforeDirtyClearAllInfo {
+    /** What triggered the clear-all (e.g. "manual", custom string from caller). */
+    reason: string;
+    /** Collection whose dirty entries are about to be deleted. */
+    collection: string;
+    /** Meta of every dirty entry in this collection (no `changes` payload). */
+    items: import("./I_DexieDb").DirtyMeta[];
+    /** Optional caller tag passed through `clearDirty(undefined, undefined, calledFrom)`. */
+    calledFrom?: string;
+    /** Timestamp when the callback fires. */
+    timestamp: Date;
+}
 /**
  * Callback payload for server write requests (before sending)
  */
@@ -649,6 +671,17 @@ export interface SyncedDbConfig {
      * where `this._id` and `this.protokol._id` had drifted apart.
      */
     onSaveIdMismatch?: (info: SaveIdMismatchInfo) => void;
+    /**
+     * Fired by `clearDirty()` (no collection argument — clear-all path)
+     * BEFORE the Dexie delete runs, once per collection that has
+     * dirty entries. Use to archive the dirty state to syslog / audit
+     * trail before it's gone, or to abort by throwing (the throw
+     * aborts only the in-flight clear, doesn't propagate).
+     *
+     * Per-collection `clearDirty(coll, ...)` calls are SILENT — they
+     * don't fire this callback.
+     */
+    onBeforeDirtyClearAll?: (info: BeforeDirtyClearAllInfo) => void;
     /**
      * Enable in-memory object metadata feature.
      * When true, collections with hasMetadata=true will have their metadata callbacks invoked

package/package.json

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