cry-synced-db-client 0.1.170 → 0.1.172

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`