tsdf 18.3.1 → 18.4.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/offline.md CHANGED
@@ -109,6 +109,42 @@ A mutation is also queued while online when older mutations for the same entitie
109
109
 
110
110
  Queued mutations and pending resolutions are persisted through the store's own `persistentStorage.adapter`, and the cached entries they reference are protected from cache expiry until the queue is replayed or discarded. They are not migrated when a store's adapter changes: let the queue drain first. See [Changing a store's adapter](./persistent-storage.md#changing-a-stores-adapter).
111
111
 
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
+
114
+ ## Reading While Offline
115
+
116
+ 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:
117
+
118
+ - **Cached data** (loaded earlier, or restored from persistent storage): the cached data stays visible with `status: 'success'` and `error: null`. A refetch attempted offline leaves it that way, so there is no offline error to hide in the UI.
119
+ - **Nothing cached**: the read fails with `status: 'error'` and the offline error `{ code: 0, id: 'offline', message: 'Offline' }`. This is the only offline state the app has to explain to the user.
120
+
121
+ Use `isOfflineStoreError(error)` to recognise that error instead of comparing `error.id` by hand. It matches the whole error shape, so an app error whose `errorNormalizer` also uses the `'offline'` id is not mistaken for it, and it narrows the error to the exported `OfflineStoreError` type:
122
+
123
+ ```tsx
124
+ import { isOfflineStoreError } from 'tsdf';
125
+
126
+ function UserName({ id }: { id: number }) {
127
+ const { data, error, isLoading } = userStore.useItem({ id });
128
+
129
+ if (isLoading) return <Spinner />;
130
+ if (isOfflineStoreError(error)) return <NotAvailableOffline />;
131
+ if (error) return <ErrorMessage error={error} />;
132
+
133
+ return <span>{data?.name}</span>;
134
+ }
135
+ ```
136
+
137
+ It also accepts the `StoreFetchError` returned by the `awaitFetch` methods, which resolve with the cached data while offline and with the offline error only when nothing is cached.
138
+
139
+ With [partial resources](./partial-resources.md), "cached" is decided per hook, by the `fields` it requests:
140
+
141
+ - A hook whose requested fields are all cached is a cached read: `status: 'success'`, `error: null`. Fields that were loaded and later invalidated count as cached — they stay visible and are refreshed after recovering.
142
+ - A hook requesting fields that were never loaded has nothing usable to return for them, so it reports `status: 'error'` with the offline error, without attempting a fetch. Its data stays hidden as it would be while loading (`data: null`, `items: []`), or stays visible with `loadingFields` when `showPartialAsRefetching` is enabled.
143
+
144
+ 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
+
146
+ Both kinds of reads are refetched once the session recovers (see below): reads that failed offline load, and cached reads get refreshed.
147
+
112
148
  ## Revalidation After Recovering
113
149
 
114
150
  While the session is in offline mode, automatic revalidations that could only fail are held: `onTransportReconnect()` signals and window-focus revalidations only re-check connectivity (`network.getIsOffline`) instead of refetching, and cached data stays visible. When the re-check finds the connection back, the session leaves offline mode and the stores revalidate as described below.
@@ -126,7 +162,7 @@ Mounted data refetches right away, unmounted data on its next mount. Stores with
126
162
  All offline operations define:
127
163
 
128
164
  - `inputSchema` - Validates mutation input before it enters the queue and again when restored.
129
- - `kind` - `create`, `update`, or `delete`; TSDF derives each affected entity's lifecycle from this.
165
+ - `kind` - `create`, `update`, or `delete`; TSDF derives each affected entity's lifecycle from this. Every item a `create` returns from `getEntityRefs` is treated as created by it (discarding a `create` without temp entity removes all of them), so return only the created items: change existing items in a separate `update` operation, and reference the items the creation needs with `dependsOn`.
130
166
  - `execute(ctx)` - Sends queued work to the server during replay.
131
167
 
132
168
  Collection and list-query operations also define:
@@ -160,7 +196,7 @@ await userStore.resolveOfflineResolution(resolutions[0].id, 'renameUser', {
160
196
 
161
197
  Supported resolution actions include:
162
198
 
163
- - `discard` - Drop the resolution record. The optimistic changes of the discarded mutation cannot be rolled back locally, so TSDF refetches what the operation referenced (`getEntityRefs`): the document, the collection item, or the list query item together with the store's lists (the change may have moved or removed the row). An entity that other changes still wait for a decision on is not refetched, since the refetch would replace those changes: it is revalidated once the last one is handled. Likewise, while other changes of a list query store still wait for a manual resolution, only the item is refetched: its lists are revalidated once the last one is handled. Discarding a temp create removes the temp entity and everything queued on top of it; existing entities changed on top of it are refetched.
199
+ - `discard` - Drop the resolution record. The optimistic changes of the discarded mutation cannot be rolled back locally, so TSDF refetches what the operation referenced (`getEntityRefs`): the document, the collection item, or the list query item together with the store's lists (the change may have moved or removed the row). An entity that other changes still wait for a decision on is not refetched, since the refetch would replace those changes: it is revalidated once the last one is handled. Likewise, while other changes of a list query store still wait for a manual resolution, only the item is refetched: its lists are revalidated once the last one is handled. Discarding a temp create removes the temp entity and everything queued on top of it; existing entities changed on top of it are refetched. Discarding a `create` without temp entity (the app generated the id on the client) removes the items it created (its `getEntityRefs`) from the store, its lists and the persisted cache, like a temp entity, instead of refetching them: a discarded creation is treated as never sent. If the server did create one (the response of an earlier replay attempt was lost, or a conflict reported that it already exists), it stays removed locally until something fetches it again: the recovery revalidation of a list query store's lists brings it back (right away when no other change waits for a decision, otherwise once the last one is handled), but a collection item, or a list query item outside every loaded list, shows `deleted` until it is fetched again, e.g. after a reload. Discarding a temp create has the same tradeoff. Unlike changes made on top of a temp entity, changes queued on such an item are not held behind its failed creation: they are sent on their own and need their own decision if the server rejects them. Until they are sent, their optimistic view keeps the item visible in its views, even though the discard removed it from the store.
164
200
  - `requeue` - Queue replacement input for an operation conflict.
165
201
  - `commit` - Accept an externally completed resolution result.
166
202
  - `retry` - Retry a retry-exhausted record.
@@ -243,6 +279,19 @@ Each store also exposes scoped APIs:
243
279
 
244
280
  List-query stores additionally expose `usePendingOfflineItems(...)`, which returns pending creates/updates and pending deletes without mounting or fetching a query.
245
281
 
282
+ ### Per-item state
283
+
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 }`:
285
+
286
+ ```tsx
287
+ const offlineState = userStore.useItemOfflineState({ id: 1 });
288
+ // null | { syncState: 'pending', pendingMutations: 1, requiresResolution: false, isUnsentCreation: false }
289
+ ```
290
+
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).
292
+
293
+ Document stores hold a single entity, so they do not need a per-item reader: use `useDocument().pendingSync` or `useOfflineEntities()[0]`.
294
+
246
295
  ## Multiple Tabs
247
296
 
248
297
  Tabs of the same session share one offline queue. Every tab can queue mutations and every tab shows the same pending state, but only one tab sends the queued work:
@@ -285,7 +334,7 @@ Configure uploads on `offlineSession.uploads` when queued mutations depend on lo
285
334
  - `resolveOfflineUploads(ids)`
286
335
  - `useOfflineUploads()`
287
336
 
288
- Operations can declare `dependsOnUploads({ input })` and then read resolved upload refs from `execute({ uploads })`. `opfsOfflineUploadAdapter` is exported as a built-in OPFS-backed upload adapter.
337
+ 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.
289
338
 
290
339
  ### Upload metadata
291
340
 
@@ -331,3 +380,85 @@ await storeManager.saveOfflineUpload({
331
380
  - Because it is read back from storage, it is typed as an unvalidated `ValidPayload`: parse it with a schema before using it, as above. Uploads staged without metadata reach the transport with `metadata: undefined`, so handle that case explicitly. This includes the ones persisted by older versions and files attached directly to a mutation with its `upload` option, which can't carry metadata.
332
381
  - `saveOfflineUpload` stores exactly the metadata it receives. `replaceOfflineUpload` keeps the metadata already saved for that id unless new `metadata` is passed. Both fail while that upload is queued or being sent.
333
382
  - Custom `OfflineUploadAdapter` implementations must persist and restore the record's `metadata` and `storeName` fields together with the rest of the record. `storeName` marks which store queued a file attached to a mutation. That file is removed once nothing in that store's queue uses it, and only while that store is created in the tab, so a store created later (for example on a code-split screen) still finds its files.
383
+
384
+ ### Upload lifecycle
385
+
386
+ A staged upload follows the queued work that depends on it:
387
+
388
+ - While a queue entry or resolution record declares the upload through `dependsOnUploads`, the upload is kept. This includes a failed mutation waiting for a manual resolution, so `retry` still finds the file. `deleteOfflineUpload(id)` returns an error for an upload in this state.
389
+ - When the last queue entry or resolution record that declares it leaves the queue, TSDF deletes the upload (its record and the stored file). It does not matter how the work ended:
390
+ - it replayed successfully, or `shouldSkipSync` dropped it;
391
+ - its resolution was discarded, together with the queued work discarded with it (the edits of an entity whose create was discarded);
392
+ - a later operation pruned it with `supersedes`, or cancelled it with its temp entity (`dropSelfIfTempLifecycleCancelled`);
393
+ - its conflict was resolved with `commit`, or with a `requeue` whose replacement input no longer declares the upload. Uploads the replacement input still declares are kept.
394
+ - References are session-wide. An upload declared by queued mutations of several stores is deleted only after the last of them is gone. Only stores created in the tab count: an upload staged with `saveOfflineUpload` and shared with a store that is not created in the tab yet (a code-split screen, or the app restarted on another screen) can be deleted when the stores already created release it, and that store's queued mutation then fails to replay. If an upload id is shared across lazily created stores, create those stores before their queued work replays, or stage a separate upload for each store. Files attached directly to a mutation don't have this limit: they record the store that queued them (see `storeName` above).
395
+ - An upload that no queued work declared yet is never deleted for being unreferenced: the app stages the file first and queues the mutation afterwards. It stays until a mutation that declares it is queued and leaves the queue, until the app calls `deleteOfflineUpload(id)`, or until it expires. Unreferenced uploads expire after the session has been online for one week without interruption (going offline restarts the window). This also applies to uploads the app resolves itself with `resolveOfflineUpload(s)` for an online mutation, because they never enter the queue.
396
+
397
+ After an upload that was already sent is deleted, its id keeps resolving to the same server ref for the rest of the app session, in every tab open when it was deleted: a mutation queued later that still declares it (for example from optimistic or draft data that was not updated with the server ref yet) replays with that ref without uploading again, and `resolveOfflineUpload(id)` returns it. This ref is kept in memory only: after a reload, in a tab opened later, or after `deleteOfflineUpload(id)`, the id is unknown again, so stage the file again with `saveOfflineUpload` before reusing it. Uploads deleted before they were sent (discarded, superseded or cancelled work) are not kept.
398
+
399
+ 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
+
401
+ ### Upload failure handling
402
+
403
+ The `upload` transport reports a failure by rejecting (throwing). What happens next depends on who started the upload.
404
+
405
+ #### Dependency uploads during replay
406
+
407
+ When a queued operation with `dependsOnUploads` replays, a transport failure is classified by the same session hooks as a failed `execute`: `classifyFailure(error, ctx)` and then `classifyRetryableFailure(error, ctx)`. `ctx` is the context of the operation being replayed (`phase: 'sync'`, `storeType`, `operationName`, `sessionKey`) plus `uploadId`, the id of the upload that failed. `execute` is not called for that attempt. Other failures while resolving that upload, such as a storage error reading the staged file, are classified the same way with `uploadId` set, so check the error type instead of assuming every failure with `uploadId` came from the transport.
408
+
409
+ - **Connection problem or outage** - `classifyFailure` returns `'network'` or `'outage'` (and that mode is enabled, as for any other failure). The session enters that mode, the upload goes back to `pending` (with `lastError` set) and the operation stays queued. Replay runs the upload again when the session recovers. The replay retry budget is not consumed, however long the outage lasts.
410
+ - **Transient failure that is safe to repeat** - `classifyFailure` returns `'ignore'` and `classifyRetryableFailure` returns `true`. The upload goes back to `pending` and is sent again on the `replayRetry` cadence (`intervalMs`, 5s by default). After `maxFailures` attempts (3 by default) it is handled as a permanent failure.
411
+ - **Permanent failure** (file too large, type not accepted) - no hook recognizes the error, which is the default. The upload becomes `failed` and the operation moves right away to a `retry-exhausted` resolution: `lastReplayError` carries the upload error and `dependencyUploadIds` lists the uploads it depends on. Resolving it with `retry` requeues the operation, which runs the upload again; `discard` removes the operation and, when no other queued work declares the upload, deletes the staged file (see "Upload lifecycle").
412
+
413
+ `lastError` is cleared when an upload succeeds.
414
+
415
+ The hooks are the only way to tell these cases apart, so the transport must throw errors they can recognize:
416
+
417
+ ```ts
418
+ class UploadError extends Error {
419
+ kind: 'connection' | 'server-down' | 'rejected';
420
+
421
+ constructor(kind: UploadError['kind'], message: string) {
422
+ super(message);
423
+ this.kind = kind;
424
+ }
425
+ }
426
+
427
+ const storeManager = createStoreManager({
428
+ getSessionKey: () => currentTenantId ?? false,
429
+ errorNormalizer: normalizeError,
430
+ offlineSession: {
431
+ network: { enabled: true, recoveryCheck: pingApi },
432
+ outage: { enabled: true, recoveryCheck: pingApi },
433
+ classifyFailure: (error) => {
434
+ if (error instanceof UploadError) {
435
+ if (error.kind === 'connection') return 'network';
436
+ if (error.kind === 'server-down') return 'outage';
437
+ return 'ignore'; // rejected file: manual resolution
438
+ }
439
+
440
+ return classifyApiError(error);
441
+ },
442
+ uploads: {
443
+ adapter: opfsOfflineUploadAdapter,
444
+ // Throws `UploadError` with the kind that matches what went wrong.
445
+ upload: ({ file, onProgress }) => uploadFile(file, onProgress),
446
+ },
447
+ },
448
+ });
449
+ ```
450
+
451
+ Check `ctx.uploadId !== undefined` when a classifier needs to treat upload failures differently from `execute` failures that throw the same error type.
452
+
453
+ #### `resolveOfflineUpload(s)`
454
+
455
+ When the app uploads a staged file itself, a transport failure is returned to the caller as `Result.err(error)` and the upload becomes `failed` with `lastError` set. The session hooks are not consulted, the session mode does not change, and nothing is retried automatically: the caller decides what to do, and calling `resolveOfflineUpload(s)` again runs the upload again.
456
+
457
+ #### Upload states
458
+
459
+ - `pending` - staged and waiting to be uploaded, including uploads waiting for an automatic retry (those have `lastError` set).
460
+ - `uploading` - the transport is running.
461
+ - `uploaded` - the transport returned the final ref (`resolvedRef`).
462
+ - `failed` - the last attempt failed and TSDF will not retry on its own. A `failed` upload is never blocked: it is uploaded again the next time an operation that depends on it is replayed or `resolveOfflineUpload(s)` is called for it.
463
+
464
+ Queued mutations and staged uploads live in browser storage (localStorage, IndexedDB, OPFS), which the browser may evict under storage pressure unless the origin was granted persistent storage. TSDF does not request it: `navigator.storage.persist()` is an origin-wide permission and some browsers prompt for it, so the app should call it at a moment of its choosing (for example when the first change is queued).
@@ -143,6 +143,8 @@ If you enable `showPartialAsRefetching`, the hook exposes `loadingFields` with t
143
143
 
144
144
  Invalidations are refetches, not new loads: when an invalidation (full or per-field) marks cached data as stale, hooks whose requested fields are still present keep the stale data visible while the refetch is in flight (with a `refetching` status when `returnRefetchingStatus` is enabled). Data is only hidden behind `loading` when a requested field was genuinely never loaded.
145
145
 
146
+ While the session of an [offline-enabled store](./offline.md#reading-while-offline) is in offline mode, missing fields cannot be fetched. A hook requesting fields that were never loaded does not wait on `loading`: it reports `status: 'error'` with the offline error (`isOfflineStoreError(error)`), keeping its data hidden (or visible with `loadingFields` under `showPartialAsRefetching`). Hooks whose requested fields are all cached — including invalidated ones — keep returning them with `status: 'success'`. The missing and the invalidated fields are fetched once the session recovers.
147
+
146
148
  The same holds across reloads with persistent storage: an item invalidated before the page was closed is persisted with every field its snapshot still holds, and is restored as stale cached data: shown right away, then refetched on mount (a hook with a `fields` selection refetches only the fields it requests). An invalidated fully-loaded (`'*'`) item still satisfies `fields: '*'` reads from cache, which keeps it readable when the app is reopened offline.
147
149
 
148
150
  ## Fields in Scheduling and Fetching
@@ -167,6 +167,21 @@ persistentStorage: {
167
167
 
168
168
  Use `createIndexedDbPersistentStorage({ databaseName })` from `tsdf/indexed-db-storage` when an app needs an isolated IndexedDB database.
169
169
 
170
+ #### Connection recovery
171
+
172
+ Browsers can take an IndexedDB connection away from a page that keeps running: the storage process restarts, a backgrounded mobile tab comes back with a dead connection, or another tab upgrades or deletes the database. The adapter recovers without a page reload:
173
+
174
+ - A failed open is not remembered. The next operation opens the database again.
175
+ - When the browser closes the connection (`close`), or another tab needs it released (`versionchange`), the adapter closes and forgets it, so the other tab is not blocked. The next operation opens a new connection.
176
+ - When an operation fails with a connection error (`InvalidStateError`, `AbortError`, or `UnknownError`, e.g. WebKit's "Connection to Indexed Database server lost"), the adapter drops the connection, opens a new one, and runs the operation once more. Every adapter operation is a self-contained transaction that writes whole values, so repeating it never applies a batch twice or leaves half of it behind. Quota, data, and version errors are not retried.
177
+ - When IndexedDB stops answering — an open or a transaction delivers no event at all — the operation is treated like a lost connection after two consecutive checks, 15 seconds apart, during which no event of the same database reached the page while the tab was visible (30 to 45 seconds). Progress is what is measured, not total duration: a large batch on a slow device is never cut short in the tab running it. Only events reaching this page count, so an operation of another tab that waits more than 30 seconds behind that batch can still be given up and retried. A check interval during which the tab was hidden at any point, or the page was not running at all (frozen tab, sleeping device), does not count, so an operation is never given up the moment a page resumes.
178
+
179
+ If the second attempt also fails, the error is reported through `onPersistentStorageError`. Recovery depends on the browser accepting a new connection; some Safari versions refuse one until the page is reloaded, in which case each failing operation is reported instead of staying pending.
180
+
181
+ #### When a write fails
182
+
183
+ A persistence write that still fails after the recovery above is reported through `onPersistentStorageError` and dropped. In-memory store state is not affected and the app keeps working; the entry keeps its previous persisted value (or stays absent) until the store saves it again. See [Offline](./offline.md#queuing-mutations) for what this means for queued mutations.
184
+
170
185
  ### Custom async adapters
171
186
 
172
187
  Use `createAsyncStorageAdapter(driver)` only when the built-in OPFS and IndexedDB adapters are not a fit. It wraps an `AsyncStorageDriver`, which is the low-level async backend contract used by TSDF persistence internals.
@@ -16,6 +16,10 @@ type StoreError = {
16
16
  };
17
17
  ```
18
18
 
19
+ ### isOfflineStoreError
20
+
21
+ `isOfflineStoreError(error)` tells whether a `StoreError` (or a `StoreFetchError`) is the error TSDF reports for a fetch that could not complete because the offline session is in offline mode, narrowing it to `OfflineStoreError` (`{ code: 0, id: 'offline', message: 'Offline' }`). See [Reading While Offline](./offline.md#reading-while-offline).
22
+
19
23
  ## StoreFetchError
20
24
 
21
25
  An `Error` subclass returned by `awaitFetch` methods. Contains the same fields as `StoreError` plus a `type` indicating why the fetch failed:
@@ -172,10 +172,14 @@ Upload methods:
172
172
  - `replaceOfflineUpload({ id, file, metadata? })` keeps the saved metadata unless new `metadata` is passed
173
173
  - `loadOfflineUpload(id)`
174
174
  - `deleteOfflineUpload(id)`
175
- - `resolveOfflineUpload(id)`
176
- - `resolveOfflineUploads(ids)`
175
+ - `resolveOfflineUpload(id)` uploads the staged file if needed and returns its final ref
176
+ - `resolveOfflineUploads(ids)` does the same for several ids and fails as a whole with the first transport error
177
177
  - `useOfflineUploads()`
178
178
 
179
+ 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
+
179
181
  `metadata` is a JSON-serializable `ValidPayload` persisted with the upload. The `upload` transport receives it in its context and `getOfflineUploads()` / `useOfflineUploads()` expose it on each `OfflineUpload`. See [Offline: Upload metadata](./offline.md#upload-metadata).
180
182
 
183
+ 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
+
181
185
  Most upload methods return `Result` objects so UI can branch on `result.ok` without catching thrown errors.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tsdf",
3
- "version": "18.3.1",
3
+ "version": "18.4.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",