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/collection-store.md
CHANGED
|
@@ -80,13 +80,14 @@ The overall store state is `Record<string, TSFDCollectionItem | null>` where key
|
|
|
80
80
|
|
|
81
81
|
### Hooks
|
|
82
82
|
|
|
83
|
-
| Hook | Description
|
|
84
|
-
| ---------------------------------------- |
|
|
85
|
-
| `useItem(payload, options?)` | Fetch and subscribe to a single item
|
|
86
|
-
| `useMultipleItems(items, options?)` | Fetch and subscribe to multiple items
|
|
87
|
-
| `
|
|
88
|
-
| `
|
|
89
|
-
| `
|
|
83
|
+
| Hook | Description | Details |
|
|
84
|
+
| ---------------------------------------- | --------------------------------------- | ----------------------------------------------------------------- |
|
|
85
|
+
| `useItem(payload, options?)` | Fetch and subscribe to a single item | See [Hooks - useItem](./hooks.md#useitem) |
|
|
86
|
+
| `useMultipleItems(items, options?)` | Fetch and subscribe to multiple items | See [Hooks - useMultipleItems](./hooks.md#usemultipleitems) |
|
|
87
|
+
| `useItemOfflineState(payload)` | Read the offline sync state of one item | See [Hooks - useItemOfflineState](./hooks.md#useitemofflinestate) |
|
|
88
|
+
| `useListItemIsLoading(payload, options)` | Detect if a sub-item is loading | See [Hooks - useListItem Hooks](./hooks.md#uselistitem-hooks) |
|
|
89
|
+
| `useListItemIsDeleted(payload, options)` | Detect if a sub-item was deleted | See [Hooks - useListItem Hooks](./hooks.md#uselistitem-hooks) |
|
|
90
|
+
| `useListItem(payload, options)` | Combined loading + deletion detection | See [Hooks - useListItem Hooks](./hooks.md#uselistitem-hooks) |
|
|
90
91
|
|
|
91
92
|
### Methods
|
|
92
93
|
|
|
@@ -113,6 +114,7 @@ The overall store state is `Record<string, TSFDCollectionItem | null>` where key
|
|
|
113
114
|
| Method | Description |
|
|
114
115
|
| ----------------------------------------------------- | ----------------------------------------------------------------- |
|
|
115
116
|
| `getOfflineEntities()` / `useOfflineEntities()` | Read offline entities scoped to this store |
|
|
117
|
+
| `getItemOfflineState(payload)` | Read the offline sync state of one item, `null` if nothing queued |
|
|
116
118
|
| `getOfflineResolutions()` / `useOfflineResolutions()` | Read manual conflict/retry resolutions scoped to this store |
|
|
117
119
|
| `parseOfflineResolutionConflict(resolution)` | Narrow a persisted resolution to this store's operation types |
|
|
118
120
|
| `resolveOfflineResolution(id, operation, action)` | Resolve, retry, discard, requeue, or commit an offline resolution |
|
package/docs/hooks.md
CHANGED
|
@@ -149,7 +149,7 @@ store.useDocument({ disabled: true });
|
|
|
149
149
|
|
|
150
150
|
- `data` - The selected data (or `null` if not loaded)
|
|
151
151
|
- `status` - `'idle'` | `'loading'` | `'success'` | `'error'` | `'refetching'`
|
|
152
|
-
- `error` - The `StoreError` if the fetch failed, otherwise `null`
|
|
152
|
+
- `error` - The `StoreError` if the fetch failed, otherwise `null`. While [offline](./offline.md#reading-while-offline), it is only set when there is no cached data to return; check it with `isOfflineStoreError(error)`
|
|
153
153
|
- `isLoading` - Shorthand for `status === 'loading'`
|
|
154
154
|
- `pendingSync` - `true` while local offline changes for this document still need to sync to the server
|
|
155
155
|
|
|
@@ -204,7 +204,7 @@ because the required refresh must be scheduled immediately.
|
|
|
204
204
|
|
|
205
205
|
- `data` - The selected data (or `null`)
|
|
206
206
|
- `status` - `'idle'` | `'loading'` | `'success'` | `'error'` | `'refetching'` | `'deleted'`
|
|
207
|
-
- `error` - The `StoreError` if the fetch failed
|
|
207
|
+
- `error` - The `StoreError` if the fetch failed. While [offline](./offline.md#reading-while-offline), it is only set when there is no cached data to return; check it with `isOfflineStoreError(error)`
|
|
208
208
|
- `isLoading` - Shorthand for `status === 'loading'`
|
|
209
209
|
- `payload` - The resolved payload
|
|
210
210
|
- `itemStateKey` - The internal key for this item
|
|
@@ -280,7 +280,7 @@ changes on every keystroke.
|
|
|
280
280
|
- `isDerived` - Whether the result is currently coming from `derivedQueries` instead of an exact cached/fetched query
|
|
281
281
|
- `isLoading` - Shorthand for `status === 'loading'`
|
|
282
282
|
- `isLoadingMore` - Shorthand for `status === 'loadingMore'`
|
|
283
|
-
- `error` - The `StoreError` if the fetch failed
|
|
283
|
+
- `error` - The `StoreError` if the fetch failed. While [offline](./offline.md#reading-while-offline), it is only set when there is no cached data to return; check it with `isOfflineStoreError(error)`
|
|
284
284
|
- `payload` - The resolved payload
|
|
285
285
|
- `queryKey` - The internal key for this query
|
|
286
286
|
- `pendingSync` - `true` while local offline changes for this query still need to sync to the server
|
|
@@ -329,6 +329,93 @@ Behavior:
|
|
|
329
329
|
- `items` - Visible pending items (or selected items)
|
|
330
330
|
- `deletedItems` - Payloads for pending deletes
|
|
331
331
|
|
|
332
|
+
## useItemOfflineState
|
|
333
|
+
|
|
334
|
+
**Stores**: [Collection Store](./collection-store.md), [List Query Store](./list-query-store.md)
|
|
335
|
+
|
|
336
|
+
Returns the offline sync state of one item, or `null` when the item has nothing
|
|
337
|
+
queued and no manual resolution waiting. It does not fetch anything. Use it for
|
|
338
|
+
per-row sync badges:
|
|
339
|
+
|
|
340
|
+
```tsx
|
|
341
|
+
const Row = memo(function Row({ itemPayload }: { itemPayload: UserPayload }) {
|
|
342
|
+
const offlineState = store.useItemOfflineState(itemPayload);
|
|
343
|
+
|
|
344
|
+
if (!offlineState) return null;
|
|
345
|
+
if (offlineState.requiresResolution)
|
|
346
|
+
return <Badge>Needs your attention</Badge>;
|
|
347
|
+
if (offlineState.syncState === 'syncing') return <Badge>Syncing</Badge>;
|
|
348
|
+
return <Badge>Waiting to sync</Badge>;
|
|
349
|
+
});
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
Behavior:
|
|
353
|
+
|
|
354
|
+
- The component re-renders only when the state of its own item changes, not
|
|
355
|
+
when other items of the store are queued, replayed, or resolved
|
|
356
|
+
- A falsy payload (`null`, `undefined`, `false`) returns `null`
|
|
357
|
+
- Stores without offline support always return `null`
|
|
358
|
+
- `store.getItemOfflineState(itemPayload)` reads the same state without
|
|
359
|
+
subscribing, for event handlers
|
|
360
|
+
|
|
361
|
+
### Return value
|
|
362
|
+
|
|
363
|
+
`null`, or an `ItemOfflineState`:
|
|
364
|
+
|
|
365
|
+
- `syncState` - `'pending'` (waiting to be sent), `'syncing'` (being sent),
|
|
366
|
+
`'needs-confirmation'` (a send failed and it is not known whether it reached
|
|
367
|
+
the server, so it is re-checked or retried) or `'resolution-required'`. With
|
|
368
|
+
several mutations queued for the item this is the most urgent state among
|
|
369
|
+
them (`'needs-confirmation'` > `'syncing'` > `'pending'`): the item is
|
|
370
|
+
`'syncing'` while any of its mutations is being sent
|
|
371
|
+
- `pendingMutations` - Number of queued mutations of the item still waiting to
|
|
372
|
+
sync
|
|
373
|
+
- `requiresResolution` - `true` while the item waits for a manual resolution
|
|
374
|
+
(see [Offline - Conflict Resolution](./offline.md#conflict-resolution))
|
|
375
|
+
- `isUnsentCreation` - `true` while the item was created offline (a
|
|
376
|
+
`tempEntity` / `tempEntities` operation) and the server has not confirmed it
|
|
377
|
+
yet, so it is still tracked under its temporary payload. Creations queued
|
|
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
|
|
388
|
+
|
|
389
|
+
### Items created offline
|
|
390
|
+
|
|
391
|
+
An item created offline is tracked under its temporary payload until the server
|
|
392
|
+
confirms it. After that the temporary payload returns `null`, and the final
|
|
393
|
+
payload reports the mutations that are still queued for the item (for example
|
|
394
|
+
an edit made right after creating it) with `isUnsentCreation: false`.
|
|
395
|
+
|
|
396
|
+
```ts
|
|
397
|
+
function onDeleteClick(itemPayload: UserPayload) {
|
|
398
|
+
const offlineState = store.getItemOfflineState(itemPayload);
|
|
399
|
+
|
|
400
|
+
// The server never saw a creation that was not attempted, so deleting it
|
|
401
|
+
// only discards local work: no need to ask before deleting for everyone.
|
|
402
|
+
const onlyExistsLocally =
|
|
403
|
+
offlineState?.isUnsentCreation && !offlineState.creationAttempted;
|
|
404
|
+
|
|
405
|
+
if (onlyExistsLocally || confirmDeleteForEveryone()) {
|
|
406
|
+
deleteUser(itemPayload);
|
|
407
|
+
}
|
|
408
|
+
}
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
`isUnsentCreation` stays `true` while the creation itself is being sent, until
|
|
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.
|
|
418
|
+
|
|
332
419
|
## useMultipleItems
|
|
333
420
|
|
|
334
421
|
**Stores**: [Collection Store](./collection-store.md), [List Query Store](./list-query-store.md)
|
|
@@ -449,3 +536,29 @@ const { isLoading, isDeleted, data } = collectionStore.useListItem(
|
|
|
449
536
|
},
|
|
450
537
|
);
|
|
451
538
|
```
|
|
539
|
+
|
|
540
|
+
## useOfflineUploadFile
|
|
541
|
+
|
|
542
|
+
**Source**: [Store Manager](./store-manager.md#upload-apis)
|
|
543
|
+
|
|
544
|
+
Reads the file of an upload staged with `saveOfflineUpload` / `performMutation({ upload })`, to render local files (e.g. thumbnails of optimistic entities) by upload id.
|
|
545
|
+
|
|
546
|
+
```tsx
|
|
547
|
+
const { status, url, file, error } = storeManager.useOfflineUploadFile(
|
|
548
|
+
isLocalFile && uploadId,
|
|
549
|
+
);
|
|
550
|
+
```
|
|
551
|
+
|
|
552
|
+
- Does not fetch from the server: it reads the session's staged uploads
|
|
553
|
+
- Components using the same id share one read and one object URL
|
|
554
|
+
- `url` is managed by TSDF: do not revoke it or keep it outside of render
|
|
555
|
+
- A falsy id disables the hook (`status: 'idle'`)
|
|
556
|
+
|
|
557
|
+
### Return value
|
|
558
|
+
|
|
559
|
+
- `status` - `'idle'` | `'loading'` | `'success'` | `'missing'` | `'error'`
|
|
560
|
+
- `url` - Object URL of the staged file, or `null` unless `status` is `'success'`
|
|
561
|
+
- `file` - The staged `File`, or `null` unless `status` is `'success'`
|
|
562
|
+
- `error` - The read failure, or `null` unless `status` is `'error'`
|
|
563
|
+
|
|
564
|
+
`'missing'` means no upload with this id is staged in the active session: it was never staged, or it was deleted, expired or already consumed by its mutation. See [Offline: Rendering staged files](./offline.md#rendering-staged-files) for the URL lifetime and the pattern for switching to the uploaded file.
|
package/docs/list-query-store.md
CHANGED
|
@@ -190,6 +190,7 @@ derivedQueries: {
|
|
|
190
190
|
Behavior:
|
|
191
191
|
|
|
192
192
|
- Online: exact query cache wins; otherwise TSDF can derive when `isComplete(...)` returns `true`
|
|
193
|
+
- `isComplete(...)` only receives the group's queries that have loaded at least once, so a list still on its first fetch never makes the group look complete
|
|
193
194
|
- Offline: derivation is attempted before the exact cached query result
|
|
194
195
|
- `deriveQuery(...)` receives `{ fields, isOfflineMode, deriveSource }`
|
|
195
196
|
- `fields` lets derivation opt out of partial-resource queries when local data is insufficient
|
|
@@ -207,6 +208,7 @@ Behavior:
|
|
|
207
208
|
| ------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------- |
|
|
208
209
|
| `useListQuery(payload, options?)` | Fetch and subscribe to a list query | See [Hooks - useListQuery](./hooks.md#uselistquery) |
|
|
209
210
|
| `usePendingOfflineItems(options?)` | Read queued offline items without fetching | See [Hooks - usePendingOfflineItems](./hooks.md#usependingofflineitems) |
|
|
211
|
+
| `useItemOfflineState(payload)` | Read the offline sync state of one item | See [Hooks - useItemOfflineState](./hooks.md#useitemofflinestate) |
|
|
210
212
|
| `useMultipleListQueries(queries, options?)` | Fetch multiple list queries | See [Hooks - useMultipleListQueries](./hooks.md#usemultiplelistqueries) |
|
|
211
213
|
| `useItem(payload, options?)` | Fetch and subscribe to a single item | See [Hooks - useItem](./hooks.md#useitem) |
|
|
212
214
|
| `useMultipleItems(items, options?)` | Fetch multiple individual items | See [Hooks - useMultipleItems](./hooks.md#usemultipleitems) |
|
|
@@ -242,6 +244,7 @@ Behavior:
|
|
|
242
244
|
| Method | Description |
|
|
243
245
|
| ----------------------------------------------------- | ----------------------------------------------------------------- |
|
|
244
246
|
| `getOfflineEntities()` / `useOfflineEntities()` | Read offline entities scoped to this store |
|
|
247
|
+
| `getItemOfflineState(payload)` | Read the offline sync state of one item, `null` if nothing queued |
|
|
245
248
|
| `getOfflineResolutions()` / `useOfflineResolutions()` | Read manual conflict/retry resolutions scoped to this store |
|
|
246
249
|
| `parseOfflineResolutionConflict(resolution)` | Narrow a persisted resolution to this store's operation types |
|
|
247
250
|
| `resolveOfflineResolution(id, operation, action)` | Resolve, retry, discard, requeue, or commit an offline resolution |
|