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/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
- // A creation that was not sent yet only exists locally, so deleting it
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 isLocalOnly =
394
- offlineState?.isUnsentCreation && offlineState.syncState === 'pending';
402
+ const onlyExistsLocally =
403
+ offlineState?.isUnsentCreation && !offlineState.creationAttempted;
395
404
 
396
- if (isLocalOnly || confirmDeleteForEveryone()) {
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. The server may already have the item while
404
- `syncState` is `'syncing'` or `'needs-confirmation'`, which is why the example
405
- also checks for `'pending'`.
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.
@@ -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)`:
@@ -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
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tsdf",
3
- "version": "18.4.0",
3
+ "version": "18.5.0",
4
4
  "description": "A data fetching solution based on t-state",
5
5
  "license": "PolyForm-Noncommercial-1.0.0",
6
6
  "author": "Lucas Santos",