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.
@@ -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 | 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
- | `useListItemIsLoading(payload, options)` | Detect if a sub-item is loading | See [Hooks - useListItem Hooks](./hooks.md#uselistitem-hooks) |
88
- | `useListItemIsDeleted(payload, options)` | Detect if a sub-item was deleted | See [Hooks - useListItem Hooks](./hooks.md#uselistitem-hooks) |
89
- | `useListItem(payload, options)` | Combined loading + deletion detection | See [Hooks - useListItem Hooks](./hooks.md#uselistitem-hooks) |
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.
@@ -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 |