tsdf 17.0.0-alpha.9 → 17.0.0-beta.0

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.
@@ -17,10 +17,7 @@ const store = createListQueryStore<Task, TaskFilter, string, false, true>({
17
17
  return api.getTasks(filter, { offset, limit, signal });
18
18
  },
19
19
 
20
- offsetPagination: {
21
- maxInvalidationLimit: 200,
22
- maxParallel: 3,
23
- },
20
+ offsetPagination: { maxInvalidationLimit: 200, maxParallel: 3 },
24
21
 
25
22
  // ...other options
26
23
  });
@@ -30,9 +30,6 @@ const taskStore = createListQueryStore<Task, TaskFilter, string>({
30
30
 
31
31
  // Where to add new items
32
32
  appendNewTo: 'start',
33
-
34
- // Trigger background revalidation when items are moved
35
- invalidateQueries: true,
36
33
  },
37
34
  {
38
35
  // Sort a specific query by priority
@@ -112,7 +109,9 @@ Sorting is applied only to queries that contain the updated item.
112
109
 
113
110
  ### invalidateQueries
114
111
 
115
- When `true`, queries affected by the optimistic update are invalidated in the background. This ensures the server's actual ordering/filtering is fetched eventually.
112
+ Schedules a background refetch of queries this rule mutated.
113
+
114
+ **Leave off by default.** Only enable when the optimistic update can't represent the final server state — e.g. sort depends on a server-assigned field (`updatedAt`, computed score), membership depends on server-only data (permissions, full-text match), or cursor pagination shifts the page window. If `filterItem` and `sort` already match the server, the extra refetch is just noise.
116
115
 
117
116
  ```ts
118
117
  invalidateQueries: true;
@@ -137,8 +136,8 @@ They are **not** triggered by:
137
136
  const storeManager = createStoreManager({
138
137
  getSessionKey: () => currentTenantId ?? false,
139
138
  errorNormalizer: normalizeError,
140
- lowPriorityThrottleMs: 5,
141
- baseCoalescingWindowMs: 10,
139
+ lowPriorityThrottleMs: 40 * 60 * 1_000,
140
+ baseCoalescingWindowMs: 16,
142
141
  blockWindowClose: null,
143
142
  });
144
143
 
@@ -149,31 +148,28 @@ const taskStore = createListQueryStore<Task, { status: string }, string>({
149
148
  fetchItemFn: (id, { signal }) => api.getTask(id, signal),
150
149
 
151
150
  optimisticListUpdates: [
152
- {
153
- // Move tasks between status columns
154
- queries: (q) => true,
155
- filterItem: (item) => item.status === 'todo',
156
- // Only applies to queries where status matches
157
- },
151
+ // Membership follows status — the optimistic change is final.
158
152
  {
159
153
  queries: { status: 'todo' },
160
154
  filterItem: (item) => item.status === 'todo',
161
155
  appendNewTo: 'start',
162
- invalidateQueries: true,
163
156
  },
164
157
  {
165
158
  queries: { status: 'done' },
166
159
  filterItem: (item) => item.status === 'done',
167
160
  appendNewTo: 'end',
161
+ },
162
+ // Server sorts by `updatedAt`, which it assigns — refetch to settle order.
163
+ {
164
+ queries: (q) => true,
165
+ sort: { sortBy: (item) => item.updatedAt, order: 'desc' },
168
166
  invalidateQueries: true,
169
167
  },
170
168
  ],
171
169
  });
172
170
 
173
- // When a task is moved to "done", it's automatically:
174
- // 1. Removed from the "todo" query
175
- // 2. Added to the "done" query
176
- // 3. Both queries are revalidated in the background
171
+ // Moving "task-1" to done removes it from the todo query and adds it to the
172
+ // done query. Only the sort rule triggers a background refetch.
177
173
  taskStore.updateItemState('task-1', (draft) => {
178
174
  draft.status = 'done';
179
175
  });
@@ -44,10 +44,18 @@ const userStore = createListQueryStore<User, UserFilter, string, true>({
44
44
  selectFields: (fields, item) => {
45
45
  const result: Partial<User> = {};
46
46
  for (const field of fields) {
47
- result[field] = item[field];
47
+ if (item[field] !== undefined) {
48
+ result[field] = item[field];
49
+ }
48
50
  }
49
51
  return result as User;
50
52
  },
53
+
54
+ // Report which logical fields are genuinely present in an item snapshot —
55
+ // the only signal for metadata-free snapshots (manually added or offline
56
+ // items), and a way to vouch for fields present beyond tracked metadata.
57
+ inferFields: (item) =>
58
+ Object.keys(item).filter((field) => item[field] !== undefined),
51
59
  },
52
60
 
53
61
  // ...other options
@@ -61,6 +69,7 @@ const userStore = createListQueryStore<User, UserFilter, string, true>({
61
69
  3. When a hook requests fields that haven't been loaded yet, a fetch is triggered requesting only the missing fields
62
70
  4. The `mergeItems` function combines the newly fetched data with previously loaded data
63
71
  5. The `selectFields` function extracts the requested fields for the hook's return value
72
+ 6. The `inferFields` function reports which fields are genuinely present in an item snapshot, complementing (or substituting for) the tracked metadata
64
73
 
65
74
  ## Using Fields in Hooks
66
75
 
@@ -130,6 +139,8 @@ When a hook requests fields that are partially loaded:
130
139
 
131
140
  If you enable `showPartialAsRefetching`, the hook exposes `loadingFields` with the requested fields that are still pending. When cached partial data already exists, TSDF keeps it visible during the follow-up fetch.
132
141
 
142
+ Invalidations are refetches, not new loads: when an invalidation (full or per-field) marks cached data as stale, hooks whose requested fields are still present keep the stale data visible while the refetch is in flight (with a `refetching` status when `returnRefetchingStatus` is enabled). Data is only hidden behind `loading` when a requested field was genuinely never loaded.
143
+
133
144
  ## Fields in Scheduling and Fetching
134
145
 
135
146
  Fields propagate through the scheduling and fetching APIs:
@@ -166,3 +177,17 @@ selectFields: (fields: string[], item: ItemState) => ItemState;
166
177
  ```
167
178
 
168
179
  Called when a hook requests specific fields. Should return an item containing only the requested fields.
180
+
181
+ ### inferFields
182
+
183
+ ```ts
184
+ inferFields: (item: ItemState) => string[] | '*';
185
+ ```
186
+
187
+ Reports which logical fields are genuinely present in an item snapshot. Return the available fields, or `'*'` if the snapshot is complete.
188
+
189
+ It is the only availability signal for snapshots without `itemLoadedFields` metadata — manually inserted items, persisted fallback snapshots, and offline optimistic rows. But it is also consulted for metadata-tracked items: the loaded-fields metadata only records what fetches delivered, so `inferFields` can additionally vouch for fields that are present beyond the tracked list (e.g. written into the item by a mutation), avoiding refetches of data that is already there. Returning `'*'` marks the snapshot complete even when the tracked metadata is a partial field list.
190
+
191
+ Because it can vouch for any snapshot, `inferFields` must only report fields whose data is genuinely usable — inspect the item, don't return `'*'` unconditionally unless every snapshot your store can ever hold is complete. Staleness is not its concern: fields awaiting an invalidation refetch are excluded by TSDF before `inferFields` is consulted.
192
+
193
+ TSDF does not infer fields by checking object keys internally. If your field names are top-level properties, implement that rule explicitly in `inferFields` (excluding keys with `undefined` values); if your fields are logical or nested, return those logical field names instead.
@@ -64,7 +64,7 @@ Store-specific options:
64
64
 
65
65
  > `persistentStorage` automatically reuses the store's existing `id` for its storage namespace and the store manager's `getSessionKey` for session scoping. When `getSessionKey` returns `false`, no persistence operations run.
66
66
 
67
- Enable `createStoreManager({ debug: true, ... })` to inspect load, save/write, commit, clear, metadata, and offline protection persistence operations. Async adapters include `durationMs` on debug entries so OPFS, IndexedDB, or custom driver performance can be inspected.
67
+ Enable `createStoreManager({ debugLogger: true, ... })` to inspect load, save/write, commit, clear, metadata, and offline protection persistence operations in development. Production-safe quota cleanup logs are emitted through the manager `logger` by default; they include the affected quota, configured byte budget, total unprotected bytes, and kept/evicted entry counts. Pass `logger: false` to disable them. Async adapters also emit timed `adapter-operation` entries with `durationMs` for concrete OPFS, IndexedDB, or custom driver work in development.
68
68
 
69
69
  ## Converted Data Schemas
70
70
 
@@ -202,8 +202,8 @@ const getSessionKey = () => (userId ? `tenant:${userId}` : false);
202
202
  const storeManager = createStoreManager({
203
203
  getSessionKey,
204
204
  errorNormalizer: normalizeError,
205
- lowPriorityThrottleMs: 5,
206
- baseCoalescingWindowMs: 10,
205
+ lowPriorityThrottleMs: 40 * 60 * 1_000,
206
+ baseCoalescingWindowMs: 16,
207
207
  blockWindowClose: null,
208
208
  onPersistentStorageError: (error) => {
209
209
  console.error('TSDF persistence failed', error);
@@ -90,6 +90,8 @@ dynamicRealtimeThrottleMs: ({ lastFetchDuration, windowIsNotFocused }) => {
90
90
 
91
91
  This prevents the UI from being overwhelmed by rapid updates while keeping data fresh.
92
92
 
93
+ When the window regains focus, any refetch still waiting on the background throttle is re-evaluated with the focused throttle: it fires immediately if the focused interval has already elapsed, or is rescheduled to the shorter focused delay. Returning to a tab never has to wait out the rest of a long background window.
94
+
93
95
  ## Transport Reconnection
94
96
 
95
97
  When your WebSocket or SSE connection drops and reconnects, events may have been missed. Call the manager-level `onTransportReconnect()` once for the shared transport:
@@ -16,8 +16,9 @@ const storeManager = createStoreManager({
16
16
  id: 'unknown-error',
17
17
  message: error.message,
18
18
  }),
19
- lowPriorityThrottleMs: 5,
20
- baseCoalescingWindowMs: 10,
19
+ lowPriorityThrottleMs: 40 * 60 * 1_000,
20
+ baseCoalescingWindowMs: 16,
21
+ backgroundCoalescingDelayMs: 3_000,
21
22
  dynamicRealtimeThrottleMs: ({ lastFetchDuration, windowIsNotFocused }) =>
22
23
  windowIsNotFocused ? lastFetchDuration * 10 : lastFetchDuration * 2,
23
24
  blockWindowClose: null,
@@ -28,41 +29,48 @@ const storeManager = createStoreManager({
28
29
  onPersistentStorageError: (error) => {
29
30
  console.error('TSDF persistence failed', error);
30
31
  },
31
- debug: true,
32
+ debugLogger: true,
32
33
  });
33
34
  ```
34
35
 
35
36
  Options:
36
37
 
37
- | Option | Required | Description |
38
- | --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
39
- | `getSessionKey` | Yes | Returns the active tenant/account key. Return `false` while no session is ready. |
40
- | `errorNormalizer` | Yes | Converts thrown `Error` values into TSDF's shared `StoreError` shape. |
41
- | `lowPriorityThrottleMs` | No | Default minimum interval between low-priority fetches for attached stores. Defaults to `5`. |
42
- | `baseCoalescingWindowMs` | No | Default window to group fetch requests for attached stores. Defaults to `10`. |
43
- | `dynamicRealtimeThrottleMs` | No | Default adaptive throttle for real-time updates in attached stores. Defaults to `100ms` focused and `1000ms` in the background. Store options override it. |
44
- | `blockWindowClose` | No | Shared window-close blocker for mutations in attached stores. Defaults to `null`. |
45
- | `revalidateOnWindowFocus` | No | Default focus revalidation policy for attached stores. Store options override it. |
46
- | `onMutationError` | No | Global fallback for mutation failures when a store does not provide its own handler. |
47
- | `onPersistentStorageError` | No | Global fallback for persistent storage failures when a store does not provide its own handler. |
48
- | `debug` | No | Enables browser-tab sync and persistent-storage debug logs. Pass `true` or a logger function. |
49
- | `offlineSession` | No | Shared offline config used by stores with `persistentStorage.offline`. |
38
+ | Option | Required | Description |
39
+ | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
40
+ | `getSessionKey` | Yes | Returns the active tenant/account key. Return `false` while no session is ready. |
41
+ | `errorNormalizer` | Yes | Converts thrown `Error` values into TSDF's shared `StoreError` shape. |
42
+ | `lowPriorityThrottleMs` | No | Default minimum interval between low-priority fetches for attached stores. Defaults to 40 minutes (`2_400_000ms`). |
43
+ | `baseCoalescingWindowMs` | No | Default window to group fetch requests for attached stores. Defaults to `16ms`. |
44
+ | `backgroundCoalescingDelayMs` | No | Extra browser-tab coalescing delay applied only while a tab is in the background. Defaults to `3000ms`. |
45
+ | `dynamicRealtimeThrottleMs` | No | Default adaptive throttle for real-time updates in attached stores. Defaults to `100ms` focused and `1000ms` in the background. Store options override it. |
46
+ | `blockWindowClose` | No | Shared window-close blocker for mutations in attached stores. Defaults to `null`. |
47
+ | `revalidateOnWindowFocus` | No | Default focus revalidation policy for attached stores. Store options override it. |
48
+ | `onMutationError` | No | Global fallback for mutation failures when a store does not provide its own handler. |
49
+ | `onPersistentStorageError` | No | Global fallback for persistent storage failures when a store does not provide its own handler. |
50
+ | `debugLogger` | No | Enables verbose development-only browser-tab sync, focus revalidation, and persistent-storage debug logs. Pass `true` or a logger function. |
51
+ | `logger` | No | Enables low-volume production-safe logs such as persistent-storage quota cleanup. Defaults to console logging; pass `false` to disable or a function to customize. |
52
+ | `offlineSession` | No | Shared offline config used by stores with `persistentStorage.offline`. |
50
53
 
51
54
  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.
52
55
 
53
- Stores inherit the manager's `lowPriorityThrottleMs`, `baseCoalescingWindowMs`, and `dynamicRealtimeThrottleMs` unless they provide their own store-level overrides. The built-in `dynamicRealtimeThrottleMs` default returns `100ms` while focused and `1000ms` while the window is in the background. `blockWindowClose` is manager-only so window-close mutation protection is consistent across attached stores.
56
+ 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.
54
57
 
55
58
  Store-level options can explicitly disable inherited defaults when the option supports disabling: use `revalidateOnWindowFocus: false`, `onMutationError: null`, or `persistentStorage.onPersistentStorageError: null`.
56
59
 
57
60
  ## Debug Logging
58
61
 
59
- Pass `debug: true` to log browser-tab sync operations and persistent-storage operations through `console.log`, `console.warn`, and `console.error`. Async persistent storage logs include `durationMs` so slow OPFS, IndexedDB, or custom driver paths can be inspected.
62
+ Pass `debugLogger: true` to log browser-tab sync operations, focus revalidation decisions, and persistent-storage operations through `console.log`, `console.warn`, and `console.error` in development. Browser-tab sync logs include lifecycle, leader changes, publish/receive events, and skipped messages. Focus revalidation logs report when `revalidateOnWindowFocus` triggers, is dynamically disabled, or is skipped because real-time updates own freshness. 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. Async persistent storage adapters emit timed `adapter-operation` entries with `durationMs` so slow OPFS, IndexedDB, or custom driver paths can be inspected.
63
+
64
+ Low-volume production-safe signals are logged by default through `console.log`, `console.warn`, and `console.error`. Today this includes persistent-storage `quota-cleanup` entries. Pass `logger: false` to disable them, or pass a function to route them to your own tooling.
60
65
 
61
66
  ```ts
62
67
  const storeManager = createStoreManager({
63
68
  getSessionKey: () => currentTenantId ?? false,
64
69
  errorNormalizer: normalizeError,
65
- debug: ({ level, message, details }) => {
70
+ debugLogger: ({ level, message, details }) => {
71
+ observability[level](message, details);
72
+ },
73
+ logger: ({ level, message, details }) => {
66
74
  observability[level](message, details);
67
75
  },
68
76
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tsdf",
3
- "version": "17.0.0-alpha.9",
3
+ "version": "17.0.0-beta.0",
4
4
  "description": "A data fetching solution based on t-state",
5
5
  "license": "PolyForm-Noncommercial-1.0.0",
6
6
  "author": "Lucas Santos",
@@ -98,7 +98,7 @@
98
98
  "format": "oxfmt src/ tests/ apps/playground/src/",
99
99
  "tsc": "tsgo -p tsconfig.prod.json && tsgo -p tsconfig.playwright-fixture.json",
100
100
  "tsc:isolated": "tsgo -p tsconfig.isolated.json",
101
- "playground": "pnpm --filter @tsdf/playground dev",
101
+ "dev": "pnpm --filter @tsdf/playground dev",
102
102
  "playground:build": "pnpm --filter @tsdf/playground build",
103
103
  "build": "pnpm lint && pnpm test:all && pnpm build:no-test",
104
104
  "build:no-test": "tsdown",