tsdf 17.0.0-alpha.8 → 17.0.0-beta.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.
Files changed (35) hide show
  1. package/dist/async-storage.d.ts +1 -1
  2. package/dist/async-storage.js +2 -1
  3. package/dist/asyncStorageAdapter-CGfnsd9m.js +1945 -0
  4. package/dist/{asyncStorageAdapter-kvAIhrBD.d.ts → asyncStorageAdapter-CMohMeKm.d.ts} +1 -1
  5. package/dist/asyncStorageAdapters-BpfM2_Y6.js +3 -0
  6. package/dist/indexed-db-storage.d.ts +4 -2
  7. package/dist/indexed-db-storage.js +2 -1
  8. package/dist/indexedDbPersistentStorage-DC9GsYHH.js +954 -0
  9. package/dist/main.d.ts +355 -414
  10. package/dist/main.js +16046 -1
  11. package/dist/opfs-storage.d.ts +1 -1
  12. package/dist/opfs-storage.js +2 -1
  13. package/dist/{opfsPersistentStorage-D_fecOJg.d.ts → opfsPersistentStorage-Ci0JcCo5.d.ts} +1 -1
  14. package/dist/opfsPersistentStorage-DqJXzF7M.js +892 -0
  15. package/dist/{types-DkNgE_f9.d.ts → types-D0ttVGmj.d.ts} +395 -65
  16. package/docs/README.md +16 -16
  17. package/docs/batch-fetching.md +1 -1
  18. package/docs/browser-tabs-sync.md +5 -2
  19. package/docs/collection-store.md +26 -24
  20. package/docs/document-store.md +8 -6
  21. package/docs/fetch-scheduling.md +18 -14
  22. package/docs/list-query-store.md +37 -35
  23. package/docs/mutations.md +2 -0
  24. package/docs/offline.md +2 -2
  25. package/docs/offset-pagination.md +1 -4
  26. package/docs/optimistic-list-updates.md +13 -17
  27. package/docs/partial-resources.md +26 -1
  28. package/docs/persistent-storage.md +4 -2
  29. package/docs/real-time-updates.md +7 -5
  30. package/docs/store-manager.md +41 -14
  31. package/package.json +6 -3
  32. package/dist/asyncStorageAdapter-CgG3vm0t.js +0 -1
  33. package/dist/asyncStorageAdapters-eagaD77Y.js +0 -1
  34. package/dist/indexedDbPersistentStorage-JYXvMjTG.js +0 -1
  35. package/dist/opfsPersistentStorage-DS-SWDSq.js +0 -1
package/dist/main.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { $ as OfflineResolutionRecord, A as DefineListQueryOfflineOperations, At as StoreError, B as OfflineEntityMutationKind, Bt as RequestSchedulerEventData, C as PersistentStorageSchema, Ct as OfflineUploadAdapter, D as CollectionOfflineOperationDefinition, Dt as OfflineUploadTransportContext, E as CollectionOfflineEntityRef, Et as OfflineUploadState, F as ListQueryOfflineEntityRef, Ft as ValidPayload, G as OfflineMutationQueueingPolicy, H as OfflineMutationInput, Ht as ScheduleFetchOptions, I as ListQueryOfflineOperationDefinition, It as ValidStoreState, J as OfflineReplayRetryConfig, K as OfflineOperationKind, L as OfflineAccumulationConfig, Lt as fetchTypePriority, M as DocumentOfflineOperationDefinition, Mt as StoreMutationError, N as GlobalOfflineEntity, Nt as StoreMutationErrorOptions, O as DefineCollectionOfflineOperations, Ot as MutationSkipped, P as GlobalOfflineStatus, Pt as TSDFStatus, Q as OfflineResolutionConflictParseErrorCode, R as OfflineAccumulationMergeContext, Rt as mutationSkipped, S as PersistentStoragePreloadResult, St as OfflineUpload, T as AnyOfflineOperationDefinition, Tt as OfflineUploadSource, U as OfflineMutationQueueingCause, Ut as ScheduleFetchResults, V as OfflineMutationDescriptor, Vt as RequestSchedulerEvents, W as OfflineMutationQueueingConfig, X as OfflineResolutionActionForOperation, Y as OfflineResolutionAction, Z as OfflineResolutionConflictParseError, _ as ListQueryOfflineOperationsConfig, _t as defaultOfflineRuntimeConfig, a as AsyncStorageMetadataOrder, at as OfflineSession, b as PersistentStorageDataSchema, bt as OfflineSessionUploadsConfig, c as AsyncStorageNamespaceCommitUpsert, ct as OfflineSyncState, d as AsyncStorageNamespaceKind, dt as OfflineTempEntityConfig, et as OfflineResolutionRecordForOperation, f as AsyncStorageNamespaceScope, ft as OfflineTempEntityPendingEntry, g as DocumentPersistentStorageConfig, gt as ParsedOfflineResolutionConflictResultForStore, h as ConvertedPersistentStorageDataSchema, ht as ParsedOfflineResolutionConflictResultForOperation, i as AsyncStorageDriverSetEntry, it as OfflineRuntimeConfigUpdate, j as DefineOfflineOperation, jt as StoreFetchError, k as DefineDocumentOfflineOperations, kt as PayloadDebounce, l as AsyncStorageNamespaceGetResult, lt as OfflineTempEntitiesConfig, m as CollectionPersistentStorageConfig, mt as OperationResult, n as AsyncStorageDiscoveredScope, nt as OfflineRetryExhaustedResolutionAction, o as AsyncStorageNamespaceCommitArgs, ot as OfflineSessionConfig, p as AsyncStorageReadOptions, pt as OperationConflict, q as OfflineQueueEntry, r as AsyncStorageDriver, rt as OfflineRuntimeConfig, s as AsyncStorageNamespaceCommitTouch, st as OfflineSupersedeConfig, t as AsyncStorageAdapter, tt as OfflineResolutionRecordForStore, u as AsyncStorageNamespaceHandle, ut as OfflineTempEntitiesReconciliation, v as ListQueryPersistentStorageConfig, vt as OfflineMutationUploadsInput, w as StorageAdapter, wt as OfflineUploadProgress, x as PersistentStorageErrorHandler, xt as OfflineStoredUploadRecord, y as PersistentStorageBaseConfig, yt as OfflineOperationUploadsContext, z as OfflineConflictResolutionAction, zt as FetchType } from "./types-DkNgE_f9.js";
1
+ import { $ as OfflineResolutionRecord, $t as StoreError, A as DefineListQueryOfflineOperations, At as DerivedQuerySource, B as OfflineEntityMutationKind, Bt as OptimisticListUpdate, C as PersistentStorageSchema, Ct as OfflineUploadAdapter, D as CollectionOfflineOperationDefinition, Dt as OfflineUploadTransportContext, E as CollectionOfflineEntityRef, Et as OfflineUploadState, F as ListQueryOfflineEntityRef, Ft as ListQueryUseMultipleItemsQuery, G as OfflineMutationQueueingPolicy, Gt as TSFDListQuery, H as OfflineMutationInput, Ht as QueryFetchPayload, I as ListQueryOfflineOperationDefinition, It as ListQueryUseMultipleListQueriesQuery, J as OfflineReplayRetryConfig, Jt as TSFDUseListQueryReturn, K as OfflineOperationKind, Kt as TSFDListQueryState, L as OfflineAccumulationConfig, Lt as OffsetPaginationConfig, M as DocumentOfflineOperationDefinition, Mt as FetchListFnReturnItem, N as GlobalOfflineEntity, Nt as FieldsInput, O as DefineCollectionOfflineOperations, Ot as DerivedQueriesConfig, P as GlobalOfflineStatus, Pt as FieldsOption, Q as OfflineResolutionConflictParseErrorCode, Qt as PayloadDebounce, R as OfflineAccumulationMergeContext, Rt as OnListQueryInvalidate, S as PersistentStoragePreloadResult, St as OfflineUpload, T as AnyOfflineOperationDefinition, Tt as OfflineUploadSource, U as OfflineMutationQueueingCause, Ut as QueryStatus, V as OfflineMutationDescriptor, Vt as PartialResourcesConfig, W as OfflineMutationQueueingConfig, Wt as TSDFItemQuery, X as OfflineResolutionActionForOperation, Xt as MaybeTSDFResult, Y as OfflineResolutionAction, Yt as TSFDUsePendingOfflineItemsReturn, Z as OfflineResolutionConflictParseError, Zt as MutationSkipped, _ as ListQueryOfflineOperationsConfig, _n as TSDFDebugLogger, _t as defaultOfflineRuntimeConfig, a as AsyncStorageMetadataOrder, an as ValidPayload, at as OfflineSession, b as PersistentStorageDataSchema, bt as OfflineSessionUploadsConfig, c as AsyncStorageNamespaceCommitUpsert, cn as mutationSkipped, ct as OfflineSyncState, d as AsyncStorageNamespaceKind, dn as RequestSchedulerEvents, dt as OfflineTempEntityConfig, en as StoreFetchError, et as OfflineResolutionRecordForOperation, f as AsyncStorageNamespaceScope, fn as ScheduleFetchOptions, ft as OfflineTempEntityPendingEntry, g as DocumentPersistentStorageConfig, gn as TSDFDebugLogLevel, gt as ParsedOfflineResolutionConflictResultForStore, h as ConvertedPersistentStorageDataSchema, hn as TSDFDebugLogEntry, ht as ParsedOfflineResolutionConflictResultForOperation, i as AsyncStorageDriverSetEntry, in as UnwrapTSDFResult, it as OfflineRuntimeConfigUpdate, j as DefineOfflineOperation, jt as FetchListFnReturn, k as DefineDocumentOfflineOperations, kt as DerivedQueryContext, l as AsyncStorageNamespaceGetResult, ln as FetchType, lt as OfflineTempEntitiesConfig, m as CollectionPersistentStorageConfig, mn as TSDFDebugLogArea, mt as OperationResult, n as AsyncStorageDiscoveredScope, nn as StoreMutationErrorOptions, nt as OfflineRetryExhaustedResolutionAction, o as AsyncStorageNamespaceCommitArgs, on as ValidStoreState, ot as OfflineSessionConfig, p as AsyncStorageReadOptions, pn as ScheduleFetchResults, pt as OperationConflict, q as OfflineQueueEntry, qt as TSFDUseListItemReturn, r as AsyncStorageDriver, rn as TSDFStatus, rt as OfflineRuntimeConfig, s as AsyncStorageNamespaceCommitTouch, sn as fetchTypePriority, st as OfflineSupersedeConfig, t as AsyncStorageAdapter, tn as StoreMutationError, tt as OfflineResolutionRecordForStore, u as AsyncStorageNamespaceHandle, un as RequestSchedulerEventData, ut as OfflineTempEntitiesReconciliation, v as ListQueryPersistentStorageConfig, vn as TSDFFocusDebugOperation, vt as OfflineMutationUploadsInput, w as StorageAdapter, wt as OfflineUploadProgress, x as PersistentStorageErrorHandler, xt as OfflineStoredUploadRecord, y as PersistentStorageBaseConfig, yn as TSDFLoggerOptions, yt as OfflineOperationUploadsContext, z as OfflineConflictResolutionAction, zt as OnListQueryItemInvalidate } from "./types-D0ttVGmj.js";
2
2
  import { __LEGIT_ANY__ } from "@ls-stack/utils/saferTyping";
3
3
  import { Emitter } from "evtmitter";
4
4
  import { Context } from "react";
@@ -13,26 +13,38 @@ import { Store } from "t-state";
13
13
  * `queued` means the mutation was durably persisted for offline replay.
14
14
  */
15
15
  type OfflineMutationResult<T> = {
16
- kind: 'online';
16
+ /** The direct online mutation completed successfully. */kind: 'online'; /** Server payload returned by the direct mutation. */
17
17
  data: Awaited<T>;
18
18
  } | {
19
- kind: 'queued';
19
+ /** The mutation was durably queued for offline replay. */kind: 'queued';
20
20
  };
21
21
  //#endregion
22
22
  //#region src/utils/performMutation.d.ts
23
+ /** Starts a temporary window-close block while a mutation is in progress. */
23
24
  type BlockWindowCloseHandler = () => {
24
- unblock: () => void;
25
+ /** Releases the window-close block. */unblock: () => void;
25
26
  };
27
+ /** Debounce settings for mutation calls sharing a logical context and payload. */
26
28
  type MutationDebounce = {
27
- context: string;
28
- payload: unknown;
29
+ /** Logical namespace for the debounced mutation group. */context: string; /** Payload compared with the context to decide which calls supersede each other. */
30
+ payload: unknown; /** Debounce window in milliseconds. */
29
31
  ms: number;
30
32
  };
31
33
  //#endregion
32
34
  //#region src/storeManager.d.ts
35
+ /** Minimum interval between realtime-update fetches, recomputed per fetch.
36
+ * When the window regains focus, a refetch still waiting on the unfocused
37
+ * interval is re-evaluated with the focused one, firing immediately if it has
38
+ * already elapsed. */
39
+ type DynamicRealtimeThrottleMs = (params: {
40
+ readonly lastFetchDuration: number;
41
+ readonly windowIsNotFocused: boolean;
42
+ }) => number;
33
43
  type StoreManagerStoreDefaults = {
34
44
  /** Default minimum interval between low-priority fetches for attached stores. */readonly lowPriorityThrottleMs: number; /** Default coalescing window used by attached stores when they do not override it. */
35
- readonly baseCoalescingWindowMs: number; /** Shared window-close blocker used by mutations in attached stores. */
45
+ readonly baseCoalescingWindowMs: number; /** Extra browser-tab coalescing delay applied only while a tab is in the background. */
46
+ readonly backgroundCoalescingDelayMs: number; /** Default adaptive throttle for real-time updates in attached stores. */
47
+ readonly dynamicRealtimeThrottleMs: DynamicRealtimeThrottleMs; /** Shared window-close blocker used by mutations in attached stores. */
36
48
  readonly blockWindowClose: BlockWindowCloseHandler | null; /** Default focus revalidation policy for attached stores. */
37
49
  readonly revalidateOnWindowFocus: boolean | (() => boolean) | undefined;
38
50
  };
@@ -63,8 +75,11 @@ type StoreManagerOfflineApi<TUploadRef extends ValidPayload = ValidPayload> = {
63
75
  useOfflineResolutions: () => readonly OfflineResolutionRecord[]; /** React hook subscribing to the manager's aggregated offline uploads. */
64
76
  useOfflineUploads: () => readonly OfflineUpload<TUploadRef>[];
65
77
  };
78
+ /** Shared coordinator passed to every TSDF store instance in an app/session. */
66
79
  type StoreManager<TUploadRef extends ValidPayload = ValidPayload> = {
67
- /** Returns the active shared session / tenant key. */getSessionKey: () => string | false; /** Normalizes raw exceptions into the shared StoreError shape. */
80
+ /** Returns the active shared session / tenant key. */getSessionKey: () => string | false; /** Shared debug logger for browser-tab sync, focus lifecycle, and persistent storage internals. */
81
+ debugLogger?: TSDFDebugLogger; /** Shared logger for low-volume production signals. */
82
+ logger?: TSDFDebugLogger; /** Normalizes raw exceptions into the shared StoreError shape. */
68
83
  errorNormalizer: (exception: Error) => StoreError; /** Global fallback for persistent storage failures in attached stores. */
69
84
  onPersistentStorageError: PersistentStorageErrorHandler | undefined; /** Global fallback for mutation failures in attached stores. */
70
85
  onMutationError: StoreManagerMutationErrorHandler | undefined; /** Shared defaults used by attached stores unless a store-level override exists. */
@@ -73,6 +88,7 @@ type StoreManager<TUploadRef extends ValidPayload = ValidPayload> = {
73
88
  resetAll: (ignoreStores: string[]) => void; /** Signals a shared real-time transport reconnect to all registered stores. */
74
89
  onTransportReconnect: () => void;
75
90
  } & StoreManagerOfflineApi<TUploadRef>;
91
+ /** Options used to create a shared TSDF store manager. */
76
92
  type CreateStoreManagerOptions<TUploadRef extends ValidPayload = ValidPayload> = {
77
93
  /**
78
94
  * Returns the current authenticated session / tenant key shared by all
@@ -80,13 +96,17 @@ type CreateStoreManagerOptions<TUploadRef extends ValidPayload = ValidPayload> =
80
96
  * behavior while no account is loaded.
81
97
  */
82
98
  getSessionKey: () => string | false; /** Normalizes raw exceptions into the shared StoreError shape. */
83
- errorNormalizer: (exception: Error) => StoreError; /** Default minimum interval between low-priority fetches for attached stores. Defaults to 5ms. */
84
- lowPriorityThrottleMs?: number; /** Default coalescing window for attached stores. Defaults to 10ms. */
85
- baseCoalescingWindowMs?: number; /** Shared window-close blocker used by mutations in attached stores. Pass `null` to disable. */
99
+ errorNormalizer: (exception: Error) => StoreError; /** Default minimum interval between low-priority fetches for attached stores. Defaults to 40 minutes. */
100
+ lowPriorityThrottleMs?: number; /** Default coalescing window for attached stores. Defaults to 16ms. */
101
+ baseCoalescingWindowMs?: number; /** Extra browser-tab coalescing delay applied only while a tab is in the background. Defaults to 3000ms. */
102
+ backgroundCoalescingDelayMs?: number; /** Default adaptive throttle for real-time updates in attached stores. Store-level values override it. */
103
+ dynamicRealtimeThrottleMs?: DynamicRealtimeThrottleMs; /** Shared window-close blocker used by mutations in attached stores. Pass `null` to disable. */
86
104
  blockWindowClose?: BlockWindowCloseHandler | null; /** Global fallback for persistent storage failures when a store does not provide its own handler. */
87
105
  onPersistentStorageError?: PersistentStorageErrorHandler; /** Global fallback for mutation failures when a store does not provide its own handler. */
88
106
  onMutationError?: StoreManagerMutationErrorHandler; /** Default focus revalidation policy for attached stores. Store-level values override it. */
89
- revalidateOnWindowFocus?: boolean | (() => boolean); /** Optional shared offline session config for every attached store. */
107
+ revalidateOnWindowFocus?: boolean | (() => boolean); /** Enables verbose development-only logs. Pass `true` to use console logging, or pass a logger function. */
108
+ debugLogger?: TSDFLoggerOptions; /** Enables low-volume production-safe logs. Defaults to console logging; pass `false` to disable. */
109
+ logger?: TSDFLoggerOptions; /** Optional shared offline session config for every attached store. */
90
110
  offlineSession?: OfflineSessionConfig<TUploadRef>;
91
111
  };
92
112
  declare function createStoreManager<TUploadRef extends ValidPayload = ValidPayload>(options: CreateStoreManagerOptions<TUploadRef>): StoreManager<TUploadRef>;
@@ -123,26 +143,31 @@ type UseItemOptions$1<ItemState extends ValidStoreState, Selected> = UseMultiple
123
143
  };
124
144
  //#endregion
125
145
  //#region src/collectionStore/collectionStore.d.ts
146
+ /** Lifecycle status for a cached collection item. */
126
147
  type CollectionItemStatus = TSDFStatus;
148
+ /** Raw cached state for one collection item. */
127
149
  type TSFDCollectionItem<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = {
128
- data: ItemState | null;
129
- error: StoreError | null;
130
- status: CollectionItemStatus;
131
- payload: ItemPayload;
132
- refetchOnMount: false | FetchType;
150
+ /** Latest loaded item data, or `null` before the item is available. */data: ItemState | null; /** Last fetch error for this item, when the latest fetch failed. */
151
+ error: StoreError | null; /** Current fetch lifecycle status for this item. */
152
+ status: CollectionItemStatus; /** Payload used to identify and fetch this item. */
153
+ payload: ItemPayload; /** Pending automatic refetch priority for stale data mounted by hooks. */
154
+ refetchOnMount: false | FetchType; /** Whether this item has ever loaded successfully. */
133
155
  wasLoaded: boolean;
134
156
  };
157
+ /** Raw t-state shape used by a collection store. */
135
158
  type TSFDCollectionState<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = Record<string, TSFDCollectionItem<ItemState, ItemPayload> | null>;
159
+ /** Value returned by `CollectionStore.useItem(...)` and `useMultipleItems(...)`. */
136
160
  type TSFDUseCollectionItemReturn<Selected, ItemPayload, QueryMetadata extends undefined | Record<string, unknown> = undefined> = {
137
- data: Selected;
138
- status: CollectionItemStatus | 'idle' | 'deleted';
139
- payload: ItemPayload | undefined;
140
- error: StoreError | null;
141
- itemStateKey: string;
161
+ /** Selected item data. Defaults to the full item or `null`. */data: Selected; /** Hook-visible item status, including idle/deleted states for hook ergonomics. */
162
+ status: CollectionItemStatus | 'idle' | 'deleted'; /** Item payload for this result, unless omitted or unavailable. */
163
+ payload: ItemPayload | undefined; /** Last item fetch error, if any. */
164
+ error: StoreError | null; /** Stable store key for the current item payload. */
165
+ itemStateKey: string; /** Convenience flag for `loading` or `refetching` states. */
142
166
  isLoading: boolean; /** Whether this result has local offline changes that still need to sync to the server. */
143
- pendingSync: boolean;
167
+ pendingSync: boolean; /** Caller-provided metadata copied from the query descriptor. */
144
168
  queryMetadata: QueryMetadata;
145
169
  };
170
+ /** Item descriptor accepted by `CollectionStore.useMultipleItems(...)`. */
146
171
  type CollectionUseMultipleItemsQuery<ItemPayload extends ValidPayload, QueryMetadata extends undefined | Record<string, unknown> = undefined> = {
147
172
  /** Item payload to subscribe to and fetch when needed. */payload: ItemPayload; /** Metadata returned with this query result for caller-side bookkeeping. */
148
173
  queryMetadata?: QueryMetadata; /** Omits `payload` from this query result. */
@@ -157,11 +182,13 @@ type CollectionUseMultipleItemsQuery<ItemPayload extends ValidPayload, QueryMeta
157
182
  returnRefetchingStatus?: boolean; /** Marks this subscription as off-screen, lowering automatic fetch priority. */
158
183
  isOffScreen?: boolean;
159
184
  };
185
+ /** Callback invoked when an already-loaded collection item is invalidated. */
160
186
  type OnCollectionItemInvalidate<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = (props: {
161
- itemState: ItemState;
162
- payload: ItemPayload;
187
+ /** Current cached item state at invalidation time. */itemState: ItemState; /** Payload of the invalidated item. */
188
+ payload: ItemPayload; /** Fetch priority requested for the invalidation. */
163
189
  priority: FetchType;
164
190
  }) => void;
191
+ /** Events emitted by collection mutation lifecycle helpers. */
165
192
  type CollectionStoreStoreEvents<ItemPayload extends ValidPayload> = {
166
193
  /** Emitted when a mutation begins executing */mutationStart: {
167
194
  mutationId: number;
@@ -177,9 +204,10 @@ type CollectionStoreStoreEvents<ItemPayload extends ValidPayload> = {
177
204
  finalPayload: ItemPayload;
178
205
  };
179
206
  };
207
+ /** Details passed when collection cache-limit cleanup evicts cached items. */
180
208
  type CollectionStateCleanup<ItemPayload extends ValidPayload> = {
181
- reason: 'cacheLimitEviction';
182
- itemKeys: string[];
209
+ /** Cleanup trigger that removed these items. */reason: 'cacheLimitEviction'; /** Store keys removed from the collection state. */
210
+ itemKeys: string[]; /** Original item payloads removed from the collection state. */
183
211
  payloads: ItemPayload[];
184
212
  };
185
213
  type InternalCollectionOfflineOperations<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = Record<string, AnyOfflineOperationDefinition & {
@@ -188,33 +216,34 @@ type InternalCollectionOfflineOperations<ItemState extends ValidStoreState, Item
188
216
  }) => CollectionOfflineEntityRef<ItemPayload>[];
189
217
  }> & ([ItemState | ItemPayload] extends [never] ? never : unknown);
190
218
  type CollectionOfflineOperationsConfig<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = InternalCollectionOfflineOperations<ItemState, ItemPayload> | null;
219
+ /** Options used to create a collection store. */
191
220
  type CollectionStoreOptions<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TOfflineOperations extends CollectionOfflineOperationsConfig<ItemState, ItemPayload> = null, StorageState = unknown> = {
192
221
  /**
193
222
  * Stable id for this logical collection store. Used for debug labels,
194
223
  * persistence namespaces, and browser tab sync.
195
224
  */
196
225
  id: string; /** Shared global store manager providing session scoping and error normalization. */
197
- storeManager: StoreManager;
198
- fetchFn: (params: ItemPayload, signal: AbortSignal) => Promise<ItemState>; /** Optional batch fetch function for fetching multiple items at once */
199
- batchFetchFn?: (payloads: ItemPayload[], signal: AbortSignal, batchKey: string) => Promise<Map<ItemPayload, ItemState | Error>>; /** Optional function to group batch fetches by key. Return false to fall back to individual fetchFn */
226
+ storeManager: StoreManager; /** Fetches one item by payload. */
227
+ fetchFn: (params: ItemPayload, signal: AbortSignal) => Promise<MaybeTSDFResult<ItemState>>; /** Optional batch fetch function for fetching multiple items at once */
228
+ batchFetchFn?: (payloads: ItemPayload[], signal: AbortSignal, batchKey: string) => Promise<MaybeTSDFResult<Map<ItemPayload, MaybeTSDFResult<ItemState> | Error>>>; /** Optional function to group batch fetches by key. When omitted, all batched items share one default batch key. Return false to fall back to individual fetchFn */
200
229
  getItemsBatchKey?: (payload: ItemPayload) => string | false; /** Max items per batch - triggers immediate fetch when reached */
201
230
  maxBatchSize?: number; /** Maximum number of cached items kept in memory. Defaults to 5,000. Inactive items are evicted in LRU order, while mounted hook items stay protected. */
202
231
  maxItems?: number; /** Called when cache-limit eviction removes items from in-memory state. */
203
- onStateCleanup?: (cleanup: CollectionStateCleanup<ItemPayload>) => void;
232
+ onStateCleanup?: (cleanup: CollectionStateCleanup<ItemPayload>) => void; /** Converts an item payload to the stable cache key used by this store. */
204
233
  getCollectionItemKey?: (params: ItemPayload) => ValidPayload | unknown[]; /** Overrides the manager's default minimum interval between low-priority fetches for this store. */
205
234
  lowPriorityThrottleMs?: number; /** Overrides the manager's default coalescing window for this store. */
206
- baseCoalescingWindowMs?: number;
207
- mediumPriorityDelayMs?: number;
235
+ baseCoalescingWindowMs?: number; /** Delay applied to medium-priority requests before they enter the scheduler. */
236
+ mediumPriorityDelayMs?: number; /** Computes a per-fetch throttle for real-time updates using recent fetch cost and focus state. */
208
237
  dynamicRealtimeThrottleMs?: (params: {
209
238
  lastFetchDuration: number;
210
239
  windowIsNotFocused: boolean;
211
- }) => number;
240
+ }) => number; /** Store-level focus revalidation policy. Overrides the manager default. */
212
241
  revalidateOnWindowFocus?: boolean | (() => boolean);
213
- /** Reconnect-specific cooldown. The first reconnect revalidates immediately;
242
+ /** Reconnect-specific cooldown. Defaults to 2,000ms. The first reconnect revalidates immediately;
214
243
  * additional reconnects within the cooldown are coalesced into one trailing
215
244
  * revalidation. Set to `0` to disable this cooldown. */
216
- transportReconnectCooldownMs?: number;
217
- onInvalidate?: OnCollectionItemInvalidate<ItemState, ItemPayload>;
245
+ transportReconnectCooldownMs?: number; /** Called when an already-loaded item is invalidated. */
246
+ onInvalidate?: OnCollectionItemInvalidate<ItemState, ItemPayload>; /** Observes request scheduler lifecycle events for this store. */
218
247
  onSchedulerEvent?: (event: RequestSchedulerEvents, data?: RequestSchedulerEventData) => void;
219
248
  /**
220
249
  * Store-specific mutation error handler.
@@ -222,7 +251,7 @@ type CollectionStoreOptions<ItemState extends ValidStoreState, ItemPayload exten
222
251
  * Overrides the manager fallback. Use `null` to disable inherited mutation
223
252
  * error handling for this store.
224
253
  */
225
- onMutationError?: ((error: unknown, options: StoreMutationErrorOptions) => void) | null;
254
+ onMutationError?: ((error: unknown, options: StoreMutationErrorOptions) => void) | null; /** Treats refetches as real-time driven, disabling stale mount refetches by default. Defaults to `false`. */
226
255
  usesRealTimeUpdates?: boolean;
227
256
  /** Opt-in persistent storage configuration. When provided, cached items are loaded
228
257
  * from storage on first read and saved back on successful fetches.
@@ -230,9 +259,10 @@ type CollectionStoreOptions<ItemState extends ValidStoreState, ItemPayload exten
230
259
  * persisted namespace always reuses this store's `id`. */
231
260
  persistentStorage?: CollectionPersistentStorageConfig<ItemState, ItemPayload, StorageState, TOfflineOperations>;
232
261
  };
262
+ /** Event payloads emitted by `CollectionStore.events`. */
233
263
  type CollectionStoreEvents = {
234
- invalidateData: {
235
- priority: FetchType;
264
+ /** Emitted whenever one or more cached items are invalidated. */invalidateData: {
265
+ /** Fetch priority requested by the invalidation. */priority: FetchType; /** Store key for the invalidated item. */
236
266
  itemKey: string;
237
267
  };
238
268
  };
@@ -249,7 +279,7 @@ type CollectionMutationArgsBase<T, ItemPayload extends ValidPayload> = {
249
279
  */
250
280
  optimisticUpdate?: (payload: CollectionMutationPayloadToUse<ItemPayload>) => void | boolean; /** Performs the server mutation for the affected item payloads. */
251
281
  mutation: (payload: CollectionMutationPayloadToUse<ItemPayload>) => Promise<T>; /** Called after a successful online mutation. */
252
- onSuccess?: (response: Awaited<T>, payload: CollectionMutationPayloadToUse<ItemPayload>) => void; /** Invalidates affected items after a successful online mutation. */
282
+ onSuccess?: (response: UnwrapTSDFResult<Awaited<T>>, payload: CollectionMutationPayloadToUse<ItemPayload>) => void; /** Invalidates affected items after a successful online mutation. */
253
283
  revalidateOnSuccess?: boolean;
254
284
  /**
255
285
  * Passes `{ silentErrors: true }` to `onMutationError`.
@@ -269,25 +299,55 @@ type CollectionOnlineMutationArgs<T, ItemPayload extends ValidPayload> = Collect
269
299
  upload?: undefined;
270
300
  };
271
301
  type CollectionOfflineMutationArgs<T, ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TOfflineOperations extends CollectionOfflineOperationsConfig<ItemState, ItemPayload>> = CollectionMutationArgsBase<T, ItemPayload> & {
272
- offline: TOfflineOperations extends null ? never : OfflineMutationInput<Exclude<TOfflineOperations, null>>;
302
+ /**
303
+ * Queues this mutation through the store's registered offline operation when
304
+ * the session is offline or the direct request fails with an offline outage.
305
+ */
306
+ offline: TOfflineOperations extends null ? never : OfflineMutationInput<Exclude<TOfflineOperations, null>>; /** Files to attach if this mutation is queued for offline replay. */
273
307
  upload?: OfflineMutationUploadsInput;
274
308
  };
275
309
  type CollectionPerformMutation<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TOfflineOperations extends CollectionOfflineOperationsConfig<ItemState, ItemPayload>> = {
276
- <T>(payload: CollectionMutationTarget<ItemPayload>, args: CollectionOnlineMutationArgs<T, ItemPayload>): Promise<Result<Awaited<T>, StoreMutationError | MutationSkipped>>;
277
- <T>(payload: CollectionMutationTarget<ItemPayload>, args: CollectionOfflineMutationArgs<T, ItemState, ItemPayload, TOfflineOperations>): Promise<Result<OfflineMutationResult<T>, StoreMutationError | MutationSkipped>>;
278
- <T>(payload: null, args: Omit<CollectionOnlineMutationArgs<T, ItemPayload>, 'optimisticUpdate'>): Promise<Result<Awaited<T>, StoreMutationError | MutationSkipped>>;
279
- <T>(payload: null, args: Omit<CollectionOfflineMutationArgs<T, ItemState, ItemPayload, TOfflineOperations>, 'optimisticUpdate'>): Promise<Result<OfflineMutationResult<T>, StoreMutationError | MutationSkipped>>;
280
- <T>(payload: CollectionMutationPayload<ItemPayload>, args: CollectionOnlineMutationArgs<T, ItemPayload> | CollectionOfflineMutationArgs<T, ItemState, ItemPayload, TOfflineOperations>): Promise<Result<Awaited<T> | OfflineMutationResult<T>, StoreMutationError | MutationSkipped>>;
310
+ /**
311
+ * Runs a collection mutation for one or more existing item payloads.
312
+ *
313
+ * Returns the direct server result when offline replay is not configured for
314
+ * this call.
315
+ */
316
+ <T>(payload: CollectionMutationTarget<ItemPayload>, args: CollectionOnlineMutationArgs<T, ItemPayload>): Promise<Result<UnwrapTSDFResult<Awaited<T>>, StoreMutationError | MutationSkipped>>;
317
+ /**
318
+ * Runs a collection mutation for one or more existing item payloads, with
319
+ * durable offline queueing as a fallback.
320
+ *
321
+ * When the mutation is queued, the result is `{ kind: 'queued' }` instead of
322
+ * the server payload.
323
+ */
324
+ <T>(payload: CollectionMutationTarget<ItemPayload>, args: CollectionOfflineMutationArgs<T, ItemState, ItemPayload, TOfflineOperations>): Promise<Result<OfflineMutationResult<UnwrapTSDFResult<Awaited<T>>>, StoreMutationError | MutationSkipped>>;
325
+ /**
326
+ * Runs a collection mutation with no current item target.
327
+ *
328
+ * Use this for create mutations that do not have a pre-generated item payload
329
+ * yet. Optimistic updates are not available without a target payload.
330
+ */
331
+ <T>(payload: null, args: Omit<CollectionOnlineMutationArgs<T, ItemPayload>, 'optimisticUpdate'>): Promise<Result<UnwrapTSDFResult<Awaited<T>>, StoreMutationError | MutationSkipped>>;
332
+ /**
333
+ * Runs an offline-capable collection mutation with no current item target.
334
+ *
335
+ * Use this for create mutations that do not have a pre-generated item payload
336
+ * yet. When the mutation is queued, the result is `{ kind: 'queued' }`.
337
+ */
338
+ <T>(payload: null, args: Omit<CollectionOfflineMutationArgs<T, ItemState, ItemPayload, TOfflineOperations>, 'optimisticUpdate'>): Promise<Result<OfflineMutationResult<UnwrapTSDFResult<Awaited<T>>>, StoreMutationError | MutationSkipped>>;
339
+ <T>(payload: CollectionMutationPayload<ItemPayload>, args: CollectionOnlineMutationArgs<T, ItemPayload> | CollectionOfflineMutationArgs<T, ItemState, ItemPayload, TOfflineOperations>): Promise<Result<UnwrapTSDFResult<Awaited<T>> | OfflineMutationResult<UnwrapTSDFResult<Awaited<T>>>, StoreMutationError | MutationSkipped>>;
281
340
  };
341
+ /** Public API returned by `createCollectionStore(...)`. */
282
342
  type CollectionStore<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TOfflineOperations extends CollectionOfflineOperationsConfig<ItemState, ItemPayload> = null> = {
283
- store: Store<TSFDCollectionState<ItemState, ItemPayload>>;
284
- events: Emitter<CollectionStoreEvents>;
285
- storeEvents: Emitter<CollectionStoreStoreEvents<ItemPayload>>;
286
- readonly invalidationWasTriggered: Set<string>;
343
+ /** Underlying t-state store containing raw cached items. */store: Store<TSFDCollectionState<ItemState, ItemPayload>>; /** Invalidation event emitter used by hooks and integrations. */
344
+ events: Emitter<CollectionStoreEvents>; /** Mutation lifecycle event emitter for observers and tests. */
345
+ storeEvents: Emitter<CollectionStoreStoreEvents<ItemPayload>>; /** Item keys that have been explicitly invalidated and are awaiting refresh. */
346
+ readonly invalidationWasTriggered: Set<string>; /** Schedules a fetch for one item or a batch of item payloads. */
287
347
  scheduleFetch: {
288
348
  (fetchType: FetchType, payload: ItemPayload, options?: ScheduleFetchOptions): ScheduleFetchResults;
289
349
  (fetchType: FetchType, payload: ItemPayload[], options?: ScheduleFetchOptions): ScheduleFetchResults[];
290
- };
350
+ }; /** Waits for an item fetch to settle and returns data or a fetch error. */
291
351
  awaitFetch: (params: ItemPayload, options?: {
292
352
  timeoutMs?: number;
293
353
  }) => Promise<{
@@ -296,25 +356,25 @@ type CollectionStore<ItemState extends ValidStoreState, ItemPayload extends Vali
296
356
  } | {
297
357
  data: null;
298
358
  error: StoreFetchError;
299
- }>;
359
+ }>; /** Returns cached item data when usable, otherwise fetches it first. */
300
360
  getItemFromStateOrFetch: (params: ItemPayload, options?: {
301
- ignoreStaleState?: boolean;
361
+ /** When `true`, stale cached data is ignored and refetched before returning. Defaults to `false`. */ignoreStaleState?: boolean;
302
362
  timeoutMs?: number;
303
- }) => Promise<Result<ItemState, StoreFetchError>>;
304
- useMultipleItems: <Selected = ItemState | null, QueryMetadata extends undefined | Record<string, unknown> = undefined>(items: CollectionUseMultipleItemsQuery<ItemPayload, QueryMetadata>[], options?: UseMultipleItemsOptions$1<ItemState, Selected>) => readonly TSFDUseCollectionItemReturn<Selected, ItemPayload, QueryMetadata>[];
305
- useItem: <Selected = ItemState | null>(payload: ItemPayload | undefined | false | null, options?: UseItemOptions$1<ItemState, Selected>) => TSFDUseCollectionItemReturn<Selected, ItemPayload>;
363
+ }) => Promise<Result<ItemState, StoreFetchError>>; /** React hook for subscribing to many collection items at once. */
364
+ useMultipleItems: <Selected = ItemState | null, QueryMetadata extends undefined | Record<string, unknown> = undefined>(items: CollectionUseMultipleItemsQuery<ItemPayload, QueryMetadata>[], options?: UseMultipleItemsOptions$1<ItemState, Selected>) => readonly TSFDUseCollectionItemReturn<Selected, ItemPayload, QueryMetadata>[]; /** React hook for subscribing to one collection item. */
365
+ useItem: <Selected = ItemState | null>(payload: ItemPayload | undefined | false | null, options?: UseItemOptions$1<ItemState, Selected>) => TSFDUseCollectionItemReturn<Selected, ItemPayload>; /** React hook that tracks whether a nested list item is still loading. */
306
366
  useListItemIsLoading: (payload: ItemPayload, args: {
307
367
  /** Unique identifier of the sub-item within the collection item. */itemId: string; /** Extracts the sub-item from the collection item data. */
308
368
  selector: (data: ItemState | null) => unknown; /** Called if the sub-item is still missing and no refetch is in progress. */
309
369
  loadItemFallback?: () => void; /** Forces a high-priority fetch and keeps the hook loading until data is loaded. */
310
370
  ensureIsLoaded?: boolean;
311
- }) => boolean;
371
+ }) => boolean; /** React hook that tracks whether a nested list item has been deleted. */
312
372
  useListItemIsDeleted: (payload: ItemPayload, args: {
313
373
  /** Unique identifier of the sub-item within the collection item. */itemId: string; /** Extracts the sub-item from the collection item data. */
314
374
  selector: (data: ItemState | null) => unknown; /** Called once when deletion is detected. */
315
375
  onDelete?: () => void; /** Forces a high-priority fetch and keeps the hook loading until data is loaded. */
316
376
  ensureIsLoaded?: boolean;
317
- }) => boolean;
377
+ }) => boolean; /** React hook for selecting one nested list item plus loading/deleted flags. */
318
378
  useListItem: <Selected>(payload: ItemPayload, args: {
319
379
  /** Unique identifier of the sub-item within the collection item. */itemId: string; /** Extracts and maps the sub-item from the collection item data. */
320
380
  selector: (data: ItemState | null) => Selected; /** Called if the sub-item is still missing and no refetch is in progress. */
@@ -325,52 +385,61 @@ type CollectionStore<ItemState extends ValidStoreState, ItemPayload extends Vali
325
385
  isLoading: boolean;
326
386
  isDeleted: boolean;
327
387
  data: Selected;
328
- };
329
- reset: () => void;
330
- dispose: () => void;
331
- preloadItemFromStorage: (params: ItemPayload | ItemPayload[]) => Promise<PersistentStoragePreloadResult<ItemPayload>[]>;
332
- getItemKey: (params: ItemPayload) => string;
388
+ }; /** Clears in-memory state and cancels store-local runtime state. */
389
+ reset: () => void; /** Unregisters listeners and releases resources owned by this store. */
390
+ dispose: () => void; /** Loads item payloads from persistent storage into memory when available. */
391
+ preloadItemFromStorage: (params: ItemPayload | ItemPayload[]) => Promise<PersistentStoragePreloadResult<ItemPayload>[]>; /** Returns the stable cache key for an item payload. */
392
+ getItemKey: (params: ItemPayload) => string; /** Reads one or many cached items directly from store state. */
333
393
  getItemState: {
334
394
  (params: ItemPayload): TSFDCollectionItem<ItemState, ItemPayload> | undefined | null;
335
395
  (params: ItemPayload[] | CollectionFilterItemsFn<ItemState, ItemPayload>): TSFDCollectionItem<ItemState, ItemPayload>[];
336
- };
337
- getOfflineEntities: () => GlobalOfflineEntity[];
338
- useOfflineEntities: () => readonly GlobalOfflineEntity[];
339
- useOfflineResolutions: () => readonly OfflineResolutionRecord[];
340
- getOfflineResolutions: () => OfflineResolutionRecord[];
341
- parseOfflineResolutionConflict: (resolution: OfflineResolutionRecord) => ParsedOfflineResolutionConflictResultForStore<ResolvedCollectionOfflineOperations<TOfflineOperations>>;
342
- resolveOfflineResolution: <TName extends keyof ResolvedCollectionOfflineOperations<TOfflineOperations> & string>(resolutionId: string, operationName: TName, resolution: OfflineResolutionActionForOperation<ResolvedCollectionOfflineOperations<TOfflineOperations>, TName>) => Promise<void> | void;
343
- startMutation: (fetchParams: ItemPayload | ItemPayload[] | CollectionFilterItemsFn<ItemState, ItemPayload>) => () => void;
344
- invalidateItem: (itemPayload: ItemPayload | ItemPayload[] | CollectionFilterItemsFn<ItemState, ItemPayload>, priority?: FetchType) => void;
396
+ }; /** Returns offline sync metadata for this store's tracked entities. */
397
+ getOfflineEntities: () => GlobalOfflineEntity[]; /** React hook subscribing to this store's offline entity metadata. */
398
+ useOfflineEntities: () => readonly GlobalOfflineEntity[]; /** React hook subscribing to manual offline resolutions for this store. */
399
+ useOfflineResolutions: () => readonly OfflineResolutionRecord[]; /** Returns manual offline resolutions for this store. */
400
+ getOfflineResolutions: () => OfflineResolutionRecord[]; /** Parses a stored offline conflict into the operation-specific conflict shape. */
401
+ parseOfflineResolutionConflict: (resolution: OfflineResolutionRecord) => ParsedOfflineResolutionConflictResultForStore<ResolvedCollectionOfflineOperations<TOfflineOperations>>; /** Applies a retry/discard/requeue/commit action to a pending offline resolution. */
402
+ resolveOfflineResolution: <TName extends keyof ResolvedCollectionOfflineOperations<TOfflineOperations> & string>(resolutionId: string, operationName: TName, resolution: OfflineResolutionActionForOperation<ResolvedCollectionOfflineOperations<TOfflineOperations>, TName>) => Promise<void> | void; /** Marks one or more items as mutating and returns a function that ends the mutation. */
403
+ startMutation: (fetchParams: ItemPayload | ItemPayload[] | CollectionFilterItemsFn<ItemState, ItemPayload>) => () => void; /** Marks cached items stale and schedules refetches for active subscriptions. Defaults to `highPriority`. */
404
+ invalidateItem: (itemPayload: ItemPayload | ItemPayload[] | CollectionFilterItemsFn<ItemState, ItemPayload>, /** Fetch priority used for refetches triggered by this invalidation. Defaults to `highPriority`. */
405
+
406
+ priority?: FetchType) => void; /** Applies an immutable update to one or more cached collection items. */
345
407
  updateItemState: (fetchParams: ItemPayload | ItemPayload[] | CollectionFilterItemsFn<ItemState, ItemPayload>, produceNewData: (draftData: ItemState, collectionItem: TSFDCollectionItem<ItemState, ItemPayload>) => void | ItemState, options?: {
346
408
  ifNothingWasUpdated?: () => void;
347
- }) => boolean;
348
- addItemToState: (fetchParams: ItemPayload, data: ItemState) => void;
409
+ }) => boolean; /** Adds or replaces one cached item directly in state. */
410
+ addItemToState: (fetchParams: ItemPayload, data: ItemState) => void; /** Deletes one or more cached items directly from state. */
349
411
  deleteItemState: (fetchParams: ItemPayload | ItemPayload[] | CollectionFilterItemsFn<ItemState, ItemPayload>) => void;
350
- performMutation: CollectionPerformMutation<ItemState, ItemPayload, TOfflineOperations>;
412
+ /**
413
+ * Runs the full mutation lifecycle: optional optimistic update, async
414
+ * mutation, rollback/error handling, revalidation, and offline queue fallback.
415
+ */
416
+ performMutation: CollectionPerformMutation<ItemState, ItemPayload, TOfflineOperations>; /** Notifies the store that a shared transport reconnected and should revalidate active data. */
351
417
  onTransportReconnect: () => void;
352
418
  };
353
419
  declare function createCollectionStore<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TOfflineOperations extends CollectionOfflineOperationsConfig<ItemState, ItemPayload> = null, StorageState = unknown>(storeOptions: CollectionStoreOptions<ItemState, ItemPayload, TOfflineOperations, StorageState>): CollectionStore<ItemState, ItemPayload, TOfflineOperations>;
354
420
  //#endregion
355
421
  //#region src/documentStore.d.ts
422
+ /** Lifecycle status for a document store. */
356
423
  type DocumentStatus = 'idle' | TSDFStatus;
424
+ /** Value returned by `DocumentStore.useDocument(...)`. */
357
425
  type TSDFUseDocumentReturn<Selected> = {
358
- status: DocumentStatus;
359
- data: Selected;
360
- error: StoreError | null;
426
+ /** Hook-visible document status. */status: DocumentStatus; /** Selected document data. Defaults to the full document or `null`. */
427
+ data: Selected; /** Last document fetch error, if any. */
428
+ error: StoreError | null; /** Convenience flag for `loading` or `refetching` states. */
361
429
  isLoading: boolean; /** Whether this result has local offline changes that still need to sync to the server. */
362
430
  pendingSync: boolean;
363
431
  };
364
432
  type DocumentStoreState<State extends ValidStoreState> = {
365
- data: State | null;
366
- error: StoreError | null;
367
- status: DocumentStatus;
433
+ /** Latest loaded document data, or `null` before the document is available. */data: State | null; /** Last fetch error for this document, when the latest fetch failed. */
434
+ error: StoreError | null; /** Current fetch lifecycle status for the document. */
435
+ status: DocumentStatus; /** Pending automatic refetch priority for stale data mounted by hooks. */
368
436
  refetchOnMount: false | FetchType;
369
437
  };
370
438
  type DocumentStoreEvents = {
371
439
  invalidateData: FetchType;
372
440
  };
373
441
  type OnDocumentInvalidate = (priority: FetchType) => void;
442
+ /** Events emitted by document mutation lifecycle helpers. */
374
443
  type DocumentStoreStoreEvents = {
375
444
  /** Emitted when a mutation begins executing */mutationStart: {
376
445
  mutationId: number;
@@ -389,19 +458,19 @@ type DocumentStoreOptions<State extends ValidStoreState, TOfflineOperations exte
389
458
  */
390
459
  id: string; /** Shared global store manager providing session scoping and error normalization. */
391
460
  storeManager: StoreManager;
392
- fetchFn: (signal: AbortSignal) => Promise<State>; /** Overrides the manager's default minimum interval between low-priority fetches for this store. */
461
+ fetchFn: (signal: AbortSignal) => Promise<MaybeTSDFResult<State>>; /** Overrides the manager's default minimum interval between low-priority fetches for this store. */
393
462
  lowPriorityThrottleMs?: number; /** Overrides the manager's default coalescing window for this store. */
394
- baseCoalescingWindowMs?: number;
463
+ baseCoalescingWindowMs?: number; /** Computes a per-fetch throttle for real-time updates using recent fetch cost and focus state. */
395
464
  dynamicRealtimeThrottleMs?: (params: {
396
465
  lastFetchDuration: number;
397
466
  windowIsNotFocused: boolean;
398
- }) => number;
467
+ }) => number; /** Store-level focus revalidation policy. Overrides the manager default. */
399
468
  revalidateOnWindowFocus?: boolean | (() => boolean);
400
- /** Reconnect-specific cooldown. The first reconnect revalidates immediately;
469
+ /** Reconnect-specific cooldown. Defaults to 2,000ms. The first reconnect revalidates immediately;
401
470
  * additional reconnects within the cooldown are coalesced into one trailing
402
471
  * revalidation. Set to `0` to disable this cooldown. */
403
- transportReconnectCooldownMs?: number;
404
- mediumPriorityDelayMs?: number;
472
+ transportReconnectCooldownMs?: number; /** Delay applied to medium-priority requests before they enter the scheduler. */
473
+ mediumPriorityDelayMs?: number; /** Observes request scheduler lifecycle events for this store. */
405
474
  onSchedulerEvent?: (event: RequestSchedulerEvents, data?: RequestSchedulerEventData) => void;
406
475
  /**
407
476
  * Store-specific mutation error handler.
@@ -410,6 +479,9 @@ type DocumentStoreOptions<State extends ValidStoreState, TOfflineOperations exte
410
479
  * error handling for this store.
411
480
  */
412
481
  onMutationError?: ((error: unknown, options: StoreMutationErrorOptions) => void) | null;
482
+ /** Indicates that fresh data arrives via a real-time channel. Defaults to `false`. The store
483
+ * skips the mount-time stale refetch since real-time pushes already cover
484
+ * revalidation. */
413
485
  usesRealTimeUpdates?: boolean;
414
486
  /** Opt-in persistent storage configuration. When provided, cached data is loaded
415
487
  * from storage on first read and saved back on successful fetches.
@@ -451,20 +523,36 @@ type DocumentOnlineMutationArgs<State extends ValidStoreState, T> = DocumentMuta
451
523
  upload?: undefined;
452
524
  };
453
525
  type DocumentOfflineMutationArgs<State extends ValidStoreState, T, TOfflineOperations extends DocumentOfflineOperationsConfig<State>> = DocumentMutationArgsBase<State, T> & {
454
- offline: TOfflineOperations extends null ? never : OfflineMutationInput<Exclude<TOfflineOperations, null>>;
526
+ /**
527
+ * Queues this mutation through the store's registered offline operation when
528
+ * the session is offline or the direct request fails with an offline outage.
529
+ */
530
+ offline: TOfflineOperations extends null ? never : OfflineMutationInput<Exclude<TOfflineOperations, null>>; /** Files to attach if this mutation is queued for offline replay. */
455
531
  upload?: OfflineMutationUploadsInput;
456
532
  };
457
533
  type DocumentPerformMutation<State extends ValidStoreState, TOfflineOperations extends DocumentOfflineOperationsConfig<State>> = {
458
- <T>(args: DocumentOnlineMutationArgs<State, T>): Promise<Result<Awaited<T>, StoreMutationError | MutationSkipped>>;
459
- <T>(args: DocumentOfflineMutationArgs<State, T, TOfflineOperations>): Promise<Result<OfflineMutationResult<T>, StoreMutationError | MutationSkipped>>;
460
- <T>(args: DocumentOnlineMutationArgs<State, T> | DocumentOfflineMutationArgs<State, T, TOfflineOperations>): Promise<Result<Awaited<T> | OfflineMutationResult<T>, StoreMutationError | MutationSkipped>>;
534
+ /**
535
+ * Runs a document mutation with optional optimistic updates and revalidation.
536
+ *
537
+ * Returns the direct server result when offline replay is not configured for
538
+ * this call.
539
+ */
540
+ <T>(args: DocumentOnlineMutationArgs<State, T>): Promise<Result<UnwrapTSDFResult<Awaited<T>>, StoreMutationError | MutationSkipped>>;
541
+ /**
542
+ * Runs a document mutation that may fall back to durable offline queueing.
543
+ *
544
+ * When the mutation is queued, the result is `{ kind: 'queued' }` instead of
545
+ * the server payload.
546
+ */
547
+ <T>(args: DocumentOfflineMutationArgs<State, T, TOfflineOperations>): Promise<Result<OfflineMutationResult<UnwrapTSDFResult<Awaited<T>>>, StoreMutationError | MutationSkipped>>;
548
+ <T>(args: DocumentOnlineMutationArgs<State, T> | DocumentOfflineMutationArgs<State, T, TOfflineOperations>): Promise<Result<UnwrapTSDFResult<Awaited<T>> | OfflineMutationResult<UnwrapTSDFResult<Awaited<T>>>, StoreMutationError | MutationSkipped>>;
461
549
  };
462
550
  type DocumentStore<State extends ValidStoreState, TOfflineOperations extends DocumentOfflineOperationsConfig<State> = null> = {
463
- store: Store<DocumentStoreState<State>>;
464
- events: Emitter<DocumentStoreEvents>;
465
- storeEvents: Emitter<DocumentStoreStoreEvents>;
466
- readonly invalidationWasTriggered: boolean;
467
- scheduleFetch: (fetchType: FetchType, options?: ScheduleFetchOptions) => ScheduleFetchResults;
551
+ /** Underlying t-state store containing the raw document cache state. */store: Store<DocumentStoreState<State>>; /** Invalidation event emitter used by hooks and integrations. */
552
+ events: Emitter<DocumentStoreEvents>; /** Mutation lifecycle event emitter for observers and tests. */
553
+ storeEvents: Emitter<DocumentStoreStoreEvents>; /** Whether the document has been explicitly invalidated and is awaiting refresh. */
554
+ readonly invalidationWasTriggered: boolean; /** Schedules a document fetch with the requested priority. */
555
+ scheduleFetch: (fetchType: FetchType, options?: ScheduleFetchOptions) => ScheduleFetchResults; /** Waits for a document fetch to settle and returns data or a fetch error. */
468
556
  awaitFetch: (options?: {
469
557
  timeoutMs?: number;
470
558
  }) => Promise<{
@@ -473,22 +561,24 @@ type DocumentStore<State extends ValidStoreState, TOfflineOperations extends Doc
473
561
  } | {
474
562
  data: null;
475
563
  error: StoreFetchError;
476
- }>;
564
+ }>; /** Returns cached document data when usable, otherwise fetches it first. */
477
565
  getDataFromStateOrFetch: (options?: {
478
- ignoreStaleState?: boolean;
566
+ /** When `true`, stale cached data is ignored and refetched before returning. Defaults to `false`. */ignoreStaleState?: boolean;
479
567
  timeoutMs?: number;
480
- }) => Promise<Result<State, StoreFetchError>>;
481
- preloadPersistentStorage: () => Promise<void>;
482
- invalidateData: (priority?: FetchType) => void;
483
- updateState: DocumentUpdateState<State>;
484
- reset: () => void;
485
- dispose: () => void;
486
- startMutation: () => () => boolean;
487
- getOfflineEntities: () => GlobalOfflineEntity[];
488
- useOfflineEntities: () => readonly GlobalOfflineEntity[];
489
- useOfflineResolutions: () => readonly OfflineResolutionRecord[];
490
- getOfflineResolutions: () => OfflineResolutionRecord[];
491
- parseOfflineResolutionConflict: (resolution: OfflineResolutionRecord) => ParsedOfflineResolutionConflictResultForStore<ResolvedDocumentOfflineOperations<TOfflineOperations>>;
568
+ }) => Promise<Result<State, StoreFetchError>>; /** Loads cached document data from persistent storage when available. */
569
+ preloadPersistentStorage: () => Promise<void>; /** Marks the document stale and schedules refetches for active subscriptions. Defaults to `highPriority`. */
570
+ invalidateData: (/** Fetch priority used for refetches triggered by this invalidation. Defaults to `highPriority`. */
571
+
572
+ priority?: FetchType) => void; /** Applies an immutable update to the cached document data. */
573
+ updateState: DocumentUpdateState<State>; /** Clears in-memory state and cancels store-local runtime state. */
574
+ reset: () => void; /** Unregisters listeners and releases resources owned by this store. */
575
+ dispose: () => void; /** Marks the document as mutating and returns a function that ends the mutation. */
576
+ startMutation: () => () => boolean; /** Returns offline sync metadata for this store's tracked entity. */
577
+ getOfflineEntities: () => GlobalOfflineEntity[]; /** React hook subscribing to this store's offline entity metadata. */
578
+ useOfflineEntities: () => readonly GlobalOfflineEntity[]; /** React hook subscribing to manual offline resolutions for this store. */
579
+ useOfflineResolutions: () => readonly OfflineResolutionRecord[]; /** Returns manual offline resolutions for this store. */
580
+ getOfflineResolutions: () => OfflineResolutionRecord[]; /** Parses a stored offline conflict into the operation-specific conflict shape. */
581
+ parseOfflineResolutionConflict: (resolution: OfflineResolutionRecord) => ParsedOfflineResolutionConflictResultForStore<ResolvedDocumentOfflineOperations<TOfflineOperations>>; /** Applies a retry/discard/requeue/commit action to a pending offline resolution. */
492
582
  resolveOfflineResolution: <TName extends keyof ResolvedDocumentOfflineOperations<TOfflineOperations> & string>(resolutionId: string, operationName: TName, resolution: OfflineResolutionActionForOperation<ResolvedDocumentOfflineOperations<TOfflineOperations>, TName>) => Promise<void> | void;
493
583
  useDocument: <Selected = State | null>(args?: {
494
584
  /** Maps the document data before it is returned from the hook. */selector?: (data: State | null) => Selected; /** Disables this hook subscription and prevents automatic fetches. */
@@ -507,19 +597,19 @@ type DocumentStore<State extends ValidStoreState, TOfflineOperations extends Doc
507
597
  */
508
598
  ensureIsLoaded?: boolean; /** Returns `refetching` instead of keeping `loaded` status during refetches. */
509
599
  returnRefetchingStatus?: boolean;
510
- }) => TSDFUseDocumentReturn<Selected>;
600
+ }) => TSDFUseDocumentReturn<Selected>; /** React hook that tracks whether a nested list item is still loading. */
511
601
  useListItemIsLoading: (args: {
512
602
  /** Unique identifier of the item within the document. */itemId: string; /** Extracts the item from the document data. */
513
603
  selector: (data: State | null) => unknown; /** Called if the item is still missing and no refetch is in progress. */
514
604
  loadItemFallback?: () => void; /** Forces a high-priority fetch and keeps the hook loading until data is loaded. */
515
605
  ensureIsLoaded?: boolean;
516
- }) => boolean;
606
+ }) => boolean; /** React hook that tracks whether a nested list item has been deleted. */
517
607
  useListItemIsDeleted: (args: {
518
608
  /** Unique identifier of the item within the document. */itemId: string; /** Extracts the item from the document data. */
519
609
  selector: (data: State | null) => unknown; /** Called once when deletion is detected. */
520
610
  onDelete?: () => void; /** Forces a high-priority fetch and keeps the hook loading until data is loaded. */
521
611
  ensureIsLoaded?: boolean;
522
- }) => boolean;
612
+ }) => boolean; /** React hook for selecting one nested list item plus loading/deleted flags. */
523
613
  useListItem: <Selected>(args: {
524
614
  /** Unique identifier of the item within the document. */itemId: string; /** Extracts and maps the item from the document data. */
525
615
  selector: (data: State | null) => Selected; /** Called if the item is still missing and no refetch is in progress. */
@@ -531,220 +621,14 @@ type DocumentStore<State extends ValidStoreState, TOfflineOperations extends Doc
531
621
  isDeleted: boolean;
532
622
  data: Selected;
533
623
  };
534
- performMutation: DocumentPerformMutation<State, TOfflineOperations>;
535
- onTransportReconnect: () => void;
536
- };
537
- declare function createDocumentStore<State extends ValidStoreState, TOfflineOperations extends DocumentOfflineOperationsConfig<State> = null, StorageState = unknown>(storeOptions: DocumentStoreOptions<State, TOfflineOperations, StorageState>): DocumentStore<State, TOfflineOperations>;
538
- //#endregion
539
- //#region src/listQueryStore/types.d.ts
540
- type QueryStatus = TSDFStatus | 'loadingMore';
541
- type TSFDListQuery<QueryPayload extends ValidPayload> = {
542
- error: StoreError | null;
543
- status: QueryStatus;
544
- payload: QueryPayload;
545
- hasMore: boolean;
546
- wasLoaded: boolean;
547
- refetchOnMount: false | FetchType;
548
- items: string[];
549
- };
550
- type TSDFItemQuery<ItemPayload extends ValidPayload> = {
551
- error: StoreError | null;
552
- status: Exclude<QueryStatus, 'loadingMore'>;
553
- wasLoaded: boolean;
554
- refetchOnMount: false | FetchType;
555
- payload: ItemPayload;
556
- };
557
- type TSFDListQueryState<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = {
558
- items: Record<string, ItemState | null>;
559
- queries: Record<string, TSFDListQuery<QueryPayload>>;
560
- itemQueries: Record<string, TSDFItemQuery<ItemPayload> | null>;
561
- itemLoadedFields: Record<string, string[]>;
562
- itemFieldInvalidationFields: Record<string, string[]>;
563
- };
564
- /**
565
- * Partial-resource fields to request.
566
- *
567
- * Pass a field-name array to load only those fields, or `'*'` to load the
568
- * complete item.
569
- */
570
- type FieldsInput = string[] | '*';
571
- type TSFDUseListQueryReturn<Selected, QueryPayload, QueryMetadata extends undefined | Record<string, unknown> = undefined, HasPartialResources extends boolean = false> = {
572
- items: Selected[];
573
- status: QueryStatus | 'idle';
574
- payload: QueryPayload | undefined;
575
- fields: HasPartialResources extends true ? FieldsInput : FieldsInput | undefined; /** Requested partial-resource fields that are still pending. */
576
- loadingFields?: string[];
577
- error: StoreError | null;
578
- queryKey: string;
579
- hasMore: boolean;
580
- isDerived: boolean;
581
- isLoading: boolean;
582
- isLoadingMore: boolean; /** Whether this result has local offline changes that still need to sync to the server. */
583
- pendingSync: boolean;
584
- queryMetadata: QueryMetadata;
585
- };
586
- type TSFDUseListItemReturn<Selected, ItemPayload, QueryMetadata extends undefined | Record<string, unknown> = undefined> = {
587
- data: Selected;
588
- status: QueryStatus | 'idle' | 'deleted';
589
- payload: ItemPayload | null; /** Requested partial-resource fields that are still pending. */
590
- loadingFields?: string[];
591
- error: StoreError | null;
592
- isLoading: boolean;
593
- itemStateKey: string; /** Whether this result has local offline changes that still need to sync to the server. */
594
- pendingSync: boolean;
595
- queryMetadata: QueryMetadata;
596
- };
597
- type TSFDUsePendingOfflineItemsReturn<Selected, ItemPayload extends ValidPayload> = {
598
- items: Selected[];
599
- deletedItems: ItemPayload[];
600
- };
601
- type FetchListFnReturnItem<ItemPayload extends ValidPayload, ItemState extends ValidStoreState> = {
602
- itemPayload: ItemPayload;
603
- data: ItemState;
604
- };
605
- type FetchListFnReturn<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = {
606
- items: FetchListFnReturnItem<ItemPayload, ItemState>[];
607
- hasMore: boolean;
608
- };
609
- type ListQueryUseMultipleItemsQuery<ItemPayload extends ValidPayload, QueryMetadata extends undefined | Record<string, unknown> = undefined> = {
610
- /** Item payload to subscribe to and fetch when needed. */payload: ItemPayload;
611
- /**
612
- * Partial-resource fields to request for this item.
613
- *
614
- * Pass `'*'` to fetch the complete item. This option is required when
615
- * `partialResources` is enabled and optional otherwise.
616
- */
617
- fields?: FieldsInput; /** Metadata returned with this item result for caller-side bookkeeping. */
618
- queryMetadata?: QueryMetadata;
619
624
  /**
620
- * Only fetches when the item is missing from state, skipping stale-state and
621
- * invalidation refetches.
622
- */
623
- disableRefetches?: boolean; /** Prevents the automatic mount refetch for stale loaded data. */
624
- disableRefetchOnMount?: boolean; /** Returns `idle` instead of `loading` while the item has not been fetched. */
625
- returnIdleStatus?: boolean; /** Returns `refetching` instead of keeping `loaded` status during refetches. */
626
- returnRefetchingStatus?: boolean;
627
- /**
628
- * When requested fields are missing but cached partial data exists, return
629
- * `refetching` instead of `loading`.
630
- */
631
- showPartialAsRefetching?: boolean; /** Marks this subscription as off-screen, lowering automatic fetch priority. */
632
- isOffScreen?: boolean;
633
- };
634
- type ListQueryUseMultipleListQueriesQuery<QueryPayload extends ValidPayload, QueryMetadata extends undefined | Record<string, unknown> = undefined> = {
635
- /** Query payload to subscribe to and fetch when needed. */payload: QueryPayload;
636
- /**
637
- * Partial-resource fields to request for each item in this query.
638
- *
639
- * Pass `'*'` to fetch complete items. This option is required when
640
- * `partialResources` is enabled and optional otherwise.
625
+ * Runs the full mutation lifecycle: optional optimistic update, async
626
+ * mutation, rollback/error handling, revalidation, and offline queue fallback.
641
627
  */
642
- fields?: FieldsInput; /** Metadata returned with this query result for caller-side bookkeeping. */
643
- queryMetadata?: QueryMetadata; /** Omits `payload` from this query result. */
644
- omitPayload?: boolean;
645
- /**
646
- * Only fetches when the query is missing from state, skipping stale-state and
647
- * invalidation refetches.
648
- */
649
- disableRefetches?: boolean; /** Prevents the automatic mount refetch for stale loaded data. */
650
- disableRefetchOnMount?: boolean; /** Returns `idle` instead of `loading` while the query has not been fetched. */
651
- returnIdleStatus?: boolean; /** Returns `refetching` instead of keeping `loaded` status during refetches. */
652
- returnRefetchingStatus?: boolean;
653
- /**
654
- * When requested fields are missing but cached partial data exists, return
655
- * `refetching` instead of `loading`.
656
- */
657
- showPartialAsRefetching?: boolean; /** Marks this subscription as off-screen, lowering automatic fetch priority. */
658
- isOffScreen?: boolean; /** Number of items to request when fetching this query page. */
659
- loadSize?: number;
660
- };
661
- type OnListQueryInvalidate<QueryPayload extends ValidPayload> = (query: QueryPayload, priority: FetchType) => void;
662
- type OnListQueryItemInvalidate<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = (props: {
663
- itemState: ItemState;
664
- payload: ItemPayload;
665
- priority: FetchType;
666
- }) => void;
667
- type OptimisticListUpdate<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = {
668
- queries: QueryPayload | ((query: QueryPayload) => boolean) | QueryPayload[];
669
- filterItem?: (item: ItemState) => boolean | null;
670
- appendNewTo?: 'start' | 'end';
671
- invalidateQueries?: boolean;
672
- sort?: {
673
- sortBy: (item: ItemState, itemPayload: ItemPayload) => string | number | (string | number)[];
674
- order?: 'asc' | 'desc' | ('asc' | 'desc')[];
675
- };
676
- };
677
- type QueryFetchPayload<QueryPayload extends ValidPayload> = {
678
- /** Whether this request loads the first page or a later page. */type: 'load' | 'loadMore'; /** Query payload being fetched. */
679
- payload: QueryPayload; /** Offset used for offset-paginated fetches. */
680
- offset: number; /** Maximum number of items requested. */
681
- limit: number; /** Partial-resource fields requested for each item in the fetched query. */
682
- fields?: string[];
683
- };
684
- type OffsetPaginationConfig = {
685
- maxInvalidationLimit: number; /** Max parallel chunk requests during chunked invalidation (default: 3) */
686
- maxParallel?: number;
687
- };
688
- type PartialResourcesConfig<ItemState extends ValidStoreState> = {
689
- mergeItems: (prev: ItemState | undefined, fetched: ItemState) => ItemState;
690
- selectFields: (fields: string[], item: ItemState) => ItemState;
691
- };
692
- type DerivedQuerySummary<QueryPayload extends ValidPayload> = {
693
- payload: QueryPayload;
694
- hasMore: boolean;
695
- itemCount: number;
696
- };
697
- type DerivedQueryItem<ItemState extends ValidStoreState> = {
698
- key: string;
699
- data: ItemState;
700
- };
701
- /** Why a derived query is currently being resolved. */
702
- type DerivedQuerySource = 'online' | 'offline' | 'sticky-offline';
703
- /** Runtime context passed to `derivedQueries.deriveQuery(...)`. */
704
- type DerivedQueryContext = {
705
- /** The requested hook fields for this query, when partial resources are enabled. */fields: FieldsInput | undefined; /** Whether the store is currently in offline mode. */
706
- isOfflineMode: boolean;
707
- /**
708
- * What caused derivation to run.
709
- * `sticky-offline` means a query that was derived offline is still sticking
710
- * to the local derived view after reconnect, until explicit invalidation.
711
- */
712
- deriveSource: DerivedQuerySource;
713
- };
714
- type DerivedQueriesConfig<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = {
715
- /** Extracts the domain/group key for a query payload. */getQueryGroup: (queryPayload: QueryPayload) => string; /** Extracts the domain/group key for a materialized item. */
716
- getItemGroup: (item: ItemState, itemPayload: ItemPayload) => string;
717
- /**
718
- * Returns whether the local data for the query group is complete enough to
719
- * derive from while online.
720
- */
721
- isComplete: (queryPayload: QueryPayload, context: {
722
- queries: DerivedQuerySummary<QueryPayload>[];
723
- }) => boolean;
724
- /**
725
- * Computes a derived ordered list of item keys for a query, or `false` to
726
- * fall back to the regular fetch/cache path. `context.fields` lets the
727
- * callback decide whether partial-resource queries should still derive.
728
- */
729
- deriveQuery: (queryPayload: QueryPayload, items: DerivedQueryItem<ItemState>[], context: DerivedQueryContext) => string[] | false;
730
- };
731
- type FieldsOption<HasPartialResources extends boolean> = HasPartialResources extends true ? {
732
- /**
733
- * Partial-resource fields to request.
734
- *
735
- * Pass `'*'` to fetch complete items. This option is required when
736
- * `partialResources` is enabled.
737
- */
738
- fields: FieldsInput;
739
- } : {
740
- /**
741
- * Partial-resource fields to request.
742
- *
743
- * Pass `'*'` to fetch complete items. This option is optional when
744
- * `partialResources` is not enabled.
745
- */
746
- fields?: FieldsInput;
628
+ performMutation: DocumentPerformMutation<State, TOfflineOperations>; /** Notifies the store that a shared transport reconnected and should revalidate active data. */
629
+ onTransportReconnect: () => void;
747
630
  };
631
+ declare function createDocumentStore<State extends ValidStoreState, TOfflineOperations extends DocumentOfflineOperationsConfig<State> = null, StorageState = unknown>(storeOptions: DocumentStoreOptions<State, TOfflineOperations, StorageState>): DocumentStore<State, TOfflineOperations>;
748
632
  //#endregion
749
633
  //#region src/listQueryStore/useMultipleItems.d.ts
750
634
  type UseMultipleItemsOptions<ItemState extends ValidStoreState, Selected> = {
@@ -851,14 +735,15 @@ type UsePendingOfflineItemsOptions<ItemState extends ValidStoreState, ItemPayloa
851
735
  };
852
736
  //#endregion
853
737
  //#region src/listQueryStore/listQueryStore.d.ts
738
+ /** Event payloads emitted by `ListQueryStore.events`. */
854
739
  type ListQueryStoreEvents = {
855
- invalidateQuery: {
856
- priority: FetchType;
740
+ /** Emitted whenever one or more list queries are invalidated. */invalidateQuery: {
741
+ /** Fetch priority requested by the invalidation. */priority: FetchType; /** Store key for the invalidated query. */
857
742
  queryKey: string;
858
- };
743
+ }; /** Emitted whenever one or more list-query items are invalidated. */
859
744
  invalidateItem: {
860
- priority: FetchType;
861
- itemKey: string;
745
+ /** Fetch priority requested by the invalidation. */priority: FetchType; /** Store key for the invalidated item. */
746
+ itemKey: string; /** Partial-resource fields invalidated on this item, when applicable. */
862
747
  invalidateFields?: string[];
863
748
  };
864
749
  };
@@ -898,19 +783,19 @@ type ListQueryFetchFieldsOption<TPartialResources extends boolean> = ListQueryHa
898
783
  };
899
784
  type ListQueryScheduleFetchWithFieldsOption<TPartialResources extends boolean> = ScheduleFetchOptions & ListQueryFetchFieldsOption<TPartialResources>;
900
785
  type ListQueryScheduleListQueryFetchApi<QueryPayload extends ValidPayload, TPartialResources extends boolean> = {
901
- (fetchType: FetchType, payload: QueryPayload, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [size: number | undefined, options: ListQueryScheduleFetchWithFieldsOption<TPartialResources>] : [size?: number, options?: ListQueryScheduleFetchWithFieldsOption<TPartialResources>]): ScheduleFetchResults;
902
- (fetchType: FetchType, payload: QueryPayload[], ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [size: number | undefined, options: ListQueryScheduleFetchWithFieldsOption<TPartialResources>] : [size?: number, options?: ListQueryScheduleFetchWithFieldsOption<TPartialResources>]): ScheduleFetchResults[];
786
+ (fetchType: FetchType, payload: QueryPayload, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [/** Number of items to request. Defaults to the store's `defaultQuerySize`. */size: number | undefined, options: ListQueryScheduleFetchWithFieldsOption<TPartialResources>] : [/** Number of items to request. Defaults to the store's `defaultQuerySize`. */size?: number, options?: ListQueryScheduleFetchWithFieldsOption<TPartialResources>]): ScheduleFetchResults;
787
+ (fetchType: FetchType, payload: QueryPayload[], ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [/** Number of items to request. Defaults to the store's `defaultQuerySize`. */size: number | undefined, options: ListQueryScheduleFetchWithFieldsOption<TPartialResources>] : [/** Number of items to request. Defaults to the store's `defaultQuerySize`. */size?: number, options?: ListQueryScheduleFetchWithFieldsOption<TPartialResources>]): ScheduleFetchResults[];
903
788
  };
904
789
  type ListQueryScheduleItemFetchApi<ItemPayload extends ValidPayload, TPartialResources extends boolean> = {
905
790
  (fetchType: FetchType, itemPayload: ItemPayload, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [options: ListQueryScheduleFetchWithFieldsOption<TPartialResources>] : [options?: ListQueryScheduleFetchWithFieldsOption<TPartialResources>]): ScheduleFetchResults;
906
791
  (fetchType: FetchType, itemPayload: ItemPayload[], ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [options: ListQueryScheduleFetchWithFieldsOption<TPartialResources>] : [options?: ListQueryScheduleFetchWithFieldsOption<TPartialResources>]): ScheduleFetchResults[];
907
792
  };
908
793
  type ListQueryLoadMoreWithFieldsOptions<TPartialResources extends boolean> = {
909
- size?: number;
794
+ /** Number of additional items to request. Defaults to the store's `defaultQuerySize`. */size?: number;
910
795
  } & ListQueryFetchFieldsOption<TPartialResources>;
911
- type ListQueryLoadMoreApi<QueryPayload extends ValidPayload, TPartialResources extends boolean> = (params: QueryPayload, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [size: number, options: ListQueryFetchFieldsOption<TPartialResources>] | [options: ListQueryLoadMoreWithFieldsOptions<TPartialResources>] : [size?: number, options?: ListQueryFetchFieldsOption<TPartialResources>] | [options?: ListQueryLoadMoreWithFieldsOptions<TPartialResources>]) => ScheduleFetchResults;
796
+ type ListQueryLoadMoreApi<QueryPayload extends ValidPayload, TPartialResources extends boolean> = (params: QueryPayload, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [size: number, options: ListQueryFetchFieldsOption<TPartialResources>] | [options: ListQueryLoadMoreWithFieldsOptions<TPartialResources>] : [/** Number of additional items to request. Defaults to the store's `defaultQuerySize`. */size?: number, options?: ListQueryFetchFieldsOption<TPartialResources>] | [options?: ListQueryLoadMoreWithFieldsOptions<TPartialResources>]) => ScheduleFetchResults;
912
797
  type ListQueryAwaitListQueryFetchOptions<TPartialResources extends boolean> = {
913
- size?: number;
798
+ /** Number of items to request. Defaults to the store's `defaultQuerySize`. */size?: number;
914
799
  timeoutMs?: number;
915
800
  } & ListQueryFetchFieldsOption<TPartialResources>;
916
801
  type ListQueryAwaitListQueryFetchApi<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean> = (params: QueryPayload, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [options: ListQueryAwaitListQueryFetchOptions<TPartialResources>] : [options?: ListQueryAwaitListQueryFetchOptions<TPartialResources>]) => Promise<{
@@ -926,7 +811,7 @@ type ListQueryAwaitListQueryFetchApi<ItemState extends ValidStoreState, QueryPay
926
811
  hasMore: boolean;
927
812
  }>;
928
813
  type ListQueryGetQueryFromStateOrFetchOptions<TPartialResources extends boolean> = {
929
- ignoreStaleState?: boolean;
814
+ /** When `true`, stale cached queries are ignored and refetched before returning. Defaults to `false`. */ignoreStaleState?: boolean; /** Number of items to request when a fetch is needed. Defaults to the store's `defaultQuerySize`. */
930
815
  size?: number;
931
816
  timeoutMs?: number;
932
817
  } & ListQueryFetchFieldsOption<TPartialResources>;
@@ -948,7 +833,7 @@ type ListQueryAwaitItemFetchApi<ItemState extends ValidStoreState, ItemPayload e
948
833
  error: null;
949
834
  }>;
950
835
  type ListQueryGetItemFromStateOrFetchOptions<TPartialResources extends boolean> = {
951
- ignoreStaleState?: boolean;
836
+ /** When `true`, stale cached items are ignored and refetched before returning. Defaults to `false`. */ignoreStaleState?: boolean;
952
837
  timeoutMs?: number;
953
838
  } & ListQueryFetchFieldsOption<TPartialResources>;
954
839
  type ListQueryGetItemFromStateOrFetchApi<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TPartialResources extends boolean> = (itemPayload: ItemPayload, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [options: ListQueryGetItemFromStateOrFetchOptions<TPartialResources>] : [options?: ListQueryGetItemFromStateOrFetchOptions<TPartialResources>]) => Promise<Result<ItemState, StoreFetchError>>;
@@ -978,12 +863,30 @@ type ListQueryFilterItem<ItemState extends ValidStoreState, ItemPayload extends
978
863
  type ListQueryMutationPayload<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload> | null;
979
864
  type ListQueryMutationPayloadToUse<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload>;
980
865
  type ListQueryMutationArgsBase<T, ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = {
981
- optimisticUpdate?: (payload: ListQueryMutationPayloadToUse<ItemState, ItemPayload>) => void | boolean;
866
+ /**
867
+ * Applies optimistic updates for the affected item payloads before the
868
+ * mutation runs. Return `false` to cancel the mutation before the async
869
+ * mutation function is called.
870
+ */
871
+ optimisticUpdate?: (payload: ListQueryMutationPayloadToUse<ItemState, ItemPayload>) => void | boolean; /** Performs the server mutation for the affected item payloads. */
982
872
  mutation: (payload: ListQueryMutationPayloadToUse<ItemState, ItemPayload>) => Promise<T>;
983
- revalidateOnSuccess?: ListQueryRevalidateOnSuccessOption<QueryPayload>;
984
- onSuccess?: (response: Awaited<T>, payload: ListQueryMutationPayloadToUse<ItemState, ItemPayload>) => void;
873
+ /**
874
+ * Controls query and item invalidation after a successful online mutation.
875
+ *
876
+ * Use `true` to invalidate affected items and all queries, `'queries'` to
877
+ * invalidate only queries, a query filter to invalidate affected items and
878
+ * matching queries, or `{ queries, items }` to choose both explicitly.
879
+ */
880
+ revalidateOnSuccess?: ListQueryRevalidateOnSuccessOption<QueryPayload>; /** Called after a successful online mutation. */
881
+ onSuccess?: (response: UnwrapTSDFResult<Awaited<T>>, payload: ListQueryMutationPayloadToUse<ItemState, ItemPayload>) => void; /** Called after a failed or skipped mutation. */
985
882
  onError?: (error: StoreMutationError | MutationSkipped) => void;
986
- silentErrors?: boolean;
883
+ /**
884
+ * Passes `{ silentErrors: true }` to `onMutationError`.
885
+ *
886
+ * The handler is still called so centralized logging and recovery can run,
887
+ * but UI handlers can suppress user-facing notifications.
888
+ */
889
+ silentErrors?: boolean; /** Debounces mutations with the same context and payload. Superseded calls are skipped. */
987
890
  debounce?: {
988
891
  context: string;
989
892
  payload: unknown;
@@ -995,15 +898,44 @@ type ListQueryOnlineMutationArgs<T, ItemState extends ValidStoreState, QueryPayl
995
898
  upload?: undefined;
996
899
  };
997
900
  type ListQueryOfflineMutationArgs<T, ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload>> = ListQueryMutationArgsBase<T, ItemState, QueryPayload, ItemPayload> & {
998
- offline: TOfflineOperations extends null ? never : OfflineMutationInput<Exclude<TOfflineOperations, null>>;
901
+ /**
902
+ * Queues this mutation through the store's registered offline operation when
903
+ * the session is offline or the direct request fails with an offline outage.
904
+ */
905
+ offline: TOfflineOperations extends null ? never : OfflineMutationInput<Exclude<TOfflineOperations, null>>; /** Files to attach if this mutation is queued for offline replay. */
999
906
  upload?: OfflineMutationUploadsInput;
1000
907
  };
1001
908
  type ListQueryPerformMutationApi<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload>> = {
1002
- <T>(payload: ListQueryMutationPayloadToUse<ItemState, ItemPayload>, args: ListQueryOnlineMutationArgs<T, ItemState, QueryPayload, ItemPayload>): Promise<Result<Awaited<T>, StoreMutationError | MutationSkipped>>;
1003
- <T>(payload: ListQueryMutationPayloadToUse<ItemState, ItemPayload>, args: ListQueryOfflineMutationArgs<T, ItemState, QueryPayload, ItemPayload, TOfflineOperations>): Promise<Result<OfflineMutationResult<T>, StoreMutationError | MutationSkipped>>;
1004
- <T>(payload: null, args: Omit<ListQueryOnlineMutationArgs<T, ItemState, QueryPayload, ItemPayload>, 'optimisticUpdate'>): Promise<Result<Awaited<T>, StoreMutationError | MutationSkipped>>;
1005
- <T>(payload: null, args: Omit<ListQueryOfflineMutationArgs<T, ItemState, QueryPayload, ItemPayload, TOfflineOperations>, 'optimisticUpdate'>): Promise<Result<OfflineMutationResult<T>, StoreMutationError | MutationSkipped>>;
1006
- <T>(payload: ListQueryMutationPayload<ItemState, ItemPayload>, args: ListQueryOnlineMutationArgs<T, ItemState, QueryPayload, ItemPayload> | ListQueryOfflineMutationArgs<T, ItemState, QueryPayload, ItemPayload, TOfflineOperations>): Promise<Result<Awaited<T> | OfflineMutationResult<T>, StoreMutationError | MutationSkipped>>;
909
+ /**
910
+ * Runs a list-query mutation for existing item payloads or an item filter.
911
+ *
912
+ * Returns the direct server result when offline replay is not configured for
913
+ * this call.
914
+ */
915
+ <T>(payload: ListQueryMutationPayloadToUse<ItemState, ItemPayload>, args: ListQueryOnlineMutationArgs<T, ItemState, QueryPayload, ItemPayload>): Promise<Result<UnwrapTSDFResult<Awaited<T>>, StoreMutationError | MutationSkipped>>;
916
+ /**
917
+ * Runs a list-query mutation for existing item payloads or an item filter,
918
+ * with durable offline queueing as a fallback.
919
+ *
920
+ * When the mutation is queued, the result is `{ kind: 'queued' }` instead of
921
+ * the server payload.
922
+ */
923
+ <T>(payload: ListQueryMutationPayloadToUse<ItemState, ItemPayload>, args: ListQueryOfflineMutationArgs<T, ItemState, QueryPayload, ItemPayload, TOfflineOperations>): Promise<Result<OfflineMutationResult<UnwrapTSDFResult<Awaited<T>>>, StoreMutationError | MutationSkipped>>;
924
+ /**
925
+ * Runs a list-query mutation with no current item target.
926
+ *
927
+ * Use this for create mutations that do not have a pre-generated item payload
928
+ * yet. Optimistic updates are not available without a target payload.
929
+ */
930
+ <T>(payload: null, args: Omit<ListQueryOnlineMutationArgs<T, ItemState, QueryPayload, ItemPayload>, 'optimisticUpdate'>): Promise<Result<UnwrapTSDFResult<Awaited<T>>, StoreMutationError | MutationSkipped>>;
931
+ /**
932
+ * Runs an offline-capable list-query mutation with no current item target.
933
+ *
934
+ * Use this for create mutations that do not have a pre-generated item payload
935
+ * yet. When the mutation is queued, the result is `{ kind: 'queued' }`.
936
+ */
937
+ <T>(payload: null, args: Omit<ListQueryOfflineMutationArgs<T, ItemState, QueryPayload, ItemPayload, TOfflineOperations>, 'optimisticUpdate'>): Promise<Result<OfflineMutationResult<UnwrapTSDFResult<Awaited<T>>>, StoreMutationError | MutationSkipped>>;
938
+ <T>(payload: ListQueryMutationPayload<ItemState, ItemPayload>, args: ListQueryOnlineMutationArgs<T, ItemState, QueryPayload, ItemPayload> | ListQueryOfflineMutationArgs<T, ItemState, QueryPayload, ItemPayload, TOfflineOperations>): Promise<Result<UnwrapTSDFResult<Awaited<T>> | OfflineMutationResult<UnwrapTSDFResult<Awaited<T>>>, StoreMutationError | MutationSkipped>>;
1007
939
  };
1008
940
  type ListQueryUpdateItemStateApi<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = (itemIds: ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload>, produceNewData: (draftData: ItemState, itemPayload: ItemPayload) => void | ItemState, options?: {
1009
941
  ifNothingWasUpdated?: () => void;
@@ -1016,7 +948,7 @@ type ListQueryAddItemToStateApi<ItemState extends ValidStoreState, QueryPayload
1016
948
  }) => void;
1017
949
  type ListQueryDeleteItemStateApi<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = (itemId: ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload>) => void;
1018
950
  type ListQueryInvalidateQueryAndItemsArgs<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = {
1019
- /** Invalidate every cached query and every cached item. */all: true; /** Fetch priority used for refetches triggered by this invalidation. */
951
+ /** Invalidate every cached query and every cached item. */all: true; /** Fetch priority used for refetches triggered by this invalidation. Defaults to `highPriority`. */
1020
952
  type?: FetchType;
1021
953
  /**
1022
954
  * Partial-resource fields to invalidate on matching items.
@@ -1041,7 +973,7 @@ type ListQueryInvalidateQueryAndItemsArgs<ItemState extends ValidStoreState, Que
1041
973
  * Pass one payload, many payloads, a predicate over cached queries, or
1042
974
  * `false` to skip query invalidation.
1043
975
  */
1044
- queryPayload: QueryPayload | QueryPayload[] | ListQueryFilterQuery<QueryPayload> | false; /** Fetch priority used for refetches triggered by this invalidation. */
976
+ queryPayload: QueryPayload | QueryPayload[] | ListQueryFilterQuery<QueryPayload> | false; /** Fetch priority used for refetches triggered by this invalidation. Defaults to `highPriority`. */
1045
977
  type?: FetchType;
1046
978
  /**
1047
979
  * Partial-resource fields to invalidate on matching items.
@@ -1050,122 +982,130 @@ type ListQueryInvalidateQueryAndItemsArgs<ItemState extends ValidStoreState, Que
1050
982
  */
1051
983
  fields?: string[];
1052
984
  };
985
+ /** Public API returned by `createListQueryStore(...)`. */
1053
986
  type ListQueryStore<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean = false, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload> = null> = {
1054
- store: Store<TSFDListQueryState<ItemState, QueryPayload, ItemPayload>>;
1055
- events: Emitter<ListQueryStoreEvents>;
1056
- storeEvents: Emitter<ListQueryStoreStoreEvents<ItemPayload>>;
1057
- readonly queryInvalidationWasTriggered: Set<string>;
1058
- readonly itemInvalidationWasTriggered: Set<string>;
1059
- reset: () => void;
1060
- dispose: () => void;
1061
- scheduleListQueryFetch: ListQueryScheduleListQueryFetchApi<QueryPayload, TPartialResources>;
1062
- getQueryState: (params: QueryPayload) => TSFDListQuery<QueryPayload> | undefined;
1063
- getQueryKey: (params: QueryPayload) => string;
987
+ /** Underlying t-state store containing raw cached queries and items. */store: Store<TSFDListQueryState<ItemState, QueryPayload, ItemPayload>>; /** Invalidation event emitter used by hooks and integrations. */
988
+ events: Emitter<ListQueryStoreEvents>; /** Mutation lifecycle event emitter for observers and tests. */
989
+ storeEvents: Emitter<ListQueryStoreStoreEvents<ItemPayload>>; /** Query keys that have been explicitly invalidated and are awaiting refresh. */
990
+ readonly queryInvalidationWasTriggered: Set<string>; /** Item keys that have been explicitly invalidated and are awaiting refresh. */
991
+ readonly itemInvalidationWasTriggered: Set<string>; /** Clears in-memory state and cancels store-local runtime state. */
992
+ reset: () => void; /** Unregisters listeners and releases resources owned by this store. */
993
+ dispose: () => void; /** Schedules a list-query fetch with the requested priority. */
994
+ scheduleListQueryFetch: ListQueryScheduleListQueryFetchApi<QueryPayload, TPartialResources>; /** Reads one cached query directly from store state. */
995
+ getQueryState: (params: QueryPayload) => TSFDListQuery<QueryPayload> | undefined; /** Returns the stable cache key for a query payload. */
996
+ getQueryKey: (params: QueryPayload) => string; /** Reads many cached queries directly from store state. */
1064
997
  getQueriesState: (params: QueryPayload[] | ListQueryFilterQuery<QueryPayload>) => {
1065
998
  query: TSFDListQuery<QueryPayload>;
1066
999
  key: string;
1067
- }[];
1000
+ }[]; /** Finds cached queries that currently include the item payload. */
1068
1001
  getQueriesRelatedToItem: (itemPayload: ItemPayload) => {
1069
1002
  query: TSFDListQuery<QueryPayload>;
1070
1003
  key: string;
1071
- }[];
1072
- awaitListQueryFetch: ListQueryAwaitListQueryFetchApi<ItemState, QueryPayload, ItemPayload, TPartialResources>;
1073
- getQueryFromStateOrFetch: ListQueryGetQueryFromStateOrFetchApi<ItemState, QueryPayload, ItemPayload, TPartialResources>;
1074
- preloadQueryFromStorage: (params: QueryPayload | QueryPayload[]) => Promise<PersistentStoragePreloadResult<QueryPayload>[]>;
1075
- loadMore: ListQueryLoadMoreApi<QueryPayload, TPartialResources>;
1076
- getItemKey: (params: ItemPayload) => string;
1004
+ }[]; /** Waits for a list-query fetch to settle and returns query data or a fetch error. */
1005
+ awaitListQueryFetch: ListQueryAwaitListQueryFetchApi<ItemState, QueryPayload, ItemPayload, TPartialResources>; /** Returns a cached query when usable, otherwise fetches it first. */
1006
+ getQueryFromStateOrFetch: ListQueryGetQueryFromStateOrFetchApi<ItemState, QueryPayload, ItemPayload, TPartialResources>; /** Loads query payloads from persistent storage into memory when available. */
1007
+ preloadQueryFromStorage: (params: QueryPayload | QueryPayload[]) => Promise<PersistentStoragePreloadResult<QueryPayload>[]>; /** Fetches and appends the next page for a list query. */
1008
+ loadMore: ListQueryLoadMoreApi<QueryPayload, TPartialResources>; /** Returns the stable cache key for an item payload. */
1009
+ getItemKey: (params: ItemPayload) => string; /** Reads one or many cached items directly from store state. */
1077
1010
  getItemState: {
1078
1011
  (itemPayload: ItemPayload): ItemState | null | undefined;
1079
1012
  (itemPayload: ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload>): {
1080
1013
  payload: ItemPayload;
1081
1014
  data: ItemState;
1082
1015
  }[];
1083
- };
1084
- usePendingOfflineItems: ListQueryUsePendingOfflineItemsApi<ItemState, ItemPayload>;
1085
- getOfflineEntities: () => GlobalOfflineEntity[];
1086
- useOfflineEntities: () => readonly GlobalOfflineEntity[];
1087
- useOfflineResolutions: () => readonly OfflineResolutionRecord[];
1088
- getOfflineResolutions: () => OfflineResolutionRecord[];
1089
- parseOfflineResolutionConflict: (resolution: OfflineResolutionRecord) => ParsedOfflineResolutionConflictResultForStore<ResolvedListQueryOfflineOperations<TOfflineOperations>>;
1090
- resolveOfflineResolution: <TName extends keyof ResolvedListQueryOfflineOperations<TOfflineOperations> & string>(resolutionId: string, operationName: TName, resolution: OfflineResolutionActionForOperation<ResolvedListQueryOfflineOperations<TOfflineOperations>, TName>) => Promise<void> | void;
1091
- preloadItemFromStorage: (params: ItemPayload | ItemPayload[]) => Promise<PersistentStoragePreloadResult<ItemPayload>[]>;
1092
- scheduleItemFetch: ListQueryScheduleItemFetchApi<ItemPayload, TPartialResources>;
1093
- awaitItemFetch: ListQueryAwaitItemFetchApi<ItemState, ItemPayload, TPartialResources>;
1094
- getItemFromStateOrFetch: ListQueryGetItemFromStateOrFetchApi<ItemState, ItemPayload, TPartialResources>;
1095
- invalidateQueryAndItems: (args: ListQueryInvalidateQueryAndItemsArgs<ItemState, QueryPayload, ItemPayload>) => void;
1096
- invalidateItem: (itemId: ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload>, priority?: FetchType) => void;
1097
- startItemMutation: (itemId: ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload>) => () => void;
1098
- updateItemState: ListQueryUpdateItemStateApi<ItemState, ItemPayload>;
1099
- addItemToState: ListQueryAddItemToStateApi<ItemState, QueryPayload, ItemPayload>;
1016
+ }; /** React hook for locally pending offline items in this store. */
1017
+ usePendingOfflineItems: ListQueryUsePendingOfflineItemsApi<ItemState, ItemPayload>; /** Returns offline sync metadata for this store's tracked entities. */
1018
+ getOfflineEntities: () => GlobalOfflineEntity[]; /** React hook subscribing to this store's offline entity metadata. */
1019
+ useOfflineEntities: () => readonly GlobalOfflineEntity[]; /** React hook subscribing to manual offline resolutions for this store. */
1020
+ useOfflineResolutions: () => readonly OfflineResolutionRecord[]; /** Returns manual offline resolutions for this store. */
1021
+ getOfflineResolutions: () => OfflineResolutionRecord[]; /** Parses a stored offline conflict into the operation-specific conflict shape. */
1022
+ parseOfflineResolutionConflict: (resolution: OfflineResolutionRecord) => ParsedOfflineResolutionConflictResultForStore<ResolvedListQueryOfflineOperations<TOfflineOperations>>; /** Applies a retry/discard/requeue/commit action to a pending offline resolution. */
1023
+ resolveOfflineResolution: <TName extends keyof ResolvedListQueryOfflineOperations<TOfflineOperations> & string>(resolutionId: string, operationName: TName, resolution: OfflineResolutionActionForOperation<ResolvedListQueryOfflineOperations<TOfflineOperations>, TName>) => Promise<void> | void; /** Loads item payloads from persistent storage into memory when available. */
1024
+ preloadItemFromStorage: (params: ItemPayload | ItemPayload[]) => Promise<PersistentStoragePreloadResult<ItemPayload>[]>; /** Schedules an item fetch with the requested priority. */
1025
+ scheduleItemFetch: ListQueryScheduleItemFetchApi<ItemPayload, TPartialResources>; /** Waits for an item fetch to settle and returns data or a fetch error. */
1026
+ awaitItemFetch: ListQueryAwaitItemFetchApi<ItemState, ItemPayload, TPartialResources>; /** Returns cached item data when usable, otherwise fetches it first. */
1027
+ getItemFromStateOrFetch: ListQueryGetItemFromStateOrFetchApi<ItemState, ItemPayload, TPartialResources>; /** Invalidates selected queries and items together. Defaults to `highPriority`. */
1028
+ invalidateQueryAndItems: (args: ListQueryInvalidateQueryAndItemsArgs<ItemState, QueryPayload, ItemPayload>) => void; /** Marks cached items stale and schedules refetches for active subscriptions. Defaults to `highPriority`. */
1029
+ invalidateItem: (itemId: ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload>, /** Fetch priority used for refetches triggered by this invalidation. Defaults to `highPriority`. */
1030
+
1031
+ priority?: FetchType) => void; /** Marks one or more items as mutating and returns a function that ends the mutation. */
1032
+ startItemMutation: (itemId: ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload>) => () => void; /** Applies an immutable update to one or more cached list-query items. */
1033
+ updateItemState: ListQueryUpdateItemStateApi<ItemState, ItemPayload>; /** Adds or replaces one cached item directly in state. */
1034
+ addItemToState: ListQueryAddItemToStateApi<ItemState, QueryPayload, ItemPayload>; /** Deletes one cached item directly from state and query membership. */
1100
1035
  deleteItemState: ListQueryDeleteItemStateApi<ItemState, ItemPayload>;
1101
- performMutation: ListQueryPerformMutationApi<ItemState, QueryPayload, ItemPayload, TOfflineOperations>;
1102
- useMultipleListQueries: ListQueryUseMultipleListQueriesApi<ItemState, QueryPayload, ItemPayload, TPartialResources>;
1103
- useListQuery: ListQueryUseListQueryApi<ItemState, QueryPayload, ItemPayload, TPartialResources>;
1104
- useMultipleItems: ListQueryUseMultipleItemsApi<ItemState, ItemPayload, TPartialResources>;
1105
- useItem: ListQueryUseItemApi<ItemState, ItemPayload, TPartialResources>;
1036
+ /**
1037
+ * Runs the full mutation lifecycle: optional optimistic update, async
1038
+ * mutation, rollback/error handling, revalidation, and offline queue fallback.
1039
+ */
1040
+ performMutation: ListQueryPerformMutationApi<ItemState, QueryPayload, ItemPayload, TOfflineOperations>; /** React hook for subscribing to many list queries at once. */
1041
+ useMultipleListQueries: ListQueryUseMultipleListQueriesApi<ItemState, QueryPayload, ItemPayload, TPartialResources>; /** React hook for subscribing to one list query. */
1042
+ useListQuery: ListQueryUseListQueryApi<ItemState, QueryPayload, ItemPayload, TPartialResources>; /** React hook for subscribing to many list-query items at once. */
1043
+ useMultipleItems: ListQueryUseMultipleItemsApi<ItemState, ItemPayload, TPartialResources>; /** React hook for subscribing to one list-query item. */
1044
+ useItem: ListQueryUseItemApi<ItemState, ItemPayload, TPartialResources>; /** React hook for selecting the first cached item matching a predicate. */
1106
1045
  useFindItem: <SelectedItem = ItemState | null>(findItemFn: (item: ItemState, itemPayload: ItemPayload) => boolean, options?: {
1107
1046
  /** Maps the matched item before it is returned from the hook. */selector?: (data: ItemState, id: ItemPayload) => SelectedItem;
1108
- }) => SelectedItem | null;
1047
+ }) => SelectedItem | null; /** Notifies the store that a shared transport reconnected and should revalidate active data. */
1109
1048
  onTransportReconnect: () => void;
1110
1049
  };
1050
+ /** Details passed when list-query cache-limit cleanup evicts cached items or queries. */
1111
1051
  type ListQueryStateCleanup<QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = {
1112
- reason: 'cacheLimitEviction';
1113
- itemKeys: string[];
1114
- itemPayloads: ItemPayload[];
1115
- queryKeys: string[];
1052
+ /** Cleanup trigger that removed these records. */reason: 'cacheLimitEviction'; /** Item store keys removed from state. */
1053
+ itemKeys: string[]; /** Original item payloads removed from state. */
1054
+ itemPayloads: ItemPayload[]; /** Query store keys removed from state. */
1055
+ queryKeys: string[]; /** Original query payloads removed from state. */
1116
1056
  queryPayloads: QueryPayload[];
1117
1057
  };
1118
1058
  type FetchListFnSizeMode<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = (payload: QueryPayload, size: number, options: {
1119
1059
  signal: AbortSignal;
1120
1060
  fields?: string[];
1121
- }) => Promise<FetchListFnReturn<ItemState, ItemPayload>>;
1061
+ }) => Promise<MaybeTSDFResult<FetchListFnReturn<ItemState, ItemPayload>>>;
1122
1062
  type FetchListFnOffsetMode<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = (payload: QueryPayload, pagination: {
1123
1063
  offset: number;
1124
1064
  limit: number;
1125
1065
  }, options: {
1126
1066
  signal: AbortSignal;
1127
1067
  fields?: string[];
1128
- }) => Promise<FetchListFnReturn<ItemState, ItemPayload>>;
1068
+ }) => Promise<MaybeTSDFResult<FetchListFnReturn<ItemState, ItemPayload>>>;
1129
1069
  type ListQueryStoreOptionsBase<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean = false, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload> = null, StorageState = unknown> = {
1130
1070
  /**
1131
1071
  * Stable id for this logical list-query store. Used for debug labels,
1132
1072
  * persistence namespaces, and browser tab sync.
1133
1073
  */
1134
1074
  id: string; /** Shared global store manager providing session scoping and error normalization. */
1135
- storeManager: StoreManager;
1075
+ storeManager: StoreManager; /** Fetches one item by payload. Required when items can be loaded outside list pages. */
1136
1076
  fetchItemFn?: (payload: ItemPayload, options: {
1137
1077
  signal: AbortSignal;
1138
1078
  fields?: string[];
1139
- }) => Promise<ItemState>;
1079
+ }) => Promise<MaybeTSDFResult<ItemState>>; /** Optional batch fetch function for fetching multiple items at once. */
1140
1080
  batchFetchItemFn?: (requests: {
1141
1081
  payload: ItemPayload;
1142
1082
  fields?: string[];
1143
1083
  }[], options: {
1144
1084
  signal: AbortSignal;
1145
1085
  batchKey: string;
1146
- }) => Promise<Map<ItemPayload, ItemState | Error>>;
1147
- getItemsBatchKey?: (payload: ItemPayload) => string | false;
1148
- defaultQuerySize?: number;
1086
+ }) => Promise<MaybeTSDFResult<Map<ItemPayload, MaybeTSDFResult<ItemState> | Error>>>; /** Optional function to group item batch fetches by key. When omitted, all batched items share one default batch key. Return false to fetch individually. */
1087
+ getItemsBatchKey?: (payload: ItemPayload) => string | false; /** Default number of items requested by list-query fetches. Defaults to 50. */
1088
+ defaultQuerySize?: number; /** Max items per item batch. Defaults to 50. Triggers an immediate fetch when reached. */
1149
1089
  maxItemBatchSize?: number; /** Maximum number of cached items kept in memory. Defaults to 5,000. Item pressure may evict whole inactive queries to avoid leaving cached queries partially loaded. */
1150
1090
  maxItems?: number; /** Maximum number of cached queries kept in memory. Defaults to 1,000. Inactive queries are evicted in LRU order while mounted hook queries stay protected. */
1151
1091
  maxQueries?: number; /** Called when cache-limit eviction removes items or queries from in-memory state. */
1152
- onStateCleanup?: (cleanup: ListQueryStateCleanup<QueryPayload, ItemPayload>) => void;
1092
+ onStateCleanup?: (cleanup: ListQueryStateCleanup<QueryPayload, ItemPayload>) => void; /** Treats refetches as real-time driven, disabling stale mount refetches by default. Defaults to `false`. */
1153
1093
  usesRealTimeUpdates?: boolean; /** Overrides the manager's default minimum interval between low-priority fetches for this store. */
1154
1094
  lowPriorityThrottleMs?: number; /** Overrides the manager's default coalescing window for this store. */
1155
- baseCoalescingWindowMs?: number;
1156
- mediumPriorityDelayMs?: number;
1095
+ baseCoalescingWindowMs?: number; /** Delay applied to medium-priority requests before they enter the scheduler. */
1096
+ mediumPriorityDelayMs?: number; /** Computes a per-fetch throttle for real-time updates using recent fetch cost and focus state. */
1157
1097
  dynamicRealtimeThrottleMs?: (params: {
1158
1098
  lastFetchDuration: number;
1159
1099
  windowIsNotFocused: boolean;
1160
- }) => number;
1100
+ }) => number; /** Store-level focus revalidation policy. Overrides the manager default. */
1161
1101
  revalidateOnWindowFocus?: boolean | (() => boolean);
1162
- /** Reconnect-specific cooldown. The first reconnect revalidates immediately;
1102
+ /** Reconnect-specific cooldown. Defaults to 2,000ms. The first reconnect revalidates immediately;
1163
1103
  * additional reconnects within the cooldown are coalesced into one trailing
1164
1104
  * revalidation. Set to `0` to disable this cooldown. */
1165
- transportReconnectCooldownMs?: number;
1166
- optimisticListUpdates?: OptimisticListUpdate<ItemState, QueryPayload, ItemPayload>[];
1167
- onInvalidateQuery?: OnListQueryInvalidate<QueryPayload>;
1168
- onInvalidateItem?: OnListQueryItemInvalidate<ItemState, ItemPayload>;
1105
+ transportReconnectCooldownMs?: number; /** Rules that keep cached query membership in sync after item updates. */
1106
+ optimisticListUpdates?: OptimisticListUpdate<ItemState, QueryPayload, ItemPayload>[]; /** Called when an already-loaded query is invalidated. */
1107
+ onInvalidateQuery?: OnListQueryInvalidate<QueryPayload>; /** Called when an already-loaded item is invalidated. */
1108
+ onInvalidateItem?: OnListQueryItemInvalidate<ItemState, ItemPayload>; /** Observes request scheduler lifecycle events for this store. */
1169
1109
  onSchedulerEvent?: (event: RequestSchedulerEvents, data?: RequestSchedulerEventData) => void;
1170
1110
  /**
1171
1111
  * Store-specific mutation error handler.
@@ -1174,8 +1114,8 @@ type ListQueryStoreOptionsBase<ItemState extends ValidStoreState, QueryPayload e
1174
1114
  * error handling for this store.
1175
1115
  */
1176
1116
  onMutationError?: ((error: unknown, options: StoreMutationErrorOptions) => void) | null; /** Opt-in hook-level query derivation from locally materialized items. */
1177
- derivedQueries?: DerivedQueriesConfig<ItemState, QueryPayload, ItemPayload>;
1178
- getQueryKey?: (params: QueryPayload) => ValidPayload | unknown[];
1117
+ derivedQueries?: DerivedQueriesConfig<ItemState, QueryPayload, ItemPayload>; /** Converts a query payload to the stable cache key used by this store. */
1118
+ getQueryKey?: (params: QueryPayload) => ValidPayload | unknown[]; /** Converts an item payload to the stable cache key used by this store. */
1179
1119
  getItemKey?: (params: ItemPayload) => ValidPayload | unknown[];
1180
1120
  /** Opt-in persistent storage configuration. When provided, cached items and queries
1181
1121
  * are loaded from storage on first read and saved back on successful fetches.
@@ -1187,11 +1127,12 @@ type ListQueryStoreOptionsBase<ItemState extends ValidStoreState, QueryPayload e
1187
1127
  } : {
1188
1128
  partialResources?: undefined;
1189
1129
  });
1130
+ /** Options used to create a list-query store. */
1190
1131
  type ListQueryStoreOptions<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean = false, TOffsetPagination extends boolean = false, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload> = null, StorageState = unknown> = ListQueryStoreOptionsBase<ItemState, QueryPayload, ItemPayload, TPartialResources, TOfflineOperations, StorageState> & ([TOffsetPagination] extends [true] ? {
1191
- fetchListFn: FetchListFnOffsetMode<ItemState, QueryPayload, ItemPayload>;
1132
+ /** Fetches one offset-paginated list query page. */fetchListFn: FetchListFnOffsetMode<ItemState, QueryPayload, ItemPayload>; /** Enables offset-pagination behavior and invalidation sizing. */
1192
1133
  offsetPagination: OffsetPaginationConfig;
1193
1134
  } : {
1194
- fetchListFn: FetchListFnSizeMode<ItemState, QueryPayload, ItemPayload>;
1135
+ /** Fetches one size-based list query page. */fetchListFn: FetchListFnSizeMode<ItemState, QueryPayload, ItemPayload>; /** Not allowed unless offset pagination is enabled. */
1195
1136
  offsetPagination?: undefined;
1196
1137
  });
1197
1138
  declare function createListQueryStore<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean = false, TOffsetPagination extends boolean = false, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload> = null, StorageState = unknown>(storeOptions: ListQueryStoreOptions<ItemState, QueryPayload, ItemPayload, TPartialResources, TOffsetPagination, TOfflineOperations, StorageState>): ListQueryStore<ItemState, QueryPayload, ItemPayload, TPartialResources, TOfflineOperations>;
@@ -1345,4 +1286,4 @@ declare function clearAllSessionStorage(sessionKey: string): Promise<void>;
1345
1286
  //#region src/persistentStorage/opfsOfflineUploadAdapter.d.ts
1346
1287
  declare const opfsOfflineUploadAdapter: OfflineUploadAdapter;
1347
1288
  //#endregion
1348
- export { type AsyncStorageAdapter, type AsyncStorageDiscoveredScope, type AsyncStorageDriver, type AsyncStorageDriverSetEntry, type AsyncStorageMetadataOrder, type AsyncStorageNamespaceCommitArgs, type AsyncStorageNamespaceCommitTouch, type AsyncStorageNamespaceCommitUpsert, type AsyncStorageNamespaceGetResult, type AsyncStorageNamespaceHandle, type AsyncStorageNamespaceKind, type AsyncStorageNamespaceScope, type AsyncStorageReadOptions, type BlockWindowCloseHandler, CollectionItemStatus, type CollectionOfflineEntityRef, type CollectionOfflineOperationDefinition, type CollectionPersistentStorageConfig, CollectionStateCleanup, CollectionStore, CollectionStoreEvents, CollectionStoreOptions, CollectionStoreStoreEvents, CollectionUseMultipleItemsQuery, type ConvertedPersistentStorageDataSchema, type CreateStoreManagerOptions, type DefineCollectionOfflineOperations, type DefineDocumentOfflineOperations, type DefineListQueryOfflineOperations, type DefineOfflineOperation, type DerivedQueriesConfig, type DerivedQueryContext, type DerivedQuerySource, type DocumentOfflineOperationDefinition, type DocumentPersistentStorageConfig, DocumentStatus, DocumentStore, DocumentStoreOptions, DocumentStoreState, DocumentStoreStoreEvents, type FetchListFnReturn, type FetchListFnReturnItem, type FieldsInput, type FieldsOption, GET_ALL, type GlobalOfflineEntity, type GlobalOfflineStatus, IsOffScreenContext, type ListQueryOfflineEntityRef, type ListQueryOfflineOperationDefinition, type ListQueryPersistentStorageConfig, type ListQueryStore, type ListQueryStoreEvents, type ListQueryStoreOptions, type ListQueryUseMultipleItemsQuery, type ListQueryUseMultipleListQueriesQuery, type MutationDebounce, type MutationSkipped, type OfflineAccumulationConfig, type OfflineAccumulationMergeContext, type OfflineConflictResolutionAction, type OfflineEntityMutationKind, type OfflineMutationDescriptor, type OfflineMutationInput, type OfflineMutationQueueingCause, type OfflineMutationQueueingConfig, type OfflineMutationQueueingPolicy, type OfflineMutationResult, type OfflineMutationUploadsInput, type OfflineOperationKind, type OfflineOperationUploadsContext, type OfflineQueueEntry, type OfflineReplayRetryConfig, type OfflineResolutionAction, type OfflineResolutionActionForOperation, type OfflineResolutionConflictParseError, type OfflineResolutionConflictParseErrorCode, type OfflineResolutionRecord, type OfflineResolutionRecordForOperation, type OfflineResolutionRecordForStore, type OfflineRetryExhaustedResolutionAction, type OfflineRuntimeConfig, type OfflineRuntimeConfigUpdate, type OfflineSession, type OfflineSessionConfig, type OfflineSessionUploadsConfig, type OfflineStoredUploadRecord, type OfflineSupersedeConfig, type OfflineSyncState, type OfflineTempEntitiesConfig, type OfflineTempEntitiesReconciliation, type OfflineTempEntityConfig, type OfflineTempEntityPendingEntry, type OfflineUpload, type OfflineUploadAdapter, type OfflineUploadProgress, type OfflineUploadSource, type OfflineUploadState, type OfflineUploadTransportContext, type OffsetPaginationConfig, OnCollectionItemInvalidate, OnDocumentInvalidate, type OnListQueryInvalidate, type OnListQueryItemInvalidate, type OperationConflict, type OperationResult, type OptimisticListUpdate, type ParsedOfflineResolutionConflictResultForOperation, type PartialResourcesConfig, type PayloadDebounce, type PersistentStorageBaseConfig, type PersistentStorageDataSchema, type PersistentStoragePreloadResult, type PersistentStorageSchema, type QueryFetchPayload, type QueryStatus, type StorageAdapter, type StoreError, StoreFetchError, type StoreManager, StoreMutationError, type StoreMutationErrorOptions, type TSDFItemQuery, type TSDFStatus, TSDFUseDocumentReturn, TSFDCollectionItem, TSFDCollectionState, type TSFDListQuery, type TSFDListQueryState, TSFDUseCollectionItemReturn, type TSFDUseListItemReturn, type TSFDUseListQueryReturn, type TSFDUsePendingOfflineItemsReturn, type ValidPayload, type ValidStoreState, clearAllSessionStorage, clearSessionStorage, createCollectionStore, createDocumentStore, createListQueryStore, createStoreManager, defaultOfflineRuntimeConfig, fetchTypePriority, getGlobalOfflineEntities, getGlobalOfflineResolutions, getGlobalOfflineStatus, localPersistentStorage, mutationSkipped, opfsOfflineUploadAdapter, useGlobalOfflineEntities, useGlobalOfflineResolutions, useGlobalOfflineStatus };
1289
+ export { type AsyncStorageAdapter, type AsyncStorageDiscoveredScope, type AsyncStorageDriver, type AsyncStorageDriverSetEntry, type AsyncStorageMetadataOrder, type AsyncStorageNamespaceCommitArgs, type AsyncStorageNamespaceCommitTouch, type AsyncStorageNamespaceCommitUpsert, type AsyncStorageNamespaceGetResult, type AsyncStorageNamespaceHandle, type AsyncStorageNamespaceKind, type AsyncStorageNamespaceScope, type AsyncStorageReadOptions, type BlockWindowCloseHandler, CollectionItemStatus, type CollectionOfflineEntityRef, type CollectionOfflineOperationDefinition, type CollectionPersistentStorageConfig, CollectionStateCleanup, CollectionStore, CollectionStoreEvents, CollectionStoreOptions, CollectionStoreStoreEvents, CollectionUseMultipleItemsQuery, type ConvertedPersistentStorageDataSchema, type CreateStoreManagerOptions, type DefineCollectionOfflineOperations, type DefineDocumentOfflineOperations, type DefineListQueryOfflineOperations, type DefineOfflineOperation, type DerivedQueriesConfig, type DerivedQueryContext, type DerivedQuerySource, type DocumentOfflineOperationDefinition, type DocumentPersistentStorageConfig, DocumentStatus, DocumentStore, DocumentStoreOptions, DocumentStoreState, DocumentStoreStoreEvents, type DynamicRealtimeThrottleMs, type FetchListFnReturn, type FetchListFnReturnItem, type FieldsInput, type FieldsOption, GET_ALL, type GlobalOfflineEntity, type GlobalOfflineStatus, IsOffScreenContext, type ListQueryOfflineEntityRef, type ListQueryOfflineOperationDefinition, type ListQueryPersistentStorageConfig, type ListQueryStore, type ListQueryStoreEvents, type ListQueryStoreOptions, type ListQueryUseMultipleItemsQuery, type ListQueryUseMultipleListQueriesQuery, type MaybeTSDFResult, type MutationDebounce, type MutationSkipped, type OfflineAccumulationConfig, type OfflineAccumulationMergeContext, type OfflineConflictResolutionAction, type OfflineEntityMutationKind, type OfflineMutationDescriptor, type OfflineMutationInput, type OfflineMutationQueueingCause, type OfflineMutationQueueingConfig, type OfflineMutationQueueingPolicy, type OfflineMutationResult, type OfflineMutationUploadsInput, type OfflineOperationKind, type OfflineOperationUploadsContext, type OfflineQueueEntry, type OfflineReplayRetryConfig, type OfflineResolutionAction, type OfflineResolutionActionForOperation, type OfflineResolutionConflictParseError, type OfflineResolutionConflictParseErrorCode, type OfflineResolutionRecord, type OfflineResolutionRecordForOperation, type OfflineResolutionRecordForStore, type OfflineRetryExhaustedResolutionAction, type OfflineRuntimeConfig, type OfflineRuntimeConfigUpdate, type OfflineSession, type OfflineSessionConfig, type OfflineSessionUploadsConfig, type OfflineStoredUploadRecord, type OfflineSupersedeConfig, type OfflineSyncState, type OfflineTempEntitiesConfig, type OfflineTempEntitiesReconciliation, type OfflineTempEntityConfig, type OfflineTempEntityPendingEntry, type OfflineUpload, type OfflineUploadAdapter, type OfflineUploadProgress, type OfflineUploadSource, type OfflineUploadState, type OfflineUploadTransportContext, type OffsetPaginationConfig, OnCollectionItemInvalidate, OnDocumentInvalidate, type OnListQueryInvalidate, type OnListQueryItemInvalidate, type OperationConflict, type OperationResult, type OptimisticListUpdate, type ParsedOfflineResolutionConflictResultForOperation, type PartialResourcesConfig, type PayloadDebounce, type PersistentStorageBaseConfig, type PersistentStorageDataSchema, type PersistentStoragePreloadResult, type PersistentStorageSchema, type QueryFetchPayload, type QueryStatus, type StorageAdapter, type StoreError, StoreFetchError, type StoreManager, StoreMutationError, type StoreMutationErrorOptions, type TSDFDebugLogArea, type TSDFDebugLogEntry, type TSDFDebugLogLevel, type TSDFDebugLogger, type TSDFFocusDebugOperation, type TSDFItemQuery, type TSDFLoggerOptions, type TSDFStatus, TSDFUseDocumentReturn, TSFDCollectionItem, TSFDCollectionState, type TSFDListQuery, type TSFDListQueryState, TSFDUseCollectionItemReturn, type TSFDUseListItemReturn, type TSFDUseListQueryReturn, type TSFDUsePendingOfflineItemsReturn, type ValidPayload, type ValidStoreState, clearAllSessionStorage, clearSessionStorage, createCollectionStore, createDocumentStore, createListQueryStore, createStoreManager, defaultOfflineRuntimeConfig, fetchTypePriority, getGlobalOfflineEntities, getGlobalOfflineResolutions, getGlobalOfflineStatus, localPersistentStorage, mutationSkipped, opfsOfflineUploadAdapter, useGlobalOfflineEntities, useGlobalOfflineResolutions, useGlobalOfflineStatus };