tsdf 17.0.0-alpha.1 → 17.0.0-alpha.2

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 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; /** Shared defaults used by attached stores unless a store-level override exists. */
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; /** Optional shared offline session config for every attached store. */
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>;
@@ -1644,9 +1653,9 @@ type CollectionStoreOptions<ItemState extends ValidStoreState, ItemPayload exten
1644
1653
  transportReconnectCooldownMs?: number;
1645
1654
  onInvalidate?: OnCollectionItemInvalidate<ItemState, ItemPayload>;
1646
1655
  onSchedulerEvent?: (event: RequestSchedulerEvents, data?: RequestSchedulerEventData) => void;
1647
- onMutationError?: (error: unknown, options: {
1656
+ onMutationError?: ((error: unknown, options: {
1648
1657
  silentErrors?: boolean;
1649
- }) => void;
1658
+ }) => void) | null;
1650
1659
  usesRealTimeUpdates?: boolean;
1651
1660
  /** Opt-in persistent storage configuration. When provided, cached items are loaded
1652
1661
  * from storage on first read and saved back on successful fetches.
@@ -1710,6 +1719,10 @@ type CollectionStore<ItemState extends ValidStoreState, ItemPayload extends Vali
1710
1719
  data: null;
1711
1720
  error: StoreFetchError;
1712
1721
  }>;
1722
+ getItemFromStateOrFetch: (params: ItemPayload, options?: {
1723
+ ignoreStaleState?: boolean;
1724
+ timeoutMs?: number;
1725
+ }) => Promise<Result<ItemState, StoreFetchError>>;
1713
1726
  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
1727
  useItem: <Selected = ItemState | null>(payload: ItemPayload | undefined | false | null, options?: UseItemOptions$1<ItemState, Selected>) => TSFDUseCollectionItemReturn<Selected, ItemPayload>;
1715
1728
  useListItemIsLoading: (payload: ItemPayload, args: {
@@ -1848,9 +1861,9 @@ type DocumentStoreOptions<State extends ValidStoreState, TOfflineOperations exte
1848
1861
  transportReconnectCooldownMs?: number;
1849
1862
  mediumPriorityDelayMs?: number;
1850
1863
  onSchedulerEvent?: (event: RequestSchedulerEvents, data?: RequestSchedulerEventData) => void;
1851
- onMutationError?: (error: unknown, options: {
1864
+ onMutationError?: ((error: unknown, options: {
1852
1865
  dontShowToast?: boolean;
1853
- }) => void;
1866
+ }) => void) | null;
1854
1867
  usesRealTimeUpdates?: boolean;
1855
1868
  /** Opt-in persistent storage configuration. When provided, cached data is loaded
1856
1869
  * from storage on first read and saved back on successful fetches.
@@ -1903,6 +1916,10 @@ type DocumentStore<State extends ValidStoreState, TOfflineOperations extends Doc
1903
1916
  data: null;
1904
1917
  error: StoreFetchError;
1905
1918
  }>;
1919
+ getDataFromStateOrFetch: (options?: {
1920
+ ignoreStaleState?: boolean;
1921
+ timeoutMs?: number;
1922
+ }) => Promise<Result<State, StoreFetchError>>;
1906
1923
  preloadPersistentStorage: () => Promise<void>;
1907
1924
  invalidateData: (priority?: FetchType) => void;
1908
1925
  updateState: DocumentUpdateState<State>;
@@ -2310,6 +2327,18 @@ type ListQueryAwaitListQueryFetchApi<ItemState extends ValidStoreState, QueryPay
2310
2327
  error: null;
2311
2328
  hasMore: boolean;
2312
2329
  }>;
2330
+ type ListQueryGetQueryFromStateOrFetchOptions<TPartialResources extends boolean> = {
2331
+ ignoreStaleState?: boolean;
2332
+ size?: number;
2333
+ timeoutMs?: number;
2334
+ } & ListQueryFetchFieldsOption<TPartialResources>;
2335
+ 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<{
2336
+ items: {
2337
+ data: ItemState;
2338
+ itemPayload: ItemPayload;
2339
+ }[];
2340
+ hasMore: boolean;
2341
+ }, StoreFetchError>>;
2313
2342
  type ListQueryAwaitItemFetchOptions<TPartialResources extends boolean> = {
2314
2343
  timeoutMs?: number;
2315
2344
  } & ListQueryFetchFieldsOption<TPartialResources>;
@@ -2320,6 +2349,11 @@ type ListQueryAwaitItemFetchApi<ItemState extends ValidStoreState, ItemPayload e
2320
2349
  data: ItemState;
2321
2350
  error: null;
2322
2351
  }>;
2352
+ type ListQueryGetItemFromStateOrFetchOptions<TPartialResources extends boolean> = {
2353
+ ignoreStaleState?: boolean;
2354
+ timeoutMs?: number;
2355
+ } & ListQueryFetchFieldsOption<TPartialResources>;
2356
+ 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
2357
  type ListQueryUseMultipleListQueriesApi<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean> = {
2324
2358
  <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
2359
  <S = ItemState>(queries: ListQueryUseMultipleListQueriesQuery<QueryPayload, undefined>[], options: UseMultipleListQueriesOptions<ItemState, ItemPayload, S>): readonly TSFDUseListQueryReturn<S, QueryPayload, undefined>[];
@@ -2407,6 +2441,7 @@ type ListQueryStore<ItemState extends ValidStoreState, QueryPayload extends Vali
2407
2441
  key: string;
2408
2442
  }[];
2409
2443
  awaitListQueryFetch: ListQueryAwaitListQueryFetchApi<ItemState, QueryPayload, ItemPayload, TPartialResources>;
2444
+ getQueryFromStateOrFetch: ListQueryGetQueryFromStateOrFetchApi<ItemState, QueryPayload, ItemPayload, TPartialResources>;
2410
2445
  preloadQueryFromStorage: (params: QueryPayload | QueryPayload[]) => Promise<PersistentStoragePreloadResult<QueryPayload>[]>;
2411
2446
  loadMore: ListQueryLoadMoreApi<QueryPayload, TPartialResources>;
2412
2447
  getItemKey: (params: ItemPayload) => string;
@@ -2427,6 +2462,7 @@ type ListQueryStore<ItemState extends ValidStoreState, QueryPayload extends Vali
2427
2462
  preloadItemFromStorage: (params: ItemPayload | ItemPayload[]) => Promise<PersistentStoragePreloadResult<ItemPayload>[]>;
2428
2463
  scheduleItemFetch: ListQueryScheduleItemFetchApi<ItemPayload, TPartialResources>;
2429
2464
  awaitItemFetch: ListQueryAwaitItemFetchApi<ItemState, ItemPayload, TPartialResources>;
2465
+ getItemFromStateOrFetch: ListQueryGetItemFromStateOrFetchApi<ItemState, ItemPayload, TPartialResources>;
2430
2466
  invalidateQueryAndItems: (args: {
2431
2467
  itemPayload: ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload> | false;
2432
2468
  queryPayload: QueryPayload | QueryPayload[] | ListQueryFilterQuery<QueryPayload> | false;
@@ -2549,9 +2585,9 @@ type ListQueryStoreOptionsBase<ItemState extends ValidStoreState, QueryPayload e
2549
2585
  onInvalidateQuery?: OnListQueryInvalidate<QueryPayload>;
2550
2586
  onInvalidateItem?: OnListQueryItemInvalidate<ItemState, ItemPayload>;
2551
2587
  onSchedulerEvent?: (event: RequestSchedulerEvents, data?: RequestSchedulerEventData) => void;
2552
- onMutationError?: (error: unknown, options: {
2588
+ onMutationError?: ((error: unknown, options: {
2553
2589
  silentErrors?: boolean;
2554
- }) => void; /** Opt-in hook-level query derivation from locally materialized items. */
2590
+ }) => void) | null; /** Opt-in hook-level query derivation from locally materialized items. */
2555
2591
  derivedQueries?: DerivedQueriesConfig<ItemState, QueryPayload, ItemPayload>;
2556
2592
  getQueryKey?: (params: QueryPayload) => ValidPayload | unknown[];
2557
2593
  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);
@@ -11457,6 +11471,8 @@ function createCollectionStore({ debugName, id, storeManager, fetchFn, batchFetc
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 ?? storeManager.onPersistentStorageError,
11510
+ onPersistentStorageError: resolveManagerFallback(persistentStorageConfig.onPersistentStorageError, storeManager.onPersistentStorageError),
11495
11511
  offline: persistentStorageConfig.offline ? {
11496
11512
  ...persistentStorageConfig.offline,
11497
11513
  session: resolvedOfflineSessionForPersistentStorage
@@ -11506,6 +11522,7 @@ 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
11527
  debugName,
11511
11528
  state: () => {
@@ -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
- (resolvedPersistentStorageConfig?.onPersistentStorageError ?? storeManager.onPersistentStorageError)?.(/* @__PURE__ */ new Error("Persistent storage preload is not available"));
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 && onMutationError) onMutationError(exception, { 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,
@@ -12593,6 +12619,8 @@ function createDocumentStore({ debugName, id, storeManager, fetchFn, lowPriority
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 ?? storeManager.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));
@@ -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
- (resolvedPersistentStorageConfig?.onPersistentStorageError ?? storeManager.onPersistentStorageError)?.(/* @__PURE__ */ new Error("Async preload is not available"));
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 (onMutationError) onMutationError(exception, { dontShowToast: dontShowErrorToast });
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,
@@ -17587,6 +17693,8 @@ function createListQueryStore(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 ?? storeManager.onPersistentStorageError,
17740
+ onPersistentStorageError: resolveManagerFallback(persistentStorageConfig.onPersistentStorageError, storeManager.onPersistentStorageError),
17633
17741
  offline: persistentStorageConfig.offline ? {
17634
17742
  ...persistentStorageConfig.offline,
17635
17743
  session: resolvedOfflineSessionForPersistentStorage
@@ -17642,6 +17750,7 @@ 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;
@@ -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
- (resolvedPersistentStorageConfig?.onPersistentStorageError ?? storeManager.onPersistentStorageError)?.(/* @__PURE__ */ new Error("Persistent storage preload is not available"));
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
- (resolvedPersistentStorageConfig?.onPersistentStorageError ?? storeManager.onPersistentStorageError)?.(/* @__PURE__ */ new Error("Persistent storage preload is not available"));
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,18 @@ function UserProfile() {
77
81
 
78
82
  All three store types share these creation options:
79
83
 
80
- | Option | Type | Required | Description |
81
- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------ |
82
- | `debugName` | `string` | No | Debug name for the store |
83
- | `storeManager` | `StoreManager` | Yes | Shared global config with session scoping, store defaults, and global store controls |
84
- | `lowPriorityThrottleMs` | `number` | No | Overrides the manager default minimum interval between low-priority fetches |
85
- | `baseCoalescingWindowMs` | `number` | No | Overrides the manager default window to group multiple fetch requests into a batch |
86
- | `mediumPriorityDelayMs` | `number` | No | Delay before medium-priority fetches execute |
87
- | `dynamicRealtimeThrottleMs` | `(params) => number` | No | Dynamic throttle for [real-time updates](./real-time-updates.md) |
88
- | `revalidateOnWindowFocus` | `boolean \| (() => boolean)` | No | Refetch data when window regains focus |
89
- | `transportReconnectCooldownMs` | `number` | No | Cooldown for repeated transport reconnect revalidation |
90
- | `persistentStorage` | `DocumentPersistentStorageConfig<...> \| CollectionPersistentStorageConfig<...> \| ListQueryPersistentStorageConfig<...>` | No | Configure cache persistence and optional session-based offline behavior |
91
- | `usesRealTimeUpdates` | `boolean` | No | Enables [real-time update mode](./real-time-updates.md) |
92
- | `onSchedulerEvent` | `(event) => void` | No | Callback for [scheduler events](./fetch-scheduling.md) |
93
- | `onMutationError` | `(error, options) => void` | No | Global handler for [mutation](./mutations.md) errors |
94
- | `id` | `string` | Yes | Stable logical store id for [Browser Tabs Sync](./browser-tabs-sync.md) |
84
+ | Option | Type | Required | Description |
85
+ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
86
+ | `debugName` | `string` | No | Debug name for the store |
87
+ | `storeManager` | `StoreManager` | Yes | Shared global config with session scoping, store defaults, and global store controls |
88
+ | `lowPriorityThrottleMs` | `number` | No | Overrides the manager default minimum interval between low-priority fetches |
89
+ | `baseCoalescingWindowMs` | `number` | No | Overrides the manager default window to group multiple fetch requests into a batch |
90
+ | `mediumPriorityDelayMs` | `number` | No | Delay before medium-priority fetches execute |
91
+ | `dynamicRealtimeThrottleMs` | `(params) => number` | No | Dynamic throttle for [real-time updates](./real-time-updates.md) |
92
+ | `revalidateOnWindowFocus` | `boolean \| (() => boolean)` | No | Overrides the manager default for refetching data when window regains focus. Use `false` to disable |
93
+ | `transportReconnectCooldownMs` | `number` | No | Cooldown for repeated transport reconnect revalidation |
94
+ | `persistentStorage` | `DocumentPersistentStorageConfig<...> \| CollectionPersistentStorageConfig<...> \| ListQueryPersistentStorageConfig<...>` | No | Configure cache persistence and optional session-based offline behavior |
95
+ | `usesRealTimeUpdates` | `boolean` | No | Enables [real-time update mode](./real-time-updates.md) |
96
+ | `onSchedulerEvent` | `(event) => void` | No | Callback for [scheduler events](./fetch-scheduling.md) |
97
+ | `onMutationError` | `(error, options) => void \| null` | No | Store-specific handler for [mutation](./mutations.md) errors. Overrides the manager fallback; use `null` to disable it |
98
+ | `id` | `string` | Yes | Stable logical store id for [Browser Tabs Sync](./browser-tabs-sync.md) |
@@ -88,22 +88,23 @@ The overall store state is `Record<string, TSFDCollectionItem | null>` where key
88
88
 
89
89
  ### Methods
90
90
 
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
- | `preloadItemFromStorage` | `(params) => Promise<PersistentStoragePreloadResult<ItemPayload>[]>` | Preload cached item payloads from async storage (OPFS) |
96
- | `getItemKey` | `(params) => string` | Get the composite key for a payload |
97
- | `getItemState` | `(params) => CollectionItem` | Get item state (single, array, or filter function) |
98
- | `invalidateItem` | `(payload(s), priority?) => void` | See [Invalidation](./invalidation.md) |
99
- | `updateItemState` | `(params, produceFn, options?) => boolean` | Immer-based state update |
100
- | `addItemToState` | `(payload, data) => void` | Add a new item to the store |
101
- | `deleteItemState` | `(params) => void` | Delete item(s) and cleanup scheduler resources |
102
- | `startMutation` | `(params) => () => void` | Start mutation lock. See [Mutations](./mutations.md) |
103
- | `performMutation` | `(payload, options) => Promise<Result<T>>` | Full mutation lifecycle. See [Mutations](./mutations.md) |
104
- | `reset` | `() => void` | Reset store and all schedulers |
105
- | `dispose` | `() => void` | Release listeners and store-manager registration |
106
- | `onTransportReconnect` | `() => void` | See [Real-Time Updates](./real-time-updates.md) |
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
 
@@ -78,17 +78,18 @@ type DocumentStoreState<State> = {
78
78
 
79
79
  ### Methods
80
80
 
81
- | Method | Signature | Description |
82
- | -------------------------- | ----------------------------------------------- | --------------------------------------------------------------- |
83
- | `scheduleFetch` | `(fetchType, options?) => ScheduleFetchResults` | Schedule a fetch. See [Fetch Scheduling](./fetch-scheduling.md) |
84
- | `awaitFetch` | `(options?) => Promise<{ data, error }>` | Await a fetch with optional `timeoutMs` |
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` | See [Real-Time Updates](./real-time-updates.md) |
81
+ | Method | Signature | Description |
82
+ | -------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
83
+ | `scheduleFetch` | `(fetchType, options?) => ScheduleFetchResults` | Schedule a fetch. See [Fetch Scheduling](./fetch-scheduling.md) |
84
+ | `awaitFetch` | `(options?) => Promise<{ data, error }>` | Await a fetch with optional `timeoutMs` |
85
+ | `getDataFromStateOrFetch` | `(options?) => Promise<Result<State, StoreFetchError>>` | Return loaded state or fetch it if missing |
86
+ | `preloadPersistentStorage` | `() => Promise<void>` | Preload cached document data from async storage (OPFS) |
87
+ | `invalidateData` | `(priority?) => void` | Invalidate data. See [Invalidation](./invalidation.md) |
88
+ | `updateState` | `(produceFn) => boolean` | Immer-based state update. Returns `false` if no data exists |
89
+ | `reset` | `() => void` | Reset store to idle state |
90
+ | `startMutation` | `() => () => boolean` | Manually start a mutation lock. See [Mutations](./mutations.md) |
91
+ | `performMutation` | `(options) => Promise<Result<T>>` | Full mutation lifecycle. See [Mutations](./mutations.md) |
92
+ | `onTransportReconnect` | `() => void` | Store-level reconnect hook. Prefer `storeManager.onTransportReconnect()` for shared transports. See [Real-Time Updates](./real-time-updates.md) |
92
93
 
93
94
  ### Offline Methods
94
95
 
@@ -211,26 +211,28 @@ Behavior:
211
211
 
212
212
  ### Query Methods
213
213
 
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
- | `preloadQueryFromStorage` | `(payloads) => Promise<PersistentStoragePreloadResult<QueryPayload>[]>` | Preload cached list query payloads from async storage (OPFS) |
219
- | `loadMore` | `(params, size?, options?) => ScheduleFetchResults` | Load more items (pagination) |
220
- | `getQueryState` | `(params) => TSFDListQuery` | Get query state |
221
- | `getQueryKey` | `(params) => string` | Get composite key for a query payload |
222
- | `getQueriesState` | `(params) => { query, key }[]` | Get multiple query states |
223
- | `getQueriesRelatedToItem` | `(itemPayload) => TSFDListQuery[]` | Find queries containing an item |
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 | Signature | Description |
228
- | ------------------------ | -------------------------------------------------------------------- | --------------------------------------------------- |
229
- | `scheduleItemFetch` | `(fetchType, payload(s), options?) => ScheduleFetchResults` | Schedule an item fetch |
230
- | `awaitItemFetch` | `(itemPayload, options?) => Promise<{ data, error }>` | Await an item fetch |
231
- | `preloadItemFromStorage` | `(params) => Promise<PersistentStoragePreloadResult<ItemPayload>[]>` | Preload cached list items from async storage (OPFS) |
232
- | `getItemKey` | `(params) => string` | Get composite key for an item payload |
233
- | `getItemState` | `(payload) => ItemState \| null` | Get item data |
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()` to revalidate:
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
- store.onTransportReconnect();
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
- taskStore.onTransportReconnect();
156
+ storeManager.onTransportReconnect();
155
157
  });
156
158
  ```
@@ -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
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tsdf",
3
- "version": "17.0.0-alpha.1",
3
+ "version": "17.0.0-alpha.2",
4
4
  "description": "A data fetching solution based on t-state",
5
5
  "license": "MIT",
6
6
  "author": "Lucas Santos",