tsdf 18.3.0 → 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/dist/async-storage.d.ts +1 -1
- package/dist/{asyncStorageAdapter-BDWpJ1vC.d.ts → asyncStorageAdapter-Ca9ntO1N.d.ts} +1 -1
- package/dist/{asyncStorageAdapters-Daewq7dv.js → asyncStorageAdapters-BFn-BuAl.js} +1 -1
- package/dist/indexed-db-storage.d.ts +1 -1
- package/dist/indexed-db-storage.js +1 -1
- package/dist/indexedDbPersistentStorage-DljRDcOr.js +1156 -0
- package/dist/main.d.ts +109 -11
- package/dist/main.js +954 -189
- package/dist/opfs-storage.d.ts +1 -1
- package/dist/{opfsPersistentStorage-CcdWYuhc.d.ts → opfsPersistentStorage-BeUPOyk4.d.ts} +1 -1
- package/dist/{types-2UJIjziu.d.ts → types-DUtkSBT8.d.ts} +160 -14
- package/docs/collection-store.md +9 -7
- package/docs/hooks.md +78 -3
- package/docs/list-query-store.md +2 -0
- package/docs/offline.md +161 -12
- package/docs/partial-resources.md +2 -0
- package/docs/persistent-storage.md +15 -0
- package/docs/shared-types.md +4 -0
- package/docs/store-manager.md +6 -2
- package/package.json +1 -1
- package/dist/indexedDbPersistentStorage-JJdUGGI8.js +0 -966
package/dist/opfs-storage.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import { t as opfsPersistentStorage } from "./opfsPersistentStorage-
|
|
1
|
+
import { t as opfsPersistentStorage } from "./opfsPersistentStorage-BeUPOyk4.js";
|
|
2
2
|
export { opfsPersistentStorage };
|
|
@@ -403,7 +403,21 @@ type FieldsOption<HasPartialResources extends boolean> = HasPartialResources ext
|
|
|
403
403
|
};
|
|
404
404
|
//#endregion
|
|
405
405
|
//#region src/persistentStorage/offlineUploadTypes.d.ts
|
|
406
|
-
/**
|
|
406
|
+
/**
|
|
407
|
+
* Lifecycle state for a session-scoped offline upload.
|
|
408
|
+
*
|
|
409
|
+
* - `pending`: staged and waiting to be uploaded. An upload whose transport
|
|
410
|
+
* failed during replay with a failure TSDF retries on its own (session went
|
|
411
|
+
* offline, or the failure was classified as retryable) goes back to
|
|
412
|
+
* `pending` with `lastError` set.
|
|
413
|
+
* - `uploading`: the `upload` transport is running.
|
|
414
|
+
* - `uploaded`: the transport returned the final ref (`resolvedRef`).
|
|
415
|
+
* - `failed`: the last transport attempt failed and TSDF will not retry on
|
|
416
|
+
* its own: the dependent operation was moved to manual resolution, or the
|
|
417
|
+
* upload was started through `resolveOfflineUpload(s)`. A failed upload is
|
|
418
|
+
* not blocked: it is uploaded again when a dependent operation is replayed
|
|
419
|
+
* (resolution `retry`) or `resolveOfflineUpload(s)` is called again.
|
|
420
|
+
*/
|
|
407
421
|
type OfflineUploadState = 'pending' | 'uploading' | 'uploaded' | 'failed';
|
|
408
422
|
/** Source that created a staged offline upload. */
|
|
409
423
|
type OfflineUploadSource = 'manual' | 'mutation';
|
|
@@ -447,7 +461,11 @@ type OfflineUpload<TResolvedRef extends ValidPayload = ValidPayload> = {
|
|
|
447
461
|
createdAt: number; /** Epoch timestamp for the latest upload metadata change. */
|
|
448
462
|
updatedAt: number; /** Final server-side reference after upload completes. */
|
|
449
463
|
resolvedRef?: TResolvedRef; /** Latest upload progress snapshot. */
|
|
450
|
-
progress?: OfflineUploadProgress;
|
|
464
|
+
progress?: OfflineUploadProgress;
|
|
465
|
+
/**
|
|
466
|
+
* Message of the latest failed upload attempt. It stays set while the upload
|
|
467
|
+
* is retried and is cleared once the upload succeeds.
|
|
468
|
+
*/
|
|
451
469
|
lastError?: {
|
|
452
470
|
message: string;
|
|
453
471
|
};
|
|
@@ -463,6 +481,12 @@ type OfflineStoredUploadRecord<TResolvedRef extends ValidPayload = ValidPayload>
|
|
|
463
481
|
/** Staged file blob restored from the upload adapter. */file: File; /** Last online session start time seen before the upload was stored. */
|
|
464
482
|
lastOnlineSessionStartedAt?: number; /** File last-modified timestamp. */
|
|
465
483
|
lastModified: number;
|
|
484
|
+
/**
|
|
485
|
+
* Store whose queued mutation attached this file, set on uploads with
|
|
486
|
+
* `source: 'mutation'`. Custom adapters must persist it: the file is removed
|
|
487
|
+
* once that store's queue no longer uses it.
|
|
488
|
+
*/
|
|
489
|
+
storeName?: string;
|
|
466
490
|
};
|
|
467
491
|
/** Storage backend contract for session-scoped offline upload files. */
|
|
468
492
|
type OfflineUploadAdapter = {
|
|
@@ -492,7 +516,19 @@ type OfflineUploadTransportContext = {
|
|
|
492
516
|
};
|
|
493
517
|
/** Upload handling config for an offline session. */
|
|
494
518
|
type OfflineSessionUploadsConfig<TResolvedRef extends ValidPayload = ValidPayload> = {
|
|
495
|
-
/** Adapter used to persist staged files until replay can upload them. */adapter: OfflineUploadAdapter;
|
|
519
|
+
/** Adapter used to persist staged files until replay can upload them. */adapter: OfflineUploadAdapter;
|
|
520
|
+
/**
|
|
521
|
+
* Upload transport that returns the final server-side file reference.
|
|
522
|
+
*
|
|
523
|
+
* Reject (throw) to report a failure. When the upload runs as a dependency
|
|
524
|
+
* of a replayed operation, the thrown error goes through the session's
|
|
525
|
+
* `classifyFailure` / `classifyRetryableFailure` hooks with `ctx.uploadId`
|
|
526
|
+
* set, exactly like a failed `execute`: classify connection problems as
|
|
527
|
+
* `'network'` / `'outage'` (or as retryable) so they are retried, and leave
|
|
528
|
+
* permanent ones (file too large, type not accepted) unclassified so the
|
|
529
|
+
* operation goes to manual resolution. Throw errors those hooks can tell
|
|
530
|
+
* apart.
|
|
531
|
+
*/
|
|
496
532
|
upload: (ctx: OfflineUploadTransportContext) => Promise<TResolvedRef>; /** Maximum number of concurrent upload transports. */
|
|
497
533
|
concurrency?: number;
|
|
498
534
|
};
|
|
@@ -583,6 +619,16 @@ type OfflineFailureContext = {
|
|
|
583
619
|
storeType: OfflineStoreType; /** Optional operation name associated with the failure. */
|
|
584
620
|
operationName?: string; /** Session key used by browser tab and persistence scoping. */
|
|
585
621
|
sessionKey: string;
|
|
622
|
+
/**
|
|
623
|
+
* Set when replaying `operationName` (`phase: 'sync'`) failed while
|
|
624
|
+
* resolving one of its `dependsOnUploads` uploads: the id of that upload.
|
|
625
|
+
* The operation's `execute` was not called. The error is usually the one
|
|
626
|
+
* thrown by the session `upload` transport, but it can also be a storage
|
|
627
|
+
* error reading or updating the staged upload, or the error for an upload
|
|
628
|
+
* that no longer exists. `undefined` for every failure that did not come
|
|
629
|
+
* from a dependency upload.
|
|
630
|
+
*/
|
|
631
|
+
uploadId?: string;
|
|
586
632
|
};
|
|
587
633
|
/** Re-check strategy for recovery probing. Omitted fields use built-in defaults (which differ between network and outage modes). */
|
|
588
634
|
type OfflineRecoveryProbeConfig = {
|
|
@@ -658,6 +704,10 @@ type OfflineSessionConfig<TUploadRef extends ValidPayload = ValidPayload> = {
|
|
|
658
704
|
* `network` activates network offline handling for future operations only
|
|
659
705
|
* when `network.enabled` is true. Existing offline recovery may keep using
|
|
660
706
|
* classifications until already-active work finishes recovering.
|
|
707
|
+
*
|
|
708
|
+
* Failures of the `uploads.upload` transport during replay are classified
|
|
709
|
+
* here too, with `ctx.uploadId` set: `outage` / `network` keep the upload
|
|
710
|
+
* `pending` and the dependent operation queued until the session recovers.
|
|
661
711
|
*/
|
|
662
712
|
classifyFailure?: (error: unknown, ctx: OfflineFailureContext) => Promise<OfflineFailureClassification> | OfflineFailureClassification;
|
|
663
713
|
/**
|
|
@@ -669,6 +719,11 @@ type OfflineSessionConfig<TUploadRef extends ValidPayload = ValidPayload> = {
|
|
|
669
719
|
* case the entry still enters `needs-confirmation` so `shouldSkipSync` /
|
|
670
720
|
* conflict checks can run before the mutation is promoted to manual
|
|
671
721
|
* resolution.
|
|
722
|
+
*
|
|
723
|
+
* When `ctx.uploadId` is set the failure came from a dependency upload and
|
|
724
|
+
* the mutation was not sent: return `true` to run the upload again on the
|
|
725
|
+
* `replayRetry` cadence, or `false` for a permanent failure (file rejected),
|
|
726
|
+
* which moves the operation to manual resolution right away.
|
|
672
727
|
*/
|
|
673
728
|
classifyRetryableFailure?: (error: unknown, ctx: OfflineFailureContext) => Promise<boolean> | boolean; /** Network detection strategy and browser integration. */
|
|
674
729
|
network?: OfflineNetworkModeConfig; /** Outage detection and recovery strategy for remote failures. */
|
|
@@ -711,6 +766,42 @@ type GlobalOfflineStatus = {
|
|
|
711
766
|
};
|
|
712
767
|
/** Queue state of an offline mutation entry. */
|
|
713
768
|
type OfflineSyncState = 'pending' | 'syncing' | 'needs-confirmation';
|
|
769
|
+
/**
|
|
770
|
+
* Offline sync state of one collection/list-query item, returned by the
|
|
771
|
+
* stores' `useItemOfflineState(...)` and `getItemOfflineState(...)`.
|
|
772
|
+
*/
|
|
773
|
+
type ItemOfflineState = {
|
|
774
|
+
/**
|
|
775
|
+
* Where the item's offline work stands (same value as the item's
|
|
776
|
+
* {@link GlobalOfflineEntity.syncState}):
|
|
777
|
+
*
|
|
778
|
+
* - `pending`: queued, waiting to be sent
|
|
779
|
+
* - `syncing`: being sent
|
|
780
|
+
* - `needs-confirmation`: a send failed and it is not known whether it
|
|
781
|
+
* reached the server, so the mutation is re-checked or retried
|
|
782
|
+
* - `resolution-required`: waiting for a manual resolution
|
|
783
|
+
*
|
|
784
|
+
* With several mutations queued for the item this is the most urgent state
|
|
785
|
+
* among them (`needs-confirmation` > `syncing` > `pending`): the item is
|
|
786
|
+
* `syncing` while any of its mutations is being sent (`pendingMutations`
|
|
787
|
+
* drops as each one finishes).
|
|
788
|
+
*/
|
|
789
|
+
syncState: OfflineSyncState | 'resolution-required'; /** Number of queued mutations of the item still waiting to sync. */
|
|
790
|
+
pendingMutations: number; /** Whether the item is waiting for a manual resolution. */
|
|
791
|
+
requiresResolution: boolean;
|
|
792
|
+
/**
|
|
793
|
+
* Whether the item was created offline through a `tempEntity` /
|
|
794
|
+
* `tempEntities` operation and the server has not confirmed it yet, so it is
|
|
795
|
+
* still tracked under its temporary payload. Creations queued without a temp
|
|
796
|
+
* entity (e.g. with a client-generated id) report `false`. It stays `true`
|
|
797
|
+
* while the creation itself is being sent, so the server may already have
|
|
798
|
+
* it while `syncState` is `syncing` or `needs-confirmation`; only with
|
|
799
|
+
* `syncState: 'pending'` has it not been sent yet. Once the server entity is
|
|
800
|
+
* reconciled, the temporary payload has no state anymore and the final
|
|
801
|
+
* payload reports any mutation still queued with `isUnsentCreation: false`.
|
|
802
|
+
*/
|
|
803
|
+
isUnsentCreation: boolean;
|
|
804
|
+
};
|
|
714
805
|
/** Aggregated offline status for a tracked document/item/query entity. */
|
|
715
806
|
type GlobalOfflineEntity = {
|
|
716
807
|
/** Internal entity identifier tracked by offline machinery. */id: string; /** Session key for this offline entity. */
|
|
@@ -720,7 +811,13 @@ type GlobalOfflineEntity = {
|
|
|
720
811
|
entityKey: string; /** Entity kind used in queue partitioning. */
|
|
721
812
|
entityKind: OfflineEntityKind; /** Effective lifecycle derived from queued operations targeting this entity. */
|
|
722
813
|
kind: OfflineEntityMutationKind; /** Number of pending mutations waiting for sync. */
|
|
723
|
-
pendingMutations: number;
|
|
814
|
+
pendingMutations: number;
|
|
815
|
+
/**
|
|
816
|
+
* Current sync state for the entity. With several mutations queued for it
|
|
817
|
+
* this is the most urgent state among them (`needs-confirmation` >
|
|
818
|
+
* `syncing` > `pending`): the entity is `syncing` while any of its mutations
|
|
819
|
+
* is being sent.
|
|
820
|
+
*/
|
|
724
821
|
syncState: OfflineSyncState | 'resolution-required'; /** Whether the entity currently requires manual resolution. */
|
|
725
822
|
requiresResolution: boolean; /** Resolution ids currently blocking this entity from being resolved/applied. */
|
|
726
823
|
blockedByResolutionIds: string[]; /** Child resolution ids currently derived from this entity's dependency chain. */
|
|
@@ -789,7 +886,11 @@ type OfflineRetryExhaustedResolutionRecordBase<TInput = unknown> = {
|
|
|
789
886
|
operation: string; /** Input value that exhausted replay retries. */
|
|
790
887
|
input: TInput; /** Timestamp when the original queued mutation was enqueued. */
|
|
791
888
|
enqueuedAt: number; /** Entity references involved in the resolution. */
|
|
792
|
-
entityRefs: OfflineEntityRef[];
|
|
889
|
+
entityRefs: OfflineEntityRef[];
|
|
890
|
+
/**
|
|
891
|
+
* Last replay error snapshot captured before exhaustion. When a dependency
|
|
892
|
+
* upload failed permanently, this is the error of the `upload` transport.
|
|
893
|
+
*/
|
|
793
894
|
lastReplayError: {
|
|
794
895
|
message: string;
|
|
795
896
|
}; /** Resolution creation timestamp. */
|
|
@@ -823,12 +924,31 @@ type OfflineSession<TUploadRef extends ValidPayload = ValidPayload> = {
|
|
|
823
924
|
getOfflineStatus: () => GlobalOfflineStatus; /** Returns the latest aggregated offline entities for the session. */
|
|
824
925
|
getOfflineEntities: () => readonly GlobalOfflineEntity[]; /** Returns the latest aggregated conflict/retry resolutions for the session. */
|
|
825
926
|
getOfflineResolutions: () => readonly OfflineResolutionRecord[]; /** Returns the latest session-scoped offline uploads for the session. */
|
|
826
|
-
getOfflineUploads: () => readonly OfflineUpload<TUploadRef>[];
|
|
827
|
-
|
|
828
|
-
|
|
927
|
+
getOfflineUploads: () => readonly OfflineUpload<TUploadRef>[];
|
|
928
|
+
/**
|
|
929
|
+
* Resolves a staged upload id to its latest final ref, uploading first if
|
|
930
|
+
* needed. Rejects with the error thrown by the `upload` transport, leaving
|
|
931
|
+
* the upload `failed`; the session failure classifiers are not consulted.
|
|
932
|
+
*/
|
|
933
|
+
resolveOfflineUpload: (id: string) => Promise<TUploadRef>;
|
|
934
|
+
/**
|
|
935
|
+
* Resolves multiple staged upload ids to their latest final refs. Rejects
|
|
936
|
+
* with the first transport error, like `resolveOfflineUpload`.
|
|
937
|
+
*/
|
|
938
|
+
resolveOfflineUploads: (ids: readonly string[]) => Promise<Record<string, TUploadRef>>;
|
|
939
|
+
/**
|
|
940
|
+
* Saves a session-scoped upload locally for later dependency resolution or
|
|
941
|
+
* ref usage. It is deleted automatically once the queued work that depends
|
|
942
|
+
* on it leaves the queue.
|
|
943
|
+
*/
|
|
829
944
|
saveOfflineUpload: (args: SaveOfflineUploadArgs) => Promise<void>; /** Replaces a previously stored session-scoped upload, keeping its metadata unless new metadata is passed. */
|
|
830
945
|
replaceOfflineUpload: (args: ReplaceOfflineUploadArgs) => Promise<void>; /** Loads a previously stored session-scoped upload. */
|
|
831
|
-
loadOfflineUpload: (id: string) => Promise<File | null>;
|
|
946
|
+
loadOfflineUpload: (id: string) => Promise<File | null>;
|
|
947
|
+
/**
|
|
948
|
+
* Deletes a stored upload that no queued work references. Only needed for
|
|
949
|
+
* uploads no queued mutation used: the others are deleted with the work that
|
|
950
|
+
* depends on them.
|
|
951
|
+
*/
|
|
832
952
|
deleteOfflineUpload: (id: string) => Promise<void>; /** React hook subscribing to the session's global offline status. */
|
|
833
953
|
useOfflineStatus: () => GlobalOfflineStatus; /** React hook subscribing to the session's aggregated offline entities. */
|
|
834
954
|
useOfflineEntities: () => readonly GlobalOfflineEntity[]; /** React hook subscribing to the session's aggregated conflict/retry resolutions. */
|
|
@@ -1161,7 +1281,18 @@ type ConfiguredTempEntityFields<TInput, TTempResult, TTempId extends ValidPayloa
|
|
|
1161
1281
|
* @typeParam TTempResult - Result returned by `execute`, used only when `tempEntity` or `tempEntities` needs to reconcile the final server entity. Defaults to `void`.
|
|
1162
1282
|
*/
|
|
1163
1283
|
type OfflineOperationDefinition<TInput, TConflict, TTempResult = void, TServerSnapshot = unknown, TTempId extends ValidPayload = string, TPendingEntity = unknown, TFinalPayload extends ValidPayload = ValidPayload, TFinalData = unknown, TUploadRef extends ValidPayload = ValidPayload> = {
|
|
1164
|
-
/** Schema used to validate incoming operation input. */inputSchema: PersistentStorageSchema<TInput>;
|
|
1284
|
+
/** Schema used to validate incoming operation input. */inputSchema: PersistentStorageSchema<TInput>;
|
|
1285
|
+
/**
|
|
1286
|
+
* Lifecycle classification for the queued operation. TSDF derives the
|
|
1287
|
+
* lifecycle of each entity the operation references (`getEntityRefs`) from
|
|
1288
|
+
* it.
|
|
1289
|
+
*
|
|
1290
|
+
* Every item a `create` references is treated as created by it: discarding
|
|
1291
|
+
* a `create` without temp entity removes all of them locally, without
|
|
1292
|
+
* refetching them. Return only the
|
|
1293
|
+
* created items, change existing items in a separate `update` operation, and
|
|
1294
|
+
* reference the items the creation needs with `dependsOn`.
|
|
1295
|
+
*/
|
|
1165
1296
|
kind: OfflineOperationKind;
|
|
1166
1297
|
/**
|
|
1167
1298
|
* Optional queue pruning for newer operations that supersede older queued work.
|
|
@@ -1301,7 +1432,12 @@ type DocumentOperationServerSnapshot<TOptions extends DefineOfflineOperation> =
|
|
|
1301
1432
|
* ```
|
|
1302
1433
|
*/
|
|
1303
1434
|
type DocumentOfflineOperationDefinition<State extends ValidStoreState, TOptions extends DefineOfflineOperation = DefineOfflineOperation, TUploadRef extends ValidPayload = ValidPayload> = WithoutTempEntity<OfflineOperationDefinition<DocumentOperationInput<TOptions>, DocumentOperationConflict<TOptions>, DocumentOperationResult<TOptions>, DocumentOperationServerSnapshot<TOptions>, string, unknown, ValidPayload, unknown, TUploadRef>> & {
|
|
1304
|
-
/**
|
|
1435
|
+
/**
|
|
1436
|
+
* Declares which upload ids must finish before replaying this operation.
|
|
1437
|
+
* A staged upload is deleted once the last queued operation or resolution
|
|
1438
|
+
* record that declares it leaves the queue.
|
|
1439
|
+
*/
|
|
1440
|
+
dependsOnUploads?: (ctx: OperationEntityRefsContext<DocumentOperationInput<TOptions>>) => string[];
|
|
1305
1441
|
} & ([State] extends [never] ? never : unknown);
|
|
1306
1442
|
/**
|
|
1307
1443
|
* Builds a document offline operations map from a compact operation spec.
|
|
@@ -1387,7 +1523,12 @@ type CollectionOfflineOperationDefinition<ItemState extends ValidStoreState, Ite
|
|
|
1387
1523
|
* Declares which collection item refs must resolve before replaying this
|
|
1388
1524
|
* operation.
|
|
1389
1525
|
*/
|
|
1390
|
-
dependsOn?: (ctx: OperationEntityRefsContext<TInput>) => CollectionOfflineEntityRef<ItemPayloadUnused>[];
|
|
1526
|
+
dependsOn?: (ctx: OperationEntityRefsContext<TInput>) => CollectionOfflineEntityRef<ItemPayloadUnused>[];
|
|
1527
|
+
/**
|
|
1528
|
+
* Declares which upload ids must finish before replaying this operation.
|
|
1529
|
+
* A staged upload is deleted once the last queued operation or resolution
|
|
1530
|
+
* record that declares it leaves the queue.
|
|
1531
|
+
*/
|
|
1391
1532
|
dependsOnUploads?: (ctx: OperationEntityRefsContext<TInput>) => string[];
|
|
1392
1533
|
} & ([ItemState | ItemPayloadUnused] extends [never] ? never : unknown);
|
|
1393
1534
|
/**
|
|
@@ -1458,7 +1599,12 @@ type ListQueryOfflineOperationDefinition<ItemState extends ValidStoreState, Quer
|
|
|
1458
1599
|
* Declares which list item refs must resolve before replaying this
|
|
1459
1600
|
* operation.
|
|
1460
1601
|
*/
|
|
1461
|
-
dependsOn?: (ctx: OperationEntityRefsContext<TInput>) => ListQueryOfflineEntityRef<ItemPayloadUnused>[];
|
|
1602
|
+
dependsOn?: (ctx: OperationEntityRefsContext<TInput>) => ListQueryOfflineEntityRef<ItemPayloadUnused>[];
|
|
1603
|
+
/**
|
|
1604
|
+
* Declares which upload ids must finish before replaying this operation.
|
|
1605
|
+
* A staged upload is deleted once the last queued operation or resolution
|
|
1606
|
+
* record that declares it leaves the queue.
|
|
1607
|
+
*/
|
|
1462
1608
|
dependsOnUploads?: (ctx: OperationEntityRefsContext<TInput>) => string[];
|
|
1463
1609
|
} & ([ItemState | QueryPayload | ItemPayloadUnused] extends [never] ? never : unknown);
|
|
1464
1610
|
/**
|
|
@@ -1831,4 +1977,4 @@ type ListQueryPersistentStorageFields<QueryPayload extends ValidPayload, ItemPay
|
|
|
1831
1977
|
/** Persistent storage config for ListQueryStore. */
|
|
1832
1978
|
type ListQueryPersistentStorageConfig<ItemState extends ValidStoreState, QueryPayload extends ValidPayload = ValidPayload, ItemPayload extends ValidPayload = ValidPayload, StorageState = unknown, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload> = null> = StorePersistentStorageBaseConfig<ItemState, StorageState> & PublicStoreOfflineConfigField<TOfflineOperations> & ListQueryPersistentStorageFields<QueryPayload, ItemPayload>;
|
|
1833
1979
|
//#endregion
|
|
1834
|
-
export {
|
|
1980
|
+
export { OfflineResolutionAction as $, TSDFItemQuery as $t, DefineListQueryOfflineOperations as A, OfflineUploadAdapter as At, OfflineConflictResolutionAction as B, FetchListFnReturn as Bt, PersistentStorageSchema as C, TSDFDebugLogArea as Cn, ParsedOfflineResolutionConflictResultForStore as Ct, CollectionOfflineOperationDefinition as D, TSDFFocusDebugOperation as Dn, OfflineSessionUploadsConfig as Dt, CollectionOfflineEntityRef as E, TSDFDebugLogger as En, OfflineOperationUploadsContext as Et, ItemOfflineState as F, ReplaceOfflineUploadArgs as Ft, OfflineMutationDescriptor as G, ListQueryUseMultipleListQueriesQuery as Gt, OfflineFailureClassification as H, FieldsInput as Ht, ListQueryOfflineEntityRef as I, SaveOfflineUploadArgs as It, OfflineMutationQueueingConfig as J, OnListQueryItemInvalidate as Jt, OfflineMutationInput as K, OffsetPaginationConfig as Kt, ListQueryOfflineOperationDefinition as L, DerivedQueriesConfig as Lt, DocumentOfflineOperationDefinition as M, OfflineUploadSource as Mt, GlobalOfflineEntity as N, OfflineUploadState as Nt, DefineCollectionOfflineOperations as O, TSDFLoggerOptions as On, OfflineStoredUploadRecord as Ot, GlobalOfflineStatus as P, OfflineUploadTransportContext as Pt, OfflineReplayRetryConfig as Q, QueryStatus as Qt, OfflineAccumulationConfig as R, DerivedQueryContext as Rt, PersistentStoragePreloadResult as S, ScheduleFetchResults as Sn, ParsedOfflineResolutionConflictResultForOperation as St, AnyOfflineOperationDefinition as T, TSDFDebugLogLevel as Tn, OfflineMutationUploadsInput as Tt, OfflineFailureContext as U, FieldsOption as Ut, OfflineEntityMutationKind as V, FetchListFnReturnItem as Vt, OfflineFailurePhase as W, ListQueryUseMultipleItemsQuery as Wt, OfflineOperationKind as X, PartialResourcesConfig as Xt, OfflineMutationQueueingPolicy as Y, OptimisticListUpdate as Yt, OfflineQueueEntry as Z, QueryFetchPayload as Zt, ListQueryOfflineOperationsConfig as _, mutationSkipped as _n, OfflineTempEntitiesReconciliation as _t, AsyncStorageMetadataOrder as a, MaybeTSDFResult as an, OfflineResolutionGenericAction as at, PersistentStorageDataSchema as b, RequestSchedulerEvents as bn, OperationConflict as bt, AsyncStorageNamespaceCommitUpsert as c, StoreError as cn, OfflineResolutionRecordForStore as ct, AsyncStorageNamespaceKind as d, StoreMutationErrorOptions as dn, OfflineRuntimeConfigUpdate as dt, TSFDListQuery as en, OfflineResolutionActionError as et, AsyncStorageNamespaceScope as f, TSDFStatus as fn, OfflineSession as ft, DocumentPersistentStorageConfig as g, fetchTypePriority as gn, OfflineTempEntitiesConfig as gt, ConvertedPersistentStorageDataSchema as h, ValidStoreState as hn, OfflineSyncState as ht, AsyncStorageDriverSetEntry as i, TSFDUsePendingOfflineItemsReturn as in, OfflineResolutionConflictParseErrorCode as it, DefineOfflineOperation as j, OfflineUploadProgress as jt, DefineDocumentOfflineOperations as k, OfflineUpload as kt, AsyncStorageNamespaceGetResult as l, StoreFetchError as ln, OfflineRetryExhaustedResolutionAction as lt, CollectionPersistentStorageConfig as m, ValidPayload as mn, OfflineSupersedeConfig as mt, AsyncStorageDiscoveredScope as n, TSFDUseListItemReturn as nn, OfflineResolutionActionForOperation as nt, AsyncStorageNamespaceCommitArgs as o, MutationSkipped as on, OfflineResolutionRecord as ot, AsyncStorageReadOptions as p, UnwrapTSDFResult as pn, OfflineSessionConfig as pt, OfflineMutationQueueingCause as q, OnListQueryInvalidate as qt, AsyncStorageDriver as r, TSFDUseListQueryReturn as rn, OfflineResolutionConflictParseError as rt, AsyncStorageNamespaceCommitTouch as s, PayloadDebounce as sn, OfflineResolutionRecordForOperation as st, AsyncStorageAdapter as t, TSFDListQueryState as tn, OfflineResolutionActionErrorCode as tt, AsyncStorageNamespaceHandle as u, StoreMutationError as un, OfflineRuntimeConfig as ut, ListQueryPersistentStorageConfig as v, FetchType as vn, OfflineTempEntityConfig as vt, StorageAdapter as w, TSDFDebugLogEntry as wn, defaultOfflineRuntimeConfig as wt, PersistentStorageErrorHandler as x, ScheduleFetchOptions as xn, OperationResult as xt, PersistentStorageBaseConfig as y, RequestSchedulerEventData as yn, OfflineTempEntityPendingEntry as yt, OfflineAccumulationMergeContext as z, DerivedQuerySource as zt };
|
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,81 @@ 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
|
+
|
|
380
|
+
### Items created offline
|
|
381
|
+
|
|
382
|
+
An item created offline is tracked under its temporary payload until the server
|
|
383
|
+
confirms it. After that the temporary payload returns `null`, and the final
|
|
384
|
+
payload reports the mutations that are still queued for the item (for example
|
|
385
|
+
an edit made right after creating it) with `isUnsentCreation: false`.
|
|
386
|
+
|
|
387
|
+
```ts
|
|
388
|
+
function onDeleteClick(itemPayload: UserPayload) {
|
|
389
|
+
const offlineState = store.getItemOfflineState(itemPayload);
|
|
390
|
+
|
|
391
|
+
// A creation that was not sent yet only exists locally, so deleting it
|
|
392
|
+
// only discards local work: no need to ask before deleting for everyone.
|
|
393
|
+
const isLocalOnly =
|
|
394
|
+
offlineState?.isUnsentCreation && offlineState.syncState === 'pending';
|
|
395
|
+
|
|
396
|
+
if (isLocalOnly || confirmDeleteForEveryone()) {
|
|
397
|
+
deleteUser(itemPayload);
|
|
398
|
+
}
|
|
399
|
+
}
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
`isUnsentCreation` stays `true` while the creation itself is being sent, until
|
|
403
|
+
the server result is reconciled. The server may already have the item while
|
|
404
|
+
`syncState` is `'syncing'` or `'needs-confirmation'`, which is why the example
|
|
405
|
+
also checks for `'pending'`.
|
|
406
|
+
|
|
332
407
|
## useMultipleItems
|
|
333
408
|
|
|
334
409
|
**Stores**: [Collection Store](./collection-store.md), [List Query Store](./list-query-store.md)
|
package/docs/list-query-store.md
CHANGED
|
@@ -207,6 +207,7 @@ Behavior:
|
|
|
207
207
|
| ------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------- |
|
|
208
208
|
| `useListQuery(payload, options?)` | Fetch and subscribe to a list query | See [Hooks - useListQuery](./hooks.md#uselistquery) |
|
|
209
209
|
| `usePendingOfflineItems(options?)` | Read queued offline items without fetching | See [Hooks - usePendingOfflineItems](./hooks.md#usependingofflineitems) |
|
|
210
|
+
| `useItemOfflineState(payload)` | Read the offline sync state of one item | See [Hooks - useItemOfflineState](./hooks.md#useitemofflinestate) |
|
|
210
211
|
| `useMultipleListQueries(queries, options?)` | Fetch multiple list queries | See [Hooks - useMultipleListQueries](./hooks.md#usemultiplelistqueries) |
|
|
211
212
|
| `useItem(payload, options?)` | Fetch and subscribe to a single item | See [Hooks - useItem](./hooks.md#useitem) |
|
|
212
213
|
| `useMultipleItems(items, options?)` | Fetch multiple individual items | See [Hooks - useMultipleItems](./hooks.md#usemultipleitems) |
|
|
@@ -242,6 +243,7 @@ Behavior:
|
|
|
242
243
|
| Method | Description |
|
|
243
244
|
| ----------------------------------------------------- | ----------------------------------------------------------------- |
|
|
244
245
|
| `getOfflineEntities()` / `useOfflineEntities()` | Read offline entities scoped to this store |
|
|
246
|
+
| `getItemOfflineState(payload)` | Read the offline sync state of one item, `null` if nothing queued |
|
|
245
247
|
| `getOfflineResolutions()` / `useOfflineResolutions()` | Read manual conflict/retry resolutions scoped to this store |
|
|
246
248
|
| `parseOfflineResolutionConflict(resolution)` | Narrow a persisted resolution to this store's operation types |
|
|
247
249
|
| `resolveOfflineResolution(id, operation, action)` | Resolve, retry, discard, requeue, or commit an offline resolution |
|