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.
@@ -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; /** Final server-side reference after upload completes. */
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>; /** Maximum number of concurrent upload transports. */
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>; /** Final uploaded refs by upload id. */
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
- /** Enable outage mode logic and confirmation retry flow. */enabled: boolean; /** Probe the remote service to confirm outage recovery. */
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; /** Optional probe config to tune recovery behavior. */
684
- recoveryProbe?: OfflineRecoveryProbeConfig;
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
- /** Shared offline/session policy reused by every store in the same session. */
700
- type OfflineSessionConfig<TUploadRef extends ValidPayload = ValidPayload> = {
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; /** Outage detection and recovery strategy for remote failures. */
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
- * When the pruned entries include a temp-entity lifecycle, drop the current
1111
- * operation itself instead of persisting a replacement entry.
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
- tempEntities?: OfflineTempEntitiesConfig<__LEGIT_ANY__, __LEGIT_ANY__, __LEGIT_ANY__>;
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 { OfflineResolutionAction as $, TSDFItemQuery as $t, DefineListQueryOfflineOperations as A, OfflineUploadAdapter as At, OfflineConflictResolutionAction as B, FetchListFnReturn as Bt, PersistentStorageSchema as C, TSDFDebugLogArea as Cn, ParsedOfflineResolutionConflictResultForStore as Ct, CollectionOfflineOperationDefinition as D, TSDFFocusDebugOperation as Dn, OfflineSessionUploadsConfig as Dt, CollectionOfflineEntityRef as E, TSDFDebugLogger as En, OfflineOperationUploadsContext as Et, ItemOfflineState as F, ReplaceOfflineUploadArgs as Ft, OfflineMutationDescriptor as G, ListQueryUseMultipleListQueriesQuery as Gt, OfflineFailureClassification as H, FieldsInput as Ht, ListQueryOfflineEntityRef as I, SaveOfflineUploadArgs as It, OfflineMutationQueueingConfig as J, OnListQueryItemInvalidate as Jt, OfflineMutationInput as K, OffsetPaginationConfig as Kt, ListQueryOfflineOperationDefinition as L, DerivedQueriesConfig as Lt, DocumentOfflineOperationDefinition as M, OfflineUploadSource as Mt, GlobalOfflineEntity as N, OfflineUploadState as Nt, DefineCollectionOfflineOperations as O, TSDFLoggerOptions as On, OfflineStoredUploadRecord as Ot, GlobalOfflineStatus as P, OfflineUploadTransportContext as Pt, OfflineReplayRetryConfig as Q, QueryStatus as Qt, OfflineAccumulationConfig as R, DerivedQueryContext as Rt, PersistentStoragePreloadResult as S, ScheduleFetchResults as Sn, ParsedOfflineResolutionConflictResultForOperation as St, AnyOfflineOperationDefinition as T, TSDFDebugLogLevel as Tn, OfflineMutationUploadsInput as Tt, OfflineFailureContext as U, FieldsOption as Ut, OfflineEntityMutationKind as V, FetchListFnReturnItem as Vt, OfflineFailurePhase as W, ListQueryUseMultipleItemsQuery as Wt, OfflineOperationKind as X, PartialResourcesConfig as Xt, OfflineMutationQueueingPolicy as Y, OptimisticListUpdate as Yt, OfflineQueueEntry as Z, QueryFetchPayload as Zt, ListQueryOfflineOperationsConfig as _, mutationSkipped as _n, OfflineTempEntitiesReconciliation as _t, AsyncStorageMetadataOrder as a, MaybeTSDFResult as an, OfflineResolutionGenericAction as at, PersistentStorageDataSchema as b, RequestSchedulerEvents as bn, OperationConflict as bt, AsyncStorageNamespaceCommitUpsert as c, StoreError as cn, OfflineResolutionRecordForStore as ct, AsyncStorageNamespaceKind as d, StoreMutationErrorOptions as dn, OfflineRuntimeConfigUpdate as dt, TSFDListQuery as en, OfflineResolutionActionError as et, AsyncStorageNamespaceScope as f, TSDFStatus as fn, OfflineSession as ft, DocumentPersistentStorageConfig as g, fetchTypePriority as gn, OfflineTempEntitiesConfig as gt, ConvertedPersistentStorageDataSchema as h, ValidStoreState as hn, OfflineSyncState as ht, AsyncStorageDriverSetEntry as i, TSFDUsePendingOfflineItemsReturn as in, OfflineResolutionConflictParseErrorCode as it, DefineOfflineOperation as j, OfflineUploadProgress as jt, DefineDocumentOfflineOperations as k, OfflineUpload as kt, AsyncStorageNamespaceGetResult as l, StoreFetchError as ln, OfflineRetryExhaustedResolutionAction as lt, CollectionPersistentStorageConfig as m, ValidPayload as mn, OfflineSupersedeConfig as mt, AsyncStorageDiscoveredScope as n, TSFDUseListItemReturn as nn, OfflineResolutionActionForOperation as nt, AsyncStorageNamespaceCommitArgs as o, MutationSkipped as on, OfflineResolutionRecord as ot, AsyncStorageReadOptions as p, UnwrapTSDFResult as pn, OfflineSessionConfig as pt, OfflineMutationQueueingCause as q, OnListQueryInvalidate as qt, AsyncStorageDriver as r, TSFDUseListQueryReturn as rn, OfflineResolutionConflictParseError as rt, AsyncStorageNamespaceCommitTouch as s, PayloadDebounce as sn, OfflineResolutionRecordForOperation as st, AsyncStorageAdapter as t, TSFDListQueryState as tn, OfflineResolutionActionErrorCode as tt, AsyncStorageNamespaceHandle as u, StoreMutationError as un, OfflineRuntimeConfig as ut, ListQueryPersistentStorageConfig as v, FetchType as vn, OfflineTempEntityConfig as vt, StorageAdapter as w, TSDFDebugLogEntry as wn, defaultOfflineRuntimeConfig as wt, PersistentStorageErrorHandler as x, ScheduleFetchOptions as xn, OperationResult as xt, PersistentStorageBaseConfig as y, RequestSchedulerEventData as yn, OfflineTempEntityPendingEntry as yt, OfflineAccumulationMergeContext as z, DerivedQuerySource as zt };
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 };