tsdf 18.3.1 → 18.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/async-storage.d.ts +1 -1
- package/dist/async-storage.js +1 -1
- package/dist/{asyncStorageAdapter-D_Ltk0xg.d.ts → asyncStorageAdapter-C7J64ZKi.d.ts} +1 -1
- package/dist/{asyncStorageAdapter-NrI38v4g.js → asyncStorageAdapter-D6IVBzPg.js} +1 -1
- package/dist/{asyncStorageAdapters-Daewq7dv.js → asyncStorageAdapters-CBMshtkY.js} +2 -2
- package/dist/indexed-db-storage.d.ts +1 -1
- package/dist/indexed-db-storage.js +1 -1
- package/dist/indexedDbPersistentStorage-x6dVEqkJ.js +1156 -0
- package/dist/main.d.ts +133 -20
- package/dist/main.js +1589 -372
- package/dist/opfs-storage.d.ts +1 -1
- package/dist/opfs-storage.js +1 -1
- package/dist/{opfsPersistentStorage-HRMP5gzd.d.ts → opfsPersistentStorage-CEhiNR8Q.d.ts} +1 -1
- package/dist/{opfsPersistentStorage-amwSWm_p.js → opfsPersistentStorage-CwmY3O1r.js} +1 -1
- package/dist/{types-DeZ9VDOe.d.ts → types-Bp7_Ra7_.d.ts} +625 -45
- package/docs/collection-store.md +9 -7
- package/docs/hooks.md +116 -3
- package/docs/list-query-store.md +3 -0
- package/docs/offline.md +457 -4
- package/docs/partial-resources.md +4 -0
- package/docs/persistent-storage.md +30 -0
- package/docs/shared-types.md +4 -0
- package/docs/store-manager.md +22 -3
- package/package.json +1 -1
- package/dist/indexedDbPersistentStorage-JJdUGGI8.js +0 -966
|
@@ -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>[];
|
|
@@ -403,7 +425,21 @@ type FieldsOption<HasPartialResources extends boolean> = HasPartialResources ext
|
|
|
403
425
|
};
|
|
404
426
|
//#endregion
|
|
405
427
|
//#region src/persistentStorage/offlineUploadTypes.d.ts
|
|
406
|
-
/**
|
|
428
|
+
/**
|
|
429
|
+
* Lifecycle state for a session-scoped offline upload.
|
|
430
|
+
*
|
|
431
|
+
* - `pending`: staged and waiting to be uploaded. An upload whose transport
|
|
432
|
+
* failed during replay with a failure TSDF retries on its own (session went
|
|
433
|
+
* offline, or the failure was classified as retryable) goes back to
|
|
434
|
+
* `pending` with `lastError` set.
|
|
435
|
+
* - `uploading`: the `upload` transport is running.
|
|
436
|
+
* - `uploaded`: the transport returned the final ref (`resolvedRef`).
|
|
437
|
+
* - `failed`: the last transport attempt failed and TSDF will not retry on
|
|
438
|
+
* its own: the dependent operation was moved to manual resolution, or the
|
|
439
|
+
* upload was started through `resolveOfflineUpload(s)`. A failed upload is
|
|
440
|
+
* not blocked: it is uploaded again when a dependent operation is replayed
|
|
441
|
+
* (resolution `retry`) or `resolveOfflineUpload(s)` is called again.
|
|
442
|
+
*/
|
|
407
443
|
type OfflineUploadState = 'pending' | 'uploading' | 'uploaded' | 'failed';
|
|
408
444
|
/** Source that created a staged offline upload. */
|
|
409
445
|
type OfflineUploadSource = 'manual' | 'mutation';
|
|
@@ -435,6 +471,47 @@ type ReplaceOfflineUploadArgs = {
|
|
|
435
471
|
*/
|
|
436
472
|
metadata?: ValidPayload;
|
|
437
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
|
+
};
|
|
438
515
|
/** Public metadata for a file staged for offline mutation replay. */
|
|
439
516
|
type OfflineUpload<TResolvedRef extends ValidPayload = ValidPayload> = {
|
|
440
517
|
/** Stable upload id used by offline operation inputs. */id: string; /** Session key that owns this upload. */
|
|
@@ -445,9 +522,17 @@ type OfflineUpload<TResolvedRef extends ValidPayload = ValidPayload> = {
|
|
|
445
522
|
mimeType: string; /** File size in bytes. */
|
|
446
523
|
sizeBytes: number; /** Epoch timestamp when the upload was staged. */
|
|
447
524
|
createdAt: number; /** Epoch timestamp for the latest upload metadata change. */
|
|
448
|
-
updatedAt: number;
|
|
525
|
+
updatedAt: number;
|
|
526
|
+
/**
|
|
527
|
+
* Final server-side reference after upload completes, as returned by the
|
|
528
|
+
* session `upload` transport.
|
|
529
|
+
*/
|
|
449
530
|
resolvedRef?: TResolvedRef; /** Latest upload progress snapshot. */
|
|
450
|
-
progress?: OfflineUploadProgress;
|
|
531
|
+
progress?: OfflineUploadProgress;
|
|
532
|
+
/**
|
|
533
|
+
* Message of the latest failed upload attempt. It stays set while the upload
|
|
534
|
+
* is retried and is cleared once the upload succeeds.
|
|
535
|
+
*/
|
|
451
536
|
lastError?: {
|
|
452
537
|
message: string;
|
|
453
538
|
};
|
|
@@ -496,10 +581,58 @@ type OfflineUploadTransportContext = {
|
|
|
496
581
|
metadata?: ValidPayload; /** Reports upload progress back to TSDF. */
|
|
497
582
|
onProgress: (progress: OfflineUploadProgress) => void;
|
|
498
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
|
+
};
|
|
499
601
|
/** Upload handling config for an offline session. */
|
|
500
602
|
type OfflineSessionUploadsConfig<TResolvedRef extends ValidPayload = ValidPayload> = {
|
|
501
|
-
/** Adapter used to persist staged files until replay can upload them. */adapter: OfflineUploadAdapter;
|
|
502
|
-
|
|
603
|
+
/** Adapter used to persist staged files until replay can upload them. */adapter: OfflineUploadAdapter;
|
|
604
|
+
/**
|
|
605
|
+
* Upload transport that returns the final server-side file reference.
|
|
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
|
+
*
|
|
611
|
+
* Reject (throw) to report a failure. When the upload runs as a dependency
|
|
612
|
+
* of a replayed operation, the thrown error goes through the session's
|
|
613
|
+
* `classifyFailure` / `classifyRetryableFailure` hooks with `ctx.uploadId`
|
|
614
|
+
* set, exactly like a failed `execute`: classify connection problems as
|
|
615
|
+
* `'network'` / `'outage'` (or as retryable) so they are retried, and leave
|
|
616
|
+
* permanent ones (file too large, type not accepted) unclassified so the
|
|
617
|
+
* operation goes to manual resolution. Throw errors those hooks can tell
|
|
618
|
+
* apart.
|
|
619
|
+
*/
|
|
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. */
|
|
503
636
|
concurrency?: number;
|
|
504
637
|
};
|
|
505
638
|
/** Files attached to an offline-capable mutation call, keyed by upload id. */
|
|
@@ -507,7 +640,12 @@ type OfflineMutationUploadsInput = Record<string, Blob | File>;
|
|
|
507
640
|
type OfflineAttachedUploadIds = Record<string, string>;
|
|
508
641
|
/** Resolved upload files and references available while an offline operation replays. */
|
|
509
642
|
type OfflineOperationUploadsContext<TResolvedRef extends ValidPayload = ValidPayload> = {
|
|
510
|
-
/** 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
|
+
*/
|
|
511
649
|
resolvedRefsById: Record<string, TResolvedRef>;
|
|
512
650
|
};
|
|
513
651
|
//#endregion
|
|
@@ -521,6 +659,15 @@ type OfflineStoreType = 'document' | 'collection' | 'listQuery';
|
|
|
521
659
|
type OfflineFailurePhase = 'fetch' | 'mutation' | 'sync';
|
|
522
660
|
/** High-level classification used by outage detection. */
|
|
523
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';
|
|
524
671
|
/** Kinds of entities participating in offline conflict/sync tracking. */
|
|
525
672
|
type OfflineEntityKind = 'document' | 'item' | 'query';
|
|
526
673
|
/** Lifecycle declared per offline operation definition. */
|
|
@@ -589,6 +736,16 @@ type OfflineFailureContext = {
|
|
|
589
736
|
storeType: OfflineStoreType; /** Optional operation name associated with the failure. */
|
|
590
737
|
operationName?: string; /** Session key used by browser tab and persistence scoping. */
|
|
591
738
|
sessionKey: string;
|
|
739
|
+
/**
|
|
740
|
+
* Set when replaying `operationName` (`phase: 'sync'`) failed while
|
|
741
|
+
* resolving one of its `dependsOnUploads` uploads: the id of that upload.
|
|
742
|
+
* The operation's `execute` was not called. The error is usually the one
|
|
743
|
+
* thrown by the session `upload` transport, but it can also be a storage
|
|
744
|
+
* error reading or updating the staged upload, or the error for an upload
|
|
745
|
+
* that no longer exists. `undefined` for every failure that did not come
|
|
746
|
+
* from a dependency upload.
|
|
747
|
+
*/
|
|
748
|
+
uploadId?: string;
|
|
592
749
|
};
|
|
593
750
|
/** Re-check strategy for recovery probing. Omitted fields use built-in defaults (which differ between network and outage modes). */
|
|
594
751
|
type OfflineRecoveryProbeConfig = {
|
|
@@ -629,19 +786,87 @@ type OfflineNetworkModeConfig = {
|
|
|
629
786
|
/**
|
|
630
787
|
* Probe whether classified network recovery has completed.
|
|
631
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.
|
|
632
793
|
*/
|
|
633
794
|
recoveryCheck?: (ctx: {
|
|
634
795
|
sessionKey: string;
|
|
635
796
|
}) => Promise<boolean> | boolean; /** Optional probe config to tune classified network recovery behavior. */
|
|
636
797
|
recoveryProbe?: OfflineRecoveryProbeConfig;
|
|
637
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
|
+
};
|
|
638
803
|
/** Server outage detection and recovery configuration. */
|
|
639
|
-
type OfflineOutageModeConfig = {
|
|
640
|
-
/**
|
|
641
|
-
recoveryCheck: (ctx: {
|
|
804
|
+
type OfflineOutageModeConfig = OfflineOutageModeBaseConfig & {
|
|
805
|
+
/** Probe the remote service to confirm outage recovery. */recoveryCheck: (ctx: {
|
|
642
806
|
sessionKey: string;
|
|
643
|
-
}) => Promise<boolean> | boolean;
|
|
644
|
-
|
|
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;
|
|
645
870
|
};
|
|
646
871
|
/** Fixed replay retry policy for healthy online replay failures. Omitted fields use built-in defaults. */
|
|
647
872
|
type OfflineReplayRetryConfig = {
|
|
@@ -656,29 +881,69 @@ type OfflineReplayRetryConfig = {
|
|
|
656
881
|
*/
|
|
657
882
|
intervalMs?: number;
|
|
658
883
|
};
|
|
659
|
-
|
|
660
|
-
|
|
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;
|
|
661
909
|
/**
|
|
662
910
|
* Classify a remote failure as `outage`, `network`, or `ignore`.
|
|
663
911
|
* `outage` activates outage recovery behavior.
|
|
664
912
|
* `network` activates network offline handling for future operations only
|
|
665
913
|
* when `network.enabled` is true. Existing offline recovery may keep using
|
|
666
914
|
* classifications until already-active work finishes recovering.
|
|
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
|
+
*
|
|
924
|
+
* Failures of the `uploads.upload` transport during replay are classified
|
|
925
|
+
* here too, with `ctx.uploadId` set: `outage` / `network` keep the upload
|
|
926
|
+
* `pending` and the dependent operation queued until the session recovers.
|
|
667
927
|
*/
|
|
668
|
-
classifyFailure?: (error: unknown, ctx: OfflineFailureContext) => Promise<OfflineFailureClassification> | OfflineFailureClassification;
|
|
928
|
+
classifyFailure?: (error: unknown, ctx: OfflineFailureContext) => Promise<OfflineFailureClassification | 'unknown'> | OfflineFailureClassification | 'unknown';
|
|
669
929
|
/**
|
|
670
930
|
* Optional replay-only classifier for ambiguous sync failures that stayed
|
|
671
|
-
* online (`classifyFailure(...) === 'ignore'`
|
|
931
|
+
* online (`classifyFailure(...) === 'ignore'`, or `healthCheck` answered
|
|
932
|
+
* `'up'`).
|
|
672
933
|
*
|
|
673
934
|
* Return `true` only when automatically re-sending the replayed mutation is
|
|
674
935
|
* known to be safe. Return `false` to avoid auto-replay retries; in that
|
|
675
936
|
* case the entry still enters `needs-confirmation` so `shouldSkipSync` /
|
|
676
937
|
* conflict checks can run before the mutation is promoted to manual
|
|
677
938
|
* resolution.
|
|
939
|
+
*
|
|
940
|
+
* When `ctx.uploadId` is set the failure came from a dependency upload and
|
|
941
|
+
* the mutation was not sent: return `true` to run the upload again on the
|
|
942
|
+
* `replayRetry` cadence, or `false` for a permanent failure (file rejected),
|
|
943
|
+
* which moves the operation to manual resolution right away.
|
|
678
944
|
*/
|
|
679
945
|
classifyRetryableFailure?: (error: unknown, ctx: OfflineFailureContext) => Promise<boolean> | boolean; /** Network detection strategy and browser integration. */
|
|
680
|
-
network?: OfflineNetworkModeConfig; /**
|
|
681
|
-
outage?: OfflineOutageModeConfig; /** Fixed retry policy for healthy online replay failures. */
|
|
946
|
+
network?: OfflineNetworkModeConfig; /** Fixed retry policy for healthy online replay failures. */
|
|
682
947
|
replayRetry?: OfflineReplayRetryConfig;
|
|
683
948
|
/**
|
|
684
949
|
* Root policy controlling whether offline-enabled mutations may enter the
|
|
@@ -688,6 +953,39 @@ type OfflineSessionConfig<TUploadRef extends ValidPayload = ValidPayload> = {
|
|
|
688
953
|
mutationQueueing?: OfflineMutationQueueingConfig; /** Optional upload transport/storage config shared by the whole session. */
|
|
689
954
|
uploads?: OfflineSessionUploadsConfig<TUploadRef>;
|
|
690
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
|
+
});
|
|
691
989
|
/** Per-session offline status snapshot shared across tabs. */
|
|
692
990
|
type GlobalOfflineStatus = {
|
|
693
991
|
/** Session key for this status bucket. */sessionKey: string;
|
|
@@ -717,6 +1015,60 @@ type GlobalOfflineStatus = {
|
|
|
717
1015
|
};
|
|
718
1016
|
/** Queue state of an offline mutation entry. */
|
|
719
1017
|
type OfflineSyncState = 'pending' | 'syncing' | 'needs-confirmation';
|
|
1018
|
+
/**
|
|
1019
|
+
* Offline sync state of one collection/list-query item, returned by the
|
|
1020
|
+
* stores' `useItemOfflineState(...)` and `getItemOfflineState(...)`.
|
|
1021
|
+
*/
|
|
1022
|
+
type ItemOfflineState = {
|
|
1023
|
+
/**
|
|
1024
|
+
* Where the item's offline work stands (same value as the item's
|
|
1025
|
+
* {@link GlobalOfflineEntity.syncState}):
|
|
1026
|
+
*
|
|
1027
|
+
* - `pending`: queued, waiting to be sent
|
|
1028
|
+
* - `syncing`: being sent
|
|
1029
|
+
* - `needs-confirmation`: a send failed and it is not known whether it
|
|
1030
|
+
* reached the server, so the mutation is re-checked or retried
|
|
1031
|
+
* - `resolution-required`: waiting for a manual resolution
|
|
1032
|
+
*
|
|
1033
|
+
* With several mutations queued for the item this is the most urgent state
|
|
1034
|
+
* among them (`needs-confirmation` > `syncing` > `pending`): the item is
|
|
1035
|
+
* `syncing` while any of its mutations is being sent (`pendingMutations`
|
|
1036
|
+
* drops as each one finishes).
|
|
1037
|
+
*/
|
|
1038
|
+
syncState: OfflineSyncState | 'resolution-required'; /** Number of queued mutations of the item still waiting to sync. */
|
|
1039
|
+
pendingMutations: number; /** Whether the item is waiting for a manual resolution. */
|
|
1040
|
+
requiresResolution: boolean;
|
|
1041
|
+
/**
|
|
1042
|
+
* Whether the item was created offline through a `tempEntity` /
|
|
1043
|
+
* `tempEntities` operation and the server has not confirmed it yet, so it is
|
|
1044
|
+
* still tracked under its temporary payload. Creations queued without a temp
|
|
1045
|
+
* entity (e.g. with a client-generated id) report `false`. It stays `true`
|
|
1046
|
+
* while the creation itself is being sent, so the server may already have
|
|
1047
|
+
* it while `syncState` is `syncing` or `needs-confirmation`; only with
|
|
1048
|
+
* `syncState: 'pending'` has it not been sent yet. Once the server entity is
|
|
1049
|
+
* reconciled, the temporary payload has no state anymore and the final
|
|
1050
|
+
* payload reports any mutation still queued with `isUnsentCreation: false`.
|
|
1051
|
+
*/
|
|
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;
|
|
1071
|
+
};
|
|
720
1072
|
/** Aggregated offline status for a tracked document/item/query entity. */
|
|
721
1073
|
type GlobalOfflineEntity = {
|
|
722
1074
|
/** Internal entity identifier tracked by offline machinery. */id: string; /** Session key for this offline entity. */
|
|
@@ -726,7 +1078,13 @@ type GlobalOfflineEntity = {
|
|
|
726
1078
|
entityKey: string; /** Entity kind used in queue partitioning. */
|
|
727
1079
|
entityKind: OfflineEntityKind; /** Effective lifecycle derived from queued operations targeting this entity. */
|
|
728
1080
|
kind: OfflineEntityMutationKind; /** Number of pending mutations waiting for sync. */
|
|
729
|
-
pendingMutations: number;
|
|
1081
|
+
pendingMutations: number;
|
|
1082
|
+
/**
|
|
1083
|
+
* Current sync state for the entity. With several mutations queued for it
|
|
1084
|
+
* this is the most urgent state among them (`needs-confirmation` >
|
|
1085
|
+
* `syncing` > `pending`): the entity is `syncing` while any of its mutations
|
|
1086
|
+
* is being sent.
|
|
1087
|
+
*/
|
|
730
1088
|
syncState: OfflineSyncState | 'resolution-required'; /** Whether the entity currently requires manual resolution. */
|
|
731
1089
|
requiresResolution: boolean; /** Resolution ids currently blocking this entity from being resolved/applied. */
|
|
732
1090
|
blockedByResolutionIds: string[]; /** Child resolution ids currently derived from this entity's dependency chain. */
|
|
@@ -795,7 +1153,11 @@ type OfflineRetryExhaustedResolutionRecordBase<TInput = unknown> = {
|
|
|
795
1153
|
operation: string; /** Input value that exhausted replay retries. */
|
|
796
1154
|
input: TInput; /** Timestamp when the original queued mutation was enqueued. */
|
|
797
1155
|
enqueuedAt: number; /** Entity references involved in the resolution. */
|
|
798
|
-
entityRefs: OfflineEntityRef[];
|
|
1156
|
+
entityRefs: OfflineEntityRef[];
|
|
1157
|
+
/**
|
|
1158
|
+
* Last replay error snapshot captured before exhaustion. When a dependency
|
|
1159
|
+
* upload failed permanently, this is the error of the `upload` transport.
|
|
1160
|
+
*/
|
|
799
1161
|
lastReplayError: {
|
|
800
1162
|
message: string;
|
|
801
1163
|
}; /** Resolution creation timestamp. */
|
|
@@ -829,17 +1191,37 @@ type OfflineSession<TUploadRef extends ValidPayload = ValidPayload> = {
|
|
|
829
1191
|
getOfflineStatus: () => GlobalOfflineStatus; /** Returns the latest aggregated offline entities for the session. */
|
|
830
1192
|
getOfflineEntities: () => readonly GlobalOfflineEntity[]; /** Returns the latest aggregated conflict/retry resolutions for the session. */
|
|
831
1193
|
getOfflineResolutions: () => readonly OfflineResolutionRecord[]; /** Returns the latest session-scoped offline uploads for the session. */
|
|
832
|
-
getOfflineUploads: () => readonly OfflineUpload<TUploadRef>[];
|
|
833
|
-
|
|
834
|
-
|
|
1194
|
+
getOfflineUploads: () => readonly OfflineUpload<TUploadRef>[];
|
|
1195
|
+
/**
|
|
1196
|
+
* Resolves a staged upload id to its latest final ref, uploading first if
|
|
1197
|
+
* needed. Rejects with the error thrown by the `upload` transport, leaving
|
|
1198
|
+
* the upload `failed`; the session failure classifiers are not consulted.
|
|
1199
|
+
*/
|
|
1200
|
+
resolveOfflineUpload: (id: string) => Promise<TUploadRef>;
|
|
1201
|
+
/**
|
|
1202
|
+
* Resolves multiple staged upload ids to their latest final refs. Rejects
|
|
1203
|
+
* with the first transport error, like `resolveOfflineUpload`.
|
|
1204
|
+
*/
|
|
1205
|
+
resolveOfflineUploads: (ids: readonly string[]) => Promise<Record<string, TUploadRef>>;
|
|
1206
|
+
/**
|
|
1207
|
+
* Saves a session-scoped upload locally for later dependency resolution or
|
|
1208
|
+
* ref usage. It is deleted automatically once the queued work that depends
|
|
1209
|
+
* on it leaves the queue.
|
|
1210
|
+
*/
|
|
835
1211
|
saveOfflineUpload: (args: SaveOfflineUploadArgs) => Promise<void>; /** Replaces a previously stored session-scoped upload, keeping its metadata unless new metadata is passed. */
|
|
836
1212
|
replaceOfflineUpload: (args: ReplaceOfflineUploadArgs) => Promise<void>; /** Loads a previously stored session-scoped upload. */
|
|
837
|
-
loadOfflineUpload: (id: string) => Promise<File | null>;
|
|
1213
|
+
loadOfflineUpload: (id: string) => Promise<File | null>;
|
|
1214
|
+
/**
|
|
1215
|
+
* Deletes a stored upload that no queued work references. Only needed for
|
|
1216
|
+
* uploads no queued mutation used: the others are deleted with the work that
|
|
1217
|
+
* depends on them.
|
|
1218
|
+
*/
|
|
838
1219
|
deleteOfflineUpload: (id: string) => Promise<void>; /** React hook subscribing to the session's global offline status. */
|
|
839
1220
|
useOfflineStatus: () => GlobalOfflineStatus; /** React hook subscribing to the session's aggregated offline entities. */
|
|
840
1221
|
useOfflineEntities: () => readonly GlobalOfflineEntity[]; /** React hook subscribing to the session's aggregated conflict/retry resolutions. */
|
|
841
1222
|
useOfflineResolutions: () => readonly OfflineResolutionRecord[]; /** React hook subscribing to the session's upload list. */
|
|
842
|
-
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;
|
|
843
1225
|
};
|
|
844
1226
|
/**
|
|
845
1227
|
* Persisted offline mutation queue entry.
|
|
@@ -880,6 +1262,10 @@ type OfflineRetryExhaustedResolutionAction = {
|
|
|
880
1262
|
/**
|
|
881
1263
|
* Controls whether retrying a resolution should also requeue retryable
|
|
882
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.
|
|
883
1269
|
* @default 'self-and-descendants'
|
|
884
1270
|
*/
|
|
885
1271
|
scope?: 'self' | 'self-and-descendants';
|
|
@@ -981,6 +1367,10 @@ type OfflineAccumulationConfig<TInput> = {
|
|
|
981
1367
|
* `same-entity` only applies to operations that resolve exactly one entity ref.
|
|
982
1368
|
* When enabled, the new operation may remove earlier unattempted pending entries
|
|
983
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.
|
|
984
1374
|
*/
|
|
985
1375
|
type OfflineSupersedeConfig = {
|
|
986
1376
|
/** Drop earlier unattempted pending entries for the same single entity. */scope: 'same-entity';
|
|
@@ -993,11 +1383,53 @@ type OfflineSupersedeConfig = {
|
|
|
993
1383
|
*/
|
|
994
1384
|
operations?: 'self' | readonly string[];
|
|
995
1385
|
/**
|
|
996
|
-
*
|
|
997
|
-
* 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.
|
|
998
1415
|
*/
|
|
999
1416
|
dropSelfIfTempLifecycleCancelled?: boolean;
|
|
1000
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
|
+
};
|
|
1001
1433
|
/** Shared context passed to offline replay lifecycle hooks. */
|
|
1002
1434
|
type OperationBaseContext<TInput> = {
|
|
1003
1435
|
/** Input payload for the queued mutation currently being processed. */input: TInput; /** Timestamp when the operation was originally enqueued. */
|
|
@@ -1096,15 +1528,35 @@ type OfflineTempEntityReconciliation<TFinalPayload extends ValidPayload = ValidP
|
|
|
1096
1528
|
type OfflineTempEntitiesReconciliation<TTempId extends ValidPayload = ValidPayload, TFinalPayload extends ValidPayload = ValidPayload, TFinalData = unknown> = OfflineTempEntityReconciliation<TFinalPayload, TFinalData> & {
|
|
1097
1529
|
/** Temporary payload that should be reconciled. */tempId: TTempId;
|
|
1098
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;
|
|
1099
1536
|
/**
|
|
1100
1537
|
* Pending temp-entity returned by `tempEntities.buildPendingEntities(...)`.
|
|
1101
1538
|
*
|
|
1102
1539
|
* @typeParam TTempId - Temporary payload used to track the optimistic entity.
|
|
1103
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.
|
|
1104
1542
|
*/
|
|
1105
|
-
type OfflineTempEntityPendingEntry<TTempId extends ValidPayload = ValidPayload, TPendingEntity = unknown> = {
|
|
1543
|
+
type OfflineTempEntityPendingEntry<TTempId extends ValidPayload = ValidPayload, TPendingEntity = unknown, TQueryPayload extends ValidPayload = never> = {
|
|
1106
1544
|
/** Temporary payload that identifies the optimistic entity. */tempId: TTempId; /** Pending entity snapshot inserted while the mutation is queued. */
|
|
1107
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>;
|
|
1108
1560
|
};
|
|
1109
1561
|
/**
|
|
1110
1562
|
* Optional temp-id lifecycle for optimistic offline create flows.
|
|
@@ -1112,8 +1564,9 @@ type OfflineTempEntityPendingEntry<TTempId extends ValidPayload = ValidPayload,
|
|
|
1112
1564
|
* @typeParam TInput - Input type used to derive the temporary entity and identifier.
|
|
1113
1565
|
* @typeParam TTempResult - Result returned by `execute`, used only by `tempEntity.reconcileServerEntity(...)`.
|
|
1114
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.
|
|
1115
1568
|
*/
|
|
1116
|
-
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> = {
|
|
1117
1570
|
/**
|
|
1118
1571
|
* Builds the optimistic entity inserted into local state while the mutation
|
|
1119
1572
|
* is queued offline.
|
|
@@ -1122,6 +1575,44 @@ type OfflineTempEntityConfig<TInput, TTempResult, TTempId extends ValidPayload =
|
|
|
1122
1575
|
* until replay succeeds and the final server entity can replace it.
|
|
1123
1576
|
*/
|
|
1124
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>;
|
|
1125
1616
|
/**
|
|
1126
1617
|
* Reconciles the optimistic temp entity with the successful replay result.
|
|
1127
1618
|
*/
|
|
@@ -1133,16 +1624,23 @@ type OfflineTempEntityConfig<TInput, TTempResult, TTempId extends ValidPayload =
|
|
|
1133
1624
|
* @typeParam TInput - Input type used to derive the temporary entities and identifiers.
|
|
1134
1625
|
* @typeParam TTempResult - Result returned by `execute`, used only by `tempEntities.reconcileServerEntities(...)`.
|
|
1135
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.
|
|
1136
1628
|
*/
|
|
1137
|
-
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> = {
|
|
1138
1630
|
/**
|
|
1139
1631
|
* Builds the optimistic entities inserted into local state while the mutation
|
|
1140
1632
|
* is queued offline.
|
|
1141
1633
|
*
|
|
1142
1634
|
* `tempIds` are the temporary payloads derived from the operation entity refs
|
|
1143
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.
|
|
1144
1642
|
*/
|
|
1145
|
-
buildPendingEntities: (input: TInput, tempIds: readonly TTempId[]) => readonly OfflineTempEntityPendingEntry<TTempId, TPendingEntity>[];
|
|
1643
|
+
buildPendingEntities: (input: TInput, tempIds: readonly TTempId[]) => readonly OfflineTempEntityPendingEntry<TTempId, TPendingEntity, TQueryPayload>[];
|
|
1146
1644
|
/**
|
|
1147
1645
|
* Reconciles the optimistic temp entities with the successful replay result.
|
|
1148
1646
|
*/
|
|
@@ -1152,12 +1650,12 @@ type NoTempEntityFields = {
|
|
|
1152
1650
|
tempEntity?: never;
|
|
1153
1651
|
tempEntities?: never;
|
|
1154
1652
|
};
|
|
1155
|
-
type ConfiguredTempEntityFields<TInput, TTempResult, TTempId extends ValidPayload, TPendingEntity = unknown, TFinalPayload extends ValidPayload = ValidPayload, TFinalData = unknown> = {
|
|
1156
|
-
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>;
|
|
1157
1655
|
tempEntities?: never;
|
|
1158
1656
|
} | {
|
|
1159
1657
|
tempEntity?: never;
|
|
1160
|
-
tempEntities: OfflineTempEntitiesConfig<TInput, TTempResult, TTempId, TPendingEntity, TFinalPayload, TFinalData>;
|
|
1658
|
+
tempEntities: OfflineTempEntitiesConfig<TInput, TTempResult, TTempId, TPendingEntity, TFinalPayload, TFinalData, TQueryPayload>;
|
|
1161
1659
|
};
|
|
1162
1660
|
/**
|
|
1163
1661
|
* Shape used by `persistentStorage.offline.operations` for each operation name.
|
|
@@ -1165,9 +1663,21 @@ type ConfiguredTempEntityFields<TInput, TTempResult, TTempId extends ValidPayloa
|
|
|
1165
1663
|
* @typeParam TInput - The persisted input payload for the queued offline operation.
|
|
1166
1664
|
* @typeParam TConflict - The conflict payload produced by pre-execution conflict detection.
|
|
1167
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.
|
|
1168
1667
|
*/
|
|
1169
|
-
type OfflineOperationDefinition<TInput, TConflict, TTempResult = void, TServerSnapshot = unknown, TTempId extends ValidPayload = string, TPendingEntity = unknown, TFinalPayload extends ValidPayload = ValidPayload, TFinalData = unknown, TUploadRef extends ValidPayload = ValidPayload> = {
|
|
1170
|
-
/** Schema used to validate incoming operation input. */inputSchema: PersistentStorageSchema<TInput>;
|
|
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> = {
|
|
1669
|
+
/** Schema used to validate incoming operation input. */inputSchema: PersistentStorageSchema<TInput>;
|
|
1670
|
+
/**
|
|
1671
|
+
* Lifecycle classification for the queued operation. TSDF derives the
|
|
1672
|
+
* lifecycle of each entity the operation references (`getEntityRefs`) from
|
|
1673
|
+
* it.
|
|
1674
|
+
*
|
|
1675
|
+
* Every item a `create` references is treated as created by it: discarding
|
|
1676
|
+
* a `create` without temp entity removes all of them locally, without
|
|
1677
|
+
* refetching them. Return only the
|
|
1678
|
+
* created items, change existing items in a separate `update` operation, and
|
|
1679
|
+
* reference the items the creation needs with `dependsOn`.
|
|
1680
|
+
*/
|
|
1171
1681
|
kind: OfflineOperationKind;
|
|
1172
1682
|
/**
|
|
1173
1683
|
* Optional queue pruning for newer operations that supersede older queued work.
|
|
@@ -1207,7 +1717,7 @@ type OfflineOperationDefinition<TInput, TConflict, TTempResult = void, TServerSn
|
|
|
1207
1717
|
*/
|
|
1208
1718
|
onSuccessExecute?: undefined; /** Temp-entity operations cannot compact multiple queued creates. */
|
|
1209
1719
|
accumulation?: never;
|
|
1210
|
-
} & ConfiguredTempEntityFields<TInput, TTempResult, TTempId, TPendingEntity, TFinalPayload, TFinalData>));
|
|
1720
|
+
} & ConfiguredTempEntityFields<TInput, TTempResult, TTempId, TPendingEntity, TFinalPayload, TFinalData, TQueryPayload>));
|
|
1211
1721
|
type WithoutTempEntity<T extends {
|
|
1212
1722
|
tempEntity?: unknown;
|
|
1213
1723
|
tempEntities?: unknown;
|
|
@@ -1219,6 +1729,16 @@ type WithoutTempEntity<T extends {
|
|
|
1219
1729
|
type OperationEntityRefsContext<TInput> = {
|
|
1220
1730
|
/** Input payload for the queued mutation. */input: TInput;
|
|
1221
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
|
+
};
|
|
1222
1742
|
/** Non-store-specific offline operation definition alias. */
|
|
1223
1743
|
type AnyOfflineOperationDefinition<TUploadRef extends ValidPayload = ValidPayload> = {
|
|
1224
1744
|
inputSchema: PersistentStorageSchema<__LEGIT_ANY__>;
|
|
@@ -1229,8 +1749,12 @@ type AnyOfflineOperationDefinition<TUploadRef extends ValidPayload = ValidPayloa
|
|
|
1229
1749
|
};
|
|
1230
1750
|
accumulation?: OfflineAccumulationConfig<__LEGIT_ANY__>;
|
|
1231
1751
|
supersedes?: OfflineSupersedeConfig;
|
|
1232
|
-
tempEntity?: OfflineTempEntityConfig<__LEGIT_ANY__, __LEGIT_ANY__, __LEGIT_ANY__
|
|
1233
|
-
|
|
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
|
+
};
|
|
1234
1758
|
getServerSnapshot?: (ctx: OperationBaseContext<__LEGIT_ANY__>) => unknown;
|
|
1235
1759
|
execute: (ctx: OperationExecuteContext<__LEGIT_ANY__, TUploadRef>) => unknown;
|
|
1236
1760
|
onSuccessExecute?: OfflineOperationExecuteSuccessHandler<__LEGIT_ANY__, __LEGIT_ANY__>;
|
|
@@ -1239,6 +1763,7 @@ type AnyOfflineOperationDefinition<TUploadRef extends ValidPayload = ValidPayloa
|
|
|
1239
1763
|
getEntityRefs?: (ctx: OperationEntityRefsContext<__LEGIT_ANY__>) => unknown[];
|
|
1240
1764
|
dependsOn?: (ctx: OperationEntityRefsContext<__LEGIT_ANY__>) => __LEGIT_ANY__[];
|
|
1241
1765
|
dependsOnUploads?: (ctx: OperationEntityRefsContext<__LEGIT_ANY__>) => string[];
|
|
1766
|
+
cancelledWith?: (ctx: OperationEntityRefsContext<__LEGIT_ANY__>) => OfflineExternalEntityRef[];
|
|
1242
1767
|
};
|
|
1243
1768
|
/**
|
|
1244
1769
|
* Compact type-spec helper for a single offline operation.
|
|
@@ -1293,6 +1818,7 @@ type DocumentOperationServerSnapshot<TOptions extends DefineOfflineOperation> =
|
|
|
1293
1818
|
*
|
|
1294
1819
|
* @typeParam State - Document state type for the owning store.
|
|
1295
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`.
|
|
1296
1822
|
*
|
|
1297
1823
|
* @example
|
|
1298
1824
|
* ```ts
|
|
@@ -1307,7 +1833,12 @@ type DocumentOperationServerSnapshot<TOptions extends DefineOfflineOperation> =
|
|
|
1307
1833
|
* ```
|
|
1308
1834
|
*/
|
|
1309
1835
|
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>> & {
|
|
1310
|
-
/**
|
|
1836
|
+
/**
|
|
1837
|
+
* Declares which upload ids must finish before replaying this operation.
|
|
1838
|
+
* A staged upload is deleted once the last queued operation or resolution
|
|
1839
|
+
* record that declares it leaves the queue.
|
|
1840
|
+
*/
|
|
1841
|
+
dependsOnUploads?: (ctx: OperationEntityRefsContext<DocumentOperationInput<TOptions>>) => string[];
|
|
1311
1842
|
} & ([State] extends [never] ? never : unknown);
|
|
1312
1843
|
/**
|
|
1313
1844
|
* Builds a document offline operations map from a compact operation spec.
|
|
@@ -1319,6 +1850,7 @@ type DocumentOfflineOperationDefinition<State extends ValidStoreState, TOptions
|
|
|
1319
1850
|
*
|
|
1320
1851
|
* @typeParam State - Document state type for the owning store.
|
|
1321
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`.
|
|
1322
1854
|
*
|
|
1323
1855
|
* @example
|
|
1324
1856
|
* ```ts
|
|
@@ -1380,6 +1912,7 @@ type CollectionOfflineEntityRef<ItemPayload extends ValidPayload> = ItemPayload;
|
|
|
1380
1912
|
* When `tempEntity` or `tempEntities` is provided, the pending builders must
|
|
1381
1913
|
* return `ItemState`, and the reconciliation hooks must return an
|
|
1382
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`.
|
|
1383
1916
|
*/
|
|
1384
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> & {
|
|
1385
1918
|
/**
|
|
@@ -1393,8 +1926,29 @@ type CollectionOfflineOperationDefinition<ItemState extends ValidStoreState, Ite
|
|
|
1393
1926
|
* Declares which collection item refs must resolve before replaying this
|
|
1394
1927
|
* operation.
|
|
1395
1928
|
*/
|
|
1396
|
-
dependsOn?: (ctx: OperationEntityRefsContext<TInput>) => CollectionOfflineEntityRef<ItemPayloadUnused>[];
|
|
1929
|
+
dependsOn?: (ctx: OperationEntityRefsContext<TInput>) => CollectionOfflineEntityRef<ItemPayloadUnused>[];
|
|
1930
|
+
/**
|
|
1931
|
+
* Declares which upload ids must finish before replaying this operation.
|
|
1932
|
+
* A staged upload is deleted once the last queued operation or resolution
|
|
1933
|
+
* record that declares it leaves the queue.
|
|
1934
|
+
*/
|
|
1397
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[];
|
|
1398
1952
|
} & ([ItemState | ItemPayloadUnused] extends [never] ? never : unknown);
|
|
1399
1953
|
/**
|
|
1400
1954
|
* Builds a collection offline operations map from a compact operation spec.
|
|
@@ -1410,6 +1964,7 @@ type CollectionOfflineOperationDefinition<ItemState extends ValidStoreState, Ite
|
|
|
1410
1964
|
* @typeParam ItemState - Collection item state type for the owning store.
|
|
1411
1965
|
* @typeParam ItemPayload - Collection payload type for the owning store.
|
|
1412
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`.
|
|
1413
1968
|
*
|
|
1414
1969
|
* @example
|
|
1415
1970
|
* ```ts
|
|
@@ -1450,9 +2005,12 @@ type ListQueryOfflineEntityRef<ItemPayload extends ValidPayload> = ItemPayload;
|
|
|
1450
2005
|
* @typeParam TTempResult - Result returned by `execute`.
|
|
1451
2006
|
* When `tempEntity` or `tempEntities` is provided, the pending builders must
|
|
1452
2007
|
* return `ItemState`, and the reconciliation hooks must return an
|
|
1453
|
-
* `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`.
|
|
1454
2012
|
*/
|
|
1455
|
-
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> & {
|
|
1456
2014
|
/**
|
|
1457
2015
|
* Declares which list-query entities are affected by this queued mutation.
|
|
1458
2016
|
*
|
|
@@ -1464,8 +2022,29 @@ type ListQueryOfflineOperationDefinition<ItemState extends ValidStoreState, Quer
|
|
|
1464
2022
|
* Declares which list item refs must resolve before replaying this
|
|
1465
2023
|
* operation.
|
|
1466
2024
|
*/
|
|
1467
|
-
dependsOn?: (ctx: OperationEntityRefsContext<TInput>) => ListQueryOfflineEntityRef<ItemPayloadUnused>[];
|
|
2025
|
+
dependsOn?: (ctx: OperationEntityRefsContext<TInput>) => ListQueryOfflineEntityRef<ItemPayloadUnused>[];
|
|
2026
|
+
/**
|
|
2027
|
+
* Declares which upload ids must finish before replaying this operation.
|
|
2028
|
+
* A staged upload is deleted once the last queued operation or resolution
|
|
2029
|
+
* record that declares it leaves the queue.
|
|
2030
|
+
*/
|
|
1468
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[];
|
|
1469
2048
|
} & ([ItemState | QueryPayload | ItemPayloadUnused] extends [never] ? never : unknown);
|
|
1470
2049
|
/**
|
|
1471
2050
|
* Builds a list-query offline operations map from a compact operation spec.
|
|
@@ -1482,6 +2061,7 @@ type ListQueryOfflineOperationDefinition<ItemState extends ValidStoreState, Quer
|
|
|
1482
2061
|
* @typeParam QueryPayload - Query payload type used by the list store.
|
|
1483
2062
|
* @typeParam ItemPayload - Item payload type used by the list store.
|
|
1484
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`.
|
|
1485
2065
|
*
|
|
1486
2066
|
* @example
|
|
1487
2067
|
* ```ts
|
|
@@ -1837,4 +2417,4 @@ type ListQueryPersistentStorageFields<QueryPayload extends ValidPayload, ItemPay
|
|
|
1837
2417
|
/** Persistent storage config for ListQueryStore. */
|
|
1838
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>;
|
|
1839
2419
|
//#endregion
|
|
1840
|
-
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 };
|