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.
@@ -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:
@@ -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
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tsdf",
3
- "version": "18.3.1",
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",