tsdf 18.4.0 → 18.5.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-Ca9ntO1N.d.ts → asyncStorageAdapter-C7J64ZKi.d.ts} +1 -1
- package/dist/{asyncStorageAdapter-NrI38v4g.js → asyncStorageAdapter-D6IVBzPg.js} +1 -1
- package/dist/{asyncStorageAdapters-BFn-BuAl.js → asyncStorageAdapters-CBMshtkY.js} +2 -2
- package/dist/indexed-db-storage.d.ts +1 -1
- package/dist/indexed-db-storage.js +1 -1
- package/dist/{indexedDbPersistentStorage-DljRDcOr.js → indexedDbPersistentStorage-x6dVEqkJ.js} +1 -1
- package/dist/main.d.ts +35 -12
- package/dist/main.js +1047 -285
- package/dist/opfs-storage.d.ts +1 -1
- package/dist/opfs-storage.js +1 -1
- package/dist/{opfsPersistentStorage-BeUPOyk4.d.ts → opfsPersistentStorage-CEhiNR8Q.d.ts} +1 -1
- package/dist/{opfsPersistentStorage-amwSWm_p.js → opfsPersistentStorage-CwmY3O1r.js} +1 -1
- package/dist/{types-DUtkSBT8.d.ts → types-Bp7_Ra7_.d.ts} +472 -32
- package/docs/hooks.md +45 -7
- package/docs/list-query-store.md +1 -0
- package/docs/offline.md +326 -4
- package/docs/partial-resources.md +2 -0
- package/docs/persistent-storage.md +15 -0
- package/docs/store-manager.md +16 -1
- package/package.json +1 -1
package/docs/hooks.md
CHANGED
|
@@ -376,6 +376,15 @@ Behavior:
|
|
|
376
376
|
`tempEntity` / `tempEntities` operation) and the server has not confirmed it
|
|
377
377
|
yet, so it is still tracked under its temporary payload. Creations queued
|
|
378
378
|
without a temp entity (e.g. with a client-generated id) report `false`
|
|
379
|
+
- `creationAttempted` - Only `true` for an unsent creation whose create
|
|
380
|
+
request is being sent, failed without telling whether the server got it, or
|
|
381
|
+
waits for a manual resolution: the server may already have the item. While
|
|
382
|
+
it is `false` the creation is still waiting in the queue, and deleting the
|
|
383
|
+
item only discards local work. The server never saw the item, except when the
|
|
384
|
+
creation was queued after its direct online request failed, or sent again
|
|
385
|
+
with `requeue` after a conflict: an earlier request may have created a
|
|
386
|
+
server item, which the temporary payload can't target, so the delete leaves
|
|
387
|
+
it as is
|
|
379
388
|
|
|
380
389
|
### Items created offline
|
|
381
390
|
|
|
@@ -388,21 +397,24 @@ an edit made right after creating it) with `isUnsentCreation: false`.
|
|
|
388
397
|
function onDeleteClick(itemPayload: UserPayload) {
|
|
389
398
|
const offlineState = store.getItemOfflineState(itemPayload);
|
|
390
399
|
|
|
391
|
-
//
|
|
400
|
+
// The server never saw a creation that was not attempted, so deleting it
|
|
392
401
|
// only discards local work: no need to ask before deleting for everyone.
|
|
393
|
-
const
|
|
394
|
-
offlineState?.isUnsentCreation && offlineState.
|
|
402
|
+
const onlyExistsLocally =
|
|
403
|
+
offlineState?.isUnsentCreation && !offlineState.creationAttempted;
|
|
395
404
|
|
|
396
|
-
if (
|
|
405
|
+
if (onlyExistsLocally || confirmDeleteForEveryone()) {
|
|
397
406
|
deleteUser(itemPayload);
|
|
398
407
|
}
|
|
399
408
|
}
|
|
400
409
|
```
|
|
401
410
|
|
|
402
411
|
`isUnsentCreation` stays `true` while the creation itself is being sent, until
|
|
403
|
-
the server result is reconciled
|
|
404
|
-
|
|
405
|
-
|
|
412
|
+
the server result is reconciled; `creationAttempted` is `true` during that
|
|
413
|
+
time. The check only covers temp-entity creations: an item created with a
|
|
414
|
+
client-generated id reports `isUnsentCreation: false` even when its delete only
|
|
415
|
+
discards local work, so the app can't tell it apart from a server item. See
|
|
416
|
+
[Offline - Deleting entities created offline](./offline.md#deleting-entities-created-offline)
|
|
417
|
+
for what a delete does in each case.
|
|
406
418
|
|
|
407
419
|
## useMultipleItems
|
|
408
420
|
|
|
@@ -524,3 +536,29 @@ const { isLoading, isDeleted, data } = collectionStore.useListItem(
|
|
|
524
536
|
},
|
|
525
537
|
);
|
|
526
538
|
```
|
|
539
|
+
|
|
540
|
+
## useOfflineUploadFile
|
|
541
|
+
|
|
542
|
+
**Source**: [Store Manager](./store-manager.md#upload-apis)
|
|
543
|
+
|
|
544
|
+
Reads the file of an upload staged with `saveOfflineUpload` / `performMutation({ upload })`, to render local files (e.g. thumbnails of optimistic entities) by upload id.
|
|
545
|
+
|
|
546
|
+
```tsx
|
|
547
|
+
const { status, url, file, error } = storeManager.useOfflineUploadFile(
|
|
548
|
+
isLocalFile && uploadId,
|
|
549
|
+
);
|
|
550
|
+
```
|
|
551
|
+
|
|
552
|
+
- Does not fetch from the server: it reads the session's staged uploads
|
|
553
|
+
- Components using the same id share one read and one object URL
|
|
554
|
+
- `url` is managed by TSDF: do not revoke it or keep it outside of render
|
|
555
|
+
- A falsy id disables the hook (`status: 'idle'`)
|
|
556
|
+
|
|
557
|
+
### Return value
|
|
558
|
+
|
|
559
|
+
- `status` - `'idle'` | `'loading'` | `'success'` | `'missing'` | `'error'`
|
|
560
|
+
- `url` - Object URL of the staged file, or `null` unless `status` is `'success'`
|
|
561
|
+
- `file` - The staged `File`, or `null` unless `status` is `'success'`
|
|
562
|
+
- `error` - The read failure, or `null` unless `status` is `'error'`
|
|
563
|
+
|
|
564
|
+
`'missing'` means no upload with this id is staged in the active session: it was never staged, or it was deleted, expired or already consumed by its mutation. See [Offline: Rendering staged files](./offline.md#rendering-staged-files) for the URL lifetime and the pattern for switching to the uploaded file.
|
package/docs/list-query-store.md
CHANGED
|
@@ -190,6 +190,7 @@ derivedQueries: {
|
|
|
190
190
|
Behavior:
|
|
191
191
|
|
|
192
192
|
- Online: exact query cache wins; otherwise TSDF can derive when `isComplete(...)` returns `true`
|
|
193
|
+
- `isComplete(...)` only receives the group's queries that have loaded at least once, so a list still on its first fetch never makes the group look complete
|
|
193
194
|
- Offline: derivation is attempted before the exact cached query result
|
|
194
195
|
- `deriveQuery(...)` receives `{ fields, isOfflineMode, deriveSource }`
|
|
195
196
|
- `fields` lets derivation opt out of partial-resource queries when local data is insufficient
|
package/docs/offline.md
CHANGED
|
@@ -111,6 +111,83 @@ Queued mutations and pending resolutions are persisted through the store's own `
|
|
|
111
111
|
|
|
112
112
|
The mutation promise resolves only after the queue write has settled, so a mutation is never reported as queued while its write is still in flight. If the storage adapter cannot write the queue at all (for example the browser lost its IndexedDB connection and a new one cannot be opened), the failure is reported through `onPersistentStorageError`, but the result is still `{ kind: 'queued' }`: the mutation stays queued in memory, its optimistic state stays visible, and it is replayed if the session recovers in the same page load. It is not on disk, so it is lost if the page is reloaded first. Treat an `onPersistentStorageError` call while offline as "pending changes may not survive a reload".
|
|
113
113
|
|
|
114
|
+
Without an active offline session — `getSessionKey()` returns `false`, or the [session gate](#session-gate) is closed — the same call runs as a plain online mutation: `mutation` is called, a success resolves with `{ kind: 'online', data }`, and a failure goes through the normal error handling (optimistic update rolled back, `onMutationError` called). Nothing is queued.
|
|
115
|
+
|
|
116
|
+
## Health Check
|
|
117
|
+
|
|
118
|
+
The session is in offline mode for one of two causes: `network` (this device cannot reach the backend) or `outage` (the backend is reached but down). Browser `online` / `offline` events only cover part of the first one. For everything else the app usually has one health endpoint that answers both "this request failed: is it the network, an outage, or just this request?" and "are we back?". Wire it once with `offlineSession.healthCheck`:
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
const storeManager = createStoreManager({
|
|
122
|
+
getSessionKey: () => currentTenantId ?? false,
|
|
123
|
+
errorNormalizer: normalizeError,
|
|
124
|
+
offlineSession: {
|
|
125
|
+
network: { enabled: true },
|
|
126
|
+
outage: { enabled: true },
|
|
127
|
+
healthCheck: {
|
|
128
|
+
check: async ({ signal }) => {
|
|
129
|
+
try {
|
|
130
|
+
const response = await fetch('/api/health', { signal });
|
|
131
|
+
return response.ok ? 'up' : 'outage';
|
|
132
|
+
} catch {
|
|
133
|
+
return 'unreachable';
|
|
134
|
+
}
|
|
135
|
+
},
|
|
136
|
+
},
|
|
137
|
+
},
|
|
138
|
+
});
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
`check(ctx)` receives `{ sessionKey, signal }` and returns (or resolves to) one of:
|
|
142
|
+
|
|
143
|
+
| Answer | Meaning | As a failure classification | As a recovery check |
|
|
144
|
+
| --------------- | ---------------------------------------------- | --------------------------- | ------------------------------- |
|
|
145
|
+
| `'up'` | The backend answered and is healthy | The session stays online | Offline mode ends |
|
|
146
|
+
| `'outage'` | The backend was reached but is down | Outage mode becomes active | Outage mode (stays or replaces) |
|
|
147
|
+
| `'unreachable'` | The backend cannot be reached from this device | Network mode becomes active | Network mode (stays or returns) |
|
|
148
|
+
|
|
149
|
+
The session uses the same function in both places:
|
|
150
|
+
|
|
151
|
+
- **Failure classification.** When a fetch, a mutation or the replay of a queued mutation fails, the session runs the check and applies the answer.
|
|
152
|
+
- **Recovery checks.** While a mode is active because of a failure, its recovery probe runs the check on that mode's `recoveryProbe` cadence (network: 5s growing to 60s, outage: 30s growing to 5min by default). `'up'` ends the offline mode — both causes at once when both are active. `'outage'` during network mode means the device reaches the backend again but the backend is down: outage mode takes over, or, when outage mode is disabled, network mode just ends and requests (including the replay of queued mutations) fail with their own errors. `'unreachable'` during outage mode activates network mode and keeps the outage, since nothing can be said about it until the backend is reachable. With a health check, `outage.recoveryCheck` is optional.
|
|
153
|
+
|
|
154
|
+
In both places an answer only activates a mode that is enabled (`network.enabled` / `outage.enabled`, including runtime overrides). An answer for a disabled mode is ignored: a failed request is left to its own error.
|
|
155
|
+
|
|
156
|
+
### `'up'` means the failure belongs to the request
|
|
157
|
+
|
|
158
|
+
When the check answers `'up'` for a failed request, the session stays online and that request's own failure handling applies, even if the endpoint it called is down. For example, an upload endpoint answering 503 while the API health check passes:
|
|
159
|
+
|
|
160
|
+
- a fetch or a direct mutation fails with its own error;
|
|
161
|
+
- a queued mutation being replayed goes through `classifyRetryableFailure` and the `replayRetry` budget, and ends in a `retry-exhausted` resolution (see [Conflict Resolution](#conflict-resolution)).
|
|
162
|
+
|
|
163
|
+
If the session should pause for that service instead, make `check` cover it (answer `'outage'` when it is down) or return `'outage'` for its failures from `classifyFailure`.
|
|
164
|
+
|
|
165
|
+
### One request for many failures
|
|
166
|
+
|
|
167
|
+
While a check is in flight, every failure and recovery tick that needs an answer waits for that same call: a burst of requests failing right when the backend goes down costs one health request. Failures that arrive while the session is already in offline mode do not run the check at all — the active mode explains them, and asking "are we back?" is the job of the recovery checks.
|
|
168
|
+
|
|
169
|
+
A finished answer is never reused. A cached `'up'` could hide an outage that started right after it, so the next failure after a check has settled starts a new one. The check is never called on the success path.
|
|
170
|
+
|
|
171
|
+
### With `classifyFailure` and `recoveryCheck`
|
|
172
|
+
|
|
173
|
+
The health check is the fallback; the more specific hooks win:
|
|
174
|
+
|
|
175
|
+
- `classifyFailure(error, ctx)` runs first. `'outage'`, `'network'` and `'ignore'` are final answers and the health check is not called for that failure. Return `'unknown'` when the error alone does not tell, to ask the health check. This keeps obvious request errors (validation, 404) from costing a health request:
|
|
176
|
+
|
|
177
|
+
```ts
|
|
178
|
+
classifyFailure: (error) => (isClientError(error) ? 'ignore' : 'unknown'),
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Without `classifyFailure`, every failure asks the health check.
|
|
182
|
+
|
|
183
|
+
- A mode with its own `recoveryCheck` (`network.recoveryCheck` / `outage.recoveryCheck`) keeps using it for its recovery; the health check is the recovery check of the modes that do not have one.
|
|
184
|
+
|
|
185
|
+
### When the check gives no answer
|
|
186
|
+
|
|
187
|
+
A check that throws, rejects, or takes longer than `healthCheck.timeoutMs` (default 10s) gives no answer and changes nothing: a failure being classified is left to its request, and a recovery check counts as "not recovered yet" and is retried on the normal cadence. `ctx.signal` is aborted on timeout so the health request can be cancelled. No answer is never read as `'unreachable'`: a broken or slow health endpoint is not evidence about connectivity, and the browser going offline is already detected by network mode. Return `'unreachable'` from `check` when the request itself fails, as in the example above.
|
|
188
|
+
|
|
189
|
+
The check is not called while the [session gate](#session-gate) is closed, or while both modes are disabled and neither is still active.
|
|
190
|
+
|
|
114
191
|
## Reading While Offline
|
|
115
192
|
|
|
116
193
|
While the session is in offline mode, fetches are not sent to the server. What a document, item or query reports depends on whether it has data to return:
|
|
@@ -143,6 +220,8 @@ With [partial resources](./partial-resources.md), "cached" is decided per hook,
|
|
|
143
220
|
|
|
144
221
|
Both can be mounted for the same item or query at the same time: the hook waiting for missing fields does not disturb the one reading cached fields.
|
|
145
222
|
|
|
223
|
+
A cached list query that lost a row before one of the rows that are left (or every row) is not a cached read: it is not reported as a complete `success`. A list that only lost its last rows (e.g. to `maxItemBytes`) is still a cached read, with fewer rows. Hooks return the rows that are left with `status: 'error'` and the offline error (`isOfflineStoreError(error)`), so the screen can show them together with a notice that the list is incomplete. See [Cached list queries that lost rows](./persistent-storage.md#cached-list-queries-that-lost-rows).
|
|
224
|
+
|
|
146
225
|
Both kinds of reads are refetched once the session recovers (see below): reads that failed offline load, and cached reads get refreshed.
|
|
147
226
|
|
|
148
227
|
## Revalidation After Recovering
|
|
@@ -168,7 +247,8 @@ All offline operations define:
|
|
|
168
247
|
Collection and list-query operations also define:
|
|
169
248
|
|
|
170
249
|
- `getEntityRefs({ input })` - Returns affected item/entity refs.
|
|
171
|
-
- `dependsOn({ input })` - Optional dependencies on other offline entities.
|
|
250
|
+
- `dependsOn({ input })` - Optional dependencies on other offline entities of the same store.
|
|
251
|
+
- `cancelledWith({ input })` - Optional entities of other stores whose cancelled creation also drops this work. See [Deleting entities created offline](#deleting-entities-created-offline).
|
|
172
252
|
|
|
173
253
|
Optional replay behavior:
|
|
174
254
|
|
|
@@ -179,8 +259,99 @@ Optional replay behavior:
|
|
|
179
259
|
- `accumulation` - Merges newer queued inputs into an existing queued mutation.
|
|
180
260
|
- `supersedes` - Prunes older queued work for the same entity.
|
|
181
261
|
|
|
262
|
+
Queued mutations and resolutions whose operation the running deploy doesn't define (for example ones queued by a newer deploy in another tab) stay in storage, together with their uploads, but that deploy neither lists nor replays them. A deploy that defines the operation picks them up and sends or resolves them. Apps are expected to reload tabs running an old deploy: TSDF doesn't coordinate the order of offline work between deploys, so an old tab can send its own edits around the work it keeps. Records of an operation removed from the app for good also stay in storage until the session's storage is cleared (`clearSessionStorage`), so keep an operation defined until its queued work is likely gone.
|
|
263
|
+
|
|
182
264
|
Create flows for collection and list-query stores can use `tempEntity` or `tempEntities` to insert optimistic entities with temporary payloads and reconcile them to final server payloads after replay. Document stores do not support temp entities.
|
|
183
265
|
|
|
266
|
+
### Temp Entities in List Queries
|
|
267
|
+
|
|
268
|
+
In a list-query store the pending entity is inserted as an item only, so it is not part of any list unless `optimisticListUpdates` rules match it. Declare `addToQueries` to add it to the lists that should show it while the mutation is queued:
|
|
269
|
+
|
|
270
|
+
```ts
|
|
271
|
+
createUser: {
|
|
272
|
+
inputSchema: createUserInputSchema,
|
|
273
|
+
kind: 'create',
|
|
274
|
+
getEntityRefs: ({ input }) => [`temp:${input.clientId}`],
|
|
275
|
+
tempEntity: {
|
|
276
|
+
buildPendingEntity: (input) => ({ id: input.clientId, name: input.name }),
|
|
277
|
+
// Same shape as the `addItemToQueries` option of `addItemToState`,
|
|
278
|
+
// or a function of the mutation input that returns it
|
|
279
|
+
addToQueries: (input) => ({
|
|
280
|
+
queries: { teamId: input.teamId },
|
|
281
|
+
appendTo: 'start',
|
|
282
|
+
}),
|
|
283
|
+
reconcileServerEntity: (result) => ({
|
|
284
|
+
finalPayload: result.id,
|
|
285
|
+
finalData: result,
|
|
286
|
+
}),
|
|
287
|
+
},
|
|
288
|
+
execute: ({ input }) => api.createUser(input),
|
|
289
|
+
},
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
- The entity is added to the queries when the mutation is queued, so `optimisticUpdate` does not need to call `addItemToState` for it. A mutation that runs online right away is never queued and creates no pending entity.
|
|
293
|
+
- `queries` follows `addItemToState`, except that queries saved in persistent storage but not loaded yet (after a restart, before a screen reads them) are loaded first, so the row also reaches them. A filter function only matches the queries the app session already knows, so prefer query payloads.
|
|
294
|
+
- The membership is stored with the queries, so the row is still in its lists after the app restarts with the mutation queued.
|
|
295
|
+
- When replay succeeds, the final server entity takes the place of the temp one in every query that still contains it. The declared queries that are only in persistent storage are loaded first: the function form of `addToQueries` runs again for this, so it should only depend on its arguments. Discarding the queued mutation removes the row from its lists.
|
|
296
|
+
- While the mutation is pending, a list refetch that does not return the row keeps it rendered at its last known position. This memory does not survive an app restart.
|
|
297
|
+
|
|
298
|
+
With `tempEntities`, each entry returned by `buildPendingEntities` declares its own `addToQueries`. The builder does not run again at replay, so a declared query that is only in persistent storage when the mutation is replayed gets the final entities on its next fetch.
|
|
299
|
+
|
|
300
|
+
With [partial resources](./partial-resources.md), the pending entity has no loaded-fields metadata, so only `inferFields` can vouch for it. Declare `loadedFields` (for example `'*'`) when the pending entity should count as loaded for hooks that read those fields: it cannot be fetched from the server before the mutation is replayed. The entity keeps the same loaded fields when it is reconciled to its final payload, so a `finalData` returned by the reconcile hook must hold at least those fields; omit `finalData` to keep the pending entity's data instead.
|
|
301
|
+
|
|
302
|
+
```ts
|
|
303
|
+
tempEntity: {
|
|
304
|
+
buildPendingEntity: (input) => ({ id: input.clientId, name: input.name }),
|
|
305
|
+
addToQueries: { queries: { teamId: 'team-1' }, appendTo: 'start' },
|
|
306
|
+
loadedFields: '*',
|
|
307
|
+
// ...
|
|
308
|
+
},
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
### Deleting entities created offline
|
|
312
|
+
|
|
313
|
+
When the user deletes something that was created offline, the server may have never seen it. Declare this on the delete operation with `supersedes.dropSelfIfTempLifecycleCancelled`:
|
|
314
|
+
|
|
315
|
+
```ts
|
|
316
|
+
deleteTask: {
|
|
317
|
+
kind: 'delete',
|
|
318
|
+
inputSchema: deleteTaskSchema,
|
|
319
|
+
getEntityRefs: ({ input }) => [input.itemId],
|
|
320
|
+
supersedes: { scope: 'same-entity', dropSelfIfTempLifecycleCancelled: true },
|
|
321
|
+
execute: async ({ input }) => {
|
|
322
|
+
try {
|
|
323
|
+
await api.deleteTask(input.itemId);
|
|
324
|
+
} catch (error) {
|
|
325
|
+
// The task is already gone: the delete is done
|
|
326
|
+
if (!isNotFoundError(error)) throw error;
|
|
327
|
+
}
|
|
328
|
+
},
|
|
329
|
+
},
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
What happens depends on whether the creation was already sent:
|
|
333
|
+
|
|
334
|
+
- **Never sent** (still waiting in the queue, or held behind the creation of another entity that waits for a resolution): nothing is sent. TSDF drops the creation, the queued edits of the entity, the delete itself and the queued work that depends on the entity (`dependsOn`), then removes the temporary entity from the store and its lists. The same applies to a `create` of an item whose id the app generates on the client: the item is removed instead of a temporary entity.
|
|
335
|
+
- **Created together with other entities** (a `tempEntities` operation that creates several entities at once): the creation is never cancelled, since the other entities still need it. The delete is queued behind it and sent with the server id, as for a creation that was sent.
|
|
336
|
+
- **Sent** (`syncing`, `needs-confirmation`, queued again after a `retry`, or, for an id the app generates, queued after its direct online request failed or sent again with `requeue` after a conflict): the server may have the entity, so the creation is kept and the delete stays queued behind it. Once the server id is known the delete is sent with it. `execute` should treat a not-found answer as success, as above: the server answers not-found when the creation never reached it, or when an earlier delete attempt did.
|
|
337
|
+
- **Waiting for a manual resolution**: the creation is kept too, and the delete is held behind that resolution. See [Entities whose creation waits for a resolution](#entities-whose-creation-waits-for-a-resolution).
|
|
338
|
+
|
|
339
|
+
`getItemOfflineState(payload)` tells the first case apart before deleting: `isUnsentCreation && !creationAttempted` means the delete only discards local work, unless the item was created together with other entities. A temp entity whose creation was queued after its direct online request failed, or sent again with `requeue` after a conflict, is in that case too: an earlier request may have created a server item, but the temporary payload can't target it, so the delete leaves that item as is. This only covers temp entities: an item whose id the app generates reports `isUnsentCreation: false`, so it can't be told apart from a server item.
|
|
340
|
+
|
|
341
|
+
Work queued in **other stores** for the cancelled entity is not known to its store. Declare the relation with `cancelledWith` in the other store's operation:
|
|
342
|
+
|
|
343
|
+
```ts
|
|
344
|
+
// comments store
|
|
345
|
+
addComment: {
|
|
346
|
+
kind: 'create',
|
|
347
|
+
// ...inputSchema, tempEntity, getEntityRefs, execute
|
|
348
|
+
// `tasks` is the `id` of the store that owns the task
|
|
349
|
+
cancelledWith: ({ input }) => [{ storeName: 'tasks', entityRef: input.taskId }],
|
|
350
|
+
},
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
When the creation of that task is cancelled as above, or its manual resolution is discarded, the queued comments are dropped with it and their temporary entities are removed. A comment added with a client-generated id instead of a temporary entity is removed the same way when it was never sent, with the work queued on it and the work of other stores declared as `cancelledWith` it. `cancelledWith` only drives this cleanup: it does not delay replay or rewrite the input when the task gets its server id, and it only reaches stores that are instantiated in the tab where the cancellation happens.
|
|
354
|
+
|
|
184
355
|
## Conflict Resolution
|
|
185
356
|
|
|
186
357
|
Stores expose resolution APIs:
|
|
@@ -205,6 +376,16 @@ A mutation that exhausted its replay retries leaves the queue when it becomes a
|
|
|
205
376
|
|
|
206
377
|
Use `parseOfflineResolutionConflict(resolution)` to narrow a persisted resolution back to the operation-specific conflict/input type before rendering a manual resolution UI.
|
|
207
378
|
|
|
379
|
+
### Entities whose creation waits for a resolution
|
|
380
|
+
|
|
381
|
+
While the creation of an entity made offline waits for a resolution, the server does not know the entity, so nothing else can be sent for it. The mutations that target or depend on it become blocked resolutions behind the creation (`blockedResolutionCount > 0`, error `Blocked by unresolved dependency`), whether they were queued before the creation failed or made afterwards, online or offline. `performMutation(...)` returns `{ kind: 'queued' }` for them and the optimistic update stays visible.
|
|
382
|
+
|
|
383
|
+
They follow the decision about the creation: `retry` (default scope) sends the creation again and then the blocked mutations with the server id, `discard` drops them with the creation. For a creation that hit a conflict, `requeue` sends them after the new creation, and `commit` sends them with the ref of the entity the result keeps. This includes a delete with `dropSelfIfTempLifecycleCancelled`: the creation may have reached the server, so it is not cancelled locally; the delete is sent after the creation is retried, or dropped when it is discarded.
|
|
384
|
+
|
|
385
|
+
A blocked mutation was never sent, so a later mutation of the same entity treats it like an unsent queued one: an `accumulation` operation merges into it, and a `supersedes` operation prunes it. This keeps the order the user made the changes in, e.g. moving a task under the waiting entity and then back under a server task sends only the second move, and retrying the creation does not move the task again. When the merged input no longer depends on the waiting entity, it is queued and sent right away. To make this possible, an online mutation of such an operation for an entity with blocked work is queued instead of sent directly. A mutation of an operation with neither `accumulation` nor `supersedes` does not touch the blocked one: it is sent first, and the blocked one is sent after it once the creation is retried.
|
|
386
|
+
|
|
387
|
+
When the merged input still depends on the waiting entity, the changes merged into it go with the decision about the creation too: discarding the creation also drops them, e.g. a rename of a server task merged into its held move under the waiting entity.
|
|
388
|
+
|
|
208
389
|
### Resolving From A Session-Wide UI
|
|
209
390
|
|
|
210
391
|
An app-wide "sync problems" panel that lists `storeManager.useOfflineResolutions()` does not need to import every store to offer Retry / Discard. The manager applies the generic actions to any resolution of the session by finding the store that owns it:
|
|
@@ -281,14 +462,14 @@ List-query stores additionally expose `usePendingOfflineItems(...)`, which retur
|
|
|
281
462
|
|
|
282
463
|
### Per-item state
|
|
283
464
|
|
|
284
|
-
Collection and list-query stores expose `useItemOfflineState(itemPayload)` / `getItemOfflineState(itemPayload)` for per-row UI such as sync badges. They return `null` when the item has nothing queued, otherwise `{ syncState, pendingMutations, requiresResolution, isUnsentCreation }`:
|
|
465
|
+
Collection and list-query stores expose `useItemOfflineState(itemPayload)` / `getItemOfflineState(itemPayload)` for per-row UI such as sync badges. They return `null` when the item has nothing queued, otherwise `{ syncState, pendingMutations, requiresResolution, isUnsentCreation, creationAttempted }`:
|
|
285
466
|
|
|
286
467
|
```tsx
|
|
287
468
|
const offlineState = userStore.useItemOfflineState({ id: 1 });
|
|
288
|
-
// null | { syncState: 'pending', pendingMutations: 1, requiresResolution: false, isUnsentCreation: false }
|
|
469
|
+
// null | { syncState: 'pending', pendingMutations: 1, requiresResolution: false, isUnsentCreation: false, creationAttempted: false }
|
|
289
470
|
```
|
|
290
471
|
|
|
291
|
-
Prefer it over building a map from `useOfflineEntities()`: a component using the hook re-renders only when the state of its own item changes. `isUnsentCreation` is `true` for an item created offline until the server confirms it; after that the temporary payload returns `null` and the final payload reports the mutations still queued for the item. See [Hooks - useItemOfflineState](./hooks.md#useitemofflinestate).
|
|
472
|
+
Prefer it over building a map from `useOfflineEntities()`: a component using the hook re-renders only when the state of its own item changes. `isUnsentCreation` is `true` for an item created offline until the server confirms it; after that the temporary payload returns `null` and the final payload reports the mutations still queued for the item. `creationAttempted` turns `true` once that creation starts being sent: before that, deleting the item only discards local work (see [Deleting entities created offline](#deleting-entities-created-offline)). See [Hooks - useItemOfflineState](./hooks.md#useitemofflinestate).
|
|
292
473
|
|
|
293
474
|
Document stores hold a single entity, so they do not need a per-item reader: use `useDocument().pendingSync` or `useOfflineEntities()[0]`.
|
|
294
475
|
|
|
@@ -322,6 +503,35 @@ storeManager.resetOfflineRuntimeConfig();
|
|
|
322
503
|
|
|
323
504
|
`getOfflineRuntimeConfig()` returns the current effective controls. Runtime updates are useful for explicit "work offline" toggles, diagnostics, or temporarily disabling queueing modes.
|
|
324
505
|
|
|
506
|
+
Disabling a mode only stops new work from entering it: an offline state that is already active is preserved so the work depending on it can still recover and replay. To turn the whole offline layer off, use the session gate instead.
|
|
507
|
+
|
|
508
|
+
### Session gate
|
|
509
|
+
|
|
510
|
+
`offlineSession.enabled` turns the whole offline layer on and off at runtime — for a feature flag or a per-workspace setting — without recreating the store manager or its stores:
|
|
511
|
+
|
|
512
|
+
```ts
|
|
513
|
+
const storeManager = createStoreManager({
|
|
514
|
+
getSessionKey: () => currentTenantId ?? false,
|
|
515
|
+
errorNormalizer: normalizeError,
|
|
516
|
+
offlineSession: {
|
|
517
|
+
enabled: () => featureFlags.offlineMode,
|
|
518
|
+
network: { enabled: true },
|
|
519
|
+
},
|
|
520
|
+
});
|
|
521
|
+
```
|
|
522
|
+
|
|
523
|
+
While it returns `false` the session behaves as if no offline session existed:
|
|
524
|
+
|
|
525
|
+
- it never enters offline mode: network detection is ignored and neither `classifyFailure` nor `healthCheck` is called. The offline status reports `isOfflineMode: false`, and `getOfflineRuntimeConfig()` reports both modes as not enabled
|
|
526
|
+
- fetches always go to the network and fail with their normal errors
|
|
527
|
+
- mutations with an `offline` descriptor run as plain online mutations (see [Queuing Mutations](#queuing-mutations))
|
|
528
|
+
|
|
529
|
+
Mutations already queued when the gate closes are neither deleted nor replayed. They stay in persistent storage untouched, still listed by the offline entities / resolutions APIs, and are replayed once the gate reopens and the session is online. A queued mutation whose replay request fails because the gate closed mid-flight goes back to the queue as pending. Mutations made while the gate is closed go straight to the server, so they are not ordered after older mutations still waiting in the queue for the same entities: when that matters, close the gate only once the offline entities list is empty.
|
|
530
|
+
|
|
531
|
+
The callback is read before every fetch and every mutation with an `offline` descriptor, on browser `online` / `offline` events, before each recovery check and before each queued mutation is replayed, so it must be synchronous and cheap (read a variable or a store, no I/O). The app does not have to call anything for a flip to apply to the next fetch or mutation. To apply it right away — clear the offline status in the UI as soon as the gate closes, or start replaying the queue as soon as it reopens on an idle screen — call `storeManager.setOfflineRuntimeConfig({})` after changing the value: every runtime config update re-reads the gate. Runtime overrides and the upload helpers are not affected by the gate.
|
|
532
|
+
|
|
533
|
+
The tabs of a session key share its offline status and its replay, so `enabled()` must return the same value in every tab of that session key. A tab with the gate closed would clear an offline mode another tab still relies on, and a leading tab with the gate closed holds back the replay of every tab. To gate per workspace, include the workspace in the session key.
|
|
534
|
+
|
|
325
535
|
## Uploads
|
|
326
536
|
|
|
327
537
|
Configure uploads on `offlineSession.uploads` when queued mutations depend on local files. The manager exposes upload helpers:
|
|
@@ -333,9 +543,74 @@ Configure uploads on `offlineSession.uploads` when queued mutations depend on lo
|
|
|
333
543
|
- `resolveOfflineUpload(id)`
|
|
334
544
|
- `resolveOfflineUploads(ids)`
|
|
335
545
|
- `useOfflineUploads()`
|
|
546
|
+
- `useOfflineUploadFile(id)` — see [Rendering staged files](#rendering-staged-files)
|
|
336
547
|
|
|
337
548
|
Operations can declare `dependsOnUploads({ input })` and then read resolved upload refs from `execute({ uploads })`. When queued mutations are merged (`accumulation.mergeInput`), the dependencies are computed again from the merged input, so files referenced by any of the merged edits are uploaded before `execute` runs. `opfsOfflineUploadAdapter` is exported as a built-in OPFS-backed upload adapter.
|
|
338
549
|
|
|
550
|
+
### Upload refs
|
|
551
|
+
|
|
552
|
+
The value the `upload` transport resolves to is the upload ref: whatever the server needs to reference the uploaded file (a string, or an object such as `{ fileId, url }`). `createStoreManager` infers its type from the transport, so it does not have to be narrowed by hand:
|
|
553
|
+
|
|
554
|
+
```ts
|
|
555
|
+
const uploadRefSchema = rc_object({ fileId: rc_string, url: rc_string });
|
|
556
|
+
|
|
557
|
+
const storeManager = createStoreManager({
|
|
558
|
+
getSessionKey: () => currentTenantId ?? false,
|
|
559
|
+
errorNormalizer: normalizeError,
|
|
560
|
+
offlineSession: {
|
|
561
|
+
uploads: {
|
|
562
|
+
adapter: opfsOfflineUploadAdapter,
|
|
563
|
+
// Resolves to `{ fileId: string; url: string }`.
|
|
564
|
+
upload: ({ file, onProgress }) => api.uploadFile(file, onProgress),
|
|
565
|
+
// Optional: validates refs restored from storage or other tabs.
|
|
566
|
+
resolvedRefSchema: uploadRefSchema,
|
|
567
|
+
},
|
|
568
|
+
},
|
|
569
|
+
});
|
|
570
|
+
|
|
571
|
+
// `{ fileId: string; url: string }`
|
|
572
|
+
type UploadRef = StoreManagerUploadRef<typeof storeManager>;
|
|
573
|
+
|
|
574
|
+
const result = await storeManager.resolveOfflineUpload(attachmentId);
|
|
575
|
+
if (result.ok) console.log(result.value.url);
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
- `resolveOfflineUpload(id)`, `resolveOfflineUploads(ids)` and the `resolvedRef` of the `OfflineUpload` entries returned by `getOfflineUploads()` / `useOfflineUploads()` are typed with the inferred ref.
|
|
579
|
+
- Let the manager type be inferred. Annotating it as plain `StoreManager` (or its config as plain `OfflineSessionConfig`) replaces the inferred ref with the default `ValidPayload`. A manager with a typed ref is still accepted wherever a plain `StoreManager` is expected, including `storeManager` on every store.
|
|
580
|
+
- Stores are created with explicit type arguments, so TypeScript cannot carry the ref type from the `storeManager` option into `execute`. Pass it as the last type argument of `DefineDocumentOfflineOperations`, `DefineCollectionOfflineOperations` or `DefineListQueryOfflineOperations` (the single-operation `*OfflineOperationDefinition` aliases take it last too). Without it, operations keep the default `ValidPayload`:
|
|
581
|
+
|
|
582
|
+
```ts
|
|
583
|
+
type UserOfflineOperations = DefineListQueryOfflineOperations<
|
|
584
|
+
User,
|
|
585
|
+
UsersQuery,
|
|
586
|
+
UserPayload,
|
|
587
|
+
{ setAvatar: DefineOfflineOperation<{ id: number; uploadId: string }> },
|
|
588
|
+
UploadRef
|
|
589
|
+
>;
|
|
590
|
+
|
|
591
|
+
// In the operation definition:
|
|
592
|
+
dependsOnUploads: ({ input }) => [input.uploadId],
|
|
593
|
+
execute: ({ input, uploads }) => {
|
|
594
|
+
// `UploadRef | undefined`
|
|
595
|
+
const avatar = uploads.resolvedRefsById[input.uploadId];
|
|
596
|
+
if (!avatar) throw new Error('Missing avatar upload');
|
|
597
|
+
|
|
598
|
+
return api.setUserAvatar(input.id, avatar.fileId);
|
|
599
|
+
},
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
#### Validating restored refs
|
|
603
|
+
|
|
604
|
+
A ref returned by the `upload` transport is trusted. A ref can also reach the session without going through the transport: it is persisted with the upload record, so it is read back from the upload adapter after a reload, and other browser tabs publish the refs they resolved. Either source can come from a different app version with a different ref shape.
|
|
605
|
+
|
|
606
|
+
Set `resolvedRefSchema` to validate those refs. It accepts the same schemas as an operation `inputSchema` (a `runcheck` type or a synchronous Standard Schema such as zod), and its output has to agree with what the transport returns: the inferred ref type is what both produce.
|
|
607
|
+
|
|
608
|
+
- Refs restored from the upload adapter are parsed once when their record is loaded, and refs received from another tab once per record version.
|
|
609
|
+
- A ref that fails the schema is dropped and its upload goes back to `pending`. The staged file is kept with the record, so the next `resolveOfflineUpload(s)` call or the replay of an operation that depends on the upload sends the file through the transport again and stores the new ref. The dependent operation is not failed, and `execute` never receives the invalid ref. The file uploaded under the old ref is not cleaned up by TSDF.
|
|
610
|
+
- The exception is a ref another tab sends when it deletes an upload that was already sent: its staged file is gone, so a ref that fails the schema can't be uploaded again, and its id stops resolving (`resolveOfflineUpload(s)` returns an unknown upload error).
|
|
611
|
+
- Queued operations only persist upload ids. Their refs are resolved when the operation replays, so they are covered by the same validation.
|
|
612
|
+
- Without `resolvedRefSchema`, restored refs are exposed as they were stored.
|
|
613
|
+
|
|
339
614
|
### Upload metadata
|
|
340
615
|
|
|
341
616
|
The session has a single `upload` transport, so uploads that need different request parameters (target kind, parent ids, ...) carry them as `metadata` instead of encoding them in the upload id:
|
|
@@ -398,6 +673,53 @@ After an upload that was already sent is deleted, its id keeps resolving to the
|
|
|
398
673
|
|
|
399
674
|
Files attached directly to a mutation (`upload: { ... }` in `performMutation`) belong to that single queued mutation and are deleted with it in the same situations.
|
|
400
675
|
|
|
676
|
+
### Rendering staged files
|
|
677
|
+
|
|
678
|
+
An entity updated optimistically with a local file usually stores the staged upload id as its file ref. `storeManager.useOfflineUploadFile(id)` reads that staged file for rendering — also after a reload, when the object URLs the app created earlier are dead:
|
|
679
|
+
|
|
680
|
+
```tsx
|
|
681
|
+
type FileRef =
|
|
682
|
+
| { kind: 'local'; uploadId: string }
|
|
683
|
+
| { kind: 'server'; url: string };
|
|
684
|
+
|
|
685
|
+
function Thumbnail({ file }: { file: FileRef }) {
|
|
686
|
+
// A falsy id disables the hook, so it is only used for local refs.
|
|
687
|
+
const staged = storeManager.useOfflineUploadFile(
|
|
688
|
+
file.kind === 'local' && file.uploadId,
|
|
689
|
+
);
|
|
690
|
+
|
|
691
|
+
if (file.kind === 'server') return <img src={file.url} />;
|
|
692
|
+
if (staged.status === 'success') return <img src={staged.url} />;
|
|
693
|
+
|
|
694
|
+
// `missing` / `error`: the local file is gone or unreadable.
|
|
695
|
+
return <FilePlaceholder isLoading={staged.status === 'loading'} />;
|
|
696
|
+
}
|
|
697
|
+
```
|
|
698
|
+
|
|
699
|
+
The hook returns an `OfflineUploadFile`, a union narrowed by `status`:
|
|
700
|
+
|
|
701
|
+
- `status` — `idle` (falsy id), `loading`, `success`, `missing` (no upload with this id is staged in the active session) or `error` (the upload adapter failed to read the file; the read is tried again once every component stops using the id, or right away when the id is staged again)
|
|
702
|
+
- `url` — object URL of the staged file, managed by TSDF. Only set on `success`
|
|
703
|
+
- `file` — the staged `File`, for reading its contents. Only set on `success`
|
|
704
|
+
- `error` — the read failure. Only set on `error`
|
|
705
|
+
|
|
706
|
+
Caching and URL lifetime:
|
|
707
|
+
|
|
708
|
+
- Components using the same id share one read and one object URL, so the hook can be called from as many components as needed.
|
|
709
|
+
- A staged file the session already holds is returned on the first render, with no `loading` state. `loading` only shows while the session is still restoring its uploads (right after a reload) or reading an upload it does not hold yet.
|
|
710
|
+
- The URL exists while at least one component uses the id. It is revoked about one second after the last one stops using it (unmount or falsy id), so remounts and React StrictMode keep the same URL.
|
|
711
|
+
- `replaceOfflineUpload` gives every consumer in the tab a new `url` / `file` and revokes the previous URL. Staging or replacing the id from another tab does not update a file this tab already read until the tab reloads; deletions from another tab apply right away.
|
|
712
|
+
- When the upload leaves the session (`deleteOfflineUpload`, retention expiry, or a mutation-attached file being consumed) the status becomes `missing` and the URL is revoked. Staging the same id again makes it available again.
|
|
713
|
+
- Use `url` directly in render (`<img src>`, `<a href>`). Do not revoke it, do not keep it outside of render, and do not create extra object URLs from `file`.
|
|
714
|
+
|
|
715
|
+
The file follows the upload record, not its upload state: it stays available while the upload is `pending`, `uploading` and `uploaded`. To move from the local file to the uploaded one without a gap, derive the id from the entity as in the example above, and write the server ref into the entity when the mutation replays:
|
|
716
|
+
|
|
717
|
+
- Uploads staged with `saveOfflineUpload` are deleted once the last queued work that declares them leaves the queue (see [Upload lifecycle](#upload-lifecycle)). Files attached with `performMutation({ upload })` are removed once their mutation replayed. Uploads no queued work declared stay until `deleteOfflineUpload` or retention removes them.
|
|
718
|
+
- A replayed mutation releases its uploads after its `onSuccessExecute` ran (and, for a temp entity create, after the result replaced the temp entity). When `onSuccessExecute` writes the server ref into the entity, the local file stays renderable until that render, and from then on the component passes a falsy id and renders the server file.
|
|
719
|
+
- Otherwise the entity keeps the local ref until it is revalidated after replay, so the hook can report `missing` for a moment in between. The same happens for work `shouldSkipSync` drops, and in other tabs, whose entities keep the local ref until they refetch.
|
|
720
|
+
|
|
721
|
+
Outside of these windows, a local ref paired with `missing` means the staged file was deleted or expired, not that it is about to appear.
|
|
722
|
+
|
|
401
723
|
### Upload failure handling
|
|
402
724
|
|
|
403
725
|
The `upload` transport reports a failure by rejecting (throwing). What happens next depends on who started the upload.
|
|
@@ -196,4 +196,6 @@ It is the only availability signal for snapshots without `itemLoadedFields` meta
|
|
|
196
196
|
|
|
197
197
|
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.
|
|
198
198
|
|
|
199
|
+
Offline temp entities are metadata-free too, and they cannot be fetched before their mutation is replayed: a hook that requests a field `inferFields` does not vouch for stays in `loading`. An `inferFields` that lists the fields present in the snapshot never returns `'*'`, so it cannot satisfy `fields: '*'` hooks. Declare the loaded fields of the pending entity in the offline operation instead (`tempEntity.loadedFields`, or `loadedFields` in each `tempEntities` entry) — see [Temp Entities in List Queries](./offline.md#temp-entities-in-list-queries).
|
|
200
|
+
|
|
199
201
|
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.
|
|
@@ -305,6 +305,7 @@ const settingsStore = createDocumentStore<Settings>({
|
|
|
305
305
|
- `local-sync`: ~1 week old entries
|
|
306
306
|
- `opfsPersistentStorage`: ~2 weeks old entries
|
|
307
307
|
- `indexedDbPersistentStorage`: ~2 weeks old entries
|
|
308
|
+
- Queued offline mutations and unresolved offline resolutions never expire, in any adapter.
|
|
308
309
|
- Entries referenced by queued offline mutations are protected from expiry until that queued work is replayed or discarded.
|
|
309
310
|
- Expiry runs for an adapter only while at least one store uses it, and then covers every entry in that adapter, including ones left by stores that moved elsewhere. See [Changing a store's adapter](#changing-a-stores-adapter).
|
|
310
311
|
|
|
@@ -347,6 +348,20 @@ When the selected adapter does not support async preload, preload methods report
|
|
|
347
348
|
- Can be an explicit list or predicate.
|
|
348
349
|
- Takes precedence over pinned lists.
|
|
349
350
|
|
|
351
|
+
### Cached list queries that lost rows
|
|
352
|
+
|
|
353
|
+
Items and queries are stored and evicted separately, so a cached list query can outlive some of its rows: `maxItemBytes` evicts the least recently read item entries while the query entry stays, and an item entry that fails `schema` (or is now covered by `ignoreItems`) is discarded when it is read.
|
|
354
|
+
|
|
355
|
+
A cached query is restored as a loaded query (`status: 'success'`, shown immediately and revalidated in the background) when every row it was saved with can be restored, or when only its last rows are missing: like a list cut by `maxQuerySize`, the rows that are left are restored as a loaded list with `hasMore: true`. This is what happens to a list larger than `maxItemBytes`: the budget evicts its last rows right after it is saved.
|
|
356
|
+
|
|
357
|
+
Eviction follows read recency, not the order of the rows in a list. A list larger than `maxItemBytes` is restored as loaded on the first start after its last rows were cut, but once an online refetch saves it again, the rows that were rewritten look more recent than the unchanged ones, so the budget can evict earlier rows instead. The next start then restores it as a list with a gap (see below). To keep such a list restorable, raise `maxItemBytes` or lower `maxQuerySize`.
|
|
358
|
+
|
|
359
|
+
When a row before one of the rows that are left is missing, or no row is left, the rows that are left are still restored, but the query is not restored as loaded (`wasLoaded: false`), so the list with a gap — or an empty list — is never presented as the complete one:
|
|
360
|
+
|
|
361
|
+
- Online, hooks report `status: 'loading'` and fetch the query right away, as for a query that was never cached. The remaining rows are available in `items` meanwhile (stores using [Partial Resources](./partial-resources.md) hide items while loading, as usual).
|
|
362
|
+
- Offline, the fetch fails with the offline error: hooks report `status: 'error'` with `error.id === 'offline'` and the remaining rows in `items`, so a screen can show what is left of the list together with a notice that it is incomplete. `awaitListQueryFetch` returns the offline error instead of the incomplete list. A loaded list doesn't load more rows from such a cached list while offline (`loadMore` is skipped and `hasMore` is `false`), since its next rows may come after a missing one.
|
|
363
|
+
- The stored query is left as it is until the list is fetched again, so the next start sees the same state. With `local-sync`, the query entry rewritten after an eviction lists only the rows that are left, and is flagged (`"m": true`) as incomplete unless only its last rows were evicted (then it is saved with `"h": true`).
|
|
364
|
+
|
|
350
365
|
## Clearing stored data
|
|
351
366
|
|
|
352
367
|
- `clearSessionStorage(sessionKey, adapter)`:
|
package/docs/store-manager.md
CHANGED
|
@@ -114,6 +114,10 @@ const storeManager = createStoreManager({
|
|
|
114
114
|
|
|
115
115
|
Manager offline methods are safe to call even when no offline session is configured. In that case they return empty/default state, and upload helpers and `resolveOfflineResolution(...)` return `Result.err(...)` where applicable.
|
|
116
116
|
|
|
117
|
+
To detect outages and network failures the browser does not report, pass `offlineSession.healthCheck: { check, timeoutMs? }`. `check({ sessionKey, signal })` answers `'up'`, `'outage'` or `'unreachable'`, and the session uses it both to classify failed requests and as the recovery check of the active offline mode. Concurrent callers share one in-flight call. `'up'` for a failed request leaves the session online: the failure is handled by that request (its error, or the replay retry budget and then a `retry-exhausted` resolution). See [Health Check](./offline.md#health-check).
|
|
118
|
+
|
|
119
|
+
To turn the whole offline layer on and off at runtime (feature flag, per-workspace setting) without recreating the manager, pass `offlineSession.enabled: () => boolean`. While it returns `false` the session never enters offline mode and mutations with an `offline` descriptor run as plain online mutations; work already queued is kept and replayed after the gate reopens. See [Session gate](./offline.md#session-gate).
|
|
120
|
+
|
|
117
121
|
## Offline Status APIs
|
|
118
122
|
|
|
119
123
|
Read session-wide offline state:
|
|
@@ -135,7 +139,7 @@ Synchronous equivalents:
|
|
|
135
139
|
|
|
136
140
|
Runtime controls:
|
|
137
141
|
|
|
138
|
-
- `setOfflineRuntimeConfig(update)` returns a `Result<void, Error
|
|
142
|
+
- `setOfflineRuntimeConfig(update)` returns a `Result<void, Error>`. Every update, even an empty `{}`, also re-reads the `offlineSession.enabled` gate right away
|
|
139
143
|
- `resetOfflineRuntimeConfig()` restores the static `offlineSession` controls
|
|
140
144
|
|
|
141
145
|
Resolution actions:
|
|
@@ -175,6 +179,7 @@ Upload methods:
|
|
|
175
179
|
- `resolveOfflineUpload(id)` uploads the staged file if needed and returns its final ref
|
|
176
180
|
- `resolveOfflineUploads(ids)` does the same for several ids and fails as a whole with the first transport error
|
|
177
181
|
- `useOfflineUploads()`
|
|
182
|
+
- `useOfflineUploadFile(id)` returns `{ status, url, file, error }` for a staged upload
|
|
178
183
|
|
|
179
184
|
When the `upload` transport fails, `resolveOfflineUpload(s)` returns `Result.err(error)` with the transport error and the upload becomes `failed` (`lastError` set). The session failure classifiers are not consulted and nothing is retried automatically; calling the method again runs the upload again, and `lastError` is cleared once it succeeds. Uploads that run as a dependency of a replayed offline operation are classified and retried by the session instead. See [Offline: Upload failure handling](./offline.md#upload-failure-handling).
|
|
180
185
|
|
|
@@ -182,4 +187,14 @@ When the `upload` transport fails, `resolveOfflineUpload(s)` returns `Result.err
|
|
|
182
187
|
|
|
183
188
|
Staged uploads are deleted automatically when the last queued mutation or resolution record that depends on them leaves the queue (replayed, discarded, superseded or cancelled). `deleteOfflineUpload(id)` is only needed for uploads no queued mutation used, which otherwise expire after a week online, and it returns an error while queued work still references the upload. See [Offline: Upload lifecycle](./offline.md#upload-lifecycle).
|
|
184
189
|
|
|
190
|
+
The ref type returned by `resolveOfflineUpload(s)` and exposed as `OfflineUpload.resolvedRef` is inferred from the `upload` transport of `offlineSession.uploads`, as long as the manager is not annotated with the plain `StoreManager` type. `StoreManagerUploadRef<typeof storeManager>` extracts it, for example to type the upload refs of offline operations. `offlineSession.uploads.resolvedRefSchema` optionally validates refs restored from storage or received from other tabs; a ref that fails it is dropped and its upload goes back to `pending`. See [Offline: Upload refs](./offline.md#upload-refs).
|
|
191
|
+
|
|
185
192
|
Most upload methods return `Result` objects so UI can branch on `result.ok` without catching thrown errors.
|
|
193
|
+
|
|
194
|
+
`useOfflineUploadFile(id)` is the render-time counterpart of `loadOfflineUpload(id)`: components using the same id share one read and one TSDF-managed object URL (`url`), which is revoked when no component uses it anymore or when the upload is replaced, deleted or consumed. Pass a falsy id to disable it. See [Offline: Rendering staged files](./offline.md#rendering-staged-files).
|
|
195
|
+
|
|
196
|
+
```tsx
|
|
197
|
+
const staged = storeManager.useOfflineUploadFile(localUploadId);
|
|
198
|
+
|
|
199
|
+
return staged.status === 'success' ? <img src={staged.url} /> : null;
|
|
200
|
+
```
|