tsdf 16.0.3 → 17.0.0-alpha.10
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/LICENSE +140 -0
- package/README.md +5 -0
- package/dist/async-storage.d.ts +2 -0
- package/dist/async-storage.js +2 -0
- package/dist/asyncStorageAdapter-BMYAF6rt.d.ts +6 -0
- package/dist/asyncStorageAdapter-BZSj1ZO5.js +1868 -0
- package/dist/asyncStorageAdapters-DbyKyARM.js +3 -0
- package/dist/indexed-db-storage.d.ts +14 -0
- package/dist/indexed-db-storage.js +2 -0
- package/dist/indexedDbPersistentStorage-DlUjN1qY.js +902 -0
- package/dist/main.d.ts +1487 -373
- package/dist/main.js +16146 -2475
- package/dist/opfs-storage.d.ts +2 -0
- package/dist/opfs-storage.js +2 -0
- package/dist/opfsPersistentStorage-BO_uDxe4.js +838 -0
- package/dist/opfsPersistentStorage-CBnUebnf.d.ts +6 -0
- package/dist/types-2zQlbxtw.d.ts +1475 -0
- package/docs/README.md +98 -0
- package/docs/batch-fetching.md +125 -0
- package/docs/browser-tabs-sync.md +61 -0
- package/docs/cache-limits.md +105 -0
- package/docs/collection-store.md +173 -0
- package/docs/document-store.md +149 -0
- package/docs/fetch-scheduling.md +93 -0
- package/docs/hooks.md +416 -0
- package/docs/invalidation.md +135 -0
- package/docs/list-query-store.md +352 -0
- package/docs/mutations.md +266 -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 +290 -0
- package/docs/real-time-updates.md +158 -0
- package/docs/shared-types.md +181 -0
- package/docs/store-manager.md +147 -0
- package/package.json +81 -47
- package/dist/main.cjs +0 -2511
- package/dist/main.d.cts +0 -400
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
# Optimistic List Updates
|
|
2
|
+
|
|
3
|
+
Optimistic list updates automatically keep list queries in sync when item state changes. When you update an item, the configured rules determine whether items should be added to, removed from, or re-sorted within queries — all without waiting for a server response.
|
|
4
|
+
|
|
5
|
+
**Store**: [List Query Store](./list-query-store.md) only.
|
|
6
|
+
|
|
7
|
+
## How It Works
|
|
8
|
+
|
|
9
|
+
When you call `updateItemState` or `addItemToState`, TSDF applies optimistic list update rules to the affected queries. These rules can:
|
|
10
|
+
|
|
11
|
+
1. **Filter items in/out of queries** based on item data
|
|
12
|
+
2. **Re-sort queries** based on updated item values
|
|
13
|
+
3. **Trigger background revalidation** of affected queries
|
|
14
|
+
|
|
15
|
+
## Configuration
|
|
16
|
+
|
|
17
|
+
Define rules when creating the store:
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
const taskStore = createListQueryStore<Task, TaskFilter, string>({
|
|
21
|
+
// ...other options
|
|
22
|
+
|
|
23
|
+
optimisticListUpdates: [
|
|
24
|
+
{
|
|
25
|
+
// Which queries this rule applies to
|
|
26
|
+
queries: (query) => query.projectId != null,
|
|
27
|
+
|
|
28
|
+
// Decide if an item should be in the query
|
|
29
|
+
filterItem: (item) => item.status === 'active',
|
|
30
|
+
|
|
31
|
+
// Where to add new items
|
|
32
|
+
appendNewTo: 'start',
|
|
33
|
+
|
|
34
|
+
// Trigger background revalidation when items are moved
|
|
35
|
+
invalidateQueries: true,
|
|
36
|
+
},
|
|
37
|
+
{
|
|
38
|
+
// Sort a specific query by priority
|
|
39
|
+
queries: { projectId: 'proj-1', status: 'active' },
|
|
40
|
+
sort: { sortBy: (item) => item.priority, order: 'desc' },
|
|
41
|
+
},
|
|
42
|
+
],
|
|
43
|
+
});
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Rule Options
|
|
47
|
+
|
|
48
|
+
### queries
|
|
49
|
+
|
|
50
|
+
Specifies which queries this rule applies to:
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
// Single query
|
|
54
|
+
queries: {
|
|
55
|
+
projectId: 'proj-1';
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
// Multiple queries
|
|
59
|
+
queries: [{ projectId: 'proj-1' }, { projectId: 'proj-2' }];
|
|
60
|
+
|
|
61
|
+
// Filter function
|
|
62
|
+
queries: (queryPayload) => queryPayload.status === 'active';
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### filterItem
|
|
66
|
+
|
|
67
|
+
Decides whether an item should be included in matching queries:
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
filterItem: (item) => {
|
|
71
|
+
// true → item should be in the query (add if missing)
|
|
72
|
+
// false → item should NOT be in the query (remove if present)
|
|
73
|
+
// null → skip this rule for this item (no change)
|
|
74
|
+
return item.status === 'active';
|
|
75
|
+
};
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
- When `filterItem` returns `true` and the item is not in the query, it's added at the position specified by `appendNewTo`
|
|
79
|
+
- When `filterItem` returns `false` and the item is in the query, it's removed
|
|
80
|
+
- When `filterItem` returns `null`, the rule is skipped for that item
|
|
81
|
+
|
|
82
|
+
### appendNewTo
|
|
83
|
+
|
|
84
|
+
Where to insert items when `filterItem` adds them to a query:
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
appendNewTo: 'start'; // prepend to the beginning
|
|
88
|
+
appendNewTo: 'end'; // append to the end (default)
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### sort
|
|
92
|
+
|
|
93
|
+
Re-sorts the query's items after an update:
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
sort: {
|
|
97
|
+
sortBy: (item, itemPayload) => item.priority,
|
|
98
|
+
order: 'desc', // 'asc' | 'desc'
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
For multi-key sorting:
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
sort: {
|
|
106
|
+
sortBy: (item) => [item.category, item.priority],
|
|
107
|
+
order: ['asc', 'desc'],
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Sorting is applied only to queries that contain the updated item.
|
|
112
|
+
|
|
113
|
+
### invalidateQueries
|
|
114
|
+
|
|
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.
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
invalidateQueries: true;
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## When Rules Are Applied
|
|
122
|
+
|
|
123
|
+
Optimistic list updates are triggered by:
|
|
124
|
+
|
|
125
|
+
1. **`updateItemState`** — After updating item data, all rules are evaluated for the updated items
|
|
126
|
+
2. **`addItemToState`** — After adding a new item, rules determine which queries should include it
|
|
127
|
+
|
|
128
|
+
They are **not** triggered by:
|
|
129
|
+
|
|
130
|
+
- `deleteItemState` (items are simply removed from all queries)
|
|
131
|
+
- Direct store mutations
|
|
132
|
+
- Fetch completions
|
|
133
|
+
|
|
134
|
+
## Example: Task Board
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
const storeManager = createStoreManager({
|
|
138
|
+
getSessionKey: () => currentTenantId ?? false,
|
|
139
|
+
errorNormalizer: normalizeError,
|
|
140
|
+
lowPriorityThrottleMs: 5,
|
|
141
|
+
baseCoalescingWindowMs: 10,
|
|
142
|
+
blockWindowClose: null,
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
const taskStore = createListQueryStore<Task, { status: string }, string>({
|
|
146
|
+
id: 'tasks',
|
|
147
|
+
storeManager,
|
|
148
|
+
fetchListFn: (filter, size, { signal }) => api.getTasks(filter, size, signal),
|
|
149
|
+
fetchItemFn: (id, { signal }) => api.getTask(id, signal),
|
|
150
|
+
|
|
151
|
+
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
|
+
},
|
|
158
|
+
{
|
|
159
|
+
queries: { status: 'todo' },
|
|
160
|
+
filterItem: (item) => item.status === 'todo',
|
|
161
|
+
appendNewTo: 'start',
|
|
162
|
+
invalidateQueries: true,
|
|
163
|
+
},
|
|
164
|
+
{
|
|
165
|
+
queries: { status: 'done' },
|
|
166
|
+
filterItem: (item) => item.status === 'done',
|
|
167
|
+
appendNewTo: 'end',
|
|
168
|
+
invalidateQueries: true,
|
|
169
|
+
},
|
|
170
|
+
],
|
|
171
|
+
});
|
|
172
|
+
|
|
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
|
|
177
|
+
taskStore.updateItemState('task-1', (draft) => {
|
|
178
|
+
draft.status = 'done';
|
|
179
|
+
});
|
|
180
|
+
```
|
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
# Partial Resources
|
|
2
|
+
|
|
3
|
+
Partial resources allow you to fetch only specific fields of an item, reducing payload size and improving performance. Different hooks can request different fields, and TSDF tracks which fields have been loaded per item.
|
|
4
|
+
|
|
5
|
+
**Store**: [List Query Store](./list-query-store.md) only.
|
|
6
|
+
|
|
7
|
+
## Enabling Partial Resources
|
|
8
|
+
|
|
9
|
+
Enable by setting the `TPartialResources` type parameter to `true` and providing a `partialResources` config:
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
type User = {
|
|
13
|
+
id: string;
|
|
14
|
+
name: string;
|
|
15
|
+
email: string;
|
|
16
|
+
avatar: string;
|
|
17
|
+
bio: string;
|
|
18
|
+
};
|
|
19
|
+
|
|
20
|
+
const storeManager = createStoreManager({
|
|
21
|
+
getSessionKey: () => currentTenantId ?? false,
|
|
22
|
+
errorNormalizer: normalizeError,
|
|
23
|
+
});
|
|
24
|
+
|
|
25
|
+
const userStore = createListQueryStore<User, UserFilter, string, true>({
|
|
26
|
+
// ^^^^ enables partial resources
|
|
27
|
+
storeManager,
|
|
28
|
+
|
|
29
|
+
fetchListFn: (filter, size, { signal, fields }) => {
|
|
30
|
+
// `fields` is string[] | undefined
|
|
31
|
+
// undefined means fetch all fields
|
|
32
|
+
return api.getUsers(filter, size, { signal, fields });
|
|
33
|
+
},
|
|
34
|
+
|
|
35
|
+
fetchItemFn: (userId, { signal, fields }) => {
|
|
36
|
+
return api.getUser(userId, { signal, fields });
|
|
37
|
+
},
|
|
38
|
+
|
|
39
|
+
partialResources: {
|
|
40
|
+
// Merge newly fetched fields with previously loaded ones
|
|
41
|
+
mergeItems: (prev, fetched) => ({ ...(prev ?? {}), ...fetched }),
|
|
42
|
+
|
|
43
|
+
// Select only the requested fields from a full item
|
|
44
|
+
selectFields: (fields, item) => {
|
|
45
|
+
const result: Partial<User> = {};
|
|
46
|
+
for (const field of fields) {
|
|
47
|
+
result[field] = item[field];
|
|
48
|
+
}
|
|
49
|
+
return result as User;
|
|
50
|
+
},
|
|
51
|
+
},
|
|
52
|
+
|
|
53
|
+
// ...other options
|
|
54
|
+
});
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## How It Works
|
|
58
|
+
|
|
59
|
+
1. Each hook specifies which `fields` it needs
|
|
60
|
+
2. TSDF tracks `itemLoadedFields` — the set of fields already loaded for each item
|
|
61
|
+
3. When a hook requests fields that haven't been loaded yet, a fetch is triggered requesting only the missing fields
|
|
62
|
+
4. The `mergeItems` function combines the newly fetched data with previously loaded data
|
|
63
|
+
5. The `selectFields` function extracts the requested fields for the hook's return value
|
|
64
|
+
|
|
65
|
+
## Using Fields in Hooks
|
|
66
|
+
|
|
67
|
+
When partial resources is enabled, the `fields` option becomes **required** in hooks:
|
|
68
|
+
|
|
69
|
+
```tsx
|
|
70
|
+
// Fetch only name and email
|
|
71
|
+
function UserCard({ userId }: { userId: string }) {
|
|
72
|
+
const { data } = userStore.useItem(userId, { fields: ['name', 'email'] });
|
|
73
|
+
|
|
74
|
+
return (
|
|
75
|
+
<div>
|
|
76
|
+
{data?.name} ({data?.email})
|
|
77
|
+
</div>
|
|
78
|
+
);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
// Fetch all fields
|
|
82
|
+
function UserProfile({ userId }: { userId: string }) {
|
|
83
|
+
const { data } = userStore.useItem(userId, {
|
|
84
|
+
fields: '*', // '*' means all fields
|
|
85
|
+
});
|
|
86
|
+
|
|
87
|
+
return <div>{data?.bio}</div>;
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
For list queries:
|
|
92
|
+
|
|
93
|
+
```tsx
|
|
94
|
+
function UserList() {
|
|
95
|
+
const { items } = userStore.useListQuery(
|
|
96
|
+
{ active: true },
|
|
97
|
+
{ fields: ['name', 'avatar'] },
|
|
98
|
+
);
|
|
99
|
+
|
|
100
|
+
return items.map((user) => (
|
|
101
|
+
<UserRow
|
|
102
|
+
key={user.id}
|
|
103
|
+
name={user.name}
|
|
104
|
+
avatar={user.avatar}
|
|
105
|
+
/>
|
|
106
|
+
));
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## Per-Field Invalidation
|
|
111
|
+
|
|
112
|
+
You can invalidate specific fields without refetching everything:
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
userStore.invalidateQueryAndItems({
|
|
116
|
+
queryPayload: false,
|
|
117
|
+
itemPayload: 'user-1',
|
|
118
|
+
fields: ['name', 'email'], // only these fields are refetched
|
|
119
|
+
});
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
This removes the specified fields from `itemLoadedFields`, causing hooks that request those fields to trigger a refetch — but only for those fields.
|
|
123
|
+
|
|
124
|
+
## Loading Behavior
|
|
125
|
+
|
|
126
|
+
When a hook requests fields that are partially loaded:
|
|
127
|
+
|
|
128
|
+
- During the field fetch, the hook returns `null` data to prevent displaying stale partial data
|
|
129
|
+
- Once the missing fields are loaded and merged, the complete data is returned
|
|
130
|
+
|
|
131
|
+
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
|
+
|
|
133
|
+
## Fields in Scheduling and Fetching
|
|
134
|
+
|
|
135
|
+
Fields propagate through the scheduling and fetching APIs:
|
|
136
|
+
|
|
137
|
+
```ts
|
|
138
|
+
// Schedule a fetch for specific fields
|
|
139
|
+
store.scheduleItemFetch('highPriority', 'user-1', {
|
|
140
|
+
fields: ['name', 'email'],
|
|
141
|
+
});
|
|
142
|
+
|
|
143
|
+
// Await a fetch for specific fields
|
|
144
|
+
const result = await store.awaitItemFetch('user-1', { fields: ['name'] });
|
|
145
|
+
|
|
146
|
+
// Schedule a list query fetch
|
|
147
|
+
store.scheduleListQueryFetch('highPriority', filter, undefined, {
|
|
148
|
+
fields: ['name', 'avatar'],
|
|
149
|
+
});
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
## partialResources Config
|
|
153
|
+
|
|
154
|
+
### mergeItems
|
|
155
|
+
|
|
156
|
+
```ts
|
|
157
|
+
mergeItems: (prev: ItemState | undefined, fetched: ItemState) => ItemState;
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Called when new fields arrive. `prev` is `undefined` if the item has never been fetched before. Should return the merged item with all known fields.
|
|
161
|
+
|
|
162
|
+
### selectFields
|
|
163
|
+
|
|
164
|
+
```ts
|
|
165
|
+
selectFields: (fields: string[], item: ItemState) => ItemState;
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
Called when a hook requests specific fields. Should return an item containing only the requested fields.
|
|
@@ -0,0 +1,290 @@
|
|
|
1
|
+
# Persistent Storage
|
|
2
|
+
|
|
3
|
+
TSDF can persist cached data across page reloads and browser sessions through the optional `persistentStorage` option on each store type.
|
|
4
|
+
|
|
5
|
+
See also: [Document Store](./document-store.md) | [Collection Store](./collection-store.md) | [List Query Store](./list-query-store.md) | [Offline](./offline.md)
|
|
6
|
+
|
|
7
|
+
## What it does
|
|
8
|
+
|
|
9
|
+
- Loads cached entries before network fetches when available.
|
|
10
|
+
- Persists successful fetch results back to local storage.
|
|
11
|
+
- Invalidates and drops cache entries when schema or version checks fail.
|
|
12
|
+
- Uses session scoped keys, so data is isolated per tenant/account.
|
|
13
|
+
|
|
14
|
+
## Public API
|
|
15
|
+
|
|
16
|
+
Exported from `tsdf`:
|
|
17
|
+
|
|
18
|
+
| Export | Description |
|
|
19
|
+
| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
|
|
20
|
+
| `PersistentStorageSchema` | Schema type supported by cache validation |
|
|
21
|
+
| `PersistentStorageDataSchema` / `ConvertedPersistentStorageDataSchema` | Direct or converted persisted data schema config |
|
|
22
|
+
| `StorageAdapter` | `'local-sync'` or a managed async storage adapter |
|
|
23
|
+
| `DocumentPersistentStorageConfig` / `CollectionPersistentStorageConfig` / `ListQueryPersistentStorageConfig` | Store-level persistence config types |
|
|
24
|
+
| `createStoreManager(options)` | Creates the shared store manager used by all stores |
|
|
25
|
+
| `PersistentStoragePreloadResult<Payload>` | Return shape for preload methods |
|
|
26
|
+
| `localPersistentStorage` | Built-in localStorage helper used by the `'local-sync'` adapter |
|
|
27
|
+
| `clearSessionStorage(sessionKey, adapter)` | Clears all TSDF entries for one session/adapter |
|
|
28
|
+
| `clearAllSessionStorage(sessionKey)` | Clears all TSDF entries for one session across built-in adapters |
|
|
29
|
+
|
|
30
|
+
Exported from async-storage subpaths:
|
|
31
|
+
|
|
32
|
+
| Export | Import From | Description |
|
|
33
|
+
| -------------------------------------------- | ------------------------- | ------------------------------------------------------------- |
|
|
34
|
+
| `opfsPersistentStorage` | `tsdf/opfs-storage` | Built-in OPFS async storage adapter |
|
|
35
|
+
| `indexedDbPersistentStorage` | `tsdf/indexed-db-storage` | Built-in IndexedDB async storage adapter |
|
|
36
|
+
| `createIndexedDbPersistentStorage(options?)` | `tsdf/indexed-db-storage` | Creates an IndexedDB adapter, optionally with a database name |
|
|
37
|
+
| `createAsyncStorageAdapter(driver)` | `tsdf/async-storage` | Wraps a custom async storage driver |
|
|
38
|
+
|
|
39
|
+
## Configuration
|
|
40
|
+
|
|
41
|
+
Each store accepts `persistentStorage` in options:
|
|
42
|
+
|
|
43
|
+
| Store | Config Type |
|
|
44
|
+
| ---------------- | ------------------------------------------------------------------------ |
|
|
45
|
+
| Document Store | `DocumentPersistentStorageConfig<State>` |
|
|
46
|
+
| Collection Store | `CollectionPersistentStorageConfig<ItemState, ItemPayload>` |
|
|
47
|
+
| List Query Store | `ListQueryPersistentStorageConfig<ItemState, QueryPayload, ItemPayload>` |
|
|
48
|
+
|
|
49
|
+
Common options (applies to all store configs):
|
|
50
|
+
|
|
51
|
+
| Option | Required | Description |
|
|
52
|
+
| --------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
53
|
+
| `schema` | Yes | Schema used to validate restored data. |
|
|
54
|
+
| `adapter` | Yes | `'local-sync'`, `opfsPersistentStorage`, `indexedDbPersistentStorage`, or a custom async adapter. |
|
|
55
|
+
| `version` | No | Cache version; bump to invalidate old entries. |
|
|
56
|
+
| `onPersistentStorageError(error)` | No | Store-specific callback for write/read failures (quota, decode, etc.). Overrides the manager fallback; use `null` to disable it. |
|
|
57
|
+
|
|
58
|
+
Store-specific options:
|
|
59
|
+
|
|
60
|
+
| Store | Additional options |
|
|
61
|
+
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
62
|
+
| Collection Store | `payloadSchema`, `maxBytes`, `pinnedItems`, `ignoreItems` |
|
|
63
|
+
| List Query Store | `itemPayloadSchema`, `queryPayloadSchema`, `maxItemBytes`, `maxQueryBytes`, `maxQuerySize`, `pinnedItems`, `pinnedQueries`, `ignoreItems` |
|
|
64
|
+
|
|
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
|
+
|
|
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.
|
|
68
|
+
|
|
69
|
+
## Converted Data Schemas
|
|
70
|
+
|
|
71
|
+
Use `ConvertedPersistentStorageDataSchema<TStore, TStorage>` when the in-memory store shape should differ from the data saved in persistent storage. This is useful for compact cache formats, migration-friendly storage shapes, or persisted data that should omit derived fields.
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
import { rc_number, rc_object, rc_string } from 'runcheck';
|
|
75
|
+
import type { ConvertedPersistentStorageDataSchema } from 'tsdf';
|
|
76
|
+
|
|
77
|
+
type User = { profile: { name: string; score: number } };
|
|
78
|
+
|
|
79
|
+
type StoredUser = { n: string; s: number };
|
|
80
|
+
|
|
81
|
+
const userPersistenceSchema: ConvertedPersistentStorageDataSchema<
|
|
82
|
+
User,
|
|
83
|
+
StoredUser
|
|
84
|
+
> = {
|
|
85
|
+
storeSchema: rc_object({
|
|
86
|
+
profile: rc_object({ name: rc_string(), score: rc_number() }),
|
|
87
|
+
}),
|
|
88
|
+
storageSchema: rc_object({ n: rc_string(), s: rc_number() }),
|
|
89
|
+
convertToStorage: (user) => ({ n: user.profile.name, s: user.profile.score }),
|
|
90
|
+
convertFromStorage: (stored) => ({
|
|
91
|
+
profile: { name: stored.n, score: stored.s },
|
|
92
|
+
}),
|
|
93
|
+
};
|
|
94
|
+
|
|
95
|
+
const userStore = createDocumentStore<User>({
|
|
96
|
+
id: 'document-user',
|
|
97
|
+
storeManager,
|
|
98
|
+
fetchFn: (signal) => api.getUser(signal),
|
|
99
|
+
lowPriorityThrottleMs: 2000,
|
|
100
|
+
baseCoalescingWindowMs: 100,
|
|
101
|
+
blockWindowClose: null,
|
|
102
|
+
persistentStorage: { adapter: 'local-sync', schema: userPersistenceSchema },
|
|
103
|
+
});
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Validation runs on both sides of the conversion:
|
|
107
|
+
|
|
108
|
+
- Loaded cache data must pass `storageSchema`.
|
|
109
|
+
- `convertFromStorage(...)` maps it to the store shape.
|
|
110
|
+
- The converted result must pass `storeSchema`.
|
|
111
|
+
- Successful fetch data passes through `convertToStorage(...)` before being saved.
|
|
112
|
+
|
|
113
|
+
If `convertFromStorage(...)`, `convertToStorage(...)`, or either schema fails, TSDF reports the error through `onPersistentStorageError` when available and removes or skips the invalid cache entry.
|
|
114
|
+
|
|
115
|
+
If `persistentStorage.offline` is configured, pass one shared offline session config to `createStoreManager(...)` and keep store-local offline behavior in `persistentStorage.offline.operations`. `createStoreManager(...)` owns that session internally and expects config, not an existing `OfflineSession` object.
|
|
116
|
+
|
|
117
|
+
Each offline operation now requires a `kind`:
|
|
118
|
+
|
|
119
|
+
- `create` for temp-entity or create-style mutations
|
|
120
|
+
- `update` for in-place edits
|
|
121
|
+
- `delete` for destructive mutations
|
|
122
|
+
|
|
123
|
+
TSDF reduces those operation kinds into a derived `GlobalOfflineEntity.kind`
|
|
124
|
+
value (`create`, `createAndUpdate`, `update`, or `delete`) so queue-aware UI
|
|
125
|
+
can read one stable lifecycle field instead of inferring it from store
|
|
126
|
+
snapshots.
|
|
127
|
+
|
|
128
|
+
Session-level `mutationQueueing` can allow or disallow durable offline mutation queueing separately for `network` and `outage` causes. This only affects mutations using the `offline` option and does not change offline reads.
|
|
129
|
+
|
|
130
|
+
## Adapter behavior
|
|
131
|
+
|
|
132
|
+
TSDF does not choose a persistence adapter automatically. Pass one of the built-in adapters or a custom async adapter in every `persistentStorage` config.
|
|
133
|
+
|
|
134
|
+
### `local-sync`
|
|
135
|
+
|
|
136
|
+
- Uses managed `localStorage` entries.
|
|
137
|
+
- Can hydrate synchronously during initial state creation for `DocumentStore`.
|
|
138
|
+
- `CollectionStore` and `ListQueryStore` use lazy hydration for unknown entries from initial keys scan.
|
|
139
|
+
- Writes are debounced and may be dropped if serialization or quota errors occur.
|
|
140
|
+
|
|
141
|
+
Use it with:
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
persistentStorage: {
|
|
145
|
+
adapter: 'local-sync',
|
|
146
|
+
schema: settingsSchema,
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### `opfsPersistentStorage`
|
|
151
|
+
|
|
152
|
+
- Uses `FileSystemAccess`-backed persistent storage.
|
|
153
|
+
- Hydration is asynchronous, and can be triggered explicitly with preload APIs.
|
|
154
|
+
|
|
155
|
+
### `indexedDbPersistentStorage`
|
|
156
|
+
|
|
157
|
+
- Alternative built-in async adapter for browsers where IndexedDB is preferred.
|
|
158
|
+
- Stores one logical row per entry and uses native indexes for recency ordering, group lookups, and protected-key scans.
|
|
159
|
+
- Hydration is asynchronous, and can be triggered explicitly with preload APIs.
|
|
160
|
+
|
|
161
|
+
Use `createIndexedDbPersistentStorage({ databaseName })` from `tsdf/indexed-db-storage` when an app needs an isolated IndexedDB database.
|
|
162
|
+
|
|
163
|
+
### Custom async adapters
|
|
164
|
+
|
|
165
|
+
Use `createAsyncStorageAdapter(driver)` only when the built-in OPFS and IndexedDB adapters are not a fit. It wraps an `AsyncStorageDriver`, which is the low-level async backend contract used by TSDF persistence internals.
|
|
166
|
+
|
|
167
|
+
A driver is responsible for storing raw records by logical namespace:
|
|
168
|
+
|
|
169
|
+
```ts
|
|
170
|
+
import { createAsyncStorageAdapter } from 'tsdf/async-storage';
|
|
171
|
+
import type { AsyncStorageDriver } from 'tsdf';
|
|
172
|
+
|
|
173
|
+
const driver: AsyncStorageDriver = {
|
|
174
|
+
get: (scope, key) => customStore.get(scope, key),
|
|
175
|
+
set: (scope, key, value) => customStore.set(scope, key, value),
|
|
176
|
+
remove: (scope, key) => customStore.remove(scope, key),
|
|
177
|
+
listKeys: (scope) => customStore.listKeys(scope),
|
|
178
|
+
clear: (scope) => customStore.clear(scope),
|
|
179
|
+
listScopes: (sessionKey) => customStore.listScopes(sessionKey),
|
|
180
|
+
listScopesWithKnownRecordKeys: (sessionKey) =>
|
|
181
|
+
customStore.listScopesWithKnownRecordKeys(sessionKey),
|
|
182
|
+
getMany: (scope, keys) => customStore.getMany(scope, keys),
|
|
183
|
+
setMany: (scope, entries) => customStore.setMany(scope, entries),
|
|
184
|
+
removeMany: (scope, keys) => customStore.removeMany(scope, keys),
|
|
185
|
+
};
|
|
186
|
+
|
|
187
|
+
const customPersistentStorage = createAsyncStorageAdapter(driver);
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Driver methods should preserve the JSON-compatible values TSDF gives them, isolate data by the full namespace scope, and implement bulk methods consistently with their single-record equivalents. `listScopes(...)` and `listScopesWithKnownRecordKeys(...)` are required for cleanup, session clearing, and offline protected-key restoration.
|
|
191
|
+
|
|
192
|
+
## Example configuration
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
import { rc_object, rc_string } from 'runcheck';
|
|
196
|
+
import { createDocumentStore, createStoreManager } from 'tsdf';
|
|
197
|
+
|
|
198
|
+
type Settings = { id: string; theme: string };
|
|
199
|
+
|
|
200
|
+
const getSessionKey = () => (userId ? `tenant:${userId}` : false);
|
|
201
|
+
|
|
202
|
+
const storeManager = createStoreManager({
|
|
203
|
+
getSessionKey,
|
|
204
|
+
errorNormalizer: normalizeError,
|
|
205
|
+
lowPriorityThrottleMs: 5,
|
|
206
|
+
baseCoalescingWindowMs: 10,
|
|
207
|
+
blockWindowClose: null,
|
|
208
|
+
onPersistentStorageError: (error) => {
|
|
209
|
+
console.error('TSDF persistence failed', error);
|
|
210
|
+
},
|
|
211
|
+
offlineSession: {
|
|
212
|
+
network: { enabled: true },
|
|
213
|
+
mutationQueueing: { network: 'allow', outage: 'allow' },
|
|
214
|
+
},
|
|
215
|
+
});
|
|
216
|
+
|
|
217
|
+
const settingsStore = createDocumentStore<Settings>({
|
|
218
|
+
id: 'document-settings',
|
|
219
|
+
storeManager,
|
|
220
|
+
fetchFn: (signal) => api.getSettings(signal),
|
|
221
|
+
persistentStorage: {
|
|
222
|
+
adapter: 'local-sync',
|
|
223
|
+
version: 2,
|
|
224
|
+
schema: rc_object({ id: rc_string(), theme: rc_string() }),
|
|
225
|
+
onPersistentStorageError: (error) => {
|
|
226
|
+
console.error('Settings persistence failed', error);
|
|
227
|
+
},
|
|
228
|
+
offline: {},
|
|
229
|
+
},
|
|
230
|
+
});
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
## Lifecycle behavior
|
|
234
|
+
|
|
235
|
+
- On successful fetch, stores save to persistence after debounce (approximately 1s).
|
|
236
|
+
- On startup/reload, stores attempt restore and set `refetchOnMount: 'lowPriority'` so stale data is revalidated.
|
|
237
|
+
- When a store instance is permanently discarded, call `store.dispose()` to release listeners, browser-tab coordination, and store-manager registration.
|
|
238
|
+
- Invalid or incompatible cache entries are removed automatically.
|
|
239
|
+
- Expired entries are removed by a periodic scan:
|
|
240
|
+
- `local-sync`: ~1 week old entries
|
|
241
|
+
- `opfsPersistentStorage`: ~2 weeks old entries
|
|
242
|
+
- `indexedDbPersistentStorage`: ~2 weeks old entries
|
|
243
|
+
|
|
244
|
+
## Preload APIs
|
|
245
|
+
|
|
246
|
+
These are useful in components that need control over when async hydration should happen.
|
|
247
|
+
|
|
248
|
+
### Document store
|
|
249
|
+
|
|
250
|
+
- `preloadPersistentStorage(): Promise<void>`
|
|
251
|
+
|
|
252
|
+
### Collection store
|
|
253
|
+
|
|
254
|
+
- `preloadItemFromStorage(params): Promise<PersistentStoragePreloadResult<ItemPayload>[]>`
|
|
255
|
+
- `params`: single payload or payload array.
|
|
256
|
+
|
|
257
|
+
### List query store
|
|
258
|
+
|
|
259
|
+
- `preloadQueryFromStorage(payloads): Promise<PersistentStoragePreloadResult<QueryPayload>[]>`
|
|
260
|
+
- `preloadItemFromStorage(params): Promise<PersistentStoragePreloadResult<ItemPayload>[]>`
|
|
261
|
+
- `params`: single payload or payload array.
|
|
262
|
+
|
|
263
|
+
When list-query offline persistence is enabled, `usePendingOfflineItems()` can
|
|
264
|
+
also restore pending offline item state from persistence without mounting
|
|
265
|
+
`useListQuery()`. This is especially useful for offline-first screens that boot
|
|
266
|
+
directly into queued work.
|
|
267
|
+
|
|
268
|
+
`preload*` returns `preloaded` boolean for each payload.
|
|
269
|
+
|
|
270
|
+
When the selected adapter does not support async preload, preload methods report errors to `onPersistentStorageError` and return `preloaded: false`.
|
|
271
|
+
|
|
272
|
+
## Cache retention controls
|
|
273
|
+
|
|
274
|
+
- `maxBytes` limits the serialized storage budget for collection items.
|
|
275
|
+
- `maxItemBytes` limits the serialized storage budget for list-query items.
|
|
276
|
+
- `maxQueryBytes` limits the serialized storage budget for list-query query entries.
|
|
277
|
+
- `maxQuerySize` limits how many items each cached query can keep.
|
|
278
|
+
- Pinned entries are never evicted.
|
|
279
|
+
- `ignoreItems` removes/blocks entries from being persisted or hydrated.
|
|
280
|
+
- Can be an explicit list or predicate.
|
|
281
|
+
- Takes precedence over pinned lists.
|
|
282
|
+
|
|
283
|
+
## Clearing stored data
|
|
284
|
+
|
|
285
|
+
- `clearSessionStorage(sessionKey, adapter)`:
|
|
286
|
+
remove all TSDF entries for one session and adapter.
|
|
287
|
+
- `clearAllSessionStorage(sessionKey)`:
|
|
288
|
+
remove TSDF entries for one session across the built-in `local-sync`, OPFS, and IndexedDB adapters.
|
|
289
|
+
|
|
290
|
+
Use these on logout, user switch, or explicit privacy actions.
|