cry-synced-db-client 0.1.170 → 0.1.172

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/dist/src/utils/computeDiff.d.ts

@@ -84,9 +84,15 @@ export declare function deleteByPath(target: any, path: string): boolean;
  *         wrapped element[0], not into the array itself. The pending insert
  *         absorbs the sub-field edit.
  *
- * 2. New path is an ANCESTOR of existing keys (e.g. existing has "koraki.0.diag",
- *    new is "koraki" with full array): remove the now-redundant descendants and
- *    set the parent path. The new full value supersedes any field-level deltas.
+ * 2. New path is an ANCESTOR of existing keys.
+ *    - Plain ancestor (e.g. existing "koraki.0.diag", new "koraki" with full
+ *      array): drop the descendants; the new full value supersedes any
+ *      field-level deltas.
+ *    - TERMINAL-bracket ancestor whose `newValue` is element-shaped
+ *      (`arr[a].sub[b]` with `[<el>]` or plain object): LAYER pending
+ *      descendant sub-field edits INTO `newValue` before dropping them,
+ *      so the element-level write absorbs the prior sub-field-level
+ *      writes instead of silently overwriting them.
  *
  * 3. New path is ORTHOGONAL to existing keys: simple set (Object.assign-equivalent).
  *

package/package.json

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