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.
- package/README.md +2 -0
- package/dist/main.d.ts +2694 -366
- package/dist/main.js +18790 -2474
- package/docs/README.md +94 -0
- package/docs/batch-fetching.md +125 -0
- package/docs/browser-tabs-sync.md +59 -0
- package/docs/cache-limits.md +105 -0
- package/docs/collection-store.md +170 -0
- package/docs/document-store.md +147 -0
- package/docs/fetch-scheduling.md +93 -0
- package/docs/hooks.md +416 -0
- package/docs/invalidation.md +133 -0
- package/docs/list-query-store.md +348 -0
- package/docs/mutations.md +261 -0
- package/docs/offline.md +207 -0
- package/docs/offset-pagination.md +111 -0
- package/docs/optimistic-list-updates.md +180 -0
- package/docs/partial-resources.md +168 -0
- package/docs/persistent-storage.md +282 -0
- package/docs/real-time-updates.md +156 -0
- package/docs/shared-types.md +169 -0
- package/docs/store-manager.md +118 -0
- package/package.json +63 -46
- package/dist/main.cjs +0 -2511
- package/dist/main.d.cts +0 -400
|
@@ -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
|