cry-synced-db-client 0.1.170 → 0.1.171

package/CHANGELOG.md

@@ -2,6 +2,102 @@
 
 ## Unreleased
 
+### Runtime collection registration (`addCollectionToSync`, `replaceSyncCollection`)
+
+Two methods to install / replace collection configs at runtime; both load the
+Dexie cursor into the sync-meta cache, hydrate in-mem from Dexie, extend an
+active `syncOnlyTheseCollections` filter, and fire a one-shot **targeted**
+download for just that collection (`syncCollectionForFind` →
+`processCollectionServerData`, cursor advances inline). Other collections
+are not re-fetched.
+
+**`addCollectionToSync(spec)` — safe, idempotent** (Promise<void>)
+
+| Existing config | Action |
+|---|---|
+| permanent (`temporaryConfig !== true`) | no-op |
+| temporary (`temporaryConfig === true`) | replaced |
+| none | added |
+
+**`replaceSyncCollection(spec)` — explicit re-config** (Promise<boolean>)
+
+| Existing | New | Result |
+|---|---|---|
+| none | any | install, returns `true` |
+| temporary | any | replace, returns `true` |
+| permanent | permanent | replace, returns `true` |
+| permanent | temporary | **blocked, returns `false`** (no-op) |
+
+The only blocked transition is permanent → temporary (cannot downgrade an
+established config to provisional).
+
+```typescript
+// Boot with a provisional config so the Dexie schema includes the
+// collection but the real query/conflict-resolver is deferred.
+new SyncedDb({ collections: [{ name: "obravnave", temporaryConfig: true }] });
+
+// Idempotent install after login:
+await syncedDb.addCollectionToSync({
+  name: "obravnave",
+  syncConfig: { query: () => ({ lokacija_id: currentLokacijaId }) },
+});
+
+// Later, user switches lokacija — explicit re-config:
+const ok = await syncedDb.replaceSyncCollection({
+  name: "obravnave",
+  syncConfig: { query: () => ({ lokacija_id: newLokacijaId }) },
+});
+// ok === true (replacement of permanent with permanent allowed)
+```
+
+### `flushToServer()` + automatic flush on `visibilitychange:hidden`
+
+`SyncedDb.flushToServer(calledFrom?)` pushes dirty data to the server
+immediately, bypassing `debounceRestWritesMs`. Flow: cancel REST upload
+debounce → `flushAll()` (pending Dexie writes) → `awaitRestUpload()`
+(in-flight upload) → `uploadDirtyItems(calledFrom)`. No-op when offline,
+forced offline, or pre-`init`.
+
+A `visibilitychange` listener fires `flushToServer("visibility-hidden")`
+automatically when the tab becomes `hidden`. Browser may throttle or
+suspend a hidden tab shortly after the event, so the debounced upload
+could otherwise never run.
+
+```typescript
+// Manual flush (e.g. before navigation)
+await syncedDb.flushToServer("pre-navigate");
+
+// Automatic: no caller action required. Listener registered in init(),
+// cleaned up in close().
+```
+
+Upload itself is **not gated on `isLeader`** — `PendingChangesManager`
+guards only on `canSync()` — so followers also drain their dirty queue
+on hidden. Cancelling the timer cancels only the *current* pending burst:
+subsequent writes schedule a new timer and the auto-sync interval still
+fires. To permanently stop uploads, call `close()` or `forceOffline(true)`.
+
+### Leadership transition timestamps (`leaderSince` / `followerSince`)
+
+Two new getters on `SyncedDb` (and `I_LeaderElectionManager`):
+
+- `leaderSince(): Date | undefined` — when this tab acquired the Web Locks
+  leader lock; `undefined` while a follower
+- `followerSince(): Date | undefined` — when this tab transitioned to
+  follower (or, for tabs that never claimed leadership, the construction
+  timestamp); `undefined` while the leader
+
+Exactly one of the two is defined at any time after construction. Useful
+for heartbeat payloads / debug overlays (`Date.now() - leaderSince()` =
+"time in current leadership state").
+
+```typescript
+const isLeader = syncedDb.isLeaderTab();
+const sinceMs = isLeader
+  ? Date.now() - syncedDb.leaderSince()!.getTime()
+  : Date.now() - syncedDb.followerSince()!.getTime();
+```
+
 ### `onServerSyncWrite` callback
 
 Single-shot callback that fires once per `restInterface.updateCollections`

package/dist/index.js

@@ -876,6 +876,7 @@ var LeaderElectionManager = class {
     this.isLeaderFlag = false;
     this.closing = false;
     this.releasingDueToVisibility = false;
+    this._followerSince = /* @__PURE__ */ new Date();
     this.tenant = config.tenant;
     this.windowId = config.windowId;
     this.callbacks = config.callbacks;
@@ -973,6 +974,21 @@ var LeaderElectionManager = class {
   isLeader() {
     return this.isLeaderFlag;
   }
+  /**
+   * Returns the timestamp when this tab became leader, or undefined if currently a follower.
+   * Cleared on transition to follower.
+   */
+  leaderSince() {
+    return this._leaderSince;
+  }
+  /**
+   * Returns the timestamp when this tab became follower, or undefined if currently a leader.
+   * Initialized at construction (every tab starts as a follower until it claims the lock).
+   * Cleared on transition to leader.
+   */
+  followerSince() {
+    return this._followerSince;
+  }
   /**
    * Cleanup resources.
    */
@@ -1024,6 +1040,8 @@ var LeaderElectionManager = class {
     }
   }
   callOnBecameLeader() {
+    this._leaderSince = /* @__PURE__ */ new Date();
+    this._followerSince = void 0;
     if (this.callbacks.onBecameLeader) {
       try {
         this.callbacks.onBecameLeader();
@@ -1033,6 +1051,8 @@ var LeaderElectionManager = class {
     }
   }
   callOnLostLeadership() {
+    this._followerSince = /* @__PURE__ */ new Date();
+    this._leaderSince = void 0;
     if (this.callbacks.onLostLeadership) {
       try {
         this.callbacks.onLostLeadership();
@@ -4499,6 +4519,55 @@ var _SyncedDb = class _SyncedDb {
   isLeaderTab() {
     return this.leaderElection.isLeader();
   }
+  leaderSince() {
+    return this.leaderElection.leaderSince();
+  }
+  followerSince() {
+    return this.leaderElection.followerSince();
+  }
+  /**
+   * Register a collection for sync at runtime. See `I_SyncedDb.addCollectionToSync`.
+   */
+  async addCollectionToSync(spec) {
+    const existing = this.collections.get(spec.name);
+    if (existing && !existing.temporaryConfig) {
+      return;
+    }
+    await this._installCollectionConfig(spec);
+  }
+  /**
+   * Replace the collection config and re-sync. See `I_SyncedDb.replaceSyncCollection`.
+   */
+  async replaceSyncCollection(spec) {
+    const existing = this.collections.get(spec.name);
+    if (existing && !existing.temporaryConfig && spec.temporaryConfig) {
+      return false;
+    }
+    await this._installCollectionConfig(spec);
+    return true;
+  }
+  /**
+   * Shared install path for addCollectionToSync / replaceSyncCollection:
+   * write config, extend active sync filter, load Dexie cursor + in-mem,
+   * fire a targeted one-shot download for just this collection.
+   */
+  async _installCollectionConfig(spec) {
+    var _a;
+    this.collections.set(spec.name, spec);
+    if (this.syncOnlyCollections) {
+      this.syncOnlyCollections.add(spec.name);
+    }
+    const meta = await this.dexieDb.getSyncMeta(spec.name);
+    if (meta) this.syncMetaCache.set(spec.name, meta);
+    if (!spec.writeOnly) {
+      await this.loadCollectionToInMem(spec.name);
+    }
+    if (!spec.writeOnly && this.connectionManager.canSync()) {
+      const rawQuery = (_a = spec.syncConfig) == null ? void 0 : _a.query;
+      const query = typeof rawQuery === "function" ? rawQuery() : rawQuery;
+      await this.syncCollectionForFind(spec.name, query, { returnDeleted: true });
+    }
+  }
   /**
    * Restrict sync to only these collections. When non-empty, only the listed
    * collections load from Dexie→in-mem and download from server. Pass an empty
@@ -4616,6 +4685,15 @@ var _SyncedDb = class _SyncedDb {
       };
       window.addEventListener("beforeunload", this.beforeUnloadHandler);
     }
+    if (typeof document !== "undefined") {
+      this.visibilityFlushHandler = () => {
+        if (document.visibilityState !== "hidden") return;
+        this.flushToServer("visibility-hidden").catch((err) => {
+          console.warn("flushToServer on visibility-hidden failed:", err == null ? void 0 : err.message);
+        });
+      };
+      document.addEventListener("visibilitychange", this.visibilityFlushHandler);
+    }
     this.initialized = true;
   }
   /**
@@ -4626,6 +4704,25 @@ var _SyncedDb = class _SyncedDb {
   async flush() {
     await this.pendingChanges.flushAll();
   }
+  /**
+   * Push dirty data to the server immediately, bypassing the upload debounce.
+   *
+   * Flushes pending Dexie writes, awaits any in-flight REST upload, then fires
+   * a fresh `uploadDirtyItems()`. Called automatically when the tab becomes
+   * hidden so data is not stranded by browser tab-throttling / suspension.
+   *
+   * No-op when offline, forced offline, or not yet initialized.
+   *
+   * @param calledFrom Diagnostic tag threaded through to upload callbacks
+   */
+  async flushToServer(calledFrom) {
+    if (!this.initialized) return;
+    if (!this.connectionManager.canSync()) return;
+    this.pendingChanges.cancelRestUploadTimer();
+    await this.pendingChanges.flushAll();
+    await this.pendingChanges.awaitRestUpload();
+    await this.syncEngine.uploadDirtyItems(calledFrom);
+  }
   /**
    * Returns when all collections were last successfully synced
    * from the server, or undefined if never.
@@ -4706,6 +4803,10 @@ var _SyncedDb = class _SyncedDb {
       window.removeEventListener("beforeunload", this.beforeUnloadHandler);
       this.beforeUnloadHandler = void 0;
     }
+    if (typeof document !== "undefined" && this.visibilityFlushHandler) {
+      document.removeEventListener("visibilitychange", this.visibilityFlushHandler);
+      this.visibilityFlushHandler = void 0;
+    }
     this.syncMetaCache.clear();
     for (const collectionName of this.collections.keys()) {
       this.inMemManager.clearCollection(collectionName);

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

@@ -1,5 +1,5 @@
 import type { AggregateOptions } from "mongodb";
-import type { I_SyncedDb, SyncedDbConfig, WsNotificationInfo, EvictionInfo, EvictionCollectionInfo } from "../types/I_SyncedDb";
+import type { I_SyncedDb, SyncedDbConfig, CollectionConfig, WsNotificationInfo, EvictionInfo, EvictionCollectionInfo } from "../types/I_SyncedDb";
 import type { DirtyMeta, MetaUpdateBroadcast } from "../types/I_DexieDb";
 import type { QuerySpec, QueryOpts, UpdateSpec, InsertSpec, BatchSpec } from "../types/I_RestInterface";
 import type { Id, DbEntity } from "../types/DbEntity";
@@ -36,6 +36,7 @@ export declare class SyncedDb implements I_SyncedDb {
     private unsubscribeServerUpdates?;
     private cleanupNotifierCallbacks?;
     private beforeUnloadHandler?;
+    private visibilityFlushHandler?;
     private readonly defaultReturnDeleted;
     private readonly defaultReturnArchived;
     private readonly onDatabaseCreated?;
@@ -62,6 +63,22 @@ export declare class SyncedDb implements I_SyncedDb {
     getInstanceId(): string;
     getCrossTabSyncDebounceMs(): number;
     isLeaderTab(): boolean;
+    leaderSince(): Date | undefined;
+    followerSince(): Date | undefined;
+    /**
+     * Register a collection for sync at runtime. See `I_SyncedDb.addCollectionToSync`.
+     */
+    addCollectionToSync(spec: CollectionConfig): Promise<void>;
+    /**
+     * Replace the collection config and re-sync. See `I_SyncedDb.replaceSyncCollection`.
+     */
+    replaceSyncCollection(spec: CollectionConfig): Promise<boolean>;
+    /**
+     * Shared install path for addCollectionToSync / replaceSyncCollection:
+     * write config, extend active sync filter, load Dexie cursor + in-mem,
+     * fire a targeted one-shot download for just this collection.
+     */
+    private _installCollectionConfig;
     /**
      * Restrict sync to only these collections. When non-empty, only the listed
      * collections load from Dexie→in-mem and download from server. Pass an empty
@@ -87,6 +104,18 @@ export declare class SyncedDb implements I_SyncedDb {
      * Does NOT upload to server — call sync() for that.
      */
     flush(): Promise<void>;
+    /**
+     * Push dirty data to the server immediately, bypassing the upload debounce.
+     *
+     * Flushes pending Dexie writes, awaits any in-flight REST upload, then fires
+     * a fresh `uploadDirtyItems()`. Called automatically when the tab becomes
+     * hidden so data is not stranded by browser tab-throttling / suspension.
+     *
+     * No-op when offline, forced offline, or not yet initialized.
+     *
+     * @param calledFrom Diagnostic tag threaded through to upload callbacks
+     */
+    flushToServer(calledFrom?: string): Promise<void>;
     private _lastFullSyncDate?;
     private _lastInitialSyncDate?;
     /**

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

@@ -12,6 +12,8 @@ export declare class LeaderElectionManager implements I_LeaderElectionManager {
     private isLeaderFlag;
     private closing;
     private releasingDueToVisibility;
+    private _leaderSince?;
+    private _followerSince?;
     private releaseLeaderLockResolve?;
     private becameLeaderPromise?;
     private becameLeaderResolve?;
@@ -36,6 +38,17 @@ export declare class LeaderElectionManager implements I_LeaderElectionManager {
      * Check if this instance is currently the leader.
      */
     isLeader(): boolean;
+    /**
+     * Returns the timestamp when this tab became leader, or undefined if currently a follower.
+     * Cleared on transition to follower.
+     */
+    leaderSince(): Date | undefined;
+    /**
+     * Returns the timestamp when this tab became follower, or undefined if currently a leader.
+     * Initialized at construction (every tab starts as a follower until it claims the lock).
+     * Cleared on transition to leader.
+     */
+    followerSince(): Date | undefined;
     /**
      * Cleanup resources.
      */

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

@@ -26,6 +26,10 @@ export interface I_LeaderElectionManager {
     releaseLeaderLock(): void;
     /** Check if this instance is currently the leader. */
     isLeader(): boolean;
+    /** Timestamp when this tab became leader, or undefined if currently a follower. */
+    leaderSince(): Date | undefined;
+    /** Timestamp when this tab became follower, or undefined if currently a leader. */
+    followerSince(): Date | undefined;
     /** Initialize (setup visibility listeners, BroadcastChannel). */
     init(): void;
     /** Cleanup resources. */

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

@@ -402,6 +402,13 @@ export interface CollectionConfig<T extends DbEntity = any, M = any> {
      * Read operations throw. Server sync and WS notifications are skipped.
      */
     writeOnly?: boolean;
+    /**
+     * Marks this config as provisional — a later `addCollectionToSync()` with
+     * a permanent (non-temporary) config will replace it. Permanent configs
+     * (the default) are immutable: subsequent `addCollectionToSync()` calls
+     * for the same collection are no-ops once a permanent config is in place.
+     */
+    temporaryConfig?: boolean;
     /** Whether this collection uses in-memory metadata */
     hasMetadata?: boolean;
     /** Callback called when a single object is written to in-mem. Returns metadata to store. */
@@ -737,6 +744,53 @@ export interface I_SyncedDb {
      * Does NOT upload to server — call sync() for that.
      */
     flush(): Promise<void>;
+    /**
+     * Push dirty data to the server immediately, bypassing the upload debounce.
+     * Flushes pending Dexie writes, awaits any in-flight REST upload, then fires
+     * a fresh upload. Called automatically on `visibilitychange` to `hidden` so
+     * data is not stranded by browser tab-throttling / suspension.
+     * No-op when offline, forced offline, or not yet initialized.
+     * @param calledFrom Diagnostic tag threaded through to upload callbacks
+     */
+    flushToServer(calledFrom?: string): Promise<void>;
+    /**
+     * Register a collection for sync at runtime.
+     *
+     * Behavior depends on whether a config already exists for `spec.name`:
+     * - permanent (existing config has `temporaryConfig !== true`): no-op
+     * - temporary (existing config has `temporaryConfig === true`): replaced by `spec`
+     * - none: `spec` is added
+     *
+     * On add or replace: loads the Dexie cursor for this collection into the
+     * sync-meta cache, hydrates in-mem from Dexie, and (when online + not
+     * `writeOnly`) fires a one-shot download sync for just this collection.
+     * If a `syncOnlyTheseCollections` filter is active, the new collection is
+     * added to it so future syncs include it.
+     *
+     * @param spec Collection config to register
+     */
+    addCollectionToSync(spec: CollectionConfig): Promise<void>;
+    /**
+     * Replace the collection config and re-sync.
+     *
+     * Like `addCollectionToSync` but more aggressive — overrides even a
+     * permanent existing config. The only blocked transition is
+     * **permanent → temporary** (cannot downgrade an already-established
+     * config to provisional):
+     *
+     * - no existing config: install `spec`, return `true`
+     * - existing temporary: replace with `spec` (any type), return `true`
+     * - existing permanent, `spec.temporaryConfig === true`: return `false`, no-op
+     * - existing permanent, `spec` permanent: replace with `spec`, return `true`
+     *
+     * On replace: extends active `syncOnlyTheseCollections` filter, reloads
+     * the Dexie cursor, re-hydrates in-mem, and (when online + not `writeOnly`)
+     * fires a one-shot targeted download.
+     *
+     * @param spec Collection config to install
+     * @returns `true` if installed, `false` if blocked (permanent → temporary)
+     */
+    replaceSyncCollection(spec: CollectionConfig): Promise<boolean>;
     /**
      * Returns when all collections were last successfully synced
      * from the server, or undefined if never synced.
@@ -954,6 +1008,19 @@ export interface I_SyncedDb {
      * @returns true if this instance holds the leader lock
      */
     isLeaderTab(): boolean;
+    /**
+     * Timestamp when this tab became the leader.
+     * Set on transition from follower to leader; cleared when leadership is lost.
+     * @returns Date of leader transition, or undefined if currently a follower
+     */
+    leaderSince(): Date | undefined;
+    /**
+     * Timestamp when this tab became a follower.
+     * Initialized at construction (every tab starts as a follower until it claims
+     * the lock); cleared when leadership is gained, set again on transition to follower.
+     * @returns Date of follower transition, or undefined if currently the leader
+     */
+    followerSince(): Date | undefined;
     /**
      * Get metadata for a single object.
      * @param collection Collection name

package/package.json

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