tsdf 18.4.0 → 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-Ca9ntO1N.d.ts → asyncStorageAdapter-C7J64ZKi.d.ts} +1 -1
- package/dist/{asyncStorageAdapter-NrI38v4g.js → asyncStorageAdapter-D6IVBzPg.js} +1 -1
- package/dist/{asyncStorageAdapters-BFn-BuAl.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-DljRDcOr.js → indexedDbPersistentStorage-x6dVEqkJ.js} +1 -1
- package/dist/main.d.ts +35 -12
- package/dist/main.js +1047 -285
- package/dist/opfs-storage.d.ts +1 -1
- package/dist/opfs-storage.js +1 -1
- package/dist/{opfsPersistentStorage-BeUPOyk4.d.ts → opfsPersistentStorage-CEhiNR8Q.d.ts} +1 -1
- package/dist/{opfsPersistentStorage-amwSWm_p.js → opfsPersistentStorage-CwmY3O1r.js} +1 -1
- package/dist/{types-DUtkSBT8.d.ts → types-Bp7_Ra7_.d.ts} +472 -32
- package/docs/hooks.md +45 -7
- package/docs/list-query-store.md +1 -0
- package/docs/offline.md +326 -4
- package/docs/partial-resources.md +2 -0
- package/docs/persistent-storage.md +15 -0
- package/docs/store-manager.md +16 -1
- package/package.json +1 -1
|
@@ -140,6 +140,27 @@ type TSFDListQuery<QueryPayload extends ValidPayload> = {
|
|
|
140
140
|
refetchOnMount: false | FetchType; /** Ordered item keys included in the cached query page. */
|
|
141
141
|
items: string[];
|
|
142
142
|
};
|
|
143
|
+
/**
|
|
144
|
+
* Query placement of an item added to a list-query store.
|
|
145
|
+
*
|
|
146
|
+
* Used by the `addItemToQueries` option of `addItemToState(...)` and by the
|
|
147
|
+
* `addToQueries` option of offline temp entities.
|
|
148
|
+
*/
|
|
149
|
+
type ListQueryAddItemToQueries<QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = {
|
|
150
|
+
/**
|
|
151
|
+
* Queries that receive the item: one query payload, a list of payloads, or
|
|
152
|
+
* a filter over the queries currently in the store. Queries that are not in
|
|
153
|
+
* the store are skipped (offline temp entities first load the ones that are
|
|
154
|
+
* only in persistent storage).
|
|
155
|
+
*/
|
|
156
|
+
queries: QueryPayload[] | ((params: QueryPayload, data: TSFDListQuery<QueryPayload>, queryKey: string) => boolean) | QueryPayload;
|
|
157
|
+
/**
|
|
158
|
+
* Where the item is inserted in each query: `'start'`, `'end'`, or a
|
|
159
|
+
* function that receives the payloads of the items currently in the query
|
|
160
|
+
* and returns the insertion index.
|
|
161
|
+
*/
|
|
162
|
+
appendTo: 'start' | 'end' | ((itemsPayload: ItemPayload[]) => number);
|
|
163
|
+
};
|
|
143
164
|
/** Raw cached state for one item query in a list-query store. */
|
|
144
165
|
type TSDFItemQuery<ItemPayload extends ValidPayload> = {
|
|
145
166
|
/** Last item fetch error, if any. */error: StoreError | null; /** Current fetch lifecycle status for this item. */
|
|
@@ -371,7 +392,8 @@ type DerivedQueriesConfig<ItemState extends ValidStoreState, QueryPayload extend
|
|
|
371
392
|
getItemGroup: (item: ItemState, itemPayload: ItemPayload) => string;
|
|
372
393
|
/**
|
|
373
394
|
* Returns whether the local data for the query group is complete enough to
|
|
374
|
-
* derive from while online.
|
|
395
|
+
* derive from while online. `context.queries` lists the group's queries in
|
|
396
|
+
* state that have loaded at least once.
|
|
375
397
|
*/
|
|
376
398
|
isComplete: (queryPayload: QueryPayload, context: {
|
|
377
399
|
queries: DerivedQuerySummary<QueryPayload>[];
|
|
@@ -449,6 +471,47 @@ type ReplaceOfflineUploadArgs = {
|
|
|
449
471
|
*/
|
|
450
472
|
metadata?: ValidPayload;
|
|
451
473
|
};
|
|
474
|
+
/**
|
|
475
|
+
* File of a staged upload, as returned by
|
|
476
|
+
* `storeManager.useOfflineUploadFile(id)`.
|
|
477
|
+
*
|
|
478
|
+
* `url` is an object URL managed by TSDF: it is created once per staged file
|
|
479
|
+
* while at least one component uses the id, shared by every component using
|
|
480
|
+
* that id, and revoked shortly after the last one stops using it or as soon
|
|
481
|
+
* as the upload is replaced, deleted or leaves the session. Render it directly
|
|
482
|
+
* (e.g. `<img src={url}>`), never revoke it, and do not keep it outside of
|
|
483
|
+
* render: always use the latest value returned by the hook.
|
|
484
|
+
*
|
|
485
|
+
* Narrow on `status`:
|
|
486
|
+
*
|
|
487
|
+
* - `idle`: the hook was called with a falsy id.
|
|
488
|
+
* - `loading`: the staged file is being read. Files the session already holds
|
|
489
|
+
* skip this state and are returned on the first render.
|
|
490
|
+
* - `success`: the file is staged; `url` and `file` are available.
|
|
491
|
+
* - `missing`: no upload with this id is staged in the active session (never
|
|
492
|
+
* staged, deleted, expired, or already consumed by its mutation).
|
|
493
|
+
* - `error`: reading the staged file from the upload adapter failed.
|
|
494
|
+
*/
|
|
495
|
+
type OfflineUploadFile = {
|
|
496
|
+
/** Current read status of the staged file. */status: 'idle' | 'loading' | 'missing'; /** Managed object URL of the staged file, only set on `success`. */
|
|
497
|
+
url: null; /** Staged file, only set on `success`. */
|
|
498
|
+
file: null; /** Read failure, only set on `error`. */
|
|
499
|
+
error: null;
|
|
500
|
+
} | {
|
|
501
|
+
/** The file is staged and ready to render. */status: 'success'; /** Managed object URL of the staged file. Do not revoke it. */
|
|
502
|
+
url: string;
|
|
503
|
+
/**
|
|
504
|
+
* Staged file, for reading its contents. Use `url` to render it instead
|
|
505
|
+
* of creating another object URL from this file.
|
|
506
|
+
*/
|
|
507
|
+
file: File; /** Read failure, only set on `error`. */
|
|
508
|
+
error: null;
|
|
509
|
+
} | {
|
|
510
|
+
/** Reading the staged file from the upload adapter failed. */status: 'error'; /** Managed object URL of the staged file, only set on `success`. */
|
|
511
|
+
url: null; /** Staged file, only set on `success`. */
|
|
512
|
+
file: null; /** Failure reported by the upload adapter. */
|
|
513
|
+
error: Error;
|
|
514
|
+
};
|
|
452
515
|
/** Public metadata for a file staged for offline mutation replay. */
|
|
453
516
|
type OfflineUpload<TResolvedRef extends ValidPayload = ValidPayload> = {
|
|
454
517
|
/** Stable upload id used by offline operation inputs. */id: string; /** Session key that owns this upload. */
|
|
@@ -459,7 +522,11 @@ type OfflineUpload<TResolvedRef extends ValidPayload = ValidPayload> = {
|
|
|
459
522
|
mimeType: string; /** File size in bytes. */
|
|
460
523
|
sizeBytes: number; /** Epoch timestamp when the upload was staged. */
|
|
461
524
|
createdAt: number; /** Epoch timestamp for the latest upload metadata change. */
|
|
462
|
-
updatedAt: number;
|
|
525
|
+
updatedAt: number;
|
|
526
|
+
/**
|
|
527
|
+
* Final server-side reference after upload completes, as returned by the
|
|
528
|
+
* session `upload` transport.
|
|
529
|
+
*/
|
|
463
530
|
resolvedRef?: TResolvedRef; /** Latest upload progress snapshot. */
|
|
464
531
|
progress?: OfflineUploadProgress;
|
|
465
532
|
/**
|
|
@@ -514,12 +581,33 @@ type OfflineUploadTransportContext = {
|
|
|
514
581
|
metadata?: ValidPayload; /** Reports upload progress back to TSDF. */
|
|
515
582
|
onProgress: (progress: OfflineUploadProgress) => void;
|
|
516
583
|
};
|
|
584
|
+
/**
|
|
585
|
+
* Schema accepted by `offlineSession.uploads.resolvedRefSchema`.
|
|
586
|
+
*
|
|
587
|
+
* Takes the same schemas as an operation `inputSchema`: a `runcheck` type or a
|
|
588
|
+
* Standard Schema v1 (zod, valibot, ...). It is typed only by what the schema
|
|
589
|
+
* outputs, which keeps a store manager with a typed upload ref assignable to
|
|
590
|
+
* the default `StoreManager`.
|
|
591
|
+
*/
|
|
592
|
+
type OfflineUploadRefSchema<TResolvedRef extends ValidPayload = ValidPayload> = StandardSchemaLike<TResolvedRef> | {
|
|
593
|
+
/** `runcheck` schemas are matched through their `parse` method. */parse: (input: unknown) => {
|
|
594
|
+
ok: true;
|
|
595
|
+
value: TResolvedRef;
|
|
596
|
+
} | {
|
|
597
|
+
ok: false;
|
|
598
|
+
errors: string[];
|
|
599
|
+
};
|
|
600
|
+
};
|
|
517
601
|
/** Upload handling config for an offline session. */
|
|
518
602
|
type OfflineSessionUploadsConfig<TResolvedRef extends ValidPayload = ValidPayload> = {
|
|
519
603
|
/** Adapter used to persist staged files until replay can upload them. */adapter: OfflineUploadAdapter;
|
|
520
604
|
/**
|
|
521
605
|
* Upload transport that returns the final server-side file reference.
|
|
522
606
|
*
|
|
607
|
+
* Its return type is the upload ref type of the whole session:
|
|
608
|
+
* `createStoreManager` infers it, so `resolveOfflineUpload(s)` and the
|
|
609
|
+
* `OfflineUpload` entries of that manager are typed with it.
|
|
610
|
+
*
|
|
523
611
|
* Reject (throw) to report a failure. When the upload runs as a dependency
|
|
524
612
|
* of a replayed operation, the thrown error goes through the session's
|
|
525
613
|
* `classifyFailure` / `classifyRetryableFailure` hooks with `ctx.uploadId`
|
|
@@ -529,7 +617,22 @@ type OfflineSessionUploadsConfig<TResolvedRef extends ValidPayload = ValidPayloa
|
|
|
529
617
|
* operation goes to manual resolution. Throw errors those hooks can tell
|
|
530
618
|
* apart.
|
|
531
619
|
*/
|
|
532
|
-
upload: (ctx: OfflineUploadTransportContext) => Promise<TResolvedRef>;
|
|
620
|
+
upload: (ctx: OfflineUploadTransportContext) => Promise<TResolvedRef>;
|
|
621
|
+
/**
|
|
622
|
+
* Schema for the ref returned by `upload`.
|
|
623
|
+
*
|
|
624
|
+
* Refs returned by `upload` are trusted, but a ref can also come back from
|
|
625
|
+
* the upload adapter after a reload or from another browser tab, possibly
|
|
626
|
+
* written by a different app version. When this schema is set, those refs
|
|
627
|
+
* are parsed once when they enter the session. A ref that fails is dropped
|
|
628
|
+
* and its upload goes back to `pending`, so the still-staged file is uploaded
|
|
629
|
+
* again the next time the ref is needed instead of a malformed ref reaching
|
|
630
|
+
* `execute`, `resolveOfflineUpload(s)`, or the upload status APIs.
|
|
631
|
+
*
|
|
632
|
+
* Without a schema, restored refs are exposed as they were stored. Async
|
|
633
|
+
* Standard Schemas are not supported: every restored ref fails them.
|
|
634
|
+
*/
|
|
635
|
+
resolvedRefSchema?: OfflineUploadRefSchema<TResolvedRef>; /** Maximum number of concurrent upload transports. */
|
|
533
636
|
concurrency?: number;
|
|
534
637
|
};
|
|
535
638
|
/** Files attached to an offline-capable mutation call, keyed by upload id. */
|
|
@@ -537,7 +640,12 @@ type OfflineMutationUploadsInput = Record<string, Blob | File>;
|
|
|
537
640
|
type OfflineAttachedUploadIds = Record<string, string>;
|
|
538
641
|
/** Resolved upload files and references available while an offline operation replays. */
|
|
539
642
|
type OfflineOperationUploadsContext<TResolvedRef extends ValidPayload = ValidPayload> = {
|
|
540
|
-
/** Locally staged files by upload id. */filesById: Record<string, File>;
|
|
643
|
+
/** Locally staged files by upload id. */filesById: Record<string, File>;
|
|
644
|
+
/**
|
|
645
|
+
* Final uploaded refs by upload id, for the ids returned by
|
|
646
|
+
* `dependsOnUploads`. Typed with the upload ref type of the operation
|
|
647
|
+
* definition.
|
|
648
|
+
*/
|
|
541
649
|
resolvedRefsById: Record<string, TResolvedRef>;
|
|
542
650
|
};
|
|
543
651
|
//#endregion
|
|
@@ -551,6 +659,15 @@ type OfflineStoreType = 'document' | 'collection' | 'listQuery';
|
|
|
551
659
|
type OfflineFailurePhase = 'fetch' | 'mutation' | 'sync';
|
|
552
660
|
/** High-level classification used by outage detection. */
|
|
553
661
|
type OfflineFailureClassification = 'outage' | 'network' | 'ignore';
|
|
662
|
+
/**
|
|
663
|
+
* Answer of `offlineSession.healthCheck.check`:
|
|
664
|
+
*
|
|
665
|
+
* - `'up'` - the backend answered and is healthy. A request that failed
|
|
666
|
+
* anyway failed for a reason of its own
|
|
667
|
+
* - `'outage'` - the backend was reached but is down
|
|
668
|
+
* - `'unreachable'` - the backend could not be reached from this device
|
|
669
|
+
*/
|
|
670
|
+
type OfflineHealthCheckResult = 'up' | 'outage' | 'unreachable';
|
|
554
671
|
/** Kinds of entities participating in offline conflict/sync tracking. */
|
|
555
672
|
type OfflineEntityKind = 'document' | 'item' | 'query';
|
|
556
673
|
/** Lifecycle declared per offline operation definition. */
|
|
@@ -669,19 +786,87 @@ type OfflineNetworkModeConfig = {
|
|
|
669
786
|
/**
|
|
670
787
|
* Probe whether classified network recovery has completed.
|
|
671
788
|
* Return `true` when the session should leave network offline mode.
|
|
789
|
+
*
|
|
790
|
+
* When omitted, `healthCheck` is used if the session has one. Without
|
|
791
|
+
* either, a classified network failure only lasts until the next fetch or
|
|
792
|
+
* mutation re-reads the browser connectivity.
|
|
672
793
|
*/
|
|
673
794
|
recoveryCheck?: (ctx: {
|
|
674
795
|
sessionKey: string;
|
|
675
796
|
}) => Promise<boolean> | boolean; /** Optional probe config to tune classified network recovery behavior. */
|
|
676
797
|
recoveryProbe?: OfflineRecoveryProbeConfig;
|
|
677
798
|
};
|
|
799
|
+
type OfflineOutageModeBaseConfig = {
|
|
800
|
+
/** Enable outage mode logic and confirmation retry flow. */enabled: boolean; /** Optional probe config to tune recovery behavior. */
|
|
801
|
+
recoveryProbe?: OfflineRecoveryProbeConfig;
|
|
802
|
+
};
|
|
678
803
|
/** Server outage detection and recovery configuration. */
|
|
679
|
-
type OfflineOutageModeConfig = {
|
|
680
|
-
/**
|
|
681
|
-
recoveryCheck: (ctx: {
|
|
804
|
+
type OfflineOutageModeConfig = OfflineOutageModeBaseConfig & {
|
|
805
|
+
/** Probe the remote service to confirm outage recovery. */recoveryCheck: (ctx: {
|
|
682
806
|
sessionKey: string;
|
|
683
|
-
}) => Promise<boolean> | boolean;
|
|
684
|
-
|
|
807
|
+
}) => Promise<boolean> | boolean;
|
|
808
|
+
};
|
|
809
|
+
/**
|
|
810
|
+
* Server outage detection and recovery configuration of a session with a
|
|
811
|
+
* `healthCheck`, which is the default outage recovery check.
|
|
812
|
+
*/
|
|
813
|
+
type OfflineHealthCheckedOutageModeConfig = OfflineOutageModeBaseConfig & {
|
|
814
|
+
/**
|
|
815
|
+
* Optional outage-specific recovery probe. When provided it is used
|
|
816
|
+
* instead of `healthCheck` to confirm outage recovery.
|
|
817
|
+
*/
|
|
818
|
+
recoveryCheck?: (ctx: {
|
|
819
|
+
sessionKey: string;
|
|
820
|
+
}) => Promise<boolean> | boolean;
|
|
821
|
+
};
|
|
822
|
+
/** Context passed to `offlineSession.healthCheck.check`. */
|
|
823
|
+
type OfflineHealthCheckContext = {
|
|
824
|
+
/** Session key the check is running for. */sessionKey: string;
|
|
825
|
+
/**
|
|
826
|
+
* Aborted when the session stops waiting for this check (`timeoutMs`
|
|
827
|
+
* elapsed). Pass it to the health request so it is cancelled too.
|
|
828
|
+
*/
|
|
829
|
+
signal: AbortSignal;
|
|
830
|
+
};
|
|
831
|
+
/**
|
|
832
|
+
* Single health check used by the offline session for both failure
|
|
833
|
+
* classification and recovery checks.
|
|
834
|
+
*/
|
|
835
|
+
type OfflineHealthCheckConfig = {
|
|
836
|
+
/**
|
|
837
|
+
* Asks the backend how it is doing, usually by calling a health endpoint:
|
|
838
|
+
*
|
|
839
|
+
* - `'up'` - the backend answered and is healthy
|
|
840
|
+
* - `'outage'` - the backend was reached but is down
|
|
841
|
+
* - `'unreachable'` - the backend could not be reached from this device
|
|
842
|
+
*
|
|
843
|
+
* `'up'` for a failed request means the failure is specific to that
|
|
844
|
+
* request, even when the endpoint it called is down (for example an upload
|
|
845
|
+
* endpoint answering 503 while the API health check passes). The session
|
|
846
|
+
* stays online and the request's own failure handling applies: a fetch or
|
|
847
|
+
* direct mutation fails with its error, and a replayed mutation goes
|
|
848
|
+
* through `classifyRetryableFailure` and the `replayRetry` budget, ending
|
|
849
|
+
* in a `retry-exhausted` resolution. To pause the session for such a
|
|
850
|
+
* service instead, make this check cover it or return `'outage'` for its
|
|
851
|
+
* failures from `classifyFailure`.
|
|
852
|
+
*
|
|
853
|
+
* Calls are deduplicated: while a check is in flight every failure and
|
|
854
|
+
* recovery tick that needs an answer waits for that same call, so a burst of
|
|
855
|
+
* failing requests costs a single health request. A finished answer is never
|
|
856
|
+
* reused: the next failure or recovery tick starts a new check.
|
|
857
|
+
*
|
|
858
|
+
* A check that throws, rejects or takes longer than `timeoutMs` gives no
|
|
859
|
+
* answer and changes nothing: a failure being classified is treated as
|
|
860
|
+
* specific to its request, and a recovery check as "not recovered yet".
|
|
861
|
+
*/
|
|
862
|
+
check: (ctx: OfflineHealthCheckContext) => Promise<OfflineHealthCheckResult> | OfflineHealthCheckResult;
|
|
863
|
+
/**
|
|
864
|
+
* How long the session waits for `check`, in milliseconds, before giving up
|
|
865
|
+
* on it and aborting `ctx.signal`. Must be a finite number below
|
|
866
|
+
* `2_147_483_647` (the `setTimeout` limit); there is no "no timeout" value.
|
|
867
|
+
* @default 10_000
|
|
868
|
+
*/
|
|
869
|
+
timeoutMs?: number;
|
|
685
870
|
};
|
|
686
871
|
/** Fixed replay retry policy for healthy online replay failures. Omitted fields use built-in defaults. */
|
|
687
872
|
type OfflineReplayRetryConfig = {
|
|
@@ -696,8 +881,31 @@ type OfflineReplayRetryConfig = {
|
|
|
696
881
|
*/
|
|
697
882
|
intervalMs?: number;
|
|
698
883
|
};
|
|
699
|
-
|
|
700
|
-
|
|
884
|
+
type OfflineSessionBaseConfig<TUploadRef extends ValidPayload = ValidPayload> = {
|
|
885
|
+
/**
|
|
886
|
+
* Gate for the whole offline session, e.g. a feature flag or a
|
|
887
|
+
* per-workspace setting. While it returns `false` the session behaves as if
|
|
888
|
+
* no offline session existed: it never enters offline mode (network
|
|
889
|
+
* detection and `classifyFailure` are skipped), fetches always go to the
|
|
890
|
+
* network and mutations with an `offline` descriptor run as plain online
|
|
891
|
+
* mutations instead of being queued.
|
|
892
|
+
*
|
|
893
|
+
* Mutations already queued when the gate closes are kept in persistent
|
|
894
|
+
* storage untouched (and stay visible through the offline entities /
|
|
895
|
+
* resolutions) and are replayed after the gate reopens while online.
|
|
896
|
+
*
|
|
897
|
+
* It is read before every fetch and every mutation with an `offline`
|
|
898
|
+
* descriptor, on browser online/offline events, before each recovery
|
|
899
|
+
* check and before replaying queued mutations, so it must be synchronous
|
|
900
|
+
* and cheap. A flip is picked up by the next of those; call
|
|
901
|
+
* `storeManager.setOfflineRuntimeConfig({})` to apply it right away.
|
|
902
|
+
*
|
|
903
|
+
* The tabs of a session key share its offline status and replay, so it
|
|
904
|
+
* must return the same value in every tab of that session key (to gate
|
|
905
|
+
* per workspace, include the workspace in the session key).
|
|
906
|
+
* @default () => true
|
|
907
|
+
*/
|
|
908
|
+
enabled?: () => boolean;
|
|
701
909
|
/**
|
|
702
910
|
* Classify a remote failure as `outage`, `network`, or `ignore`.
|
|
703
911
|
* `outage` activates outage recovery behavior.
|
|
@@ -705,14 +913,23 @@ type OfflineSessionConfig<TUploadRef extends ValidPayload = ValidPayload> = {
|
|
|
705
913
|
* when `network.enabled` is true. Existing offline recovery may keep using
|
|
706
914
|
* classifications until already-active work finishes recovering.
|
|
707
915
|
*
|
|
916
|
+
* Return `'unknown'` when the error alone does not tell: the session then
|
|
917
|
+
* asks `healthCheck` (and ignores the failure when there is none). Any
|
|
918
|
+
* other answer is final, including `'ignore'`, and `healthCheck` is not
|
|
919
|
+
* called for that failure.
|
|
920
|
+
*
|
|
921
|
+
* Not called while no classification could change anything: the session
|
|
922
|
+
* gate is closed, or both modes are disabled and neither is still active.
|
|
923
|
+
*
|
|
708
924
|
* Failures of the `uploads.upload` transport during replay are classified
|
|
709
925
|
* here too, with `ctx.uploadId` set: `outage` / `network` keep the upload
|
|
710
926
|
* `pending` and the dependent operation queued until the session recovers.
|
|
711
927
|
*/
|
|
712
|
-
classifyFailure?: (error: unknown, ctx: OfflineFailureContext) => Promise<OfflineFailureClassification> | OfflineFailureClassification;
|
|
928
|
+
classifyFailure?: (error: unknown, ctx: OfflineFailureContext) => Promise<OfflineFailureClassification | 'unknown'> | OfflineFailureClassification | 'unknown';
|
|
713
929
|
/**
|
|
714
930
|
* Optional replay-only classifier for ambiguous sync failures that stayed
|
|
715
|
-
* online (`classifyFailure(...) === 'ignore'`
|
|
931
|
+
* online (`classifyFailure(...) === 'ignore'`, or `healthCheck` answered
|
|
932
|
+
* `'up'`).
|
|
716
933
|
*
|
|
717
934
|
* Return `true` only when automatically re-sending the replayed mutation is
|
|
718
935
|
* known to be safe. Return `false` to avoid auto-replay retries; in that
|
|
@@ -726,8 +943,7 @@ type OfflineSessionConfig<TUploadRef extends ValidPayload = ValidPayload> = {
|
|
|
726
943
|
* which moves the operation to manual resolution right away.
|
|
727
944
|
*/
|
|
728
945
|
classifyRetryableFailure?: (error: unknown, ctx: OfflineFailureContext) => Promise<boolean> | boolean; /** Network detection strategy and browser integration. */
|
|
729
|
-
network?: OfflineNetworkModeConfig; /**
|
|
730
|
-
outage?: OfflineOutageModeConfig; /** Fixed retry policy for healthy online replay failures. */
|
|
946
|
+
network?: OfflineNetworkModeConfig; /** Fixed retry policy for healthy online replay failures. */
|
|
731
947
|
replayRetry?: OfflineReplayRetryConfig;
|
|
732
948
|
/**
|
|
733
949
|
* Root policy controlling whether offline-enabled mutations may enter the
|
|
@@ -737,6 +953,39 @@ type OfflineSessionConfig<TUploadRef extends ValidPayload = ValidPayload> = {
|
|
|
737
953
|
mutationQueueing?: OfflineMutationQueueingConfig; /** Optional upload transport/storage config shared by the whole session. */
|
|
738
954
|
uploads?: OfflineSessionUploadsConfig<TUploadRef>;
|
|
739
955
|
};
|
|
956
|
+
/** Shared offline/session policy reused by every store in the same session. */
|
|
957
|
+
type OfflineSessionConfig<TUploadRef extends ValidPayload = ValidPayload> = OfflineSessionBaseConfig<TUploadRef> & ({
|
|
958
|
+
healthCheck?: undefined; /** Outage detection and recovery strategy for remote failures. */
|
|
959
|
+
outage?: OfflineOutageModeConfig;
|
|
960
|
+
} | {
|
|
961
|
+
/**
|
|
962
|
+
* Single health check answering both "this request failed: is it the
|
|
963
|
+
* network, an outage, or just this request?" and "are we back?".
|
|
964
|
+
*
|
|
965
|
+
* - Failure classification: a failed fetch, mutation or queued
|
|
966
|
+
* mutation replay that `classifyFailure` did not settle (it is not
|
|
967
|
+
* configured, or returned `'unknown'`) runs the check, unless the
|
|
968
|
+
* session is already in offline mode. `'unreachable'` activates
|
|
969
|
+
* network mode, `'outage'` activates outage mode (each only when
|
|
970
|
+
* that mode is enabled) and `'up'` leaves the failure to its
|
|
971
|
+
* request: the session stays online and the request's own failure
|
|
972
|
+
* handling applies.
|
|
973
|
+
* - Recovery: while a mode is active because of a failure, its
|
|
974
|
+
* recovery probe runs the check on the mode's `recoveryProbe`
|
|
975
|
+
* cadence, unless the mode has its own `recoveryCheck`. `'up'` ends
|
|
976
|
+
* the offline mode, `'outage'` and `'unreachable'` keep it or
|
|
977
|
+
* switch to the matching mode.
|
|
978
|
+
*
|
|
979
|
+
* Never called on the success path, while the session gate is closed,
|
|
980
|
+
* or while both modes are disabled and neither is still active.
|
|
981
|
+
*/
|
|
982
|
+
healthCheck: OfflineHealthCheckConfig;
|
|
983
|
+
/**
|
|
984
|
+
* Outage detection and recovery strategy for remote failures.
|
|
985
|
+
* `recoveryCheck` is optional here: `healthCheck` is the default.
|
|
986
|
+
*/
|
|
987
|
+
outage?: OfflineHealthCheckedOutageModeConfig;
|
|
988
|
+
});
|
|
740
989
|
/** Per-session offline status snapshot shared across tabs. */
|
|
741
990
|
type GlobalOfflineStatus = {
|
|
742
991
|
/** Session key for this status bucket. */sessionKey: string;
|
|
@@ -801,6 +1050,24 @@ type ItemOfflineState = {
|
|
|
801
1050
|
* payload reports any mutation still queued with `isUnsentCreation: false`.
|
|
802
1051
|
*/
|
|
803
1052
|
isUnsentCreation: boolean;
|
|
1053
|
+
/**
|
|
1054
|
+
* Whether the creation of an unsent creation left the "never sent" state:
|
|
1055
|
+
* it is being sent, failed with an unknown outcome, or waits for a manual
|
|
1056
|
+
* resolution, so the server may have the item. A creation only held behind
|
|
1057
|
+
* the creation of another entity that waits for a resolution was never
|
|
1058
|
+
* sent, so it stays `false`. While `isUnsentCreation` is
|
|
1059
|
+
* `true` and this is `false`, the item only exists locally: deleting it
|
|
1060
|
+
* with an operation that cancels pending creations (see
|
|
1061
|
+
* {@link OfflineSupersedeConfig.dropSelfIfTempLifecycleCancelled}) sends
|
|
1062
|
+
* nothing, unless one operation created it together with other entities
|
|
1063
|
+
* (see that option). A creation queued after its direct online request
|
|
1064
|
+
* failed, or sent again with `requeue` after a conflict, also reports
|
|
1065
|
+
* `false`: an earlier request may have created a server item, but the
|
|
1066
|
+
* temporary payload can't target it, so the delete still only discards
|
|
1067
|
+
* local work and that server item is left as is. Always `false` for items
|
|
1068
|
+
* that are not unsent creations.
|
|
1069
|
+
*/
|
|
1070
|
+
creationAttempted: boolean;
|
|
804
1071
|
};
|
|
805
1072
|
/** Aggregated offline status for a tracked document/item/query entity. */
|
|
806
1073
|
type GlobalOfflineEntity = {
|
|
@@ -953,7 +1220,8 @@ type OfflineSession<TUploadRef extends ValidPayload = ValidPayload> = {
|
|
|
953
1220
|
useOfflineStatus: () => GlobalOfflineStatus; /** React hook subscribing to the session's aggregated offline entities. */
|
|
954
1221
|
useOfflineEntities: () => readonly GlobalOfflineEntity[]; /** React hook subscribing to the session's aggregated conflict/retry resolutions. */
|
|
955
1222
|
useOfflineResolutions: () => readonly OfflineResolutionRecord[]; /** React hook subscribing to the session's upload list. */
|
|
956
|
-
useOfflineUploads: () => readonly OfflineUpload<TUploadRef>[];
|
|
1223
|
+
useOfflineUploads: () => readonly OfflineUpload<TUploadRef>[]; /** React hook reading the file of a staged upload while it is staged. */
|
|
1224
|
+
useOfflineUploadFile: (id: string | false | null | undefined) => OfflineUploadFile;
|
|
957
1225
|
};
|
|
958
1226
|
/**
|
|
959
1227
|
* Persisted offline mutation queue entry.
|
|
@@ -994,6 +1262,10 @@ type OfflineRetryExhaustedResolutionAction = {
|
|
|
994
1262
|
/**
|
|
995
1263
|
* Controls whether retrying a resolution should also requeue retryable
|
|
996
1264
|
* descendants from the same temp-lifecycle dependency chain.
|
|
1265
|
+
*
|
|
1266
|
+
* With `'self'`, the descendants stay as resolutions to decide one by
|
|
1267
|
+
* one: they no longer count as work held behind the creation, so later
|
|
1268
|
+
* mutations of their entities don't merge into or cancel them.
|
|
997
1269
|
* @default 'self-and-descendants'
|
|
998
1270
|
*/
|
|
999
1271
|
scope?: 'self' | 'self-and-descendants';
|
|
@@ -1095,6 +1367,10 @@ type OfflineAccumulationConfig<TInput> = {
|
|
|
1095
1367
|
* `same-entity` only applies to operations that resolve exactly one entity ref.
|
|
1096
1368
|
* When enabled, the new operation may remove earlier unattempted pending entries
|
|
1097
1369
|
* targeting that same single entity before the new entry is persisted.
|
|
1370
|
+
*
|
|
1371
|
+
* Entries that were already sent (being sent, or failed with an unknown
|
|
1372
|
+
* outcome) are never pruned, because the server may have applied them: the
|
|
1373
|
+
* new operation is queued behind them instead.
|
|
1098
1374
|
*/
|
|
1099
1375
|
type OfflineSupersedeConfig = {
|
|
1100
1376
|
/** Drop earlier unattempted pending entries for the same single entity. */scope: 'same-entity';
|
|
@@ -1107,11 +1383,53 @@ type OfflineSupersedeConfig = {
|
|
|
1107
1383
|
*/
|
|
1108
1384
|
operations?: 'self' | readonly string[];
|
|
1109
1385
|
/**
|
|
1110
|
-
*
|
|
1111
|
-
* operation
|
|
1386
|
+
* Cancels the offline creation of the entity instead of queueing this
|
|
1387
|
+
* operation. Meant for delete operations: deleting something that was
|
|
1388
|
+
* created offline and never sent should not send anything.
|
|
1389
|
+
*
|
|
1390
|
+
* When the pruned entries include the creation of the entity, never sent
|
|
1391
|
+
* (a `tempEntity` / `tempEntities` operation, or a `create` of an item
|
|
1392
|
+
* whose id the app generated on the client), its whole lifecycle is
|
|
1393
|
+
* cancelled and no request is made:
|
|
1394
|
+
*
|
|
1395
|
+
* - the creation, the queued operations targeting the entity and this
|
|
1396
|
+
* operation itself are dropped
|
|
1397
|
+
* - queued operations that depend on the entity are dropped too, with
|
|
1398
|
+
* everything queued under them: the ones of this store that declare it in
|
|
1399
|
+
* `dependsOn`, and the ones of other stores that declare it in
|
|
1400
|
+
* `cancelledWith`
|
|
1401
|
+
* - the temp entities and the client-id items of the dropped creations are
|
|
1402
|
+
* removed from the store
|
|
1403
|
+
*
|
|
1404
|
+
* A creation held behind the creation of another entity that waits for a
|
|
1405
|
+
* manual resolution was never sent either, and is cancelled the same way.
|
|
1406
|
+
*
|
|
1407
|
+
* A creation that was already sent is not cancelled, since the server may
|
|
1408
|
+
* have the entity (this includes a `create` of a client-generated id queued
|
|
1409
|
+
* after its direct online request failed, or sent again with `requeue`
|
|
1410
|
+
* after a conflict): this operation is queued behind it and replays with
|
|
1411
|
+
* the final entity ref once the creation is confirmed. Its `execute` should
|
|
1412
|
+
* treat a not-found answer as success (catch the error and return). The
|
|
1413
|
+
* same applies to a `tempEntities` creation of several entities, which is
|
|
1414
|
+
* never cancelled: the other entities still need it.
|
|
1112
1415
|
*/
|
|
1113
1416
|
dropSelfIfTempLifecycleCancelled?: boolean;
|
|
1114
1417
|
};
|
|
1418
|
+
/**
|
|
1419
|
+
* Reference to an entity of another store, returned by the `cancelledWith`
|
|
1420
|
+
* hook of collection and list-query offline operations.
|
|
1421
|
+
*
|
|
1422
|
+
* @typeParam TEntityRef - Payload identifying the entity in its own store.
|
|
1423
|
+
*/
|
|
1424
|
+
type OfflineExternalEntityRef<TEntityRef extends ValidPayload = ValidPayload> = {
|
|
1425
|
+
/** `id` of the store that owns the entity. */storeName: string;
|
|
1426
|
+
/**
|
|
1427
|
+
* Payload of the entity in that store. For an entity created offline this
|
|
1428
|
+
* is the temporary payload, or the client-generated one, its create
|
|
1429
|
+
* operation returns in `getEntityRefs`.
|
|
1430
|
+
*/
|
|
1431
|
+
entityRef: TEntityRef;
|
|
1432
|
+
};
|
|
1115
1433
|
/** Shared context passed to offline replay lifecycle hooks. */
|
|
1116
1434
|
type OperationBaseContext<TInput> = {
|
|
1117
1435
|
/** Input payload for the queued mutation currently being processed. */input: TInput; /** Timestamp when the operation was originally enqueued. */
|
|
@@ -1210,15 +1528,35 @@ type OfflineTempEntityReconciliation<TFinalPayload extends ValidPayload = ValidP
|
|
|
1210
1528
|
type OfflineTempEntitiesReconciliation<TTempId extends ValidPayload = ValidPayload, TFinalPayload extends ValidPayload = ValidPayload, TFinalData = unknown> = OfflineTempEntityReconciliation<TFinalPayload, TFinalData> & {
|
|
1211
1529
|
/** Temporary payload that should be reconciled. */tempId: TTempId;
|
|
1212
1530
|
};
|
|
1531
|
+
/**
|
|
1532
|
+
* Resolves to `T` for list-query stores and to `never` for stores without
|
|
1533
|
+
* queries, where `TQueryPayload` is left as `never`.
|
|
1534
|
+
*/
|
|
1535
|
+
type ListQueryOnly<TQueryPayload extends ValidPayload, T> = [TQueryPayload] extends [never] ? never : T;
|
|
1213
1536
|
/**
|
|
1214
1537
|
* Pending temp-entity returned by `tempEntities.buildPendingEntities(...)`.
|
|
1215
1538
|
*
|
|
1216
1539
|
* @typeParam TTempId - Temporary payload used to track the optimistic entity.
|
|
1217
1540
|
* @typeParam TPendingEntity - Pending entity snapshot to insert locally.
|
|
1541
|
+
* @typeParam TQueryPayload - Query payload of the owning list-query store. Left as `never` for stores without queries.
|
|
1218
1542
|
*/
|
|
1219
|
-
type OfflineTempEntityPendingEntry<TTempId extends ValidPayload = ValidPayload, TPendingEntity = unknown> = {
|
|
1543
|
+
type OfflineTempEntityPendingEntry<TTempId extends ValidPayload = ValidPayload, TPendingEntity = unknown, TQueryPayload extends ValidPayload = never> = {
|
|
1220
1544
|
/** Temporary payload that identifies the optimistic entity. */tempId: TTempId; /** Pending entity snapshot inserted while the mutation is queued. */
|
|
1221
1545
|
pendingEntity: TPendingEntity;
|
|
1546
|
+
/**
|
|
1547
|
+
* List-query stores only: queries that show this pending entity while the
|
|
1548
|
+
* mutation is queued, and where it is inserted in them.
|
|
1549
|
+
*
|
|
1550
|
+
* Same behavior as `tempEntity.addToQueries`.
|
|
1551
|
+
*/
|
|
1552
|
+
addToQueries?: ListQueryOnly<TQueryPayload, ListQueryAddItemToQueries<TQueryPayload, TTempId>>;
|
|
1553
|
+
/**
|
|
1554
|
+
* List-query stores with partial resources only: fields this pending entity
|
|
1555
|
+
* already holds, or `'*'` when it is complete.
|
|
1556
|
+
*
|
|
1557
|
+
* Same behavior as `tempEntity.loadedFields`.
|
|
1558
|
+
*/
|
|
1559
|
+
loadedFields?: ListQueryOnly<TQueryPayload, ItemLoadedFields>;
|
|
1222
1560
|
};
|
|
1223
1561
|
/**
|
|
1224
1562
|
* Optional temp-id lifecycle for optimistic offline create flows.
|
|
@@ -1226,8 +1564,9 @@ type OfflineTempEntityPendingEntry<TTempId extends ValidPayload = ValidPayload,
|
|
|
1226
1564
|
* @typeParam TInput - Input type used to derive the temporary entity and identifier.
|
|
1227
1565
|
* @typeParam TTempResult - Result returned by `execute`, used only by `tempEntity.reconcileServerEntity(...)`.
|
|
1228
1566
|
* @typeParam TTempId - Temporary payload used to track optimistic entities before reconciliation.
|
|
1567
|
+
* @typeParam TQueryPayload - Query payload of the owning list-query store. Left as `never` for stores without queries.
|
|
1229
1568
|
*/
|
|
1230
|
-
type OfflineTempEntityConfig<TInput, TTempResult, TTempId extends ValidPayload = string, TPendingEntity = unknown, TFinalPayload extends ValidPayload = ValidPayload, TFinalData = unknown> = {
|
|
1569
|
+
type OfflineTempEntityConfig<TInput, TTempResult, TTempId extends ValidPayload = string, TPendingEntity = unknown, TFinalPayload extends ValidPayload = ValidPayload, TFinalData = unknown, TQueryPayload extends ValidPayload = never> = {
|
|
1231
1570
|
/**
|
|
1232
1571
|
* Builds the optimistic entity inserted into local state while the mutation
|
|
1233
1572
|
* is queued offline.
|
|
@@ -1236,6 +1575,44 @@ type OfflineTempEntityConfig<TInput, TTempResult, TTempId extends ValidPayload =
|
|
|
1236
1575
|
* until replay succeeds and the final server entity can replace it.
|
|
1237
1576
|
*/
|
|
1238
1577
|
buildPendingEntity: (input: TInput, tempId: TTempId) => TPendingEntity;
|
|
1578
|
+
/**
|
|
1579
|
+
* List-query stores only: queries that show the pending entity while the
|
|
1580
|
+
* mutation is queued, and where it is inserted in them. Same shape as the
|
|
1581
|
+
* `addItemToQueries` option of `addItemToState(...)`, or a function of the
|
|
1582
|
+
* mutation input that returns it (return `undefined` to add to no query).
|
|
1583
|
+
*
|
|
1584
|
+
* The entity is added when the mutation is queued, so the mutation does not
|
|
1585
|
+
* need to insert the temp row by hand in `optimisticUpdate`. It keeps its
|
|
1586
|
+
* position when it is reconciled to the final server entity, and leaves the
|
|
1587
|
+
* queries when the queued mutation is discarded. A mutation that runs
|
|
1588
|
+
* online right away is never queued, so it creates no pending entity.
|
|
1589
|
+
*
|
|
1590
|
+
* Queries that are only in persistent storage (after a restart, before a
|
|
1591
|
+
* screen reads them) are loaded first, so the entity also reaches them. A
|
|
1592
|
+
* filter only matches the queries the app session already knows, so
|
|
1593
|
+
* prefer query payloads. The function form also runs again when the
|
|
1594
|
+
* mutation is replayed, to load the queries the final entity is placed in;
|
|
1595
|
+
* it should only depend on its arguments.
|
|
1596
|
+
*
|
|
1597
|
+
* Without this option the pending entity is only added to the queries
|
|
1598
|
+
* matched by `optimisticListUpdates`.
|
|
1599
|
+
*/
|
|
1600
|
+
addToQueries?: ListQueryOnly<TQueryPayload, ListQueryAddItemToQueries<TQueryPayload, TTempId> | ((input: TInput, tempId: TTempId) => ListQueryAddItemToQueries<TQueryPayload, TTempId> | undefined)>;
|
|
1601
|
+
/**
|
|
1602
|
+
* List-query stores with partial resources only: fields the pending entity
|
|
1603
|
+
* already holds, or `'*'` when it is complete.
|
|
1604
|
+
*
|
|
1605
|
+
* The pending entity does not exist on the server yet, so its missing
|
|
1606
|
+
* fields cannot be fetched: declare `'*'` when hooks that read every field
|
|
1607
|
+
* (`fields: '*'`) should show it. The same loaded fields are kept when the
|
|
1608
|
+
* entity is reconciled to its final server payload, so a `finalData`
|
|
1609
|
+
* returned by `reconcileServerEntity` must hold at least these fields (omit
|
|
1610
|
+
* `finalData` to keep the pending entity's data).
|
|
1611
|
+
*
|
|
1612
|
+
* Without this option only `partialResources.inferFields` can vouch for the
|
|
1613
|
+
* fields of the pending entity.
|
|
1614
|
+
*/
|
|
1615
|
+
loadedFields?: ListQueryOnly<TQueryPayload, ItemLoadedFields>;
|
|
1239
1616
|
/**
|
|
1240
1617
|
* Reconciles the optimistic temp entity with the successful replay result.
|
|
1241
1618
|
*/
|
|
@@ -1247,16 +1624,23 @@ type OfflineTempEntityConfig<TInput, TTempResult, TTempId extends ValidPayload =
|
|
|
1247
1624
|
* @typeParam TInput - Input type used to derive the temporary entities and identifiers.
|
|
1248
1625
|
* @typeParam TTempResult - Result returned by `execute`, used only by `tempEntities.reconcileServerEntities(...)`.
|
|
1249
1626
|
* @typeParam TTempId - Temporary payload used to track optimistic entities before reconciliation.
|
|
1627
|
+
* @typeParam TQueryPayload - Query payload of the owning list-query store. Left as `never` for stores without queries.
|
|
1250
1628
|
*/
|
|
1251
|
-
type OfflineTempEntitiesConfig<TInput, TTempResult, TTempId extends ValidPayload = string, TPendingEntity = unknown, TFinalPayload extends ValidPayload = ValidPayload, TFinalData = unknown> = {
|
|
1629
|
+
type OfflineTempEntitiesConfig<TInput, TTempResult, TTempId extends ValidPayload = string, TPendingEntity = unknown, TFinalPayload extends ValidPayload = ValidPayload, TFinalData = unknown, TQueryPayload extends ValidPayload = never> = {
|
|
1252
1630
|
/**
|
|
1253
1631
|
* Builds the optimistic entities inserted into local state while the mutation
|
|
1254
1632
|
* is queued offline.
|
|
1255
1633
|
*
|
|
1256
1634
|
* `tempIds` are the temporary payloads derived from the operation entity refs
|
|
1257
1635
|
* and used until replay succeeds and the final server entities can replace them.
|
|
1636
|
+
*
|
|
1637
|
+
* In list-query stores each returned entry can also declare `addToQueries`
|
|
1638
|
+
* and `loadedFields`, with the same behavior as the `tempEntity` options.
|
|
1639
|
+
* This builder never runs again at replay, so a declared query that is only
|
|
1640
|
+
* in persistent storage when the mutation is replayed gets the final
|
|
1641
|
+
* entities on its next fetch.
|
|
1258
1642
|
*/
|
|
1259
|
-
buildPendingEntities: (input: TInput, tempIds: readonly TTempId[]) => readonly OfflineTempEntityPendingEntry<TTempId, TPendingEntity>[];
|
|
1643
|
+
buildPendingEntities: (input: TInput, tempIds: readonly TTempId[]) => readonly OfflineTempEntityPendingEntry<TTempId, TPendingEntity, TQueryPayload>[];
|
|
1260
1644
|
/**
|
|
1261
1645
|
* Reconciles the optimistic temp entities with the successful replay result.
|
|
1262
1646
|
*/
|
|
@@ -1266,12 +1650,12 @@ type NoTempEntityFields = {
|
|
|
1266
1650
|
tempEntity?: never;
|
|
1267
1651
|
tempEntities?: never;
|
|
1268
1652
|
};
|
|
1269
|
-
type ConfiguredTempEntityFields<TInput, TTempResult, TTempId extends ValidPayload, TPendingEntity = unknown, TFinalPayload extends ValidPayload = ValidPayload, TFinalData = unknown> = {
|
|
1270
|
-
tempEntity: OfflineTempEntityConfig<TInput, TTempResult, TTempId, TPendingEntity, TFinalPayload, TFinalData>;
|
|
1653
|
+
type ConfiguredTempEntityFields<TInput, TTempResult, TTempId extends ValidPayload, TPendingEntity = unknown, TFinalPayload extends ValidPayload = ValidPayload, TFinalData = unknown, TQueryPayload extends ValidPayload = never> = {
|
|
1654
|
+
tempEntity: OfflineTempEntityConfig<TInput, TTempResult, TTempId, TPendingEntity, TFinalPayload, TFinalData, TQueryPayload>;
|
|
1271
1655
|
tempEntities?: never;
|
|
1272
1656
|
} | {
|
|
1273
1657
|
tempEntity?: never;
|
|
1274
|
-
tempEntities: OfflineTempEntitiesConfig<TInput, TTempResult, TTempId, TPendingEntity, TFinalPayload, TFinalData>;
|
|
1658
|
+
tempEntities: OfflineTempEntitiesConfig<TInput, TTempResult, TTempId, TPendingEntity, TFinalPayload, TFinalData, TQueryPayload>;
|
|
1275
1659
|
};
|
|
1276
1660
|
/**
|
|
1277
1661
|
* Shape used by `persistentStorage.offline.operations` for each operation name.
|
|
@@ -1279,8 +1663,9 @@ type ConfiguredTempEntityFields<TInput, TTempResult, TTempId extends ValidPayloa
|
|
|
1279
1663
|
* @typeParam TInput - The persisted input payload for the queued offline operation.
|
|
1280
1664
|
* @typeParam TConflict - The conflict payload produced by pre-execution conflict detection.
|
|
1281
1665
|
* @typeParam TTempResult - Result returned by `execute`, used only when `tempEntity` or `tempEntities` needs to reconcile the final server entity. Defaults to `void`.
|
|
1666
|
+
* @typeParam TQueryPayload - Query payload of the owning list-query store, which enables the temp-entity query options. Left as `never` for stores without queries.
|
|
1282
1667
|
*/
|
|
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> = {
|
|
1668
|
+
type OfflineOperationDefinition<TInput, TConflict, TTempResult = void, TServerSnapshot = unknown, TTempId extends ValidPayload = string, TPendingEntity = unknown, TFinalPayload extends ValidPayload = ValidPayload, TFinalData = unknown, TUploadRef extends ValidPayload = ValidPayload, TQueryPayload extends ValidPayload = never> = {
|
|
1284
1669
|
/** Schema used to validate incoming operation input. */inputSchema: PersistentStorageSchema<TInput>;
|
|
1285
1670
|
/**
|
|
1286
1671
|
* Lifecycle classification for the queued operation. TSDF derives the
|
|
@@ -1332,7 +1717,7 @@ type OfflineOperationDefinition<TInput, TConflict, TTempResult = void, TServerSn
|
|
|
1332
1717
|
*/
|
|
1333
1718
|
onSuccessExecute?: undefined; /** Temp-entity operations cannot compact multiple queued creates. */
|
|
1334
1719
|
accumulation?: never;
|
|
1335
|
-
} & ConfiguredTempEntityFields<TInput, TTempResult, TTempId, TPendingEntity, TFinalPayload, TFinalData>));
|
|
1720
|
+
} & ConfiguredTempEntityFields<TInput, TTempResult, TTempId, TPendingEntity, TFinalPayload, TFinalData, TQueryPayload>));
|
|
1336
1721
|
type WithoutTempEntity<T extends {
|
|
1337
1722
|
tempEntity?: unknown;
|
|
1338
1723
|
tempEntities?: unknown;
|
|
@@ -1344,6 +1729,16 @@ type WithoutTempEntity<T extends {
|
|
|
1344
1729
|
type OperationEntityRefsContext<TInput> = {
|
|
1345
1730
|
/** Input payload for the queued mutation. */input: TInput;
|
|
1346
1731
|
};
|
|
1732
|
+
/**
|
|
1733
|
+
* Temp-entity list-query options as seen by the non-store-specific alias.
|
|
1734
|
+
*
|
|
1735
|
+
* Spelled out structurally: the store-specific configs disable these options
|
|
1736
|
+
* with a `never` query payload, which is not comparable with a widened one.
|
|
1737
|
+
*/
|
|
1738
|
+
type AnyTempEntityListQueryOptions = {
|
|
1739
|
+
addToQueries?: ListQueryAddItemToQueries<__LEGIT_ANY__, __LEGIT_ANY__>;
|
|
1740
|
+
loadedFields?: ItemLoadedFields;
|
|
1741
|
+
};
|
|
1347
1742
|
/** Non-store-specific offline operation definition alias. */
|
|
1348
1743
|
type AnyOfflineOperationDefinition<TUploadRef extends ValidPayload = ValidPayload> = {
|
|
1349
1744
|
inputSchema: PersistentStorageSchema<__LEGIT_ANY__>;
|
|
@@ -1354,8 +1749,12 @@ type AnyOfflineOperationDefinition<TUploadRef extends ValidPayload = ValidPayloa
|
|
|
1354
1749
|
};
|
|
1355
1750
|
accumulation?: OfflineAccumulationConfig<__LEGIT_ANY__>;
|
|
1356
1751
|
supersedes?: OfflineSupersedeConfig;
|
|
1357
|
-
tempEntity?: OfflineTempEntityConfig<__LEGIT_ANY__, __LEGIT_ANY__, __LEGIT_ANY__
|
|
1358
|
-
|
|
1752
|
+
tempEntity?: Omit<OfflineTempEntityConfig<__LEGIT_ANY__, __LEGIT_ANY__, __LEGIT_ANY__>, keyof AnyTempEntityListQueryOptions> & Omit<AnyTempEntityListQueryOptions, 'addToQueries'> & {
|
|
1753
|
+
addToQueries?: AnyTempEntityListQueryOptions['addToQueries'] | ((input: __LEGIT_ANY__, tempId: __LEGIT_ANY__) => AnyTempEntityListQueryOptions['addToQueries']);
|
|
1754
|
+
};
|
|
1755
|
+
tempEntities?: Omit<OfflineTempEntitiesConfig<__LEGIT_ANY__, __LEGIT_ANY__, __LEGIT_ANY__>, 'buildPendingEntities'> & {
|
|
1756
|
+
buildPendingEntities: (input: __LEGIT_ANY__, tempIds: readonly __LEGIT_ANY__[]) => readonly (Omit<OfflineTempEntityPendingEntry<__LEGIT_ANY__>, keyof AnyTempEntityListQueryOptions> & AnyTempEntityListQueryOptions)[];
|
|
1757
|
+
};
|
|
1359
1758
|
getServerSnapshot?: (ctx: OperationBaseContext<__LEGIT_ANY__>) => unknown;
|
|
1360
1759
|
execute: (ctx: OperationExecuteContext<__LEGIT_ANY__, TUploadRef>) => unknown;
|
|
1361
1760
|
onSuccessExecute?: OfflineOperationExecuteSuccessHandler<__LEGIT_ANY__, __LEGIT_ANY__>;
|
|
@@ -1364,6 +1763,7 @@ type AnyOfflineOperationDefinition<TUploadRef extends ValidPayload = ValidPayloa
|
|
|
1364
1763
|
getEntityRefs?: (ctx: OperationEntityRefsContext<__LEGIT_ANY__>) => unknown[];
|
|
1365
1764
|
dependsOn?: (ctx: OperationEntityRefsContext<__LEGIT_ANY__>) => __LEGIT_ANY__[];
|
|
1366
1765
|
dependsOnUploads?: (ctx: OperationEntityRefsContext<__LEGIT_ANY__>) => string[];
|
|
1766
|
+
cancelledWith?: (ctx: OperationEntityRefsContext<__LEGIT_ANY__>) => OfflineExternalEntityRef[];
|
|
1367
1767
|
};
|
|
1368
1768
|
/**
|
|
1369
1769
|
* Compact type-spec helper for a single offline operation.
|
|
@@ -1418,6 +1818,7 @@ type DocumentOperationServerSnapshot<TOptions extends DefineOfflineOperation> =
|
|
|
1418
1818
|
*
|
|
1419
1819
|
* @typeParam State - Document state type for the owning store.
|
|
1420
1820
|
* @typeParam TOptions - Operation typing options, usually created with {@link DefineOfflineOperation}.
|
|
1821
|
+
* @typeParam TUploadRef - Upload ref type read from `ctx.uploads.resolvedRefsById` in `execute`. Pass `StoreManagerUploadRef<typeof storeManager>` to use the type inferred from the manager's upload transport. Defaults to the untyped `ValidPayload`.
|
|
1421
1822
|
*
|
|
1422
1823
|
* @example
|
|
1423
1824
|
* ```ts
|
|
@@ -1449,6 +1850,7 @@ type DocumentOfflineOperationDefinition<State extends ValidStoreState, TOptions
|
|
|
1449
1850
|
*
|
|
1450
1851
|
* @typeParam State - Document state type for the owning store.
|
|
1451
1852
|
* @typeParam TOperations - Operation map where each key declares its input, replay result, and optional conflict payload.
|
|
1853
|
+
* @typeParam TUploadRef - Upload ref type read from `ctx.uploads.resolvedRefsById` in `execute`. Pass `StoreManagerUploadRef<typeof storeManager>` to use the type inferred from the manager's upload transport. Defaults to the untyped `ValidPayload`.
|
|
1452
1854
|
*
|
|
1453
1855
|
* @example
|
|
1454
1856
|
* ```ts
|
|
@@ -1510,6 +1912,7 @@ type CollectionOfflineEntityRef<ItemPayload extends ValidPayload> = ItemPayload;
|
|
|
1510
1912
|
* When `tempEntity` or `tempEntities` is provided, the pending builders must
|
|
1511
1913
|
* return `ItemState`, and the reconciliation hooks must return an
|
|
1512
1914
|
* `ItemPayload` plus optional `ItemState` replacement data.
|
|
1915
|
+
* @typeParam TUploadRef - Upload ref type read from `ctx.uploads.resolvedRefsById` in `execute`. Pass `StoreManagerUploadRef<typeof storeManager>` to use the type inferred from the manager's upload transport. Defaults to the untyped `ValidPayload`.
|
|
1513
1916
|
*/
|
|
1514
1917
|
type CollectionOfflineOperationDefinition<ItemState extends ValidStoreState, ItemPayloadUnused extends ValidPayload, TInput = unknown, TConflict = unknown, TTempResult = unknown, TServerSnapshot = unknown, TUploadRef extends ValidPayload = ValidPayload> = OfflineOperationDefinition<TInput, TConflict, TTempResult, TServerSnapshot, ItemPayloadUnused, ItemState, ItemPayloadUnused, ItemState, TUploadRef> & {
|
|
1515
1918
|
/**
|
|
@@ -1530,6 +1933,22 @@ type CollectionOfflineOperationDefinition<ItemState extends ValidStoreState, Ite
|
|
|
1530
1933
|
* record that declares it leaves the queue.
|
|
1531
1934
|
*/
|
|
1532
1935
|
dependsOnUploads?: (ctx: OperationEntityRefsContext<TInput>) => string[];
|
|
1936
|
+
/**
|
|
1937
|
+
* Declares the entities of OTHER stores this operation belongs to (for
|
|
1938
|
+
* example the task a queued comment was written on).
|
|
1939
|
+
*
|
|
1940
|
+
* When the offline creation of one of them will never reach the server (it
|
|
1941
|
+
* was cancelled before being sent, see
|
|
1942
|
+
* {@link OfflineSupersedeConfig.dropSelfIfTempLifecycleCancelled}, or its
|
|
1943
|
+
* manual resolution was discarded), this operation is dropped as well,
|
|
1944
|
+
* together with everything queued under it, and its own temp entities are
|
|
1945
|
+
* removed from the store.
|
|
1946
|
+
*
|
|
1947
|
+
* This only drives that cleanup: it does not delay the replay of this
|
|
1948
|
+
* operation nor rewrite its input when the other entity gets its final
|
|
1949
|
+
* ref. Entities of the same store are declared with `dependsOn`.
|
|
1950
|
+
*/
|
|
1951
|
+
cancelledWith?: (ctx: OperationEntityRefsContext<TInput>) => OfflineExternalEntityRef[];
|
|
1533
1952
|
} & ([ItemState | ItemPayloadUnused] extends [never] ? never : unknown);
|
|
1534
1953
|
/**
|
|
1535
1954
|
* Builds a collection offline operations map from a compact operation spec.
|
|
@@ -1545,6 +1964,7 @@ type CollectionOfflineOperationDefinition<ItemState extends ValidStoreState, Ite
|
|
|
1545
1964
|
* @typeParam ItemState - Collection item state type for the owning store.
|
|
1546
1965
|
* @typeParam ItemPayload - Collection payload type for the owning store.
|
|
1547
1966
|
* @typeParam TOperations - Operation map where each key declares its input, optional conflict payload, and optional temp-result type.
|
|
1967
|
+
* @typeParam TUploadRef - Upload ref type read from `ctx.uploads.resolvedRefsById` in `execute`. Pass `StoreManagerUploadRef<typeof storeManager>` to use the type inferred from the manager's upload transport. Defaults to the untyped `ValidPayload`.
|
|
1548
1968
|
*
|
|
1549
1969
|
* @example
|
|
1550
1970
|
* ```ts
|
|
@@ -1585,9 +2005,12 @@ type ListQueryOfflineEntityRef<ItemPayload extends ValidPayload> = ItemPayload;
|
|
|
1585
2005
|
* @typeParam TTempResult - Result returned by `execute`.
|
|
1586
2006
|
* When `tempEntity` or `tempEntities` is provided, the pending builders must
|
|
1587
2007
|
* return `ItemState`, and the reconciliation hooks must return an
|
|
1588
|
-
* `ItemPayload` plus optional `ItemState` replacement data.
|
|
2008
|
+
* `ItemPayload` plus optional `ItemState` replacement data. The pending
|
|
2009
|
+
* entities can declare `addToQueries` to show up in list queries while the
|
|
2010
|
+
* mutation is queued, and `loadedFields` when partial resources are enabled.
|
|
2011
|
+
* @typeParam TUploadRef - Upload ref type read from `ctx.uploads.resolvedRefsById` in `execute`. Pass `StoreManagerUploadRef<typeof storeManager>` to use the type inferred from the manager's upload transport. Defaults to the untyped `ValidPayload`.
|
|
1589
2012
|
*/
|
|
1590
|
-
type ListQueryOfflineOperationDefinition<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayloadUnused extends ValidPayload, TInput = unknown, TConflict = unknown, TTempResult = unknown, TServerSnapshot = unknown, TUploadRef extends ValidPayload = ValidPayload> = OfflineOperationDefinition<TInput, TConflict, TTempResult, TServerSnapshot, ItemPayloadUnused, ItemState, ItemPayloadUnused, ItemState, TUploadRef> & {
|
|
2013
|
+
type ListQueryOfflineOperationDefinition<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayloadUnused extends ValidPayload, TInput = unknown, TConflict = unknown, TTempResult = unknown, TServerSnapshot = unknown, TUploadRef extends ValidPayload = ValidPayload> = OfflineOperationDefinition<TInput, TConflict, TTempResult, TServerSnapshot, ItemPayloadUnused, ItemState, ItemPayloadUnused, ItemState, TUploadRef, QueryPayload> & {
|
|
1591
2014
|
/**
|
|
1592
2015
|
* Declares which list-query entities are affected by this queued mutation.
|
|
1593
2016
|
*
|
|
@@ -1606,6 +2029,22 @@ type ListQueryOfflineOperationDefinition<ItemState extends ValidStoreState, Quer
|
|
|
1606
2029
|
* record that declares it leaves the queue.
|
|
1607
2030
|
*/
|
|
1608
2031
|
dependsOnUploads?: (ctx: OperationEntityRefsContext<TInput>) => string[];
|
|
2032
|
+
/**
|
|
2033
|
+
* Declares the entities of OTHER stores this operation belongs to (for
|
|
2034
|
+
* example the task a queued comment was written on).
|
|
2035
|
+
*
|
|
2036
|
+
* When the offline creation of one of them will never reach the server (it
|
|
2037
|
+
* was cancelled before being sent, see
|
|
2038
|
+
* {@link OfflineSupersedeConfig.dropSelfIfTempLifecycleCancelled}, or its
|
|
2039
|
+
* manual resolution was discarded), this operation is dropped as well,
|
|
2040
|
+
* together with everything queued under it, and its own temp entities are
|
|
2041
|
+
* removed from the store.
|
|
2042
|
+
*
|
|
2043
|
+
* This only drives that cleanup: it does not delay the replay of this
|
|
2044
|
+
* operation nor rewrite its input when the other entity gets its final
|
|
2045
|
+
* ref. Entities of the same store are declared with `dependsOn`.
|
|
2046
|
+
*/
|
|
2047
|
+
cancelledWith?: (ctx: OperationEntityRefsContext<TInput>) => OfflineExternalEntityRef[];
|
|
1609
2048
|
} & ([ItemState | QueryPayload | ItemPayloadUnused] extends [never] ? never : unknown);
|
|
1610
2049
|
/**
|
|
1611
2050
|
* Builds a list-query offline operations map from a compact operation spec.
|
|
@@ -1622,6 +2061,7 @@ type ListQueryOfflineOperationDefinition<ItemState extends ValidStoreState, Quer
|
|
|
1622
2061
|
* @typeParam QueryPayload - Query payload type used by the list store.
|
|
1623
2062
|
* @typeParam ItemPayload - Item payload type used by the list store.
|
|
1624
2063
|
* @typeParam TOperations - Operation map where each key declares its input, optional conflict payload, and optional temp-result type.
|
|
2064
|
+
* @typeParam TUploadRef - Upload ref type read from `ctx.uploads.resolvedRefsById` in `execute`. Pass `StoreManagerUploadRef<typeof storeManager>` to use the type inferred from the manager's upload transport. Defaults to the untyped `ValidPayload`.
|
|
1625
2065
|
*
|
|
1626
2066
|
* @example
|
|
1627
2067
|
* ```ts
|
|
@@ -1977,4 +2417,4 @@ type ListQueryPersistentStorageFields<QueryPayload extends ValidPayload, ItemPay
|
|
|
1977
2417
|
/** Persistent storage config for ListQueryStore. */
|
|
1978
2418
|
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>;
|
|
1979
2419
|
//#endregion
|
|
1980
|
-
export {
|
|
2420
|
+
export { OfflineMutationQueueingConfig as $, ListQueryUseMultipleItemsQuery as $t, DefineDocumentOfflineOperations as A, ScheduleFetchOptions as An, OfflineMutationUploadsInput as At, OfflineAccumulationMergeContext as B, OfflineUploadState as Bt, PersistentStoragePreloadResult as C, ValidPayload as Cn, OfflineTempEntityConfig as Ct, CollectionOfflineEntityRef as D, FetchType as Dn, ParsedOfflineResolutionConflictResultForOperation as Dt, AnyOfflineOperationDefinition as E, mutationSkipped as En, OperationResult as Et, GlobalOfflineStatus as F, TSDFDebugLogger as Fn, OfflineUploadAdapter as Ft, OfflineFailureContext as G, DerivedQueryContext as Gt, OfflineEntityMutationKind as H, ReplaceOfflineUploadArgs as Ht, ItemOfflineState as I, TSDFFocusDebugOperation as In, OfflineUploadFile as It, OfflineHealthCheckContext as J, FetchListFnReturnItem as Jt, OfflineFailurePhase as K, DerivedQuerySource as Kt, ListQueryOfflineEntityRef as L, TSDFLoggerOptions as Ln, OfflineUploadProgress as Lt, DefineOfflineOperation as M, TSDFDebugLogArea as Mn, OfflineSessionUploadsConfig as Mt, DocumentOfflineOperationDefinition as N, TSDFDebugLogEntry as Nn, OfflineStoredUploadRecord as Nt, CollectionOfflineOperationDefinition as O, RequestSchedulerEventData as On, ParsedOfflineResolutionConflictResultForStore as Ot, GlobalOfflineEntity as P, TSDFDebugLogLevel as Pn, OfflineUpload as Pt, OfflineMutationQueueingCause as Q, ListQueryAddItemToQueries as Qt, ListQueryOfflineOperationDefinition as R, OfflineUploadRefSchema as Rt, PersistentStorageErrorHandler as S, UnwrapTSDFResult as Sn, OfflineTempEntitiesReconciliation as St, StorageAdapter as T, fetchTypePriority as Tn, OperationConflict as Tt, OfflineExternalEntityRef as U, SaveOfflineUploadArgs as Ut, OfflineConflictResolutionAction as V, OfflineUploadTransportContext as Vt, OfflineFailureClassification as W, DerivedQueriesConfig as Wt, OfflineMutationDescriptor as X, FieldsOption as Xt, OfflineHealthCheckResult as Y, FieldsInput as Yt, OfflineMutationInput as Z, ItemLoadedFields as Zt, DocumentPersistentStorageConfig as _, StoreError as _n, OfflineSession as _t, AsyncStorageMetadataOrder as a, PartialResourcesConfig as an, OfflineResolutionActionError as at, PersistentStorageBaseConfig as b, StoreMutationErrorOptions as bn, OfflineSyncState as bt, AsyncStorageNamespaceCommitUpsert as c, TSDFItemQuery as cn, OfflineResolutionConflictParseError as ct, AsyncStorageNamespaceKind as d, TSFDUseListItemReturn as dn, OfflineResolutionRecord as dt, ListQueryUseMultipleListQueriesQuery as en, OfflineMutationQueueingPolicy as et, AsyncStorageNamespaceScope as f, TSFDUseListQueryReturn as fn, OfflineResolutionRecordForOperation as ft, ConvertedPersistentStorageDataSchema as g, PayloadDebounce as gn, OfflineRuntimeConfigUpdate as gt, CollectionPersistentStorageConfig as h, MutationSkipped as hn, OfflineRuntimeConfig as ht, AsyncStorageDriverSetEntry as i, OptimisticListUpdate as in, OfflineResolutionAction as it, DefineListQueryOfflineOperations as j, ScheduleFetchResults as jn, OfflineOperationUploadsContext as jt, DefineCollectionOfflineOperations as k, RequestSchedulerEvents as kn, defaultOfflineRuntimeConfig as kt, AsyncStorageNamespaceGetResult as l, TSFDListQuery as ln, OfflineResolutionConflictParseErrorCode as lt, CollectionOfflineOperationsConfig as m, MaybeTSDFResult as mn, OfflineRetryExhaustedResolutionAction as mt, AsyncStorageDiscoveredScope as n, OnListQueryInvalidate as nn, OfflineQueueEntry as nt, AsyncStorageNamespaceCommitArgs as o, QueryFetchPayload as on, OfflineResolutionActionErrorCode as ot, AsyncStorageReadOptions as p, TSFDUsePendingOfflineItemsReturn as pn, OfflineResolutionRecordForStore as pt, OfflineHealthCheckConfig as q, FetchListFnReturn as qt, AsyncStorageDriver as r, OnListQueryItemInvalidate as rn, OfflineReplayRetryConfig as rt, AsyncStorageNamespaceCommitTouch as s, QueryStatus as sn, OfflineResolutionActionForOperation as st, AsyncStorageAdapter as t, OffsetPaginationConfig as tn, OfflineOperationKind as tt, AsyncStorageNamespaceHandle as u, TSFDListQueryState as un, OfflineResolutionGenericAction as ut, ListQueryOfflineOperationsConfig as v, StoreFetchError as vn, OfflineSessionConfig as vt, PersistentStorageSchema as w, ValidStoreState as wn, OfflineTempEntityPendingEntry as wt, PersistentStorageDataSchema as x, TSDFStatus as xn, OfflineTempEntitiesConfig as xt, ListQueryPersistentStorageConfig as y, StoreMutationError as yn, OfflineSupersedeConfig as yt, OfflineAccumulationConfig as z, OfflineUploadSource as zt };
|