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.
- package/dist/async-storage.d.ts +1 -1
- package/dist/async-storage.js +1 -1
- package/dist/{asyncStorageAdapter-BZSj1ZO5.js → asyncStorageAdapter-CGfnsd9m.js} +158 -81
- package/dist/{asyncStorageAdapter-BMYAF6rt.d.ts → asyncStorageAdapter-CMohMeKm.d.ts} +1 -1
- package/dist/{asyncStorageAdapters-DbyKyARM.js → asyncStorageAdapters-BpfM2_Y6.js} +2 -2
- package/dist/indexed-db-storage.d.ts +1 -1
- package/dist/indexed-db-storage.js +1 -1
- package/dist/{indexedDbPersistentStorage-DlUjN1qY.js → indexedDbPersistentStorage-DC9GsYHH.js} +63 -11
- package/dist/main.d.ts +18 -243
- package/dist/main.js +1117 -1224
- package/dist/opfs-storage.d.ts +1 -1
- package/dist/opfs-storage.js +1 -1
- package/dist/{opfsPersistentStorage-CBnUebnf.d.ts → opfsPersistentStorage-Ci0JcCo5.d.ts} +1 -1
- package/dist/{opfsPersistentStorage-BO_uDxe4.js → opfsPersistentStorage-DqJXzF7M.js} +57 -3
- package/dist/{types-2zQlbxtw.d.ts → types-D0ttVGmj.d.ts} +269 -8
- package/docs/README.md +2 -2
- package/docs/browser-tabs-sync.md +4 -3
- package/docs/collection-store.md +2 -2
- package/docs/document-store.md +4 -4
- package/docs/fetch-scheduling.md +13 -9
- package/docs/list-query-store.md +2 -2
- package/docs/offline.md +2 -2
- package/docs/offset-pagination.md +1 -4
- package/docs/optimistic-list-updates.md +13 -17
- package/docs/partial-resources.md +26 -1
- package/docs/persistent-storage.md +3 -3
- package/docs/real-time-updates.md +2 -0
- package/docs/store-manager.md +27 -19
- package/package.json +2 -2
|
@@ -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
|
-
|
|
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:
|
|
141
|
-
baseCoalescingWindowMs:
|
|
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
|
-
//
|
|
174
|
-
//
|
|
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
|
-
|
|
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({
|
|
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:
|
|
206
|
-
baseCoalescingWindowMs:
|
|
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:
|
package/docs/store-manager.md
CHANGED
|
@@ -16,8 +16,9 @@ const storeManager = createStoreManager({
|
|
|
16
16
|
id: 'unknown-error',
|
|
17
17
|
message: error.message,
|
|
18
18
|
}),
|
|
19
|
-
lowPriorityThrottleMs:
|
|
20
|
-
baseCoalescingWindowMs:
|
|
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
|
-
|
|
32
|
+
debugLogger: true,
|
|
32
33
|
});
|
|
33
34
|
```
|
|
34
35
|
|
|
35
36
|
Options:
|
|
36
37
|
|
|
37
|
-
| Option
|
|
38
|
-
|
|
|
39
|
-
| `getSessionKey`
|
|
40
|
-
| `errorNormalizer`
|
|
41
|
-
| `lowPriorityThrottleMs`
|
|
42
|
-
| `baseCoalescingWindowMs`
|
|
43
|
-
| `
|
|
44
|
-
| `
|
|
45
|
-
| `
|
|
46
|
-
| `
|
|
47
|
-
| `
|
|
48
|
-
| `
|
|
49
|
-
| `
|
|
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.
|
|
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 `
|
|
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
|
-
|
|
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-
|
|
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
|
-
"
|
|
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",
|