tsdf 18.3.1 → 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-D_Ltk0xg.d.ts → asyncStorageAdapter-C7J64ZKi.d.ts} +1 -1
- package/dist/{asyncStorageAdapter-NrI38v4g.js → asyncStorageAdapter-D6IVBzPg.js} +1 -1
- package/dist/{asyncStorageAdapters-Daewq7dv.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-x6dVEqkJ.js +1156 -0
- package/dist/main.d.ts +133 -20
- package/dist/main.js +1589 -372
- package/dist/opfs-storage.d.ts +1 -1
- package/dist/opfs-storage.js +1 -1
- package/dist/{opfsPersistentStorage-HRMP5gzd.d.ts → opfsPersistentStorage-CEhiNR8Q.d.ts} +1 -1
- package/dist/{opfsPersistentStorage-amwSWm_p.js → opfsPersistentStorage-CwmY3O1r.js} +1 -1
- package/dist/{types-DeZ9VDOe.d.ts → types-Bp7_Ra7_.d.ts} +625 -45
- package/docs/collection-store.md +9 -7
- package/docs/hooks.md +116 -3
- package/docs/list-query-store.md +3 -0
- package/docs/offline.md +457 -4
- package/docs/partial-resources.md +4 -0
- package/docs/persistent-storage.md +30 -0
- package/docs/shared-types.md +4 -0
- package/docs/store-manager.md +22 -3
- package/package.json +1 -1
- package/dist/indexedDbPersistentStorage-JJdUGGI8.js +0 -966
package/docs/shared-types.md
CHANGED
|
@@ -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:
|
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:
|
|
@@ -172,10 +176,25 @@ Upload methods:
|
|
|
172
176
|
- `replaceOfflineUpload({ id, file, metadata? })` keeps the saved metadata unless new `metadata` is passed
|
|
173
177
|
- `loadOfflineUpload(id)`
|
|
174
178
|
- `deleteOfflineUpload(id)`
|
|
175
|
-
- `resolveOfflineUpload(id)`
|
|
176
|
-
- `resolveOfflineUploads(ids)`
|
|
179
|
+
- `resolveOfflineUpload(id)` uploads the staged file if needed and returns its final ref
|
|
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
|
|
183
|
+
|
|
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).
|
|
178
185
|
|
|
179
186
|
`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
187
|
|
|
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).
|
|
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
|
+
|
|
181
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
|
+
```
|