tsdf 16.0.3 → 17.0.0-alpha.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.
@@ -0,0 +1,133 @@
1
+ # Invalidation
2
+
3
+ Invalidation marks data as stale, causing mounted hooks to refetch and future hook mounts to trigger fresh fetches. TSDF provides granular invalidation control across all store types.
4
+
5
+ ## How Invalidation Works
6
+
7
+ When data is invalidated:
8
+
9
+ 1. The `refetchOnMount` flag is set to the invalidation priority on the affected data
10
+ 2. An invalidation event is emitted
11
+ 3. Any currently mounted hooks listening for that event schedule a refetch at the specified priority
12
+ 4. If no hooks are mounted, the `refetchOnMount` flag ensures the next mount triggers a fetch
13
+
14
+ Multiple invalidations are coalesced: if data already has a pending invalidation at the same or higher priority, the new invalidation is skipped.
15
+
16
+ ## Document Store
17
+
18
+ ```ts
19
+ // Invalidate with high priority (default)
20
+ store.invalidateData();
21
+
22
+ // Invalidate with specific priority
23
+ store.invalidateData('lowPriority');
24
+ store.invalidateData('realtimeUpdate');
25
+ ```
26
+
27
+ ## Collection Store
28
+
29
+ ```ts
30
+ // Single item
31
+ store.invalidateItem('item-1');
32
+
33
+ // Multiple items
34
+ store.invalidateItem(['item-1', 'item-2']);
35
+
36
+ // By filter
37
+ store.invalidateItem((payload, data) => data?.category === 'electronics');
38
+
39
+ // With specific priority
40
+ store.invalidateItem('item-1', 'lowPriority');
41
+ ```
42
+
43
+ ## List Query Store
44
+
45
+ The List Query Store has the most flexible invalidation through `invalidateQueryAndItems`:
46
+
47
+ ```ts
48
+ // Invalidate all queries and all items
49
+ store.invalidateQueryAndItems({
50
+ queryPayload: () => true,
51
+ itemPayload: () => true,
52
+ });
53
+
54
+ // Invalidate specific queries only (skip items)
55
+ store.invalidateQueryAndItems({
56
+ queryPayload: { projectId: 'proj-1' },
57
+ itemPayload: false,
58
+ });
59
+
60
+ // Invalidate specific items only (skip queries)
61
+ store.invalidateQueryAndItems({
62
+ queryPayload: false,
63
+ itemPayload: ['task-1', 'task-2'],
64
+ });
65
+
66
+ // Invalidate by filter
67
+ store.invalidateQueryAndItems({
68
+ queryPayload: (query) => query.status === 'active',
69
+ itemPayload: (item, payload) => item.priority > 5,
70
+ type: 'lowPriority',
71
+ });
72
+ ```
73
+
74
+ ### Item-only invalidation
75
+
76
+ ```ts
77
+ // Shorthand for invalidating only items (no queries)
78
+ store.invalidateItem('task-1');
79
+ store.invalidateItem(['task-1', 'task-2']);
80
+ store.invalidateItem((item, payload) => item.stale);
81
+ ```
82
+
83
+ Note: `invalidateItem` requires `fetchItemFn` to be configured. Without it, item invalidation is a no-op.
84
+
85
+ ### Per-field Invalidation
86
+
87
+ When [Partial Resources](./partial-resources.md) is enabled, you can invalidate specific fields:
88
+
89
+ ```ts
90
+ store.invalidateQueryAndItems({
91
+ queryPayload: false,
92
+ itemPayload: 'task-1',
93
+ fields: ['name', 'description'], // only these fields are refetched
94
+ });
95
+ ```
96
+
97
+ This removes the specified fields from the item's loaded fields tracking, causing hooks requesting those fields to refetch them.
98
+
99
+ ## Invalidation Priority
100
+
101
+ Invalidation respects the [fetch priority system](./fetch-scheduling.md):
102
+
103
+ | Priority | Typical use |
104
+ | ---------------- | --------------------------------------------- |
105
+ | `highPriority` | User action, explicit refresh (default) |
106
+ | `lowPriority` | Window focus revalidation, background updates |
107
+ | `realtimeUpdate` | WebSocket push notifications |
108
+
109
+ If data already has a pending invalidation at equal or higher priority, a new invalidation at a lower priority is ignored.
110
+
111
+ ## Interaction with Hooks
112
+
113
+ ### disableRefetches
114
+
115
+ When a hook has `disableRefetches: true`, it ignores invalidation events **unless** the store status is `idle` or `error`. This means the hook only fetches on initial load or after errors.
116
+
117
+ ### disableRefetchOnMount
118
+
119
+ When a hook has `disableRefetchOnMount: true`, it only fetches when:
120
+
121
+ - The data has never been loaded (`status === 'idle'`)
122
+ - The data was explicitly invalidated (`refetchOnMount` is set)
123
+
124
+ It skips the default low-priority fetch that normally occurs on every mount.
125
+
126
+ ## Automatic Invalidation
127
+
128
+ TSDF automatically invalidates data in these scenarios:
129
+
130
+ - **Mutation error**: After a failed mutation, affected data is invalidated to revert optimistic updates
131
+ - **Mutation success with `revalidateOnSuccess`**: Affected data is invalidated to fetch the server's actual state
132
+ - **Window focus**: When `revalidateOnWindowFocus` is enabled, all data is invalidated with `lowPriority`
133
+ - **Transport reconnect**: When `onTransportReconnect()` is called, all data is invalidated with `realtimeUpdate` priority. See [Real-Time Updates](./real-time-updates.md)
@@ -0,0 +1,348 @@
1
+ # List Query Store
2
+
3
+ The most feature-rich store type. It manages paginated lists (queries) combined with individual item queries. Items are shared across queries, so updating an item in one query automatically reflects in all other queries that reference it.
4
+
5
+ See also: [Hooks](./hooks.md) | [Mutations](./mutations.md) | [Invalidation](./invalidation.md) | [Optimistic List Updates](./optimistic-list-updates.md) | [Partial Resources](./partial-resources.md) | [Offset Pagination](./offset-pagination.md) | [Batch Fetching](./batch-fetching.md) | [Cache Limits](./cache-limits.md) | [Persistent Storage](./persistent-storage.md) | [Offline](./offline.md)
6
+
7
+ ## Creating a List Query Store
8
+
9
+ ```ts
10
+ import { createListQueryStore, createStoreManager } from 'tsdf';
11
+
12
+ type Task = {
13
+ id: string;
14
+ title: string;
15
+ status: 'todo' | 'done';
16
+ priority: number;
17
+ };
18
+ type TaskFilter = { status?: 'todo' | 'done'; projectId: string };
19
+ const storeManager = createStoreManager({
20
+ getSessionKey: () =>
21
+ authState.userId ? `tenant:${authState.tenantId}` : false,
22
+ errorNormalizer: normalizeError,
23
+ lowPriorityThrottleMs: 5,
24
+ baseCoalescingWindowMs: 10,
25
+ blockWindowClose: null,
26
+ });
27
+
28
+ const taskStore = createListQueryStore<Task, TaskFilter, string>({
29
+ id: 'list-query-tasks',
30
+ storeManager,
31
+ fetchListFn: (filter, size, { signal }) => api.getTasks(filter, size, signal),
32
+ fetchItemFn: (taskId, { signal }) => api.getTask(taskId, signal),
33
+ });
34
+ ```
35
+
36
+ The type parameters are:
37
+
38
+ - `ItemState` - The shape of each item
39
+ - `QueryPayload` - The payload that identifies a query (e.g., filter params)
40
+ - `ItemPayload` - The payload that identifies an individual item (e.g., item ID)
41
+ - `TPartialResources` (optional, `boolean`) - Enables [Partial Resources](./partial-resources.md)
42
+ - `TOffsetPagination` (optional, `boolean`) - Enables [Offset Pagination](./offset-pagination.md)
43
+
44
+ ## Options
45
+
46
+ ### Required Options
47
+
48
+ | Option | Type | Description |
49
+ | -------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
50
+ | `id` | `string` | Stable logical store id shared across tabs |
51
+ | `storeManager` | `StoreManager` | Shared global config with `getSessionKey`, `errorNormalizer`, and global store controls |
52
+ | `fetchListFn` | Size mode: `(payload, size, options) => Promise<FetchListFnReturn>` | Fetches a paginated list. See [Pagination modes](#pagination-modes) |
53
+
54
+ ### Optional Options
55
+
56
+ | Option | Type | Description |
57
+ | ------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
58
+ | `lowPriorityThrottleMs` | `number` | Overrides the manager default. See [Fetch Scheduling](./fetch-scheduling.md) |
59
+ | `baseCoalescingWindowMs` | `number` | Overrides the manager default. See [Fetch Scheduling](./fetch-scheduling.md) |
60
+ | `fetchItemFn` | `(payload, options: { signal, fields? }) => Promise<ItemState>` | Fetches a single item. Required for `useItem`, `invalidateItem`, `scheduleItemFetch` |
61
+ | `batchFetchItemFn` | `(requests, options) => Promise<Map<ItemPayload, ItemState \| Error>>` | See [Batch Fetching](./batch-fetching.md) |
62
+ | `getItemsBatchKey` | `(payload: ItemPayload) => string \| false` | See [Batch Fetching](./batch-fetching.md) |
63
+ | `defaultQuerySize` | `number` | Default page size (default: `50`) |
64
+ | `maxItemBatchSize` | `number` | Max items per batch fetch |
65
+ | `maxItems` | `number` | Maximum cached items kept in memory. Defaults to `5000`. See [Cache Limits](./cache-limits.md) |
66
+ | `maxQueries` | `number` | Maximum cached queries kept in memory. Defaults to `1000`. See [Cache Limits](./cache-limits.md) |
67
+ | `onStateCleanup` | `(cleanup) => void` | Called when memory cache eviction removes items or queries. See [Cache Limits](./cache-limits.md) |
68
+ | `optimisticListUpdates` | `OptimisticListUpdate[]` | See [Optimistic List Updates](./optimistic-list-updates.md) |
69
+ | `partialResources` | `PartialResourcesConfig` | See [Partial Resources](./partial-resources.md) |
70
+ | `derivedQueries` | `DerivedQueriesConfig` | Derive hook results from local items instead of fetching when possible |
71
+ | `offsetPagination` | `OffsetPaginationConfig` | See [Offset Pagination](./offset-pagination.md) |
72
+ | `getQueryKey` | `(params) => ValidPayload \| unknown[]` | Custom query key derivation |
73
+ | `getItemKey` | `(params) => ValidPayload \| unknown[]` | Custom item key derivation |
74
+ | `mediumPriorityDelayMs` | `number` | Delay before medium-priority fetches execute |
75
+ | `dynamicRealtimeThrottleMs` | `(params) => number` | See [Real-Time Updates](./real-time-updates.md) |
76
+ | `revalidateOnWindowFocus` | `boolean \| (() => boolean)` | Refetch on window focus |
77
+ | `transportReconnectCooldownMs` | `number` | Cooldown for repeated transport reconnect revalidation |
78
+ | `usesRealTimeUpdates` | `boolean` | See [Real-Time Updates](./real-time-updates.md) |
79
+ | `onInvalidateQuery` | `(query, priority) => void` | Called when a query is invalidated |
80
+ | `onInvalidateItem` | `(props: { itemState, payload, priority }) => void` | Called when an item is invalidated |
81
+ | `persistentStorage` | `ListQueryPersistentStorageConfig<ItemState, QueryPayload, ItemPayload>` | Configure cache persistence. See [Persistent Storage](./persistent-storage.md) |
82
+ | `onSchedulerEvent` | `(event, data?) => void` | Scheduler event listener |
83
+ | `onMutationError` | `(error, options) => void` | Global mutation error handler |
84
+
85
+ ### FetchListFnReturn
86
+
87
+ The `fetchListFn` must return:
88
+
89
+ ```ts
90
+ type FetchListFnReturn<ItemState, ItemPayload> = {
91
+ items: { itemPayload: ItemPayload; data: ItemState }[];
92
+ hasMore: boolean;
93
+ };
94
+ ```
95
+
96
+ ### Pagination Modes
97
+
98
+ **Size mode (default):**
99
+
100
+ ```ts
101
+ fetchListFn: (payload, size, { signal, fields? }) => Promise<FetchListFnReturn>
102
+ ```
103
+
104
+ **Offset mode** (when `offsetPagination` is set):
105
+
106
+ ```ts
107
+ fetchListFn: (payload, { offset, limit }, { signal, fields? }) => Promise<FetchListFnReturn>
108
+ ```
109
+
110
+ See [Offset Pagination](./offset-pagination.md) for details.
111
+
112
+ ## State Shape
113
+
114
+ ```ts
115
+ type TSFDListQueryState<ItemState, QueryPayload, ItemPayload> = {
116
+ items: Record<string, ItemState | null>;
117
+ queries: Record<string, TSFDListQuery<QueryPayload>>;
118
+ itemQueries: Record<string, TSDFItemQuery<ItemPayload> | null>;
119
+ itemLoadedFields: Record<string, string[]>;
120
+ itemFieldInvalidationFields: Record<string, string[]>;
121
+ };
122
+ ```
123
+
124
+ ### Query State
125
+
126
+ ```ts
127
+ type TSFDListQuery<QueryPayload> = {
128
+ error: StoreError | null;
129
+ status: 'loading' | 'error' | 'refetching' | 'success' | 'loadingMore';
130
+ payload: QueryPayload;
131
+ hasMore: boolean;
132
+ wasLoaded: boolean;
133
+ refetchOnMount:
134
+ | false
135
+ | 'lowPriority'
136
+ | 'mediumPriority'
137
+ | 'realtimeUpdate'
138
+ | 'highPriority';
139
+ items: string[]; // Array of item keys
140
+ };
141
+ ```
142
+
143
+ ### Item Query State
144
+
145
+ ```ts
146
+ type TSDFItemQuery<ItemPayload> = {
147
+ error: StoreError | null;
148
+ status: 'loading' | 'error' | 'refetching' | 'success';
149
+ wasLoaded: boolean;
150
+ refetchOnMount:
151
+ | false
152
+ | 'lowPriority'
153
+ | 'mediumPriority'
154
+ | 'realtimeUpdate'
155
+ | 'highPriority';
156
+ payload: ItemPayload;
157
+ };
158
+ ```
159
+
160
+ Key points:
161
+
162
+ - `items` stores the actual data, shared across queries
163
+ - `queries` stores query metadata and an ordered list of item keys
164
+ - `itemQueries` stores per-item fetch metadata (for `fetchItemFn`)
165
+ - `itemLoadedFields` / `itemFieldInvalidationFields` are used by [Partial Resources](./partial-resources.md)
166
+ - Derived query results are hook-level computed views only; they are not stored in `queries`
167
+
168
+ ## Derived Queries
169
+
170
+ `derivedQueries` lets hooks resolve a list query from locally materialized items
171
+ instead of fetching when the store can produce a reliable result.
172
+
173
+ ```ts
174
+ derivedQueries: {
175
+ getQueryGroup: (queryPayload) => queryPayload.tableId,
176
+ getItemGroup: (_item, itemPayload) => itemPayload.split('||')[0] ?? '',
177
+ isComplete: (queryPayload, { queries }) => queries.length > 0,
178
+ deriveQuery: (queryPayload, items, { fields, isOfflineMode, deriveSource }) => {
179
+ if (Array.isArray(fields) && fields.includes('age')) {
180
+ return false;
181
+ }
182
+
183
+ return items.map(({ key }) => key);
184
+ },
185
+ }
186
+ ```
187
+
188
+ Behavior:
189
+
190
+ - Online: exact query cache wins; otherwise TSDF can derive when `isComplete(...)` returns `true`
191
+ - Offline: derivation is attempted before the exact cached query result
192
+ - `deriveQuery(...)` receives `{ fields, isOfflineMode, deriveSource }`
193
+ - `fields` lets derivation opt out of partial-resource queries when local data is insufficient
194
+ - `deriveSource` is `'online'`, `'offline'`, or `'sticky-offline'`
195
+ - Derived results expose `isDerived: true`
196
+ - Derived results always expose `hasMore: false`
197
+ - Derived results do not create `state.queries[queryKey]`
198
+
199
+ ## API
200
+
201
+ ### Hooks
202
+
203
+ | Hook | Description | Details |
204
+ | ------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------- |
205
+ | `useListQuery(payload, options?)` | Fetch and subscribe to a list query | See [Hooks - useListQuery](./hooks.md#uselistquery) |
206
+ | `usePendingOfflineItems(options?)` | Read queued offline items without fetching | See [Hooks - usePendingOfflineItems](./hooks.md#usependingofflineitems) |
207
+ | `useMultipleListQueries(queries, options?)` | Fetch multiple list queries | See [Hooks - useMultipleListQueries](./hooks.md#usemultiplelistqueries) |
208
+ | `useItem(payload, options?)` | Fetch and subscribe to a single item | See [Hooks - useItem](./hooks.md#useitem) |
209
+ | `useMultipleItems(items, options?)` | Fetch multiple individual items | See [Hooks - useMultipleItems](./hooks.md#usemultipleitems) |
210
+ | `useFindItem(findFn, options?)` | Find an item by predicate across all items | See [Hooks - useFindItem](./hooks.md#usefinditem) |
211
+
212
+ ### Query Methods
213
+
214
+ | Method | Signature | Description |
215
+ | ------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ |
216
+ | `scheduleListQueryFetch` | `(fetchType, payload(s), size?, options?) => ScheduleFetchResults` | Schedule a list fetch |
217
+ | `awaitListQueryFetch` | `(params, options?) => Promise<{ items, error, hasMore }>` | Await a list fetch |
218
+ | `preloadQueryFromStorage` | `(payloads) => Promise<PersistentStoragePreloadResult<QueryPayload>[]>` | Preload cached list query payloads from async storage (OPFS) |
219
+ | `loadMore` | `(params, size?, options?) => ScheduleFetchResults` | Load more items (pagination) |
220
+ | `getQueryState` | `(params) => TSFDListQuery` | Get query state |
221
+ | `getQueryKey` | `(params) => string` | Get composite key for a query payload |
222
+ | `getQueriesState` | `(params) => { query, key }[]` | Get multiple query states |
223
+ | `getQueriesRelatedToItem` | `(itemPayload) => TSFDListQuery[]` | Find queries containing an item |
224
+
225
+ ### Item Methods
226
+
227
+ | Method | Signature | Description |
228
+ | ------------------------ | -------------------------------------------------------------------- | --------------------------------------------------- |
229
+ | `scheduleItemFetch` | `(fetchType, payload(s), options?) => ScheduleFetchResults` | Schedule an item fetch |
230
+ | `awaitItemFetch` | `(itemPayload, options?) => Promise<{ data, error }>` | Await an item fetch |
231
+ | `preloadItemFromStorage` | `(params) => Promise<PersistentStoragePreloadResult<ItemPayload>[]>` | Preload cached list items from async storage (OPFS) |
232
+ | `getItemKey` | `(params) => string` | Get composite key for an item payload |
233
+ | `getItemState` | `(payload) => ItemState \| null` | Get item data |
234
+
235
+ ### Offline Methods
236
+
237
+ | Method | Description |
238
+ | ----------------------------------------------------- | ----------------------------------------------------------------- |
239
+ | `getOfflineEntities()` / `useOfflineEntities()` | Read offline entities scoped to this store |
240
+ | `getOfflineResolutions()` / `useOfflineResolutions()` | Read manual conflict/retry resolutions scoped to this store |
241
+ | `parseOfflineResolutionConflict(resolution)` | Narrow a persisted resolution to this store's operation types |
242
+ | `resolveOfflineResolution(id, operation, action)` | Resolve, retry, discard, requeue, or commit an offline resolution |
243
+
244
+ ### Offline Queue Hook
245
+
246
+ `usePendingOfflineItems(options?)` is the list-query-store hook for reading the
247
+ store's pending offline item state directly.
248
+
249
+ Use it when:
250
+
251
+ - you need queued offline items even if no query is mounted
252
+ - you want pending deletes separately from visible pending items
253
+ - you want offline queue UI without triggering fetches
254
+
255
+ Unlike `useListQuery(...)`, it does not load query results or expose query
256
+ status. It derives data from the offline queue, overlays, live store state,
257
+ and persisted item snapshots, using the precomputed offline entity lifecycle
258
+ kind so pending deletes do not need item hydration before they appear.
259
+
260
+ ### Mutation Methods
261
+
262
+ | Method | Description | Details |
263
+ | ----------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------- |
264
+ | `invalidateQueryAndItems(options)` | Invalidate queries and/or items | See [Invalidation](./invalidation.md) |
265
+ | `invalidateItem(payload(s), priority?)` | Invalidate item(s) only | See [Invalidation](./invalidation.md) |
266
+ | `updateItemState(itemIds, produceFn, options?)` | Immer-based item update + applies [Optimistic List Updates](./optimistic-list-updates.md) |
267
+ | `addItemToState(itemPayload, data, options?)` | Add an item with optional query placement |
268
+ | `deleteItemState(itemId)` | Delete item from all queries |
269
+ | `startItemMutation(itemId)` | Start mutation lock on item + related queries |
270
+ | `performMutation(payload, options)` | Full mutation lifecycle. See [Mutations](./mutations.md) |
271
+
272
+ ### Other
273
+
274
+ | Method | Description |
275
+ | ------------------------ | ----------------------------------------------- |
276
+ | `reset()` | Full reset of all state and schedulers |
277
+ | `onTransportReconnect()` | See [Real-Time Updates](./real-time-updates.md) |
278
+
279
+ ### Properties
280
+
281
+ | Property | Type | Description |
282
+ | ------------- | ------------------------------------ | --------------------------------------------------------- |
283
+ | `store` | `Store<TSFDListQueryState>` | Underlying t-state store |
284
+ | `events` | `Emitter<ListQueryStoreEvents>` | Invalidation events (`invalidateQuery`, `invalidateItem`) |
285
+ | `storeEvents` | `Emitter<ListQueryStoreStoreEvents>` | Mutation lifecycle events |
286
+
287
+ ## Usage Example
288
+
289
+ ```tsx
290
+ // List view
291
+ function TaskList({ projectId }: { projectId: string }) {
292
+ const { items, isLoading, hasMore, status } = taskStore.useListQuery({
293
+ projectId,
294
+ status: 'todo',
295
+ });
296
+
297
+ if (isLoading) return <Spinner />;
298
+
299
+ return (
300
+ <div>
301
+ {items.map((task) => (
302
+ <TaskRow
303
+ key={task.id}
304
+ task={task}
305
+ />
306
+ ))}
307
+ {hasMore && (
308
+ <button
309
+ onClick={() => taskStore.loadMore({ projectId, status: 'todo' })}
310
+ >
311
+ Load More
312
+ </button>
313
+ )}
314
+ </div>
315
+ );
316
+ }
317
+
318
+ // Item view (shares state with list)
319
+ function TaskDetail({ taskId }: { taskId: string }) {
320
+ const { data, isLoading } = taskStore.useItem(taskId);
321
+
322
+ if (isLoading) return <Spinner />;
323
+
324
+ return <div>{data?.title}</div>;
325
+ }
326
+
327
+ // Add item to specific queries
328
+ taskStore.addItemToState('task-new', newTask, {
329
+ addItemToQueries: {
330
+ queries: { projectId: 'proj-1', status: 'todo' },
331
+ appendTo: 'start',
332
+ },
333
+ });
334
+ ```
335
+
336
+ ## addItemToState Options
337
+
338
+ ```ts
339
+ addItemToState(itemPayload, data, {
340
+ addItemToQueries?: {
341
+ queries: QueryPayload[] | FilterQuery | QueryPayload;
342
+ appendTo: 'start' | 'end' | ((itemsPayload: ItemPayload[]) => number);
343
+ }
344
+ })
345
+ ```
346
+
347
+ - `queries` - Which queries to add the item to
348
+ - `appendTo` - Where to insert: `'start'`, `'end'`, or a function returning the insertion index