tsdf 17.0.0-rc.1 → 17.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,2 +1,2 @@
1
- import { t as opfsPersistentStorage } from "./opfsPersistentStorage-B_lVflof.js";
1
+ import { t as opfsPersistentStorage } from "./opfsPersistentStorage-D_k77Srq.js";
2
2
  export { opfsPersistentStorage };
@@ -1,4 +1,4 @@
1
- import { H as encodePersistedAsyncNamespaceKind, J as parsePersistedAsyncNamespaceKind, U as getNamespaceId, W as getPayloadRecordKey, _ as getTSDFDebugTimingMs, g as emitTSDFDebugLog, i as createAsyncStorageAdapter, q as parseAsyncStorageRecordKey } from "./asyncStorageAdapter-BBKVK1S_.js";
1
+ import { G as getPayloadRecordKey, J as parseAsyncStorageRecordKey, U as encodePersistedAsyncNamespaceKind, W as getNamespaceId, Y as parsePersistedAsyncNamespaceKind, _ as getTSDFDebugTimingMs, g as emitTSDFDebugLog, i as createAsyncStorageAdapter } from "./asyncStorageAdapter-BuGjbXYA.js";
2
2
  import { getCompositeKey } from "@ls-stack/utils/getCompositeKey";
3
3
  import { __LEGIT_CAST__ } from "@ls-stack/utils/saferTyping";
4
4
  import { isObject } from "@ls-stack/utils/typeGuards";
package/docs/README.md CHANGED
@@ -45,6 +45,7 @@ import { createDocumentStore, createStoreManager } from 'tsdf';
45
45
 
46
46
  const storeManager = createStoreManager({
47
47
  getSessionKey: () => (auth.userId ? `tenant:${auth.tenantId}` : false),
48
+ getAppVersion: () => BUILD_VERSION,
48
49
  errorNormalizer: (err) => ({
49
50
  code: 500,
50
51
  id: 'fetch-error',
@@ -8,6 +8,7 @@ Browser tabs sync is available when all of these are true:
8
8
 
9
9
  - All tabs use the same `id` for the same store
10
10
  - `storeManager.getSessionKey()` returns the same string in all tabs
11
+ - If configured, the `createStoreManager({ getAppVersion })` callback returns the same build version in all tabs
11
12
  - Tab communication is available (default: `BroadcastChannel`)
12
13
 
13
14
  If `getSessionKey` returns `false`, sync is disabled for that store instance.
@@ -32,9 +33,22 @@ Tabs use a versioned message model so later snapshots do not overwrite fresher r
32
33
 
33
34
  - Same `id` with different `sessionKey` values do not sync.
34
35
  - Different `id` values do not sync.
36
+ - Different values from the configured `getAppVersion` callback do not share any browser-tab sync channels.
35
37
  - When `sessionKey` changes (for example, login/logout), sync state is refreshed for the new session.
36
38
  - If transport is unavailable, sync becomes inactive silently.
37
39
 
40
+ Apps deployed while users may keep older tabs open should always provide `getAppVersion`. Return a stable release or build identifier that changes whenever a new bundle is deployed:
41
+
42
+ ```ts
43
+ const storeManager = createStoreManager({
44
+ getSessionKey: () => currentTenantId ?? false,
45
+ getAppVersion: () => BUILD_VERSION,
46
+ errorNormalizer: normalizeError,
47
+ });
48
+ ```
49
+
50
+ TSDF evaluates the callback once when the manager is created and namespaces every sync channel with that value: manager presence, document, collection, list-query, and offline-session channels. During a mixed-version rollout, old and new tabs therefore use their own network requests and in-memory snapshots. This prevents both cross-version snapshot injection and cross-version `fetch-start` deduplication. `getAppVersion` only scopes browser-tab sync; use `persistentStorage.version` separately for persisted cache migrations.
51
+
38
52
  Enable `createStoreManager({ debugLogger: true, ... })` to inspect transport open/close, publish, receive, skipped-message events, and leader changes in development. Store data sync uses store-specific channels, while tab-presence status uses one shared `presence` channel per manager/session. Presence prioritizes the focused tab; background tabs announce open/focus/blur changes and keep their last known fallback rank during quiet periods. Leader-change entries include the elected `leaderTabId`, whether the local tab is the leader, the local tab rank, and the ranked live-tab snapshot. Pass a logger function as `debugLogger` to route those entries to your own tooling.
39
53
 
40
54
  ## Required options
@@ -46,6 +60,7 @@ const storeManager = createStoreManager({
46
60
  getSessionKey: () => {
47
61
  return isLoggedIn ? `tenant:${tenantId}` : false;
48
62
  },
63
+ getAppVersion: () => BUILD_VERSION,
49
64
  errorNormalizer: normalizeError,
50
65
  backgroundCoalescingDelayMs: 3_000,
51
66
  });
@@ -137,6 +137,7 @@ TSDF does not choose a persistence adapter automatically. Pass one of the built-
137
137
  - Can hydrate synchronously during initial state creation for `DocumentStore`.
138
138
  - `CollectionStore` and `ListQueryStore` use lazy hydration for unknown entries from initial keys scan.
139
139
  - Writes are debounced and may be dropped if serialization errors occur.
140
+ - Scheduled expiration and byte-budget maintenance is split across browser idle deadlines. Timeout-fired callbacks and browsers without `requestIdleCallback` use short timer-backed slices, so large scans and eviction batches yield between slices while keeping payload entries and manifests consistent.
140
141
  - When a write hits the browser `QuotaExceededError` (the shared origin quota is full, e.g. because other parts of the app filled `localStorage`), TSDF automatically evicts its own least recently used entries — across all TSDF stores and sessions — and retries, escalating to all non-offline-protected entries if needed. Offline data and non-TSDF keys are never touched. If even that cannot free enough space, a single descriptive error is reported through `onPersistentStorageError` and persistence writes are silently skipped until the next page load. Removals of persisted entries (e.g. after deleting an item) still go through while writes are disabled, so deleted data never resurrects on the next load.
141
142
 
142
143
  Use it with:
@@ -11,6 +11,7 @@ import { createStoreManager } from 'tsdf';
11
11
 
12
12
  const storeManager = createStoreManager({
13
13
  getSessionKey: () => currentTenantId ?? false,
14
+ getAppVersion: () => BUILD_VERSION,
14
15
  errorNormalizer: (error) => ({
15
16
  code: 500,
16
17
  id: 'unknown-error',
@@ -38,6 +39,7 @@ Options:
38
39
  | Option | Required | Description |
39
40
  | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
40
41
  | `getSessionKey` | Yes | Returns the active tenant/account key. Return `false` while no session is ready. |
42
+ | `getAppVersion` | No | Returns a stable build/release version that namespaces browser-tab sync so different deployments cannot exchange fetch activity or snapshots. |
41
43
  | `errorNormalizer` | Yes | Converts thrown `Error` values into TSDF's shared `StoreError` shape. |
42
44
  | `lowPriorityThrottleMs` | No | Default minimum interval between low-priority fetches for attached stores. Defaults to 40 minutes (`2_400_000ms`). |
43
45
  | `baseCoalescingWindowMs` | No | Default window to group fetch requests for attached stores. Defaults to `16ms`. |
@@ -53,6 +55,8 @@ Options:
53
55
 
54
56
  The session key is used by browser-tab sync, persistent storage, and offline state. Stores with the same `id` but different session keys are isolated.
55
57
 
58
+ For apps that can have tabs from different deployments open at the same time, provide `getAppVersion` and return the same stable build version used by your error tracking or release tooling. TSDF evaluates it once when the manager is created and includes the result in every browser-tab sync channel, including manager presence and offline-session coordination. Tabs on different versions then fetch independently and cannot apply each other's snapshots. This option does not version persistent storage; continue using each store's `persistentStorage.version` when its persisted data shape changes.
59
+
56
60
  Stores inherit the manager's `lowPriorityThrottleMs`, `baseCoalescingWindowMs`, and `dynamicRealtimeThrottleMs` unless they provide their own store-level overrides. `backgroundCoalescingDelayMs` and `blockWindowClose` are manager-only so browser-tab background coordination and window-close mutation protection stay consistent across attached stores. The built-in `dynamicRealtimeThrottleMs` default returns `100ms` while focused and `1000ms` while the window is in the background.
57
61
 
58
62
  Store-level options can explicitly disable inherited defaults when the option supports disabling: use `revalidateOnWindowFocus: false`, `onMutationError: null`, or `persistentStorage.onPersistentStorageError: null`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tsdf",
3
- "version": "17.0.0-rc.1",
3
+ "version": "17.0.1",
4
4
  "description": "A data fetching solution based on t-state",
5
5
  "license": "PolyForm-Noncommercial-1.0.0",
6
6
  "author": "Lucas Santos",