tsdf 17.0.0-alpha.1 → 17.0.0-alpha.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/main.d.ts +59 -16
- package/dist/main.js +144 -24
- package/docs/README.md +18 -15
- package/docs/collection-store.md +39 -38
- package/docs/document-store.md +27 -27
- package/docs/list-query-store.md +24 -22
- package/docs/persistent-storage.md +6 -6
- package/docs/real-time-updates.md +5 -3
- package/docs/store-manager.md +10 -0
- package/package.json +1 -1
package/dist/main.d.ts
CHANGED
|
@@ -266,7 +266,7 @@ type PersistentStorageBaseConfig<TFinal, TStorage = unknown> = {
|
|
|
266
266
|
* Called when a storage write operation fails (e.g. quota exceeded, OPFS write error).
|
|
267
267
|
* Use this to log or report persistence failures to your error tracking service.
|
|
268
268
|
*/
|
|
269
|
-
onPersistentStorageError?: PersistentStorageErrorHandler;
|
|
269
|
+
onPersistentStorageError?: PersistentStorageErrorHandler | null;
|
|
270
270
|
};
|
|
271
271
|
/** Store-level persistent storage config. Session scoping comes from the parent store. */
|
|
272
272
|
type StorePersistentStorageBaseConfig<TFinal, TStorage = unknown> = Omit<PersistentStorageBaseConfig<TFinal, TStorage>, 'getSessionKey' | 'storeName'>;
|
|
@@ -1423,8 +1423,13 @@ type MutationDebounce = {
|
|
|
1423
1423
|
type StoreManagerStoreDefaults = {
|
|
1424
1424
|
/** 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. */
|
|
1425
1425
|
readonly baseCoalescingWindowMs: number; /** Shared window-close blocker used by mutations in attached stores. */
|
|
1426
|
-
readonly blockWindowClose: BlockWindowCloseHandler | null;
|
|
1426
|
+
readonly blockWindowClose: BlockWindowCloseHandler | null; /** Default focus revalidation policy for attached stores. */
|
|
1427
|
+
readonly revalidateOnWindowFocus: boolean | (() => boolean) | undefined;
|
|
1427
1428
|
};
|
|
1429
|
+
type StoreManagerMutationErrorHandler = (error: unknown, options: {
|
|
1430
|
+
dontShowToast?: boolean;
|
|
1431
|
+
silentErrors?: boolean;
|
|
1432
|
+
}) => void;
|
|
1428
1433
|
type StoreManagerOfflineApi<TUploadRef extends ValidPayload = ValidPayload> = {
|
|
1429
1434
|
/** Returns the shared offline config, when configured. */getOfflineConfig: () => OfflineSessionConfig<TUploadRef> | undefined; /** Latest effective runtime config for this manager's offline session. */
|
|
1430
1435
|
getOfflineRuntimeConfig: () => OfflineRuntimeConfig; /** Updates runtime controls for this manager's offline session. */
|
|
@@ -1454,10 +1459,12 @@ type StoreManagerOfflineApi<TUploadRef extends ValidPayload = ValidPayload> = {
|
|
|
1454
1459
|
type StoreManager<TUploadRef extends ValidPayload = ValidPayload> = {
|
|
1455
1460
|
/** Returns the active shared session / tenant key. */getSessionKey: () => string | false; /** Normalizes raw exceptions into the shared StoreError shape. */
|
|
1456
1461
|
errorNormalizer: (exception: Error) => StoreError; /** Global fallback for persistent storage failures in attached stores. */
|
|
1457
|
-
onPersistentStorageError: PersistentStorageErrorHandler | undefined; /**
|
|
1462
|
+
onPersistentStorageError: PersistentStorageErrorHandler | undefined; /** Global fallback for mutation failures in attached stores. */
|
|
1463
|
+
onMutationError: StoreManagerMutationErrorHandler | undefined; /** Shared defaults used by attached stores unless a store-level override exists. */
|
|
1458
1464
|
storeDefaults: StoreManagerStoreDefaults; /** Returns the unique ids of all currently registered store instances. */
|
|
1459
1465
|
getAllStoreIds: () => string[]; /** Resets all registered stores except the ignored logical ids. */
|
|
1460
|
-
resetAll: (ignoreStores: string[]) => void;
|
|
1466
|
+
resetAll: (ignoreStores: string[]) => void; /** Signals a shared real-time transport reconnect to all registered stores. */
|
|
1467
|
+
onTransportReconnect: () => void;
|
|
1461
1468
|
} & StoreManagerOfflineApi<TUploadRef>;
|
|
1462
1469
|
type CreateStoreManagerOptions<TUploadRef extends ValidPayload = ValidPayload> = {
|
|
1463
1470
|
/**
|
|
@@ -1470,7 +1477,9 @@ type CreateStoreManagerOptions<TUploadRef extends ValidPayload = ValidPayload> =
|
|
|
1470
1477
|
lowPriorityThrottleMs?: number; /** Default coalescing window for attached stores. Defaults to 10ms. */
|
|
1471
1478
|
baseCoalescingWindowMs?: number; /** Shared window-close blocker used by mutations in attached stores. Pass `null` to disable. */
|
|
1472
1479
|
blockWindowClose?: BlockWindowCloseHandler | null; /** Global fallback for persistent storage failures when a store does not provide its own handler. */
|
|
1473
|
-
onPersistentStorageError?: PersistentStorageErrorHandler; /**
|
|
1480
|
+
onPersistentStorageError?: PersistentStorageErrorHandler; /** Global fallback for mutation failures when a store does not provide its own handler. */
|
|
1481
|
+
onMutationError?: StoreManagerMutationErrorHandler; /** Default focus revalidation policy for attached stores. Store-level values override it. */
|
|
1482
|
+
revalidateOnWindowFocus?: boolean | (() => boolean); /** Optional shared offline session config for every attached store. */
|
|
1474
1483
|
offlineSession?: OfflineSessionConfig<TUploadRef>;
|
|
1475
1484
|
};
|
|
1476
1485
|
declare function createStoreManager<TUploadRef extends ValidPayload = ValidPayload>(options: CreateStoreManagerOptions<TUploadRef>): StoreManager<TUploadRef>;
|
|
@@ -1620,7 +1629,10 @@ type InternalCollectionOfflineOperations<ItemState extends ValidStoreState, Item
|
|
|
1620
1629
|
}> & ([ItemState | ItemPayload] extends [never] ? never : unknown);
|
|
1621
1630
|
type CollectionOfflineOperationsConfig<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = InternalCollectionOfflineOperations<ItemState, ItemPayload> | null;
|
|
1622
1631
|
type CollectionStoreOptions<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TOfflineOperations extends CollectionOfflineOperationsConfig<ItemState, ItemPayload> = null, StorageState = unknown> = {
|
|
1623
|
-
|
|
1632
|
+
/**
|
|
1633
|
+
* Stable id for this logical collection store. Used for debug labels,
|
|
1634
|
+
* persistence namespaces, and browser tab sync.
|
|
1635
|
+
*/
|
|
1624
1636
|
id: string; /** Shared global store manager providing session scoping and error normalization. */
|
|
1625
1637
|
storeManager: StoreManager;
|
|
1626
1638
|
fetchFn: (params: ItemPayload, signal: AbortSignal) => Promise<ItemState>; /** Optional batch fetch function for fetching multiple items at once */
|
|
@@ -1644,9 +1656,9 @@ type CollectionStoreOptions<ItemState extends ValidStoreState, ItemPayload exten
|
|
|
1644
1656
|
transportReconnectCooldownMs?: number;
|
|
1645
1657
|
onInvalidate?: OnCollectionItemInvalidate<ItemState, ItemPayload>;
|
|
1646
1658
|
onSchedulerEvent?: (event: RequestSchedulerEvents, data?: RequestSchedulerEventData) => void;
|
|
1647
|
-
onMutationError?: (error: unknown, options: {
|
|
1659
|
+
onMutationError?: ((error: unknown, options: {
|
|
1648
1660
|
silentErrors?: boolean;
|
|
1649
|
-
}) => void;
|
|
1661
|
+
}) => void) | null;
|
|
1650
1662
|
usesRealTimeUpdates?: boolean;
|
|
1651
1663
|
/** Opt-in persistent storage configuration. When provided, cached items are loaded
|
|
1652
1664
|
* from storage on first read and saved back on successful fetches.
|
|
@@ -1710,6 +1722,10 @@ type CollectionStore<ItemState extends ValidStoreState, ItemPayload extends Vali
|
|
|
1710
1722
|
data: null;
|
|
1711
1723
|
error: StoreFetchError;
|
|
1712
1724
|
}>;
|
|
1725
|
+
getItemFromStateOrFetch: (params: ItemPayload, options?: {
|
|
1726
|
+
ignoreStaleState?: boolean;
|
|
1727
|
+
timeoutMs?: number;
|
|
1728
|
+
}) => Promise<Result<ItemState, StoreFetchError>>;
|
|
1713
1729
|
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>[];
|
|
1714
1730
|
useItem: <Selected = ItemState | null>(payload: ItemPayload | undefined | false | null, options?: UseItemOptions$1<ItemState, Selected>) => TSFDUseCollectionItemReturn<Selected, ItemPayload>;
|
|
1715
1731
|
useListItemIsLoading: (payload: ItemPayload, args: {
|
|
@@ -1760,7 +1776,6 @@ type CollectionStore<ItemState extends ValidStoreState, ItemPayload extends Vali
|
|
|
1760
1776
|
onTransportReconnect: () => void;
|
|
1761
1777
|
};
|
|
1762
1778
|
declare function createCollectionStore<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TOfflineOperations extends CollectionOfflineOperationsConfig<ItemState, ItemPayload> = null, StorageState = unknown>({
|
|
1763
|
-
debugName,
|
|
1764
1779
|
id,
|
|
1765
1780
|
storeManager,
|
|
1766
1781
|
fetchFn,
|
|
@@ -1831,7 +1846,10 @@ type DocumentBrowserTabsMessage<State extends ValidStoreState> = (BrowserTabsMes
|
|
|
1831
1846
|
type InternalDocumentOfflineOperations<State extends ValidStoreState> = Record<string, AnyOfflineOperationDefinition<__LEGIT_ANY__>> & ([State] extends [never] ? never : unknown);
|
|
1832
1847
|
type DocumentOfflineOperationsConfig<State extends ValidStoreState> = InternalDocumentOfflineOperations<State> | null;
|
|
1833
1848
|
type DocumentStoreOptions<State extends ValidStoreState, TOfflineOperations extends DocumentOfflineOperationsConfig<State> = null, StorageState = unknown> = {
|
|
1834
|
-
|
|
1849
|
+
/**
|
|
1850
|
+
* Stable id for this logical document store. Used for debug labels,
|
|
1851
|
+
* persistence namespaces, and browser tab sync.
|
|
1852
|
+
*/
|
|
1835
1853
|
id: string; /** Shared global store manager providing session scoping and error normalization. */
|
|
1836
1854
|
storeManager: StoreManager;
|
|
1837
1855
|
fetchFn: (signal: AbortSignal) => Promise<State>; /** Overrides the manager's default minimum interval between low-priority fetches for this store. */
|
|
@@ -1848,9 +1866,9 @@ type DocumentStoreOptions<State extends ValidStoreState, TOfflineOperations exte
|
|
|
1848
1866
|
transportReconnectCooldownMs?: number;
|
|
1849
1867
|
mediumPriorityDelayMs?: number;
|
|
1850
1868
|
onSchedulerEvent?: (event: RequestSchedulerEvents, data?: RequestSchedulerEventData) => void;
|
|
1851
|
-
onMutationError?: (error: unknown, options: {
|
|
1869
|
+
onMutationError?: ((error: unknown, options: {
|
|
1852
1870
|
dontShowToast?: boolean;
|
|
1853
|
-
}) => void;
|
|
1871
|
+
}) => void) | null;
|
|
1854
1872
|
usesRealTimeUpdates?: boolean;
|
|
1855
1873
|
/** Opt-in persistent storage configuration. When provided, cached data is loaded
|
|
1856
1874
|
* from storage on first read and saved back on successful fetches.
|
|
@@ -1903,6 +1921,10 @@ type DocumentStore<State extends ValidStoreState, TOfflineOperations extends Doc
|
|
|
1903
1921
|
data: null;
|
|
1904
1922
|
error: StoreFetchError;
|
|
1905
1923
|
}>;
|
|
1924
|
+
getDataFromStateOrFetch: (options?: {
|
|
1925
|
+
ignoreStaleState?: boolean;
|
|
1926
|
+
timeoutMs?: number;
|
|
1927
|
+
}) => Promise<Result<State, StoreFetchError>>;
|
|
1906
1928
|
preloadPersistentStorage: () => Promise<void>;
|
|
1907
1929
|
invalidateData: (priority?: FetchType) => void;
|
|
1908
1930
|
updateState: DocumentUpdateState<State>;
|
|
@@ -1952,7 +1974,6 @@ type DocumentStore<State extends ValidStoreState, TOfflineOperations extends Doc
|
|
|
1952
1974
|
onTransportReconnect: () => void;
|
|
1953
1975
|
};
|
|
1954
1976
|
declare function createDocumentStore<State extends ValidStoreState, TOfflineOperations extends DocumentOfflineOperationsConfig<State> = null, StorageState = unknown>({
|
|
1955
|
-
debugName,
|
|
1956
1977
|
id,
|
|
1957
1978
|
storeManager,
|
|
1958
1979
|
fetchFn,
|
|
@@ -2310,6 +2331,18 @@ type ListQueryAwaitListQueryFetchApi<ItemState extends ValidStoreState, QueryPay
|
|
|
2310
2331
|
error: null;
|
|
2311
2332
|
hasMore: boolean;
|
|
2312
2333
|
}>;
|
|
2334
|
+
type ListQueryGetQueryFromStateOrFetchOptions<TPartialResources extends boolean> = {
|
|
2335
|
+
ignoreStaleState?: boolean;
|
|
2336
|
+
size?: number;
|
|
2337
|
+
timeoutMs?: number;
|
|
2338
|
+
} & ListQueryFetchFieldsOption<TPartialResources>;
|
|
2339
|
+
type ListQueryGetQueryFromStateOrFetchApi<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean> = (params: QueryPayload, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [options: ListQueryGetQueryFromStateOrFetchOptions<TPartialResources>] : [options?: ListQueryGetQueryFromStateOrFetchOptions<TPartialResources>]) => Promise<Result<{
|
|
2340
|
+
items: {
|
|
2341
|
+
data: ItemState;
|
|
2342
|
+
itemPayload: ItemPayload;
|
|
2343
|
+
}[];
|
|
2344
|
+
hasMore: boolean;
|
|
2345
|
+
}, StoreFetchError>>;
|
|
2313
2346
|
type ListQueryAwaitItemFetchOptions<TPartialResources extends boolean> = {
|
|
2314
2347
|
timeoutMs?: number;
|
|
2315
2348
|
} & ListQueryFetchFieldsOption<TPartialResources>;
|
|
@@ -2320,6 +2353,11 @@ type ListQueryAwaitItemFetchApi<ItemState extends ValidStoreState, ItemPayload e
|
|
|
2320
2353
|
data: ItemState;
|
|
2321
2354
|
error: null;
|
|
2322
2355
|
}>;
|
|
2356
|
+
type ListQueryGetItemFromStateOrFetchOptions<TPartialResources extends boolean> = {
|
|
2357
|
+
ignoreStaleState?: boolean;
|
|
2358
|
+
timeoutMs?: number;
|
|
2359
|
+
} & ListQueryFetchFieldsOption<TPartialResources>;
|
|
2360
|
+
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>>;
|
|
2323
2361
|
type ListQueryUseMultipleListQueriesApi<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean> = {
|
|
2324
2362
|
<SelectedItem = ItemState, QueryMetadata extends undefined | Record<string, unknown> = undefined>(queries: (ListQueryUseMultipleListQueriesQuery<QueryPayload, QueryMetadata> & FieldsOption<ListQueryHasPartialResources<TPartialResources>>)[], options?: UseMultipleListQueriesOptions<ItemState, ItemPayload, SelectedItem>): readonly TSFDUseListQueryReturn<SelectedItem, QueryPayload, QueryMetadata>[];
|
|
2325
2363
|
<S = ItemState>(queries: ListQueryUseMultipleListQueriesQuery<QueryPayload, undefined>[], options: UseMultipleListQueriesOptions<ItemState, ItemPayload, S>): readonly TSFDUseListQueryReturn<S, QueryPayload, undefined>[];
|
|
@@ -2407,6 +2445,7 @@ type ListQueryStore<ItemState extends ValidStoreState, QueryPayload extends Vali
|
|
|
2407
2445
|
key: string;
|
|
2408
2446
|
}[];
|
|
2409
2447
|
awaitListQueryFetch: ListQueryAwaitListQueryFetchApi<ItemState, QueryPayload, ItemPayload, TPartialResources>;
|
|
2448
|
+
getQueryFromStateOrFetch: ListQueryGetQueryFromStateOrFetchApi<ItemState, QueryPayload, ItemPayload, TPartialResources>;
|
|
2410
2449
|
preloadQueryFromStorage: (params: QueryPayload | QueryPayload[]) => Promise<PersistentStoragePreloadResult<QueryPayload>[]>;
|
|
2411
2450
|
loadMore: ListQueryLoadMoreApi<QueryPayload, TPartialResources>;
|
|
2412
2451
|
getItemKey: (params: ItemPayload) => string;
|
|
@@ -2427,6 +2466,7 @@ type ListQueryStore<ItemState extends ValidStoreState, QueryPayload extends Vali
|
|
|
2427
2466
|
preloadItemFromStorage: (params: ItemPayload | ItemPayload[]) => Promise<PersistentStoragePreloadResult<ItemPayload>[]>;
|
|
2428
2467
|
scheduleItemFetch: ListQueryScheduleItemFetchApi<ItemPayload, TPartialResources>;
|
|
2429
2468
|
awaitItemFetch: ListQueryAwaitItemFetchApi<ItemState, ItemPayload, TPartialResources>;
|
|
2469
|
+
getItemFromStateOrFetch: ListQueryGetItemFromStateOrFetchApi<ItemState, ItemPayload, TPartialResources>;
|
|
2430
2470
|
invalidateQueryAndItems: (args: {
|
|
2431
2471
|
itemPayload: ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload> | false;
|
|
2432
2472
|
queryPayload: QueryPayload | QueryPayload[] | ListQueryFilterQuery<QueryPayload> | false;
|
|
@@ -2498,7 +2538,10 @@ type ListQueryBrowserTabsMessage<ItemState extends ValidStoreState, QueryPayload
|
|
|
2498
2538
|
duration: number;
|
|
2499
2539
|
});
|
|
2500
2540
|
type ListQueryStoreOptionsBase<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean = false, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload> = null, StorageState = unknown> = {
|
|
2501
|
-
|
|
2541
|
+
/**
|
|
2542
|
+
* Stable id for this logical list-query store. Used for debug labels,
|
|
2543
|
+
* persistence namespaces, and browser tab sync.
|
|
2544
|
+
*/
|
|
2502
2545
|
id: string; /** Shared global store manager providing session scoping and error normalization. */
|
|
2503
2546
|
storeManager: StoreManager;
|
|
2504
2547
|
fetchItemFn?: (payload: ItemPayload, options: {
|
|
@@ -2549,9 +2592,9 @@ type ListQueryStoreOptionsBase<ItemState extends ValidStoreState, QueryPayload e
|
|
|
2549
2592
|
onInvalidateQuery?: OnListQueryInvalidate<QueryPayload>;
|
|
2550
2593
|
onInvalidateItem?: OnListQueryItemInvalidate<ItemState, ItemPayload>;
|
|
2551
2594
|
onSchedulerEvent?: (event: RequestSchedulerEvents, data?: RequestSchedulerEventData) => void;
|
|
2552
|
-
onMutationError?: (error: unknown, options: {
|
|
2595
|
+
onMutationError?: ((error: unknown, options: {
|
|
2553
2596
|
silentErrors?: boolean;
|
|
2554
|
-
}) => void; /** Opt-in hook-level query derivation from locally materialized items. */
|
|
2597
|
+
}) => void) | null; /** Opt-in hook-level query derivation from locally materialized items. */
|
|
2555
2598
|
derivedQueries?: DerivedQueriesConfig<ItemState, QueryPayload, ItemPayload>;
|
|
2556
2599
|
getQueryKey?: (params: QueryPayload) => ValidPayload | unknown[];
|
|
2557
2600
|
getItemKey?: (params: ItemPayload) => ValidPayload | unknown[];
|
package/dist/main.js
CHANGED
|
@@ -9936,6 +9936,15 @@ const fetchTypePriority = {
|
|
|
9936
9936
|
highPriority: 3
|
|
9937
9937
|
};
|
|
9938
9938
|
const mutationSkipped = { kind: "skipped" };
|
|
9939
|
+
/**
|
|
9940
|
+
* Resolves a store-level option that may inherit from a manager-level fallback.
|
|
9941
|
+
* `undefined` means "use the manager value" and `null` means "explicit opt-out,
|
|
9942
|
+
* ignore the manager value".
|
|
9943
|
+
*/
|
|
9944
|
+
function resolveManagerFallback(storeLevel, managerLevel) {
|
|
9945
|
+
if (storeLevel === null) return void 0;
|
|
9946
|
+
return storeLevel ?? managerLevel;
|
|
9947
|
+
}
|
|
9939
9948
|
function getStoreErrorLike(value) {
|
|
9940
9949
|
if (value === null || typeof value !== "object" || !("code" in value) || typeof value.code !== "number" || !("id" in value) || typeof value.id !== "string" || !("message" in value) || typeof value.message !== "string") return null;
|
|
9941
9950
|
return {
|
|
@@ -10650,10 +10659,12 @@ function createStoreManager(options) {
|
|
|
10650
10659
|
getSessionKey: options.getSessionKey,
|
|
10651
10660
|
errorNormalizer: options.errorNormalizer,
|
|
10652
10661
|
onPersistentStorageError: options.onPersistentStorageError,
|
|
10662
|
+
onMutationError: options.onMutationError,
|
|
10653
10663
|
storeDefaults: Object.freeze({
|
|
10654
10664
|
lowPriorityThrottleMs: options.lowPriorityThrottleMs ?? DEFAULT_LOW_PRIORITY_THROTTLE_MS,
|
|
10655
10665
|
baseCoalescingWindowMs: options.baseCoalescingWindowMs ?? DEFAULT_BASE_COALESCING_WINDOW_MS,
|
|
10656
|
-
blockWindowClose: options.blockWindowClose ?? null
|
|
10666
|
+
blockWindowClose: options.blockWindowClose ?? null,
|
|
10667
|
+
revalidateOnWindowFocus: options.revalidateOnWindowFocus
|
|
10657
10668
|
}),
|
|
10658
10669
|
getAllStoreIds: () => Array.from(registry.stores.values(), ({ id }) => id),
|
|
10659
10670
|
resetAll: (ignoreStores) => {
|
|
@@ -10663,6 +10674,9 @@ function createStoreManager(options) {
|
|
|
10663
10674
|
registeredStore.reset();
|
|
10664
10675
|
}
|
|
10665
10676
|
},
|
|
10677
|
+
onTransportReconnect: () => {
|
|
10678
|
+
for (const registeredStore of [...registry.stores.values()]) registeredStore.onTransportReconnect();
|
|
10679
|
+
},
|
|
10666
10680
|
...offlineApi
|
|
10667
10681
|
};
|
|
10668
10682
|
storeManagerRegistry.set(storeManager, registry);
|
|
@@ -11453,10 +11467,12 @@ function useMultipleItems$1(items, { selector, returnIdleStatus: allItemsReturnI
|
|
|
11453
11467
|
//#endregion
|
|
11454
11468
|
//#region src/collectionStore/collectionStore.ts
|
|
11455
11469
|
const EMPTY_COLLECTION_OFFLINE_OPERATIONS = {};
|
|
11456
|
-
function createCollectionStore({
|
|
11470
|
+
function createCollectionStore({ id, storeManager, fetchFn, batchFetchFn, getItemsBatchKey, maxBatchSize, maxItems = 5e3, onStateCleanup, lowPriorityThrottleMs: storeLowPriorityThrottleMs, baseCoalescingWindowMs: storeBaseCoalescingWindowMs, mediumPriorityDelayMs, dynamicRealtimeThrottleMs, revalidateOnWindowFocus, transportReconnectCooldownMs = 2e3, getCollectionItemKey: filterCollectionItemObjKey, onInvalidate, onSchedulerEvent, onMutationError, usesRealTimeUpdates = false, persistentStorage: persistentStorageConfig, "~test": testOptions }) {
|
|
11457
11471
|
const lowPriorityThrottleMs = storeLowPriorityThrottleMs ?? storeManager.storeDefaults.lowPriorityThrottleMs;
|
|
11458
11472
|
const baseCoalescingWindowMs = storeBaseCoalescingWindowMs ?? storeManager.storeDefaults.baseCoalescingWindowMs;
|
|
11459
11473
|
const blockWindowClose = storeManager.storeDefaults.blockWindowClose;
|
|
11474
|
+
const resolvedRevalidateOnWindowFocus = revalidateOnWindowFocus ?? storeManager.storeDefaults.revalidateOnWindowFocus;
|
|
11475
|
+
const resolvedOnMutationError = resolveManagerFallback(onMutationError, storeManager.onMutationError);
|
|
11460
11476
|
let remoteApplyDepth = 0;
|
|
11461
11477
|
let currentBroadcastConsistency = "confirmed";
|
|
11462
11478
|
const lastCollectionSyncVersions = /* @__PURE__ */ new Map();
|
|
@@ -11491,7 +11507,7 @@ function createCollectionStore({ debugName, id, storeManager, fetchFn, batchFetc
|
|
|
11491
11507
|
})();
|
|
11492
11508
|
const resolvedPersistentStorageConfig = persistentStorageConfig ? __LEGIT_CAST__({
|
|
11493
11509
|
...persistentStorageConfig,
|
|
11494
|
-
onPersistentStorageError: persistentStorageConfig.onPersistentStorageError
|
|
11510
|
+
onPersistentStorageError: resolveManagerFallback(persistentStorageConfig.onPersistentStorageError, storeManager.onPersistentStorageError),
|
|
11495
11511
|
offline: persistentStorageConfig.offline ? {
|
|
11496
11512
|
...persistentStorageConfig.offline,
|
|
11497
11513
|
session: resolvedOfflineSessionForPersistentStorage
|
|
@@ -11506,8 +11522,9 @@ function createCollectionStore({ debugName, id, storeManager, fetchFn, batchFetc
|
|
|
11506
11522
|
if (testOptions.initialError) initialError = testOptions.initialError;
|
|
11507
11523
|
}
|
|
11508
11524
|
const persistence = resolvedPersistentStorageConfig ? setupCollectionPersistence(resolvedPersistentStorageConfig, { getItemKey }) : null;
|
|
11525
|
+
const persistentStorageErrorReporter = resolvedPersistentStorageConfig ? resolvedPersistentStorageConfig.onPersistentStorageError : storeManager.onPersistentStorageError;
|
|
11509
11526
|
const store = new Store({
|
|
11510
|
-
debugName,
|
|
11527
|
+
debugName: id,
|
|
11511
11528
|
state: () => {
|
|
11512
11529
|
const initialState = {};
|
|
11513
11530
|
if (initialData) for (const item of initialData) {
|
|
@@ -11983,6 +12000,13 @@ function createCollectionStore({ debugName, id, storeManager, fetchFn, batchFetc
|
|
|
11983
12000
|
error: null
|
|
11984
12001
|
};
|
|
11985
12002
|
}
|
|
12003
|
+
async function getItemFromStateOrFetch(params, { ignoreStaleState, timeoutMs } = {}) {
|
|
12004
|
+
const item = getItemFromStateOrPersistence(getItemKey(params), { materializeSyncState: true });
|
|
12005
|
+
if (item?.data && (!ignoreStaleState || item.status === "success" && !item.error && !item.refetchOnMount)) return Result.ok(item.data);
|
|
12006
|
+
const result = await awaitFetch(params, { timeoutMs });
|
|
12007
|
+
if (result.error) return Result.err(result.error);
|
|
12008
|
+
return Result.ok(result.data);
|
|
12009
|
+
}
|
|
11986
12010
|
function getItemFromStateOrPersistence(itemKey, options = {}) {
|
|
11987
12011
|
const item = store.state[itemKey];
|
|
11988
12012
|
if (Object.hasOwn(store.state, itemKey)) return item;
|
|
@@ -12050,7 +12074,7 @@ function createCollectionStore({ debugName, id, storeManager, fetchFn, batchFetc
|
|
|
12050
12074
|
async function preloadItemFromStorage(params) {
|
|
12051
12075
|
const payloads = Array.isArray(params) ? params : [params];
|
|
12052
12076
|
if (!persistence) {
|
|
12053
|
-
|
|
12077
|
+
persistentStorageErrorReporter?.(/* @__PURE__ */ new Error("Persistent storage preload is not available"));
|
|
12054
12078
|
return payloads.map((payload) => ({
|
|
12055
12079
|
payload,
|
|
12056
12080
|
preloaded: false
|
|
@@ -12201,7 +12225,7 @@ function createCollectionStore({ debugName, id, storeManager, fetchFn, batchFetc
|
|
|
12201
12225
|
});
|
|
12202
12226
|
if (restoredItemKeys.length > 0) touchItemsAndMaybeEnforceLimits(restoredItemKeys);
|
|
12203
12227
|
}
|
|
12204
|
-
if (!silentErrors &&
|
|
12228
|
+
if (!silentErrors && resolvedOnMutationError) resolvedOnMutationError(exception, { silentErrors });
|
|
12205
12229
|
return error;
|
|
12206
12230
|
}
|
|
12207
12231
|
});
|
|
@@ -12218,7 +12242,7 @@ function createCollectionStore({ debugName, id, storeManager, fetchFn, batchFetc
|
|
|
12218
12242
|
return result;
|
|
12219
12243
|
}
|
|
12220
12244
|
const focusLifecycle = createStoreFocusLifecycle({
|
|
12221
|
-
revalidateOnWindowFocus,
|
|
12245
|
+
revalidateOnWindowFocus: resolvedRevalidateOnWindowFocus,
|
|
12222
12246
|
usesRealTimeUpdates,
|
|
12223
12247
|
transportReconnectCooldownMs,
|
|
12224
12248
|
getWindowIsFocused,
|
|
@@ -12363,7 +12387,8 @@ function createCollectionStore({ debugName, id, storeManager, fetchFn, batchFetc
|
|
|
12363
12387
|
let isDisposed = false;
|
|
12364
12388
|
const unregisterStoreFromManager = registerStoreWithManager(storeManager, {
|
|
12365
12389
|
id,
|
|
12366
|
-
reset
|
|
12390
|
+
reset,
|
|
12391
|
+
onTransportReconnect
|
|
12367
12392
|
});
|
|
12368
12393
|
return {
|
|
12369
12394
|
store,
|
|
@@ -12374,6 +12399,7 @@ function createCollectionStore({ debugName, id, storeManager, fetchFn, batchFetc
|
|
|
12374
12399
|
},
|
|
12375
12400
|
scheduleFetch,
|
|
12376
12401
|
awaitFetch,
|
|
12402
|
+
getItemFromStateOrFetch,
|
|
12377
12403
|
useMultipleItems,
|
|
12378
12404
|
useItem,
|
|
12379
12405
|
useListItemIsLoading: useListItemIsLoading$2,
|
|
@@ -12589,10 +12615,12 @@ function assertDocumentOfflineOperations(operations) {
|
|
|
12589
12615
|
}
|
|
12590
12616
|
const DOC_REQUEST_ID = "_doc";
|
|
12591
12617
|
const DOC_TARGET_KEY = "document";
|
|
12592
|
-
function createDocumentStore({
|
|
12618
|
+
function createDocumentStore({ id, storeManager, fetchFn, lowPriorityThrottleMs: storeLowPriorityThrottleMs, baseCoalescingWindowMs: storeBaseCoalescingWindowMs, dynamicRealtimeThrottleMs, revalidateOnWindowFocus, transportReconnectCooldownMs = 2e3, mediumPriorityDelayMs, onSchedulerEvent, onMutationError, usesRealTimeUpdates = false, persistentStorage: persistentStorageConfig, "~test": testOptions }) {
|
|
12593
12619
|
const lowPriorityThrottleMs = storeLowPriorityThrottleMs ?? storeManager.storeDefaults.lowPriorityThrottleMs;
|
|
12594
12620
|
const baseCoalescingWindowMs = storeBaseCoalescingWindowMs ?? storeManager.storeDefaults.baseCoalescingWindowMs;
|
|
12595
12621
|
const blockWindowClose = storeManager.storeDefaults.blockWindowClose;
|
|
12622
|
+
const resolvedRevalidateOnWindowFocus = revalidateOnWindowFocus ?? storeManager.storeDefaults.revalidateOnWindowFocus;
|
|
12623
|
+
const resolvedOnMutationError = resolveManagerFallback(onMutationError, storeManager.onMutationError);
|
|
12596
12624
|
let invalidationWasTriggered = false;
|
|
12597
12625
|
let remoteApplyDepth = 0;
|
|
12598
12626
|
let currentBroadcastConsistency = "confirmed";
|
|
@@ -12631,7 +12659,7 @@ function createDocumentStore({ debugName, id, storeManager, fetchFn, lowPriority
|
|
|
12631
12659
|
})();
|
|
12632
12660
|
const resolvedPersistentStorageConfig = persistentStorageConfig ? __LEGIT_CAST__({
|
|
12633
12661
|
...persistentStorageConfig,
|
|
12634
|
-
onPersistentStorageError: persistentStorageConfig.onPersistentStorageError
|
|
12662
|
+
onPersistentStorageError: resolveManagerFallback(persistentStorageConfig.onPersistentStorageError, storeManager.onPersistentStorageError),
|
|
12635
12663
|
offline: persistentStorageConfig.offline ? {
|
|
12636
12664
|
...persistentStorageConfig.offline,
|
|
12637
12665
|
session: resolvedOfflineSessionForPersistentStorage
|
|
@@ -12646,6 +12674,7 @@ function createDocumentStore({ debugName, id, storeManager, fetchFn, lowPriority
|
|
|
12646
12674
|
if (testOptions.initialError) initialError = testOptions.initialError;
|
|
12647
12675
|
}
|
|
12648
12676
|
const persistence = resolvedPersistentStorageConfig ? setupDocumentPersistence(resolvedPersistentStorageConfig) : null;
|
|
12677
|
+
const persistentStorageErrorReporter = resolvedPersistentStorageConfig ? resolvedPersistentStorageConfig.onPersistentStorageError : storeManager.onPersistentStorageError;
|
|
12649
12678
|
const resolvedOfflineConfig = resolvedPersistentStorageConfig?.offline;
|
|
12650
12679
|
const resolvedOfflineOperations = __LEGIT_CAST__(resolvedOfflineConfig?.operations ?? EMPTY_DOCUMENT_OFFLINE_OPERATIONS);
|
|
12651
12680
|
if (import.meta.env.DEV) assertDocumentOfflineOperations(__LEGIT_CAST__(resolvedOfflineOperations));
|
|
@@ -12699,7 +12728,7 @@ function createDocumentStore({ debugName, id, storeManager, fetchFn, lowPriority
|
|
|
12699
12728
|
}
|
|
12700
12729
|
}) : null;
|
|
12701
12730
|
const store = new Store({
|
|
12702
|
-
debugName,
|
|
12731
|
+
debugName: id,
|
|
12703
12732
|
state: () => persistence?.createInitialState({
|
|
12704
12733
|
data: initialData,
|
|
12705
12734
|
error: initialError,
|
|
@@ -12893,7 +12922,7 @@ function createDocumentStore({ debugName, id, storeManager, fetchFn, lowPriority
|
|
|
12893
12922
|
});
|
|
12894
12923
|
if (initialStatus !== "idle" || initialData !== null || initialError !== null) scheduler.setLastFetchStartTimeForRequest(DOC_REQUEST_ID, testOptions?.initialLastFetchStartTime ?? 0);
|
|
12895
12924
|
const focusLifecycle = createStoreFocusLifecycle({
|
|
12896
|
-
revalidateOnWindowFocus,
|
|
12925
|
+
revalidateOnWindowFocus: resolvedRevalidateOnWindowFocus,
|
|
12897
12926
|
usesRealTimeUpdates,
|
|
12898
12927
|
transportReconnectCooldownMs,
|
|
12899
12928
|
getWindowIsFocused,
|
|
@@ -12934,9 +12963,16 @@ function createDocumentStore({ debugName, id, storeManager, fetchFn, lowPriority
|
|
|
12934
12963
|
error: null
|
|
12935
12964
|
};
|
|
12936
12965
|
}
|
|
12966
|
+
async function getDataFromStateOrFetch({ ignoreStaleState, timeoutMs } = {}) {
|
|
12967
|
+
const state = store.state;
|
|
12968
|
+
if (state.data !== null && (!ignoreStaleState || state.status === "success" && !state.error && !state.refetchOnMount)) return Result.ok(state.data);
|
|
12969
|
+
const result = await awaitFetch({ timeoutMs });
|
|
12970
|
+
if (result.error) return Result.err(result.error);
|
|
12971
|
+
return Result.ok(result.data);
|
|
12972
|
+
}
|
|
12937
12973
|
async function preloadPersistentStorage() {
|
|
12938
12974
|
if (!persistence?.hasAsyncPreload) {
|
|
12939
|
-
|
|
12975
|
+
persistentStorageErrorReporter?.(/* @__PURE__ */ new Error("Async preload is not available"));
|
|
12940
12976
|
return;
|
|
12941
12977
|
}
|
|
12942
12978
|
await persistence.preloadPersistentStorage();
|
|
@@ -13042,7 +13078,7 @@ function createDocumentStore({ debugName, id, storeManager, fetchFn, lowPriority
|
|
|
13042
13078
|
store.setKey("data", optimisticRollbackSnapshot ?? null, { action: "rollback-mutation-error" });
|
|
13043
13079
|
publishDocumentSnapshot();
|
|
13044
13080
|
});
|
|
13045
|
-
if (
|
|
13081
|
+
if (resolvedOnMutationError) resolvedOnMutationError(exception, { dontShowToast: dontShowErrorToast });
|
|
13046
13082
|
return toStoreMutationError(exception, errorNormalizer);
|
|
13047
13083
|
}
|
|
13048
13084
|
});
|
|
@@ -13199,7 +13235,8 @@ function createDocumentStore({ debugName, id, storeManager, fetchFn, lowPriority
|
|
|
13199
13235
|
let isDisposed = false;
|
|
13200
13236
|
const unregisterStoreFromManager = registerStoreWithManager(storeManager, {
|
|
13201
13237
|
id,
|
|
13202
|
-
reset
|
|
13238
|
+
reset,
|
|
13239
|
+
onTransportReconnect
|
|
13203
13240
|
});
|
|
13204
13241
|
return {
|
|
13205
13242
|
store,
|
|
@@ -13210,6 +13247,7 @@ function createDocumentStore({ debugName, id, storeManager, fetchFn, lowPriority
|
|
|
13210
13247
|
},
|
|
13211
13248
|
scheduleFetch,
|
|
13212
13249
|
awaitFetch,
|
|
13250
|
+
getDataFromStateOrFetch,
|
|
13213
13251
|
preloadPersistentStorage,
|
|
13214
13252
|
invalidateData,
|
|
13215
13253
|
updateState,
|
|
@@ -15576,6 +15614,11 @@ function createFetchApi({ store, normalizedFetchListFn, offsetPagination, fetchI
|
|
|
15576
15614
|
return item && itemPayload ? itemDataSelector(item, itemPayload, itemKey) : false;
|
|
15577
15615
|
});
|
|
15578
15616
|
}
|
|
15617
|
+
function hasStaleRequestedFields(itemKey, fields) {
|
|
15618
|
+
const invalidationFields = store.state.itemFieldInvalidationFields[itemKey];
|
|
15619
|
+
if (!invalidationFields || invalidationFields.length === 0) return false;
|
|
15620
|
+
return fields.some((field) => invalidationFields.includes(field));
|
|
15621
|
+
}
|
|
15579
15622
|
async function awaitListQueryFetch(params, options = {}) {
|
|
15580
15623
|
const queryKey = getQueryKey(params);
|
|
15581
15624
|
const size = options.size ?? defaultQuerySize;
|
|
@@ -15634,6 +15677,43 @@ function createFetchApi({ store, normalizedFetchListFn, offsetPagination, fetchI
|
|
|
15634
15677
|
hasMore: query.hasMore
|
|
15635
15678
|
};
|
|
15636
15679
|
}
|
|
15680
|
+
async function getQueryFromStateOrFetch(params, options = {}) {
|
|
15681
|
+
const queryKey = getQueryKey(params);
|
|
15682
|
+
const fields = normalizeFieldsOption(options.fields);
|
|
15683
|
+
const query = getQueryStateByKey(queryKey);
|
|
15684
|
+
const includeStale = !!options.ignoreStaleState;
|
|
15685
|
+
const cachedQueryCanBeUsed = !!query?.wasLoaded && (!includeStale || query.status === "success" && !query.error && !query.refetchOnMount);
|
|
15686
|
+
if (query && cachedQueryCanBeUsed) {
|
|
15687
|
+
if (!(partialResources && Array.isArray(fields) && fields.length > 0)) return Result.ok({
|
|
15688
|
+
items: getQueryItems(query, (data, itemPayload) => ({
|
|
15689
|
+
data,
|
|
15690
|
+
itemPayload
|
|
15691
|
+
})),
|
|
15692
|
+
hasMore: query.hasMore
|
|
15693
|
+
});
|
|
15694
|
+
if (!query.items.some((itemKey) => {
|
|
15695
|
+
const itemState = readItemState(itemKey);
|
|
15696
|
+
const invalidation = includeStale ? store.state.itemFieldInvalidationFields[itemKey] : void 0;
|
|
15697
|
+
return fields.some((field) => !fallbackItemHasRequestedFields(itemState, [field]) || (invalidation?.includes(field) ?? false));
|
|
15698
|
+
})) return Result.ok({
|
|
15699
|
+
items: getQueryItems(query, (data, itemPayload) => ({
|
|
15700
|
+
data,
|
|
15701
|
+
itemPayload
|
|
15702
|
+
})),
|
|
15703
|
+
hasMore: query.hasMore
|
|
15704
|
+
});
|
|
15705
|
+
}
|
|
15706
|
+
const result = await awaitListQueryFetch(params, {
|
|
15707
|
+
size: options.size,
|
|
15708
|
+
timeoutMs: options.timeoutMs,
|
|
15709
|
+
fields: options.fields
|
|
15710
|
+
});
|
|
15711
|
+
if (result.error) return Result.err(result.error);
|
|
15712
|
+
return Result.ok({
|
|
15713
|
+
items: result.items,
|
|
15714
|
+
hasMore: result.hasMore
|
|
15715
|
+
});
|
|
15716
|
+
}
|
|
15637
15717
|
function scheduleItemFetch(fetchType, itemPayload, options) {
|
|
15638
15718
|
if (!fetchItemFn) throw new Error(noFetchItemFnError);
|
|
15639
15719
|
const fields = normalizeFieldsOption(options?.fields);
|
|
@@ -15694,6 +15774,30 @@ function createFetchApi({ store, normalizedFetchListFn, offsetPagination, fetchI
|
|
|
15694
15774
|
error: null
|
|
15695
15775
|
};
|
|
15696
15776
|
}
|
|
15777
|
+
async function getItemFromStateOrFetch(itemPayload, options = {}) {
|
|
15778
|
+
const itemKey = getItemKey(itemPayload);
|
|
15779
|
+
const fields = normalizeFieldsOption(options.fields);
|
|
15780
|
+
const itemState = readItemState(itemKey);
|
|
15781
|
+
const item = itemState?.item;
|
|
15782
|
+
const itemQuery = itemState?.itemQuery;
|
|
15783
|
+
const includeStale = !!options.ignoreStaleState;
|
|
15784
|
+
const needsFieldCheck = partialResources && Array.isArray(fields) && fields.length > 0;
|
|
15785
|
+
const itemHasAllFields = !needsFieldCheck || fallbackItemHasRequestedFields(itemState, fields);
|
|
15786
|
+
const itemQueryFresh = itemQuery?.status === "success" && !itemQuery.error && !itemQuery.refetchOnMount;
|
|
15787
|
+
if (item != null && itemHasAllFields && (!includeStale || itemQueryFresh && (!needsFieldCheck || !hasStaleRequestedFields(itemKey, fields)))) return Result.ok(item);
|
|
15788
|
+
if (!fetchItemFn) throw new Error(noFetchItemFnError);
|
|
15789
|
+
let fieldsToFetch = options.fields;
|
|
15790
|
+
if (needsFieldCheck && item != null && itemQueryFresh) {
|
|
15791
|
+
const invalidation = includeStale ? store.state.itemFieldInvalidationFields[itemKey] : void 0;
|
|
15792
|
+
fieldsToFetch = fields.filter((field) => !fallbackItemHasRequestedFields(itemState, [field]) || (invalidation?.includes(field) ?? false));
|
|
15793
|
+
}
|
|
15794
|
+
const result = await awaitItemFetch(itemPayload, {
|
|
15795
|
+
timeoutMs: options.timeoutMs,
|
|
15796
|
+
fields: fieldsToFetch
|
|
15797
|
+
});
|
|
15798
|
+
if (result.error) return Result.err(result.error);
|
|
15799
|
+
return Result.ok(result.data);
|
|
15800
|
+
}
|
|
15697
15801
|
function resetSchedulers() {
|
|
15698
15802
|
for (const scheduler of querySchedulers.values()) scheduler.reset();
|
|
15699
15803
|
querySchedulers.clear();
|
|
@@ -15756,8 +15860,10 @@ function createFetchApi({ store, normalizedFetchListFn, offsetPagination, fetchI
|
|
|
15756
15860
|
scheduleListQueryFetch,
|
|
15757
15861
|
loadMore,
|
|
15758
15862
|
awaitListQueryFetch,
|
|
15863
|
+
getQueryFromStateOrFetch,
|
|
15759
15864
|
scheduleItemFetch,
|
|
15760
15865
|
awaitItemFetch,
|
|
15866
|
+
getItemFromStateOrFetch,
|
|
15761
15867
|
getOrCreateQueryScheduler,
|
|
15762
15868
|
getOrCreateItemScheduler,
|
|
15763
15869
|
syncRemoteFetchStart,
|
|
@@ -17583,10 +17689,12 @@ function usePendingOfflineItems({ selector, filterPayload, includeResolutionRequ
|
|
|
17583
17689
|
const EMPTY_LIST_QUERY_OFFLINE_OPERATIONS = {};
|
|
17584
17690
|
const noPartialResourcesFieldsOptionError = "fields option is required when partialResources is enabled";
|
|
17585
17691
|
function createListQueryStore(storeOptions) {
|
|
17586
|
-
const {
|
|
17692
|
+
const { id, storeManager, fetchItemFn, batchFetchItemFn, getItemsBatchKey, defaultQuerySize = 50, maxItemBatchSize, maxItems = 5e3, maxQueries = 1e3, onStateCleanup, usesRealTimeUpdates = false, "~test": testOptions, lowPriorityThrottleMs: storeLowPriorityThrottleMs, baseCoalescingWindowMs: storeBaseCoalescingWindowMs, mediumPriorityDelayMs, dynamicRealtimeThrottleMs, revalidateOnWindowFocus, transportReconnectCooldownMs = 2e3, optimisticListUpdates, onInvalidateQuery, onInvalidateItem, onSchedulerEvent, onMutationError, derivedQueries, getQueryKey: customGetQueryKey, getItemKey: customGetItemKey, partialResources, persistentStorage: persistentStorageConfig } = storeOptions;
|
|
17587
17693
|
const lowPriorityThrottleMs = storeLowPriorityThrottleMs ?? storeManager.storeDefaults.lowPriorityThrottleMs;
|
|
17588
17694
|
const baseCoalescingWindowMs = storeBaseCoalescingWindowMs ?? storeManager.storeDefaults.baseCoalescingWindowMs;
|
|
17589
17695
|
const blockWindowClose = storeManager.storeDefaults.blockWindowClose;
|
|
17696
|
+
const resolvedRevalidateOnWindowFocus = revalidateOnWindowFocus ?? storeManager.storeDefaults.revalidateOnWindowFocus;
|
|
17697
|
+
const resolvedOnMutationError = resolveManagerFallback(onMutationError, storeManager.onMutationError);
|
|
17590
17698
|
let remoteApplyDepth = 0;
|
|
17591
17699
|
let currentBroadcastConsistency = "confirmed";
|
|
17592
17700
|
const lastQuerySyncVersions = /* @__PURE__ */ new Map();
|
|
@@ -17629,7 +17737,7 @@ function createListQueryStore(storeOptions) {
|
|
|
17629
17737
|
const globalDisableRefetchOnMount = usesRealTimeUpdates;
|
|
17630
17738
|
const resolvedPersistentStorageConfig = persistentStorageConfig ? __LEGIT_CAST__({
|
|
17631
17739
|
...persistentStorageConfig,
|
|
17632
|
-
onPersistentStorageError: persistentStorageConfig.onPersistentStorageError
|
|
17740
|
+
onPersistentStorageError: resolveManagerFallback(persistentStorageConfig.onPersistentStorageError, storeManager.onPersistentStorageError),
|
|
17633
17741
|
offline: persistentStorageConfig.offline ? {
|
|
17634
17742
|
...persistentStorageConfig.offline,
|
|
17635
17743
|
session: resolvedOfflineSessionForPersistentStorage
|
|
@@ -17642,11 +17750,12 @@ function createListQueryStore(storeOptions) {
|
|
|
17642
17750
|
getItemDerivedGroup: derivedQueries?.getItemGroup,
|
|
17643
17751
|
getQueryKey
|
|
17644
17752
|
}) : null;
|
|
17753
|
+
const persistentStorageErrorReporter = resolvedPersistentStorageConfig ? resolvedPersistentStorageConfig.onPersistentStorageError : storeManager.onPersistentStorageError;
|
|
17645
17754
|
const resolvedOfflineConfig = resolvedPersistentStorageConfig?.offline;
|
|
17646
17755
|
const resolvedOfflineOperations = __LEGIT_CAST__(resolvedOfflineConfig?.operations ?? EMPTY_LIST_QUERY_OFFLINE_OPERATIONS);
|
|
17647
17756
|
const offlineOperationsForRuntime = import.meta.env.TEST && testOptions?.onOfflineTimelineEvent && resolvedOfflineConfig ? wrapOfflineOperationsForTimeline(resolvedOfflineOperations, testOptions.onOfflineTimelineEvent) : resolvedOfflineOperations;
|
|
17648
17757
|
const store = new Store({
|
|
17649
|
-
debugName,
|
|
17758
|
+
debugName: id,
|
|
17650
17759
|
state: () => {
|
|
17651
17760
|
const initialState = {
|
|
17652
17761
|
items: {},
|
|
@@ -17831,7 +17940,7 @@ function createListQueryStore(storeOptions) {
|
|
|
17831
17940
|
async function preloadQueryFromPersistentStorage(payload) {
|
|
17832
17941
|
const payloads = Array.isArray(payload) ? payload : [payload];
|
|
17833
17942
|
if (!persistence) {
|
|
17834
|
-
|
|
17943
|
+
persistentStorageErrorReporter?.(/* @__PURE__ */ new Error("Persistent storage preload is not available"));
|
|
17835
17944
|
return payloads.map((queryPayload) => ({
|
|
17836
17945
|
payload: queryPayload,
|
|
17837
17946
|
preloaded: false
|
|
@@ -17857,7 +17966,7 @@ function createListQueryStore(storeOptions) {
|
|
|
17857
17966
|
async function preloadItemFromPersistentStorage(payload) {
|
|
17858
17967
|
const payloads = Array.isArray(payload) ? payload : [payload];
|
|
17859
17968
|
if (!persistence) {
|
|
17860
|
-
|
|
17969
|
+
persistentStorageErrorReporter?.(/* @__PURE__ */ new Error("Persistent storage preload is not available"));
|
|
17861
17970
|
return payloads.map((itemPayload) => ({
|
|
17862
17971
|
payload: itemPayload,
|
|
17863
17972
|
preloaded: false
|
|
@@ -17875,7 +17984,7 @@ function createListQueryStore(storeOptions) {
|
|
|
17875
17984
|
preloaded: results[index] ?? false
|
|
17876
17985
|
}));
|
|
17877
17986
|
}
|
|
17878
|
-
const { getQueryState, getQueriesKeyArray, getQueriesState, getQueriesRelatedToItem, getItemsKeyArray, getItemState, scheduleListQueryFetch, loadMore, awaitListQueryFetch, scheduleItemFetch, awaitItemFetch, getOrCreateQueryScheduler, getOrCreateItemScheduler, syncRemoteFetchStart, syncRemoteFetchSuccess, deleteQueryFetchResources, deleteItemFetchResources, resetSchedulers } = createFetchApi({
|
|
17987
|
+
const { getQueryState, getQueriesKeyArray, getQueriesState, getQueriesRelatedToItem, getItemsKeyArray, getItemState, scheduleListQueryFetch, loadMore, awaitListQueryFetch, getQueryFromStateOrFetch, scheduleItemFetch, awaitItemFetch, getItemFromStateOrFetch, getOrCreateQueryScheduler, getOrCreateItemScheduler, syncRemoteFetchStart, syncRemoteFetchSuccess, deleteQueryFetchResources, deleteItemFetchResources, resetSchedulers } = createFetchApi({
|
|
17879
17988
|
store,
|
|
17880
17989
|
normalizedFetchListFn,
|
|
17881
17990
|
offsetPagination,
|
|
@@ -17974,7 +18083,7 @@ function createListQueryStore(storeOptions) {
|
|
|
17974
18083
|
optimisticListUpdates,
|
|
17975
18084
|
onInvalidateQuery,
|
|
17976
18085
|
onInvalidateItem,
|
|
17977
|
-
onMutationError,
|
|
18086
|
+
onMutationError: resolvedOnMutationError,
|
|
17978
18087
|
errorNormalizer,
|
|
17979
18088
|
getItemKey,
|
|
17980
18089
|
getQueriesKeyArray,
|
|
@@ -18357,7 +18466,7 @@ function createListQueryStore(storeOptions) {
|
|
|
18357
18466
|
return useFindItem(findItemFn, options, store, registerActiveStandaloneItems, touchItems);
|
|
18358
18467
|
}
|
|
18359
18468
|
const focusLifecycle = createStoreFocusLifecycle({
|
|
18360
|
-
revalidateOnWindowFocus,
|
|
18469
|
+
revalidateOnWindowFocus: resolvedRevalidateOnWindowFocus,
|
|
18361
18470
|
usesRealTimeUpdates,
|
|
18362
18471
|
transportReconnectCooldownMs,
|
|
18363
18472
|
getWindowIsFocused,
|
|
@@ -18516,10 +18625,18 @@ function createListQueryStore(storeOptions) {
|
|
|
18516
18625
|
const [options] = args;
|
|
18517
18626
|
return awaitListQueryFetch(params, options);
|
|
18518
18627
|
};
|
|
18628
|
+
const getQueryFromStateOrFetchApi = (params, ...args) => {
|
|
18629
|
+
const [options] = args;
|
|
18630
|
+
return getQueryFromStateOrFetch(params, options);
|
|
18631
|
+
};
|
|
18519
18632
|
const awaitItemFetchApi = (itemPayload, ...args) => {
|
|
18520
18633
|
const [options] = args;
|
|
18521
18634
|
return awaitItemFetch(itemPayload, options);
|
|
18522
18635
|
};
|
|
18636
|
+
const getItemFromStateOrFetchApi = (itemPayload, ...args) => {
|
|
18637
|
+
const [options] = args;
|
|
18638
|
+
return getItemFromStateOrFetch(itemPayload, options);
|
|
18639
|
+
};
|
|
18523
18640
|
function getRelatedQueryKeysForItemEntries(itemEntries) {
|
|
18524
18641
|
return Array.from(new Set(itemEntries.flatMap(({ payload }) => getQueriesRelatedToItem(payload).map(({ key }) => key))));
|
|
18525
18642
|
}
|
|
@@ -18552,7 +18669,8 @@ function createListQueryStore(storeOptions) {
|
|
|
18552
18669
|
let isDisposed = false;
|
|
18553
18670
|
const unregisterStoreFromManager = registerStoreWithManager(storeManager, {
|
|
18554
18671
|
id,
|
|
18555
|
-
reset
|
|
18672
|
+
reset,
|
|
18673
|
+
onTransportReconnect
|
|
18556
18674
|
});
|
|
18557
18675
|
return {
|
|
18558
18676
|
store,
|
|
@@ -18572,6 +18690,7 @@ function createListQueryStore(storeOptions) {
|
|
|
18572
18690
|
getQueriesState,
|
|
18573
18691
|
getQueriesRelatedToItem,
|
|
18574
18692
|
awaitListQueryFetch: awaitListQueryFetchApi,
|
|
18693
|
+
getQueryFromStateOrFetch: getQueryFromStateOrFetchApi,
|
|
18575
18694
|
preloadQueryFromStorage: preloadQueryFromPersistentStorage,
|
|
18576
18695
|
loadMore: loadMoreApi,
|
|
18577
18696
|
getItemKey,
|
|
@@ -18604,6 +18723,7 @@ function createListQueryStore(storeOptions) {
|
|
|
18604
18723
|
preloadItemFromStorage: preloadItemFromPersistentStorage,
|
|
18605
18724
|
scheduleItemFetch: scheduleItemFetchApi,
|
|
18606
18725
|
awaitItemFetch: awaitItemFetchApi,
|
|
18726
|
+
getItemFromStateOrFetch: getItemFromStateOrFetchApi,
|
|
18607
18727
|
invalidateQueryAndItems,
|
|
18608
18728
|
invalidateItem,
|
|
18609
18729
|
startItemMutation,
|
package/docs/README.md
CHANGED
|
@@ -52,6 +52,10 @@ const storeManager = createStoreManager({
|
|
|
52
52
|
lowPriorityThrottleMs: 5,
|
|
53
53
|
baseCoalescingWindowMs: 10,
|
|
54
54
|
blockWindowClose: null,
|
|
55
|
+
revalidateOnWindowFocus: true,
|
|
56
|
+
onMutationError: (error) => {
|
|
57
|
+
console.error('TSDF mutation failed', error);
|
|
58
|
+
},
|
|
55
59
|
onPersistentStorageError: (error) => {
|
|
56
60
|
console.error('TSDF persistence failed', error);
|
|
57
61
|
},
|
|
@@ -77,18 +81,17 @@ function UserProfile() {
|
|
|
77
81
|
|
|
78
82
|
All three store types share these creation options:
|
|
79
83
|
|
|
80
|
-
| Option | Type | Required | Description
|
|
81
|
-
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | -------- |
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
86
|
-
| `
|
|
87
|
-
| `
|
|
88
|
-
| `
|
|
89
|
-
| `
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
| `id` | `string` | Yes | Stable logical store id for [Browser Tabs Sync](./browser-tabs-sync.md) |
|
|
84
|
+
| Option | Type | Required | Description |
|
|
85
|
+
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
86
|
+
| `storeManager` | `StoreManager` | Yes | Shared global config with session scoping, store defaults, and global store controls |
|
|
87
|
+
| `lowPriorityThrottleMs` | `number` | No | Overrides the manager default minimum interval between low-priority fetches |
|
|
88
|
+
| `baseCoalescingWindowMs` | `number` | No | Overrides the manager default window to group multiple fetch requests into a batch |
|
|
89
|
+
| `mediumPriorityDelayMs` | `number` | No | Delay before medium-priority fetches execute |
|
|
90
|
+
| `dynamicRealtimeThrottleMs` | `(params) => number` | No | Dynamic throttle for [real-time updates](./real-time-updates.md) |
|
|
91
|
+
| `revalidateOnWindowFocus` | `boolean \| (() => boolean)` | No | Overrides the manager default for refetching data when window regains focus. Use `false` to disable |
|
|
92
|
+
| `transportReconnectCooldownMs` | `number` | No | Cooldown for repeated transport reconnect revalidation |
|
|
93
|
+
| `persistentStorage` | `DocumentPersistentStorageConfig<...> \| CollectionPersistentStorageConfig<...> \| ListQueryPersistentStorageConfig<...>` | No | Configure cache persistence and optional session-based offline behavior |
|
|
94
|
+
| `usesRealTimeUpdates` | `boolean` | No | Enables [real-time update mode](./real-time-updates.md) |
|
|
95
|
+
| `onSchedulerEvent` | `(event) => void` | No | Callback for [scheduler events](./fetch-scheduling.md) |
|
|
96
|
+
| `onMutationError` | `(error, options) => void \| null` | No | Store-specific handler for [mutation](./mutations.md) errors. Overrides the manager fallback; use `null` to disable it |
|
|
97
|
+
| `id` | `string` | Yes | Stable logical store id used for debug labels, persistence namespaces, and [Browser Tabs Sync](./browser-tabs-sync.md) |
|
package/docs/collection-store.md
CHANGED
|
@@ -28,28 +28,28 @@ const productStore = createCollectionStore<Product, string>({
|
|
|
28
28
|
|
|
29
29
|
## Options
|
|
30
30
|
|
|
31
|
-
| Option | Type | Required | Description
|
|
32
|
-
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------- | -------- |
|
|
33
|
-
| `id` | `string` | Yes | Stable logical store id for [Browser Tabs Sync](./browser-tabs-sync.md)
|
|
34
|
-
| `storeManager` | `StoreManager` | Yes | Shared global config with `getSessionKey`, `errorNormalizer`, and global store controls
|
|
35
|
-
| `fetchFn` | `(params: ItemPayload, signal: AbortSignal) => Promise<ItemState>` | Yes | Fetches a single item
|
|
36
|
-
| `batchFetchFn` | `(payloads: ItemPayload[], signal: AbortSignal, batchKey: string) => Promise<Map<ItemPayload, ItemState \| Error>>` | No | See [Batch Fetching](./batch-fetching.md)
|
|
37
|
-
| `getItemsBatchKey` | `(payload: ItemPayload) => string \| false` | No | Groups batch fetches by key. `false` falls back to per-item fetch
|
|
38
|
-
| `maxBatchSize` | `number` | No | Triggers immediate fetch when batch reaches this size
|
|
39
|
-
| `maxItems` | `number` | No | Maximum cached items kept in memory. Defaults to `5000`. See [Cache Limits](./cache-limits.md)
|
|
40
|
-
| `onStateCleanup` | `(cleanup) => void` | No | Called when memory cache eviction removes items. See [Cache Limits](./cache-limits.md)
|
|
41
|
-
| `getCollectionItemKey` | `(params: ItemPayload) => ValidPayload \| unknown[]` | No | Custom key derivation from payload
|
|
42
|
-
| `lowPriorityThrottleMs` | `number` | No | Overrides the manager default. See [Fetch Scheduling](./fetch-scheduling.md)
|
|
43
|
-
| `baseCoalescingWindowMs` | `number` | No | Overrides the manager default. See [Fetch Scheduling](./fetch-scheduling.md)
|
|
44
|
-
| `mediumPriorityDelayMs` | `number` | No | Delay for medium-priority fetches
|
|
45
|
-
| `dynamicRealtimeThrottleMs` | `(params) => number` | No | See [Real-Time Updates](./real-time-updates.md)
|
|
46
|
-
| `revalidateOnWindowFocus` | `boolean \| (() => boolean)` | No | Refetch on window focus
|
|
47
|
-
| `transportReconnectCooldownMs` | `number` | No | Cooldown for repeated transport reconnect revalidation
|
|
48
|
-
| `usesRealTimeUpdates` | `boolean` | No | See [Real-Time Updates](./real-time-updates.md)
|
|
49
|
-
| `persistentStorage` | `CollectionPersistentStorageConfig<ItemState, ItemPayload>` | No | Configure cache persistence. See [Persistent Storage](./persistent-storage.md)
|
|
50
|
-
| `onInvalidate` | `(props: { itemState, payload, priority }) => void` | No | Called when an item is invalidated
|
|
51
|
-
| `onSchedulerEvent` | `(event, data?) => void` | No | Scheduler event listener
|
|
52
|
-
| `onMutationError` | `(error, options: { silentErrors? }) => void` | No | Global mutation error handler
|
|
31
|
+
| Option | Type | Required | Description |
|
|
32
|
+
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
33
|
+
| `id` | `string` | Yes | Stable logical store id used for debug labels, persistence namespaces, and [Browser Tabs Sync](./browser-tabs-sync.md) |
|
|
34
|
+
| `storeManager` | `StoreManager` | Yes | Shared global config with `getSessionKey`, `errorNormalizer`, and global store controls |
|
|
35
|
+
| `fetchFn` | `(params: ItemPayload, signal: AbortSignal) => Promise<ItemState>` | Yes | Fetches a single item |
|
|
36
|
+
| `batchFetchFn` | `(payloads: ItemPayload[], signal: AbortSignal, batchKey: string) => Promise<Map<ItemPayload, ItemState \| Error>>` | No | See [Batch Fetching](./batch-fetching.md) |
|
|
37
|
+
| `getItemsBatchKey` | `(payload: ItemPayload) => string \| false` | No | Groups batch fetches by key. `false` falls back to per-item fetch |
|
|
38
|
+
| `maxBatchSize` | `number` | No | Triggers immediate fetch when batch reaches this size |
|
|
39
|
+
| `maxItems` | `number` | No | Maximum cached items kept in memory. Defaults to `5000`. See [Cache Limits](./cache-limits.md) |
|
|
40
|
+
| `onStateCleanup` | `(cleanup) => void` | No | Called when memory cache eviction removes items. See [Cache Limits](./cache-limits.md) |
|
|
41
|
+
| `getCollectionItemKey` | `(params: ItemPayload) => ValidPayload \| unknown[]` | No | Custom key derivation from payload |
|
|
42
|
+
| `lowPriorityThrottleMs` | `number` | No | Overrides the manager default. See [Fetch Scheduling](./fetch-scheduling.md) |
|
|
43
|
+
| `baseCoalescingWindowMs` | `number` | No | Overrides the manager default. See [Fetch Scheduling](./fetch-scheduling.md) |
|
|
44
|
+
| `mediumPriorityDelayMs` | `number` | No | Delay for medium-priority fetches |
|
|
45
|
+
| `dynamicRealtimeThrottleMs` | `(params) => number` | No | See [Real-Time Updates](./real-time-updates.md) |
|
|
46
|
+
| `revalidateOnWindowFocus` | `boolean \| (() => boolean)` | No | Refetch on window focus |
|
|
47
|
+
| `transportReconnectCooldownMs` | `number` | No | Cooldown for repeated transport reconnect revalidation |
|
|
48
|
+
| `usesRealTimeUpdates` | `boolean` | No | See [Real-Time Updates](./real-time-updates.md) |
|
|
49
|
+
| `persistentStorage` | `CollectionPersistentStorageConfig<ItemState, ItemPayload>` | No | Configure cache persistence. See [Persistent Storage](./persistent-storage.md) |
|
|
50
|
+
| `onInvalidate` | `(props: { itemState, payload, priority }) => void` | No | Called when an item is invalidated |
|
|
51
|
+
| `onSchedulerEvent` | `(event, data?) => void` | No | Scheduler event listener |
|
|
52
|
+
| `onMutationError` | `(error, options: { silentErrors? }) => void` | No | Global mutation error handler |
|
|
53
53
|
|
|
54
54
|
## Item State Shape
|
|
55
55
|
|
|
@@ -88,22 +88,23 @@ The overall store state is `Record<string, TSFDCollectionItem | null>` where key
|
|
|
88
88
|
|
|
89
89
|
### Methods
|
|
90
90
|
|
|
91
|
-
| Method
|
|
92
|
-
|
|
|
93
|
-
| `scheduleFetch`
|
|
94
|
-
| `awaitFetch`
|
|
95
|
-
| `
|
|
96
|
-
| `
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
| `
|
|
102
|
-
| `
|
|
103
|
-
| `
|
|
104
|
-
| `
|
|
105
|
-
| `
|
|
106
|
-
| `
|
|
91
|
+
| Method | Signature | Description |
|
|
92
|
+
| ------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
93
|
+
| `scheduleFetch` | `(fetchType, payload(s), options?) => ScheduleFetchResults` | Schedule fetch for one or more items |
|
|
94
|
+
| `awaitFetch` | `(params, options?) => Promise<{ data, error }>` | Await fetch with optional `timeoutMs` |
|
|
95
|
+
| `getItemFromStateOrFetch` | `(params, options?) => Promise<Result<ItemState, StoreFetchError>>` | Return loaded item data or fetch it if missing |
|
|
96
|
+
| `preloadItemFromStorage` | `(params) => Promise<PersistentStoragePreloadResult<ItemPayload>[]>` | Preload cached item payloads from async storage (OPFS) |
|
|
97
|
+
| `getItemKey` | `(params) => string` | Get the composite key for a payload |
|
|
98
|
+
| `getItemState` | `(params) => CollectionItem` | Get item state (single, array, or filter function) |
|
|
99
|
+
| `invalidateItem` | `(payload(s), priority?) => void` | See [Invalidation](./invalidation.md) |
|
|
100
|
+
| `updateItemState` | `(params, produceFn, options?) => boolean` | Immer-based state update |
|
|
101
|
+
| `addItemToState` | `(payload, data) => void` | Add a new item to the store |
|
|
102
|
+
| `deleteItemState` | `(params) => void` | Delete item(s) and cleanup scheduler resources |
|
|
103
|
+
| `startMutation` | `(params) => () => void` | Start mutation lock. See [Mutations](./mutations.md) |
|
|
104
|
+
| `performMutation` | `(payload, options) => Promise<Result<T>>` | Full mutation lifecycle. See [Mutations](./mutations.md) |
|
|
105
|
+
| `reset` | `() => void` | Reset store and all schedulers |
|
|
106
|
+
| `dispose` | `() => void` | Release listeners and store-manager registration |
|
|
107
|
+
| `onTransportReconnect` | `() => void` | Store-level reconnect hook. Prefer `storeManager.onTransportReconnect()` for shared transports. See [Real-Time Updates](./real-time-updates.md) |
|
|
107
108
|
|
|
108
109
|
### Offline Methods
|
|
109
110
|
|
package/docs/document-store.md
CHANGED
|
@@ -28,22 +28,21 @@ const userStore = createDocumentStore<User>({
|
|
|
28
28
|
|
|
29
29
|
## Options
|
|
30
30
|
|
|
31
|
-
| Option | Type | Required | Description
|
|
32
|
-
| ------------------------------ | -------------------------------------------------------------------------------- | -------- |
|
|
33
|
-
| `id` | `string` | Yes | Stable logical store id for [Browser Tabs Sync](./browser-tabs-sync.md)
|
|
34
|
-
| `storeManager` | `StoreManager` | Yes | Shared global config with `getSessionKey`, `errorNormalizer`, and global store controls
|
|
35
|
-
| `fetchFn` | `(signal: AbortSignal) => Promise<State>` | Yes | Fetches the document data
|
|
36
|
-
| `lowPriorityThrottleMs` | `number` | No | Overrides the manager default. See [Fetch Scheduling](./fetch-scheduling.md)
|
|
37
|
-
| `baseCoalescingWindowMs` | `number` | No | Overrides the manager default. See [Fetch Scheduling](./fetch-scheduling.md)
|
|
38
|
-
| `
|
|
39
|
-
| `
|
|
40
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
| `
|
|
43
|
-
| `
|
|
44
|
-
| `
|
|
45
|
-
| `
|
|
46
|
-
| `onMutationError` | `(error, options: { dontShowToast?: boolean }) => void` | No | Global mutation error handler |
|
|
31
|
+
| Option | Type | Required | Description |
|
|
32
|
+
| ------------------------------ | -------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
33
|
+
| `id` | `string` | Yes | Stable logical store id used for debug labels, persistence namespaces, and [Browser Tabs Sync](./browser-tabs-sync.md) |
|
|
34
|
+
| `storeManager` | `StoreManager` | Yes | Shared global config with `getSessionKey`, `errorNormalizer`, and global store controls |
|
|
35
|
+
| `fetchFn` | `(signal: AbortSignal) => Promise<State>` | Yes | Fetches the document data |
|
|
36
|
+
| `lowPriorityThrottleMs` | `number` | No | Overrides the manager default. See [Fetch Scheduling](./fetch-scheduling.md) |
|
|
37
|
+
| `baseCoalescingWindowMs` | `number` | No | Overrides the manager default. See [Fetch Scheduling](./fetch-scheduling.md) |
|
|
38
|
+
| `dynamicRealtimeThrottleMs` | `(params: { lastFetchDuration: number; windowIsNotFocused: boolean }) => number` | No | See [Real-Time Updates](./real-time-updates.md) |
|
|
39
|
+
| `revalidateOnWindowFocus` | `boolean \| (() => boolean)` | No | Refetch on window focus |
|
|
40
|
+
| `transportReconnectCooldownMs` | `number` | No | Cooldown for repeated transport reconnect revalidation |
|
|
41
|
+
| `mediumPriorityDelayMs` | `number` | No | Delay for medium-priority fetches |
|
|
42
|
+
| `usesRealTimeUpdates` | `boolean` | No | Enables [Real-Time Updates](./real-time-updates.md) mode |
|
|
43
|
+
| `persistentStorage` | `DocumentPersistentStorageConfig<State>` | No | Configure cache persistence. See [Persistent Storage](./persistent-storage.md) |
|
|
44
|
+
| `onSchedulerEvent` | `(event) => void` | No | Scheduler event listener |
|
|
45
|
+
| `onMutationError` | `(error, options: { dontShowToast?: boolean }) => void` | No | Global mutation error handler |
|
|
47
46
|
|
|
48
47
|
## State Shape
|
|
49
48
|
|
|
@@ -78,17 +77,18 @@ type DocumentStoreState<State> = {
|
|
|
78
77
|
|
|
79
78
|
### Methods
|
|
80
79
|
|
|
81
|
-
| Method | Signature
|
|
82
|
-
| -------------------------- |
|
|
83
|
-
| `scheduleFetch` | `(fetchType, options?) => ScheduleFetchResults`
|
|
84
|
-
| `awaitFetch` | `(options?) => Promise<{ data, error }>`
|
|
85
|
-
| `
|
|
86
|
-
| `
|
|
87
|
-
| `
|
|
88
|
-
| `
|
|
89
|
-
| `
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
80
|
+
| Method | Signature | Description |
|
|
81
|
+
| -------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
82
|
+
| `scheduleFetch` | `(fetchType, options?) => ScheduleFetchResults` | Schedule a fetch. See [Fetch Scheduling](./fetch-scheduling.md) |
|
|
83
|
+
| `awaitFetch` | `(options?) => Promise<{ data, error }>` | Await a fetch with optional `timeoutMs` |
|
|
84
|
+
| `getDataFromStateOrFetch` | `(options?) => Promise<Result<State, StoreFetchError>>` | Return loaded state or fetch it if missing |
|
|
85
|
+
| `preloadPersistentStorage` | `() => Promise<void>` | Preload cached document data from async storage (OPFS) |
|
|
86
|
+
| `invalidateData` | `(priority?) => void` | Invalidate data. See [Invalidation](./invalidation.md) |
|
|
87
|
+
| `updateState` | `(produceFn) => boolean` | Immer-based state update. Returns `false` if no data exists |
|
|
88
|
+
| `reset` | `() => void` | Reset store to idle state |
|
|
89
|
+
| `startMutation` | `() => () => boolean` | Manually start a mutation lock. See [Mutations](./mutations.md) |
|
|
90
|
+
| `performMutation` | `(options) => Promise<Result<T>>` | Full mutation lifecycle. See [Mutations](./mutations.md) |
|
|
91
|
+
| `onTransportReconnect` | `() => void` | Store-level reconnect hook. Prefer `storeManager.onTransportReconnect()` for shared transports. See [Real-Time Updates](./real-time-updates.md) |
|
|
92
92
|
|
|
93
93
|
### Offline Methods
|
|
94
94
|
|
package/docs/list-query-store.md
CHANGED
|
@@ -47,7 +47,7 @@ The type parameters are:
|
|
|
47
47
|
|
|
48
48
|
| Option | Type | Description |
|
|
49
49
|
| -------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
50
|
-
| `id` | `string` | Stable logical store id
|
|
50
|
+
| `id` | `string` | Stable logical store id used for debug labels, persistence namespaces, and tab sync |
|
|
51
51
|
| `storeManager` | `StoreManager` | Shared global config with `getSessionKey`, `errorNormalizer`, and global store controls |
|
|
52
52
|
| `fetchListFn` | Size mode: `(payload, size, options) => Promise<FetchListFnReturn>` | Fetches a paginated list. See [Pagination modes](#pagination-modes) |
|
|
53
53
|
|
|
@@ -211,26 +211,28 @@ Behavior:
|
|
|
211
211
|
|
|
212
212
|
### Query Methods
|
|
213
213
|
|
|
214
|
-
| Method
|
|
215
|
-
|
|
|
216
|
-
| `scheduleListQueryFetch`
|
|
217
|
-
| `awaitListQueryFetch`
|
|
218
|
-
| `
|
|
219
|
-
| `
|
|
220
|
-
| `
|
|
221
|
-
| `
|
|
222
|
-
| `
|
|
223
|
-
| `
|
|
214
|
+
| Method | Signature | Description |
|
|
215
|
+
| -------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------ |
|
|
216
|
+
| `scheduleListQueryFetch` | `(fetchType, payload(s), size?, options?) => ScheduleFetchResults` | Schedule a list fetch |
|
|
217
|
+
| `awaitListQueryFetch` | `(params, options?) => Promise<{ items, error, hasMore }>` | Await a list fetch |
|
|
218
|
+
| `getQueryFromStateOrFetch` | `(params, options?) => Promise<Result<{ items, hasMore }, StoreFetchError>>` | Return loaded query data or fetch it if missing |
|
|
219
|
+
| `preloadQueryFromStorage` | `(payloads) => Promise<PersistentStoragePreloadResult<QueryPayload>[]>` | Preload cached list query payloads from async storage (OPFS) |
|
|
220
|
+
| `loadMore` | `(params, size?, options?) => ScheduleFetchResults` | Load more items (pagination) |
|
|
221
|
+
| `getQueryState` | `(params) => TSFDListQuery` | Get query state |
|
|
222
|
+
| `getQueryKey` | `(params) => string` | Get composite key for a query payload |
|
|
223
|
+
| `getQueriesState` | `(params) => { query, key }[]` | Get multiple query states |
|
|
224
|
+
| `getQueriesRelatedToItem` | `(itemPayload) => TSFDListQuery[]` | Find queries containing an item |
|
|
224
225
|
|
|
225
226
|
### Item Methods
|
|
226
227
|
|
|
227
|
-
| Method
|
|
228
|
-
|
|
|
229
|
-
| `scheduleItemFetch`
|
|
230
|
-
| `awaitItemFetch`
|
|
231
|
-
| `
|
|
232
|
-
| `
|
|
233
|
-
| `
|
|
228
|
+
| Method | Signature | Description |
|
|
229
|
+
| ------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------- |
|
|
230
|
+
| `scheduleItemFetch` | `(fetchType, payload(s), options?) => ScheduleFetchResults` | Schedule an item fetch |
|
|
231
|
+
| `awaitItemFetch` | `(itemPayload, options?) => Promise<{ data, error }>` | Await an item fetch |
|
|
232
|
+
| `getItemFromStateOrFetch` | `(itemPayload, options?) => Promise<Result<ItemState, StoreFetchError>>` | Return loaded item data or fetch it if missing |
|
|
233
|
+
| `preloadItemFromStorage` | `(params) => Promise<PersistentStoragePreloadResult<ItemPayload>[]>` | Preload cached list items from async storage (OPFS) |
|
|
234
|
+
| `getItemKey` | `(params) => string` | Get composite key for an item payload |
|
|
235
|
+
| `getItemState` | `(payload) => ItemState \| null` | Get item data |
|
|
234
236
|
|
|
235
237
|
### Offline Methods
|
|
236
238
|
|
|
@@ -271,10 +273,10 @@ kind so pending deletes do not need item hydration before they appear.
|
|
|
271
273
|
|
|
272
274
|
### Other
|
|
273
275
|
|
|
274
|
-
| Method | Description
|
|
275
|
-
| ------------------------ |
|
|
276
|
-
| `reset()` | Full reset of all state and schedulers
|
|
277
|
-
| `onTransportReconnect()` | See [Real-Time Updates](./real-time-updates.md) |
|
|
276
|
+
| Method | Description |
|
|
277
|
+
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
278
|
+
| `reset()` | Full reset of all state and schedulers |
|
|
279
|
+
| `onTransportReconnect()` | Store-level reconnect hook. Prefer `storeManager.onTransportReconnect()` for shared transports. See [Real-Time Updates](./real-time-updates.md) |
|
|
278
280
|
|
|
279
281
|
### Properties
|
|
280
282
|
|
|
@@ -42,12 +42,12 @@ Each store accepts `persistentStorage` in options:
|
|
|
42
42
|
|
|
43
43
|
Common options (applies to all store configs):
|
|
44
44
|
|
|
45
|
-
| Option | Required | Description
|
|
46
|
-
| --------------------------------- | -------- |
|
|
47
|
-
| `schema` | Yes | Schema used to validate restored data.
|
|
48
|
-
| `adapter` | Yes | `'local-sync'`, `opfsPersistentStorage`, `indexedDbPersistentStorage`, or a custom async adapter.
|
|
49
|
-
| `version` | No | Cache version; bump to invalidate old entries.
|
|
50
|
-
| `onPersistentStorageError(error)` | No | Store-specific callback for write/read failures (quota, decode, etc.). Overrides the manager fallback. |
|
|
45
|
+
| Option | Required | Description |
|
|
46
|
+
| --------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
47
|
+
| `schema` | Yes | Schema used to validate restored data. |
|
|
48
|
+
| `adapter` | Yes | `'local-sync'`, `opfsPersistentStorage`, `indexedDbPersistentStorage`, or a custom async adapter. |
|
|
49
|
+
| `version` | No | Cache version; bump to invalidate old entries. |
|
|
50
|
+
| `onPersistentStorageError(error)` | No | Store-specific callback for write/read failures (quota, decode, etc.). Overrides the manager fallback; use `null` to disable it. |
|
|
51
51
|
|
|
52
52
|
Store-specific options:
|
|
53
53
|
|
|
@@ -92,14 +92,16 @@ This prevents the UI from being overwhelmed by rapid updates while keeping data
|
|
|
92
92
|
|
|
93
93
|
## Transport Reconnection
|
|
94
94
|
|
|
95
|
-
When your WebSocket or SSE connection drops and reconnects, events may have been missed. Call `onTransportReconnect()`
|
|
95
|
+
When your WebSocket or SSE connection drops and reconnects, events may have been missed. Call the manager-level `onTransportReconnect()` once for the shared transport:
|
|
96
96
|
|
|
97
97
|
```ts
|
|
98
98
|
websocket.on('reconnect', () => {
|
|
99
|
-
|
|
99
|
+
storeManager.onTransportReconnect();
|
|
100
100
|
});
|
|
101
101
|
```
|
|
102
102
|
|
|
103
|
+
Store-level `store.onTransportReconnect()` remains available for stores backed by a dedicated transport.
|
|
104
|
+
|
|
103
105
|
Behavior:
|
|
104
106
|
|
|
105
107
|
- If the window is **focused**: all data is invalidated immediately with `realtimeUpdate` priority
|
|
@@ -151,6 +153,6 @@ ws.on('task:deleted', ({ taskId }) => {
|
|
|
151
153
|
});
|
|
152
154
|
|
|
153
155
|
ws.on('reconnect', () => {
|
|
154
|
-
|
|
156
|
+
storeManager.onTransportReconnect();
|
|
155
157
|
});
|
|
156
158
|
```
|
package/docs/store-manager.md
CHANGED
|
@@ -19,6 +19,10 @@ const storeManager = createStoreManager({
|
|
|
19
19
|
lowPriorityThrottleMs: 5,
|
|
20
20
|
baseCoalescingWindowMs: 10,
|
|
21
21
|
blockWindowClose: null,
|
|
22
|
+
revalidateOnWindowFocus: true,
|
|
23
|
+
onMutationError: (error) => {
|
|
24
|
+
console.error('TSDF mutation failed', error);
|
|
25
|
+
},
|
|
22
26
|
onPersistentStorageError: (error) => {
|
|
23
27
|
console.error('TSDF persistence failed', error);
|
|
24
28
|
},
|
|
@@ -34,6 +38,8 @@ Options:
|
|
|
34
38
|
| `lowPriorityThrottleMs` | No | Default minimum interval between low-priority fetches for attached stores. Defaults to `5`. |
|
|
35
39
|
| `baseCoalescingWindowMs` | No | Default window to group fetch requests for attached stores. Defaults to `10`. |
|
|
36
40
|
| `blockWindowClose` | No | Shared window-close blocker for mutations in attached stores. Defaults to `null`. |
|
|
41
|
+
| `revalidateOnWindowFocus` | No | Default focus revalidation policy for attached stores. Store options override it. |
|
|
42
|
+
| `onMutationError` | No | Global fallback for mutation failures when a store does not provide its own handler. |
|
|
37
43
|
| `onPersistentStorageError` | No | Global fallback for persistent storage failures when a store does not provide its own handler. |
|
|
38
44
|
| `offlineSession` | No | Shared offline config used by stores with `persistentStorage.offline`. |
|
|
39
45
|
|
|
@@ -41,6 +47,8 @@ The session key is used by browser-tab sync, persistent storage, and offline sta
|
|
|
41
47
|
|
|
42
48
|
Stores inherit the manager's `lowPriorityThrottleMs` and `baseCoalescingWindowMs` unless they provide their own store-level overrides. `blockWindowClose` is manager-only so window-close mutation protection is consistent across attached stores.
|
|
43
49
|
|
|
50
|
+
Store-level options can explicitly disable inherited defaults when the option supports disabling: use `revalidateOnWindowFocus: false`, `onMutationError: null`, or `persistentStorage.onPersistentStorageError: null`.
|
|
51
|
+
|
|
44
52
|
## Store Registry
|
|
45
53
|
|
|
46
54
|
The manager tracks attached stores:
|
|
@@ -48,10 +56,12 @@ The manager tracks attached stores:
|
|
|
48
56
|
```ts
|
|
49
57
|
storeManager.getAllStoreIds();
|
|
50
58
|
storeManager.resetAll(['document-current-user']);
|
|
59
|
+
storeManager.onTransportReconnect();
|
|
51
60
|
```
|
|
52
61
|
|
|
53
62
|
- `getAllStoreIds()` returns registered logical store ids.
|
|
54
63
|
- `resetAll(ignoreStores)` resets all registered stores except the ignored ids.
|
|
64
|
+
- `onTransportReconnect()` signals a shared real-time transport reconnect to all registered stores.
|
|
55
65
|
|
|
56
66
|
Call each store's `dispose()` when the store instance is permanently discarded so it can unregister listeners and manager state.
|
|
57
67
|
|