tsdf 17.0.1 → 17.0.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.
@@ -1,2 +1,2 @@
1
- import { t as createAsyncStorageAdapter } from "./asyncStorageAdapter-CMohMeKm.js";
1
+ import { t as createAsyncStorageAdapter } from "./asyncStorageAdapter-DuAUANgu.js";
2
2
  export { createAsyncStorageAdapter };
@@ -1,4 +1,4 @@
1
- import { r as AsyncStorageDriver, t as AsyncStorageAdapter } from "./types-D0ttVGmj.js";
1
+ import { r as AsyncStorageDriver, t as AsyncStorageAdapter } from "./types-aWgyZHLj.js";
2
2
 
3
3
  //#region src/persistentStorage/asyncStorageAdapter.d.ts
4
4
  declare function createAsyncStorageAdapter(driver: AsyncStorageDriver): AsyncStorageAdapter;
@@ -1,4 +1,4 @@
1
- import { t as AsyncStorageAdapter } from "./types-D0ttVGmj.js";
1
+ import { t as AsyncStorageAdapter } from "./types-aWgyZHLj.js";
2
2
  //#region src/persistentStorage/indexedDbAsyncStorageAdapter.d.ts
3
3
  /** Options for creating the IndexedDB persistent storage adapter. */
4
4
  type IndexedDbPersistentStorageOptions$1 = {
package/dist/main.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { $ as OfflineResolutionRecord, $t as StoreError, A as DefineListQueryOfflineOperations, At as DerivedQuerySource, B as OfflineEntityMutationKind, Bt as OptimisticListUpdate, C as PersistentStorageSchema, Ct as OfflineUploadAdapter, D as CollectionOfflineOperationDefinition, Dt as OfflineUploadTransportContext, E as CollectionOfflineEntityRef, Et as OfflineUploadState, F as ListQueryOfflineEntityRef, Ft as ListQueryUseMultipleItemsQuery, G as OfflineMutationQueueingPolicy, Gt as TSFDListQuery, H as OfflineMutationInput, Ht as QueryFetchPayload, I as ListQueryOfflineOperationDefinition, It as ListQueryUseMultipleListQueriesQuery, J as OfflineReplayRetryConfig, Jt as TSFDUseListQueryReturn, K as OfflineOperationKind, Kt as TSFDListQueryState, L as OfflineAccumulationConfig, Lt as OffsetPaginationConfig, M as DocumentOfflineOperationDefinition, Mt as FetchListFnReturnItem, N as GlobalOfflineEntity, Nt as FieldsInput, O as DefineCollectionOfflineOperations, Ot as DerivedQueriesConfig, P as GlobalOfflineStatus, Pt as FieldsOption, Q as OfflineResolutionConflictParseErrorCode, Qt as PayloadDebounce, R as OfflineAccumulationMergeContext, Rt as OnListQueryInvalidate, S as PersistentStoragePreloadResult, St as OfflineUpload, T as AnyOfflineOperationDefinition, Tt as OfflineUploadSource, U as OfflineMutationQueueingCause, Ut as QueryStatus, V as OfflineMutationDescriptor, Vt as PartialResourcesConfig, W as OfflineMutationQueueingConfig, Wt as TSDFItemQuery, X as OfflineResolutionActionForOperation, Xt as MaybeTSDFResult, Y as OfflineResolutionAction, Yt as TSFDUsePendingOfflineItemsReturn, Z as OfflineResolutionConflictParseError, Zt as MutationSkipped, _ as ListQueryOfflineOperationsConfig, _n as TSDFDebugLogger, _t as defaultOfflineRuntimeConfig, a as AsyncStorageMetadataOrder, an as ValidPayload, at as OfflineSession, b as PersistentStorageDataSchema, bt as OfflineSessionUploadsConfig, c as AsyncStorageNamespaceCommitUpsert, cn as mutationSkipped, ct as OfflineSyncState, d as AsyncStorageNamespaceKind, dn as RequestSchedulerEvents, dt as OfflineTempEntityConfig, en as StoreFetchError, et as OfflineResolutionRecordForOperation, f as AsyncStorageNamespaceScope, fn as ScheduleFetchOptions, ft as OfflineTempEntityPendingEntry, g as DocumentPersistentStorageConfig, gn as TSDFDebugLogLevel, gt as ParsedOfflineResolutionConflictResultForStore, h as ConvertedPersistentStorageDataSchema, hn as TSDFDebugLogEntry, ht as ParsedOfflineResolutionConflictResultForOperation, i as AsyncStorageDriverSetEntry, in as UnwrapTSDFResult, it as OfflineRuntimeConfigUpdate, j as DefineOfflineOperation, jt as FetchListFnReturn, k as DefineDocumentOfflineOperations, kt as DerivedQueryContext, l as AsyncStorageNamespaceGetResult, ln as FetchType, lt as OfflineTempEntitiesConfig, m as CollectionPersistentStorageConfig, mn as TSDFDebugLogArea, mt as OperationResult, n as AsyncStorageDiscoveredScope, nn as StoreMutationErrorOptions, nt as OfflineRetryExhaustedResolutionAction, o as AsyncStorageNamespaceCommitArgs, on as ValidStoreState, ot as OfflineSessionConfig, p as AsyncStorageReadOptions, pn as ScheduleFetchResults, pt as OperationConflict, q as OfflineQueueEntry, qt as TSFDUseListItemReturn, r as AsyncStorageDriver, rn as TSDFStatus, rt as OfflineRuntimeConfig, s as AsyncStorageNamespaceCommitTouch, sn as fetchTypePriority, st as OfflineSupersedeConfig, t as AsyncStorageAdapter, tn as StoreMutationError, tt as OfflineResolutionRecordForStore, u as AsyncStorageNamespaceHandle, un as RequestSchedulerEventData, ut as OfflineTempEntitiesReconciliation, v as ListQueryPersistentStorageConfig, vn as TSDFFocusDebugOperation, vt as OfflineMutationUploadsInput, w as StorageAdapter, wt as OfflineUploadProgress, x as PersistentStorageErrorHandler, xt as OfflineStoredUploadRecord, y as PersistentStorageBaseConfig, yn as TSDFLoggerOptions, yt as OfflineOperationUploadsContext, z as OfflineConflictResolutionAction, zt as OnListQueryItemInvalidate } from "./types-D0ttVGmj.js";
1
+ import { $ as OfflineResolutionRecord, $t as StoreError, A as DefineListQueryOfflineOperations, At as DerivedQuerySource, B as OfflineEntityMutationKind, Bt as OptimisticListUpdate, C as PersistentStorageSchema, Ct as OfflineUploadAdapter, D as CollectionOfflineOperationDefinition, Dt as OfflineUploadTransportContext, E as CollectionOfflineEntityRef, Et as OfflineUploadState, F as ListQueryOfflineEntityRef, Ft as ListQueryUseMultipleItemsQuery, G as OfflineMutationQueueingPolicy, Gt as TSFDListQuery, H as OfflineMutationInput, Ht as QueryFetchPayload, I as ListQueryOfflineOperationDefinition, It as ListQueryUseMultipleListQueriesQuery, J as OfflineReplayRetryConfig, Jt as TSFDUseListQueryReturn, K as OfflineOperationKind, Kt as TSFDListQueryState, L as OfflineAccumulationConfig, Lt as OffsetPaginationConfig, M as DocumentOfflineOperationDefinition, Mt as FetchListFnReturnItem, N as GlobalOfflineEntity, Nt as FieldsInput, O as DefineCollectionOfflineOperations, Ot as DerivedQueriesConfig, P as GlobalOfflineStatus, Pt as FieldsOption, Q as OfflineResolutionConflictParseErrorCode, Qt as PayloadDebounce, R as OfflineAccumulationMergeContext, Rt as OnListQueryInvalidate, S as PersistentStoragePreloadResult, St as OfflineUpload, T as AnyOfflineOperationDefinition, Tt as OfflineUploadSource, U as OfflineMutationQueueingCause, Ut as QueryStatus, V as OfflineMutationDescriptor, Vt as PartialResourcesConfig, W as OfflineMutationQueueingConfig, Wt as TSDFItemQuery, X as OfflineResolutionActionForOperation, Xt as MaybeTSDFResult, Y as OfflineResolutionAction, Yt as TSFDUsePendingOfflineItemsReturn, Z as OfflineResolutionConflictParseError, Zt as MutationSkipped, _ as ListQueryOfflineOperationsConfig, _n as TSDFDebugLogger, _t as defaultOfflineRuntimeConfig, a as AsyncStorageMetadataOrder, an as ValidPayload, at as OfflineSession, b as PersistentStorageDataSchema, bt as OfflineSessionUploadsConfig, c as AsyncStorageNamespaceCommitUpsert, cn as mutationSkipped, ct as OfflineSyncState, d as AsyncStorageNamespaceKind, dn as RequestSchedulerEvents, dt as OfflineTempEntityConfig, en as StoreFetchError, et as OfflineResolutionRecordForOperation, f as AsyncStorageNamespaceScope, fn as ScheduleFetchOptions, ft as OfflineTempEntityPendingEntry, g as DocumentPersistentStorageConfig, gn as TSDFDebugLogLevel, gt as ParsedOfflineResolutionConflictResultForStore, h as ConvertedPersistentStorageDataSchema, hn as TSDFDebugLogEntry, ht as ParsedOfflineResolutionConflictResultForOperation, i as AsyncStorageDriverSetEntry, in as UnwrapTSDFResult, it as OfflineRuntimeConfigUpdate, j as DefineOfflineOperation, jt as FetchListFnReturn, k as DefineDocumentOfflineOperations, kt as DerivedQueryContext, l as AsyncStorageNamespaceGetResult, ln as FetchType, lt as OfflineTempEntitiesConfig, m as CollectionPersistentStorageConfig, mn as TSDFDebugLogArea, mt as OperationResult, n as AsyncStorageDiscoveredScope, nn as StoreMutationErrorOptions, nt as OfflineRetryExhaustedResolutionAction, o as AsyncStorageNamespaceCommitArgs, on as ValidStoreState, ot as OfflineSessionConfig, p as AsyncStorageReadOptions, pn as ScheduleFetchResults, pt as OperationConflict, q as OfflineQueueEntry, qt as TSFDUseListItemReturn, r as AsyncStorageDriver, rn as TSDFStatus, rt as OfflineRuntimeConfig, s as AsyncStorageNamespaceCommitTouch, sn as fetchTypePriority, st as OfflineSupersedeConfig, t as AsyncStorageAdapter, tn as StoreMutationError, tt as OfflineResolutionRecordForStore, u as AsyncStorageNamespaceHandle, un as RequestSchedulerEventData, ut as OfflineTempEntitiesReconciliation, v as ListQueryPersistentStorageConfig, vn as TSDFFocusDebugOperation, vt as OfflineMutationUploadsInput, w as StorageAdapter, wt as OfflineUploadProgress, x as PersistentStorageErrorHandler, xt as OfflineStoredUploadRecord, y as PersistentStorageBaseConfig, yn as TSDFLoggerOptions, yt as OfflineOperationUploadsContext, z as OfflineConflictResolutionAction, zt as OnListQueryItemInvalidate } from "./types-aWgyZHLj.js";
2
2
  import { __LEGIT_ANY__ } from "@ls-stack/utils/saferTyping";
3
3
  import { Emitter } from "evtmitter";
4
4
  import { Context } from "react";
@@ -141,11 +141,12 @@ type UseMultipleItemsOptions$1<ItemState extends ValidStoreState, Selected> = {
141
141
  //#region src/collectionStore/useItem.d.ts
142
142
  type UseItemOptions$1<ItemState extends ValidStoreState, Selected> = UseMultipleItemsOptions$1<ItemState, Selected> & {
143
143
  /**
144
- * Forces a high-priority fetch on mount and keeps the hook in `loading`
145
- * until the current payload finishes loading. Cannot be combined with
146
- * `debouncePayload`.
144
+ * Unconditionally schedules a high-priority fetch on mount and reports
145
+ * `loading` until that refresh succeeds or fails, even when cached data
146
+ * exists. Use sparingly because each mount can cause an extra request.
147
+ * Cannot be combined with `debouncePayload`.
147
148
  */
148
- ensureIsLoaded?: boolean;
149
+ requireFreshData?: boolean;
149
150
  };
150
151
  //#endregion
151
152
  //#region src/collectionStore/collectionStore.d.ts
@@ -372,21 +373,21 @@ type CollectionStore<ItemState extends ValidStoreState, ItemPayload extends Vali
372
373
  useListItemIsLoading: (payload: ItemPayload, args: {
373
374
  /** Unique identifier of the sub-item within the collection item. */itemId: string; /** Extracts the sub-item from the collection item data. */
374
375
  selector: (data: ItemState | null) => unknown; /** Called if the sub-item is still missing and no refetch is in progress. */
375
- loadItemFallback?: () => void; /** Forces a high-priority fetch and keeps the hook loading until data is loaded. */
376
- ensureIsLoaded?: boolean;
376
+ loadItemFallback?: () => void; /** Requires a mount refresh before reporting ready. May cause an extra request. */
377
+ requireFreshData?: boolean;
377
378
  }) => boolean; /** React hook that tracks whether a nested list item has been deleted. */
378
379
  useListItemIsDeleted: (payload: ItemPayload, args: {
379
380
  /** Unique identifier of the sub-item within the collection item. */itemId: string; /** Extracts the sub-item from the collection item data. */
380
381
  selector: (data: ItemState | null) => unknown; /** Called once when deletion is detected. */
381
- onDelete?: () => void; /** Forces a high-priority fetch and keeps the hook loading until data is loaded. */
382
- ensureIsLoaded?: boolean;
382
+ onDelete?: () => void; /** Requires a mount refresh before reporting ready. May cause an extra request. */
383
+ requireFreshData?: boolean;
383
384
  }) => boolean; /** React hook for selecting one nested list item plus loading/deleted flags. */
384
385
  useListItem: <Selected>(payload: ItemPayload, args: {
385
386
  /** Unique identifier of the sub-item within the collection item. */itemId: string; /** Extracts and maps the sub-item from the collection item data. */
386
387
  selector: (data: ItemState | null) => Selected; /** Called if the sub-item is still missing and no refetch is in progress. */
387
388
  loadItemFallback?: () => void; /** Called once when deletion is detected. */
388
- onDelete?: () => void; /** Forces a high-priority fetch and keeps the hook loading until data is loaded. */
389
- ensureIsLoaded?: boolean;
389
+ onDelete?: () => void; /** Requires a mount refresh before reporting ready. May cause an extra request. */
390
+ requireFreshData?: boolean;
390
391
  }) => {
391
392
  isLoading: boolean;
392
393
  isDeleted: boolean;
@@ -598,30 +599,31 @@ type DocumentStore<State extends ValidStoreState, TOfflineOperations extends Doc
598
599
  disableRefetchOnMount?: boolean; /** Returns `idle` instead of `loading` while the document has not been fetched. */
599
600
  returnIdleStatus?: boolean;
600
601
  /**
601
- * Forces a high-priority fetch on mount and keeps the hook in `loading`
602
- * until the document finishes loading.
602
+ * Unconditionally schedules a high-priority fetch on mount and reports
603
+ * `loading` until that refresh succeeds or fails, even when cached data
604
+ * exists. Use sparingly because each mount can cause an extra request.
603
605
  */
604
- ensureIsLoaded?: boolean; /** Returns `refetching` instead of keeping `loaded` status during refetches. */
606
+ requireFreshData?: boolean; /** Returns `refetching` instead of keeping `loaded` status during refetches. */
605
607
  returnRefetchingStatus?: boolean;
606
608
  }) => TSDFUseDocumentReturn<Selected>; /** React hook that tracks whether a nested list item is still loading. */
607
609
  useListItemIsLoading: (args: {
608
610
  /** Unique identifier of the item within the document. */itemId: string; /** Extracts the item from the document data. */
609
611
  selector: (data: State | null) => unknown; /** Called if the item is still missing and no refetch is in progress. */
610
- loadItemFallback?: () => void; /** Forces a high-priority fetch and keeps the hook loading until data is loaded. */
611
- ensureIsLoaded?: boolean;
612
+ loadItemFallback?: () => void; /** Requires a mount refresh before reporting ready. May cause an extra request. */
613
+ requireFreshData?: boolean;
612
614
  }) => boolean; /** React hook that tracks whether a nested list item has been deleted. */
613
615
  useListItemIsDeleted: (args: {
614
616
  /** Unique identifier of the item within the document. */itemId: string; /** Extracts the item from the document data. */
615
617
  selector: (data: State | null) => unknown; /** Called once when deletion is detected. */
616
- onDelete?: () => void; /** Forces a high-priority fetch and keeps the hook loading until data is loaded. */
617
- ensureIsLoaded?: boolean;
618
+ onDelete?: () => void; /** Requires a mount refresh before reporting ready. May cause an extra request. */
619
+ requireFreshData?: boolean;
618
620
  }) => boolean; /** React hook for selecting one nested list item plus loading/deleted flags. */
619
621
  useListItem: <Selected>(args: {
620
622
  /** Unique identifier of the item within the document. */itemId: string; /** Extracts and maps the item from the document data. */
621
623
  selector: (data: State | null) => Selected; /** Called if the item is still missing and no refetch is in progress. */
622
624
  loadItemFallback?: () => void; /** Called once when deletion is detected. */
623
- onDelete?: () => void; /** Forces a high-priority fetch and keeps the hook loading until data is loaded. */
624
- ensureIsLoaded?: boolean;
625
+ onDelete?: () => void; /** Requires a mount refresh before reporting ready. May cause an extra request. */
626
+ requireFreshData?: boolean;
625
627
  }) => {
626
628
  isLoading: boolean;
627
629
  isDeleted: boolean;
@@ -665,11 +667,12 @@ type UseMultipleItemsOptions<ItemState extends ValidStoreState, Selected> = {
665
667
  //#region src/listQueryStore/useItem.d.ts
666
668
  type UseItemOptions<ItemState extends ValidStoreState, Selected> = UseMultipleItemsOptions<ItemState, Selected> & {
667
669
  /**
668
- * Forces a high-priority fetch on mount and keeps the hook in `loading`
669
- * until the current payload finishes loading. Cannot be combined with
670
- * `debouncePayload`.
670
+ * Unconditionally schedules a high-priority fetch on mount and reports
671
+ * `loading` until that refresh succeeds or fails, even when cached data
672
+ * exists. Use sparingly because each mount can cause an extra request.
673
+ * Cannot be combined with `debouncePayload`.
671
674
  */
672
- ensureIsLoaded?: boolean;
675
+ requireFreshData?: boolean;
673
676
  /**
674
677
  * Partial-resource fields to request for this item.
675
678
  *
@@ -714,11 +717,12 @@ type UseMultipleListQueriesOptions<ItemState extends ValidStoreState, ItemPayloa
714
717
  //#region src/listQueryStore/useListQuery.d.ts
715
718
  type UseListQueryOptions<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, SelectedItem> = UseMultipleListQueriesOptions<ItemState, ItemPayload, SelectedItem> & {
716
719
  /**
717
- * Forces a high-priority fetch on mount and keeps the hook in `loading`
718
- * until the current payload finishes loading. Cannot be combined with
719
- * `debouncePayload`.
720
+ * Unconditionally schedules a high-priority fetch on mount and reports
721
+ * `loading` until that refresh succeeds or fails, even when cached data
722
+ * exists. Use sparingly because each mount can cause an extra request.
723
+ * Cannot be combined with `debouncePayload`.
720
724
  */
721
- ensureIsLoaded?: boolean;
725
+ requireFreshData?: boolean;
722
726
  /**
723
727
  * Partial-resource fields to request for each item in this query.
724
728
  *
package/dist/main.js CHANGED
@@ -8772,29 +8772,29 @@ function getPayloadDebounceOptions(debouncePayload) {
8772
8772
  trailing: true
8773
8773
  };
8774
8774
  }
8775
- function assertNoEnsureIsLoadedWithDebouncePayload(hookName, ensureIsLoaded, debouncePayload) {
8776
- if (!import.meta.env.PROD && ensureIsLoaded && shouldDebouncePayload(debouncePayload)) throw new Error(`${hookName} does not support using ensureIsLoaded together with debouncePayload.`);
8775
+ function assertNoRequireFreshDataWithDebouncePayload(hookName, requireFreshData, debouncePayload) {
8776
+ if (!import.meta.env.PROD && requireFreshData && shouldDebouncePayload(debouncePayload)) throw new Error(`${hookName} does not support using requireFreshData together with debouncePayload.`);
8777
8777
  }
8778
8778
  //#endregion
8779
- //#region src/utils/useEnsureIsLoaded.ts
8780
- function useEnsureIsLoaded(ensureIsLoaded, enabled, forceFetch) {
8781
- const isLoadedEvtEmitter = useConst(() => evtmitter());
8782
- const [isForceLoading, setIsForceLoading] = useState(true);
8783
- useOnChange(ensureIsLoaded && isForceLoading && enabled, ({ current }) => {
8779
+ //#region src/utils/useRequireFreshData.ts
8780
+ function useRequireFreshData(requireFreshData, enabled, forceFetch) {
8781
+ const refreshSettledEvtEmitter = useConst(() => evtmitter());
8782
+ const [isWaitingForRefresh, setIsWaitingForRefresh] = useState(true);
8783
+ useOnChange(requireFreshData && isWaitingForRefresh && enabled, ({ current }) => {
8784
8784
  if (current) forceFetch();
8785
8785
  }, { callOnMount: true });
8786
- useOnEvtmitterEvent(isLoadedEvtEmitter, "isLoaded", ({ payload: isLoaded }) => {
8787
- if (ensureIsLoaded && enabled && isLoaded) setIsForceLoading(false);
8786
+ useOnEvtmitterEvent(refreshSettledEvtEmitter, "refreshSettled", ({ payload: refreshSettled }) => {
8787
+ if (requireFreshData && enabled && refreshSettled) setIsWaitingForRefresh(false);
8788
8788
  });
8789
8789
  function useModifyResult(result) {
8790
- return useGetModifyResult(result, ensureIsLoaded, enabled, isForceLoading);
8790
+ return useGetModifyResult(result, requireFreshData, enabled, isWaitingForRefresh);
8791
8791
  }
8792
- return [useModifyResult, () => isLoadedEvtEmitter.emit("isLoaded", true)];
8792
+ return [useModifyResult, () => refreshSettledEvtEmitter.emit("refreshSettled", true)];
8793
8793
  }
8794
- function useGetModifyResult(result, ensureIsLoaded, enabled, isForceLoading) {
8794
+ function useGetModifyResult(result, requireFreshData, enabled, isWaitingForRefresh) {
8795
8795
  return useMemo(() => {
8796
- if (ensureIsLoaded) {
8797
- const newStatus = enabled && isForceLoading ? "loading" : result.status;
8796
+ if (requireFreshData) {
8797
+ const newStatus = enabled && isWaitingForRefresh ? "loading" : result.status;
8798
8798
  return {
8799
8799
  ...result,
8800
8800
  isLoading: newStatus === "loading",
@@ -8803,18 +8803,18 @@ function useGetModifyResult(result, ensureIsLoaded, enabled, isForceLoading) {
8803
8803
  }
8804
8804
  return result;
8805
8805
  }, [
8806
- ensureIsLoaded,
8807
- isForceLoading,
8806
+ requireFreshData,
8807
+ isWaitingForRefresh,
8808
8808
  result,
8809
8809
  enabled
8810
8810
  ]);
8811
8811
  }
8812
8812
  //#endregion
8813
8813
  //#region src/collectionStore/useItem.ts
8814
- function useItem$1(payload, { omitPayload, selector, ensureIsLoaded, returnRefetchingStatus, disableRefetches, disableRefetchOnMount, returnIdleStatus, isOffScreen, debouncePayload }, store, scheduleFetch, useMultipleItems) {
8814
+ function useItem$1(payload, { omitPayload, selector, requireFreshData, returnRefetchingStatus, disableRefetches, disableRefetchOnMount, returnIdleStatus, isOffScreen, debouncePayload }, store, scheduleFetch, useMultipleItems) {
8815
8815
  const isInvalidPayload = payload === "";
8816
8816
  const hasPayload = payload !== false && payload !== null && payload !== void 0 && payload !== "";
8817
- assertNoEnsureIsLoadedWithDebouncePayload("useItem", ensureIsLoaded, debouncePayload);
8817
+ assertNoRequireFreshDataWithDebouncePayload("useItem", requireFreshData, debouncePayload);
8818
8818
  const query = useMemo(() => hasPayload ? [{
8819
8819
  payload,
8820
8820
  omitPayload,
@@ -8861,15 +8861,15 @@ function useItem$1(payload, { omitPayload, selector, ensureIsLoaded, returnRefet
8861
8861
  selector
8862
8862
  ]);
8863
8863
  const fetchQuery = hasPayload ? query[0] : void 0;
8864
- const [useModifyResult, emitIsLoadedEvt] = useEnsureIsLoaded(ensureIsLoaded, hasPayload, () => {
8864
+ const [useModifyResult, markRefreshSettled] = useRequireFreshData(requireFreshData, hasPayload, () => {
8865
8865
  if (fetchQuery) scheduleFetch("highPriority", fetchQuery.payload);
8866
8866
  });
8867
8867
  useSubscribeToStore(store, ({ observe }) => {
8868
- if (!ensureIsLoaded || !hasPayload || !result.itemStateKey) return;
8868
+ if (!requireFreshData || !hasPayload || !result.itemStateKey) return;
8869
8869
  observe.ifSelector((state) => {
8870
8870
  return state[result.itemStateKey]?.status;
8871
8871
  }).change.then(({ current }) => {
8872
- if (current === "success" || current === "error") emitIsLoadedEvt();
8872
+ if (current === "success" || current === "error") markRefreshSettled();
8873
8873
  });
8874
8874
  });
8875
8875
  return useModifyResult(result);
@@ -9974,11 +9974,11 @@ function createCollectionStore(storeOptions) {
9974
9974
  /** Detects whether a specific item inside a collection item's data is still loading.
9975
9975
  * Useful when a collection item holds a list/record of sub-items and a component
9976
9976
  * displays one that may not be present yet. */
9977
- function useListItemIsLoading$2(payload, { itemId, selector, loadItemFallback, ensureIsLoaded }) {
9977
+ function useListItemIsLoading$2(payload, { itemId, selector, loadItemFallback, requireFreshData }) {
9978
9978
  const item = useItem(payload, {
9979
9979
  returnRefetchingStatus: true,
9980
9980
  selector,
9981
- ensureIsLoaded
9981
+ requireFreshData
9982
9982
  });
9983
9983
  const itemExists = item.data != null;
9984
9984
  const listIsLoading = item.isLoading;
@@ -9993,11 +9993,11 @@ function createCollectionStore(storeOptions) {
9993
9993
  /** Detects when a specific item inside a collection item's data has been deleted.
9994
9994
  * Only triggers after the sub-item was previously found and then disappears — not
9995
9995
  * during initial loading. */
9996
- function useListItemIsDeleted$2(payload, { itemId, selector, onDelete, ensureIsLoaded }) {
9996
+ function useListItemIsDeleted$2(payload, { itemId, selector, onDelete, requireFreshData }) {
9997
9997
  const item = useItem(payload, {
9998
9998
  returnRefetchingStatus: true,
9999
9999
  selector,
10000
- ensureIsLoaded
10000
+ requireFreshData
10001
10001
  });
10002
10002
  const itemExists = item.data != null;
10003
10003
  const listIsLoading = item.isLoading;
@@ -10010,11 +10010,11 @@ function createCollectionStore(storeOptions) {
10010
10010
  }
10011
10011
  /** Combined hook that returns `{ isLoading, isDeleted, data }` for a specific item
10012
10012
  * inside a collection item's data. Composes `useListItemIsLoading` and `useListItemIsDeleted`. */
10013
- function useListItem$2(payload, { itemId, selector, loadItemFallback, onDelete, ensureIsLoaded }) {
10013
+ function useListItem$2(payload, { itemId, selector, loadItemFallback, onDelete, requireFreshData }) {
10014
10014
  const item = useItem(payload, {
10015
10015
  returnRefetchingStatus: true,
10016
10016
  selector,
10017
- ensureIsLoaded
10017
+ requireFreshData
10018
10018
  });
10019
10019
  const itemExists = item.data != null;
10020
10020
  const listIsLoading = item.isLoading;
@@ -10682,7 +10682,7 @@ function createDocumentStore(storeOptions) {
10682
10682
  if (!offline && result.ok && result.value.kind === "online") return Result.ok(result.value.data);
10683
10683
  return result;
10684
10684
  }
10685
- function useDocument({ selector, isOffScreen: isOffScreenProp, disabled: disabledProp, returnRefetchingStatus, disableRefetchOnMount = globalDisableRefetchOnMount, returnIdleStatus: returnIdleStatusProp, ensureIsLoaded, disableRefetches } = {}) {
10685
+ function useDocument({ selector, isOffScreen: isOffScreenProp, disabled: disabledProp, returnRefetchingStatus, disableRefetchOnMount = globalDisableRefetchOnMount, returnIdleStatus: returnIdleStatusProp, requireFreshData, disableRefetches } = {}) {
10686
10686
  const offlineEntities = useOfflineStoreEntities({
10687
10687
  sessionKey: getSessionKeyForRuntime(),
10688
10688
  inactiveScope: id,
@@ -10758,12 +10758,12 @@ function createDocumentStore(storeOptions) {
10758
10758
  disableRefetches,
10759
10759
  disabled
10760
10760
  ]);
10761
- const [useModifyResult, emitIsLoadedEvt] = useEnsureIsLoaded(ensureIsLoaded, !disabled, () => {
10761
+ const [useModifyResult, markRefreshSettled] = useRequireFreshData(requireFreshData, !disabled, () => {
10762
10762
  scheduleFetch("highPriority");
10763
10763
  });
10764
10764
  useSubscribeToStore(store, ({ observe }) => {
10765
10765
  observe.ifSelector((state) => state.status).change.then(({ current }) => {
10766
- if (current === "success" || current === "error") emitIsLoadedEvt();
10766
+ if (current === "success" || current === "error") markRefreshSettled();
10767
10767
  });
10768
10768
  });
10769
10769
  return useModifyResult(storeState);
@@ -10771,11 +10771,11 @@ function createDocumentStore(storeOptions) {
10771
10771
  /** Detects whether a specific item inside the document's data is still loading.
10772
10772
  * Useful when the document holds a list/record of items and a component displays
10773
10773
  * an individual item that may not be present yet. */
10774
- function useListItemIsLoading$1({ itemId, selector, loadItemFallback, ensureIsLoaded }) {
10774
+ function useListItemIsLoading$1({ itemId, selector, loadItemFallback, requireFreshData }) {
10775
10775
  const doc = useDocument({
10776
10776
  returnRefetchingStatus: true,
10777
10777
  selector,
10778
- ensureIsLoaded
10778
+ requireFreshData
10779
10779
  });
10780
10780
  const itemExists = doc.data != null;
10781
10781
  const listIsLoading = doc.isLoading;
@@ -10790,11 +10790,11 @@ function createDocumentStore(storeOptions) {
10790
10790
  /** Detects when a specific item inside the document's data has been deleted.
10791
10791
  * Only triggers after the item was previously found and then disappears — not
10792
10792
  * during initial loading. */
10793
- function useListItemIsDeleted$1({ itemId, selector, onDelete, ensureIsLoaded }) {
10793
+ function useListItemIsDeleted$1({ itemId, selector, onDelete, requireFreshData }) {
10794
10794
  const doc = useDocument({
10795
10795
  returnRefetchingStatus: true,
10796
10796
  selector,
10797
- ensureIsLoaded
10797
+ requireFreshData
10798
10798
  });
10799
10799
  const itemExists = doc.data != null;
10800
10800
  const listIsLoading = doc.isLoading;
@@ -10807,11 +10807,11 @@ function createDocumentStore(storeOptions) {
10807
10807
  }
10808
10808
  /** Combined hook that returns `{ isLoading, isDeleted, data }` for a specific item
10809
10809
  * inside the document's data. Composes `useListItemIsLoading` and `useListItemIsDeleted`. */
10810
- function useListItem$1({ itemId, selector, loadItemFallback, onDelete, ensureIsLoaded }) {
10810
+ function useListItem$1({ itemId, selector, loadItemFallback, onDelete, requireFreshData }) {
10811
10811
  const doc = useDocument({
10812
10812
  returnRefetchingStatus: true,
10813
10813
  selector,
10814
- ensureIsLoaded
10814
+ requireFreshData
10815
10815
  });
10816
10816
  const itemExists = doc.data != null;
10817
10817
  const listIsLoading = doc.isLoading;
@@ -14778,10 +14778,10 @@ function useFindItem(findItemFn, { selector }, store, registerActiveItems, touch
14778
14778
  }
14779
14779
  //#endregion
14780
14780
  //#region src/listQueryStore/useItem.ts
14781
- function useItem(itemPayload, { selector, ensureIsLoaded, loadFromStateOnly, disableRefetches, disableRefetchOnMount, returnIdleStatus, returnRefetchingStatus, showPartialAsRefetching, isOffScreen, fields, debouncePayload }, store, scheduleItemFetch, useMultipleItems) {
14781
+ function useItem(itemPayload, { selector, requireFreshData, loadFromStateOnly, disableRefetches, disableRefetchOnMount, returnIdleStatus, returnRefetchingStatus, showPartialAsRefetching, isOffScreen, fields, debouncePayload }, store, scheduleItemFetch, useMultipleItems) {
14782
14782
  const isInvalidPayload = itemPayload === "";
14783
14783
  const hasPayload = itemPayload !== false && itemPayload !== null && itemPayload !== void 0 && itemPayload !== "";
14784
- assertNoEnsureIsLoadedWithDebouncePayload("useItem", ensureIsLoaded, debouncePayload);
14784
+ assertNoRequireFreshDataWithDebouncePayload("useItem", requireFreshData, debouncePayload);
14785
14785
  const query = useMemo(() => hasPayload ? [{
14786
14786
  payload: itemPayload,
14787
14787
  fields,
@@ -14832,25 +14832,25 @@ function useItem(itemPayload, { selector, ensureIsLoaded, loadFromStateOnly, dis
14832
14832
  selector
14833
14833
  ]);
14834
14834
  const fetchQuery = hasPayload ? query[0] : void 0;
14835
- const [useModifyResult, emitIsLoadedEvt] = useEnsureIsLoaded(ensureIsLoaded, hasPayload, () => {
14835
+ const [useModifyResult, markRefreshSettled] = useRequireFreshData(requireFreshData, hasPayload, () => {
14836
14836
  if (fetchQuery) scheduleItemFetch("highPriority", fetchQuery.payload, { fields: fetchQuery.fields });
14837
14837
  });
14838
14838
  useSubscribeToStore(store, ({ observe }) => {
14839
- if (!ensureIsLoaded || !hasPayload || !result.itemStateKey) return;
14839
+ if (!requireFreshData || !hasPayload || !result.itemStateKey) return;
14840
14840
  observe.ifSelector((state) => {
14841
14841
  return state.itemQueries[result.itemStateKey]?.status;
14842
14842
  }).change.then(({ current }) => {
14843
- if (current === "success" || current === "error") emitIsLoadedEvt();
14843
+ if (current === "success" || current === "error") markRefreshSettled();
14844
14844
  });
14845
14845
  });
14846
14846
  return useModifyResult(result);
14847
14847
  }
14848
14848
  //#endregion
14849
14849
  //#region src/listQueryStore/useListQuery.ts
14850
- function useListQuery(payload, { itemSelector, omitPayload, disableRefetches, disableRefetchOnMount, returnIdleStatus, returnRefetchingStatus, showPartialAsRefetching, loadSize, isOffScreen, ensureIsLoaded, fields, debouncePayload }, store, getQueryKey, scheduleListQueryFetch, useMultipleListQueries) {
14850
+ function useListQuery(payload, { itemSelector, omitPayload, disableRefetches, disableRefetchOnMount, returnIdleStatus, returnRefetchingStatus, showPartialAsRefetching, loadSize, isOffScreen, requireFreshData, fields, debouncePayload }, store, getQueryKey, scheduleListQueryFetch, useMultipleListQueries) {
14851
14851
  const isInvalidPayload = payload === "";
14852
14852
  const hasPayload = payload !== false && payload !== null && payload !== void 0 && payload !== "";
14853
- assertNoEnsureIsLoadedWithDebouncePayload("useListQuery", ensureIsLoaded, debouncePayload);
14853
+ assertNoRequireFreshDataWithDebouncePayload("useListQuery", requireFreshData, debouncePayload);
14854
14854
  const query = useMemo(() => hasPayload ? [{
14855
14855
  payload,
14856
14856
  fields,
@@ -14912,15 +14912,15 @@ function useListQuery(payload, { itemSelector, omitPayload, disableRefetches, di
14912
14912
  ]);
14913
14913
  const queryKey = hasPayload ? getQueryKey(payload) : "";
14914
14914
  const fetchQuery = hasPayload ? query[0] : void 0;
14915
- const [useModifyResult, emitIsLoadedEvt] = useEnsureIsLoaded(ensureIsLoaded, hasPayload, () => {
14915
+ const [useModifyResult, markRefreshSettled] = useRequireFreshData(requireFreshData, hasPayload, () => {
14916
14916
  if (fetchQuery && hasPayload) scheduleListQueryFetch("highPriority", fetchQuery.payload, fetchQuery.loadSize, { fields: fetchQuery.fields });
14917
14917
  });
14918
14918
  useSubscribeToStore(store, ({ observe }) => {
14919
- if (!ensureIsLoaded || !hasPayload || !queryKey) return;
14919
+ if (!requireFreshData || !hasPayload || !queryKey) return;
14920
14920
  observe.ifSelector((state) => {
14921
14921
  return state.queries[queryKey]?.status;
14922
14922
  }).change.then(({ current }) => {
14923
- if (current === "success" || current === "error") emitIsLoadedEvt();
14923
+ if (current === "success" || current === "error") markRefreshSettled();
14924
14924
  });
14925
14925
  });
14926
14926
  return useModifyResult(result);
@@ -1,2 +1,2 @@
1
- import { t as opfsPersistentStorage } from "./opfsPersistentStorage-Ci0JcCo5.js";
1
+ import { t as opfsPersistentStorage } from "./opfsPersistentStorage-BB0qqnRz.js";
2
2
  export { opfsPersistentStorage };
@@ -1,4 +1,4 @@
1
- import { t as AsyncStorageAdapter } from "./types-D0ttVGmj.js";
1
+ import { t as AsyncStorageAdapter } from "./types-aWgyZHLj.js";
2
2
 
3
3
  //#region src/persistentStorage/opfsPersistentStorage.d.ts
4
4
  declare const opfsPersistentStorage: AsyncStorageAdapter;
@@ -58,7 +58,7 @@ type MaybeTSDFResult<T> = T | Result<T, ResultValidErrors>;
58
58
  *
59
59
  * The hook still reads data from state using the latest payload immediately.
60
60
  * Only the automatic fetch side is delayed. Single hooks do not support
61
- * combining this with `ensureIsLoaded`.
61
+ * combining this with `requireFreshData`.
62
62
  */
63
63
  type PayloadDebounce = {
64
64
  /** Debounce window in milliseconds before the latest payload is fetched. */ms: number;
@@ -11,7 +11,7 @@ Every fetch request has a priority that determines its behavior:
11
11
  | `lowPriority` | Hook mount (default), window focus revalidation | Throttled — skipped if a fetch happened recently (within `lowPriorityThrottleMs`) |
12
12
  | `mediumPriority` | Background refetches | Delayed by `mediumPriorityDelayMs`, then executed. Cancelled if another fetch including the same request starts. If the store has never been fetched, automatically promotes to `highPriority` |
13
13
  | `realtimeUpdate` | Real-time data pushes | Uses `dynamicRealtimeThrottleMs` for adaptive throttling based on last fetch duration |
14
- | `highPriority` | Explicit invalidation, `ensureIsLoaded` | Executes immediately (after coalescing window). Never throttled |
14
+ | `highPriority` | Explicit invalidation, `requireFreshData` | Executes immediately (after coalescing window). Never throttled |
15
15
 
16
16
  ## Throttling
17
17
 
@@ -23,6 +23,11 @@ lowPriorityThrottleMs: 40 * 60 * 1_000
23
23
 
24
24
  If a hook mounts within the configured throttle window after the last fetch completed, the low-priority fetch is **skipped** because the data is still fresh enough.
25
25
 
26
+ `requireFreshData` deliberately bypasses this mount throttling by scheduling a
27
+ high-priority fetch even when successful cached data exists. Use it only when a
28
+ component must wait for a server refresh attempt before reporting a ready
29
+ status; applying it broadly can turn remounts into repeated network requests.
30
+
26
31
  ## Coalescing
27
32
 
28
33
  When multiple fetch requests arrive in a short window, they are coalesced into a single batch:
package/docs/hooks.md CHANGED
@@ -22,7 +22,40 @@ These options are available across all data hooks:
22
22
  | `disableRefetchOnMount` | `false` (or `true` when `usesRealTimeUpdates` is enabled) | Only fetches if data was explicitly invalidated or has never been loaded. Skips the low-priority refetch that normally happens on mount |
23
23
  | `returnIdleStatus` | `true` when disabled, `false` otherwise | When `false`, maps `idle` status to `loading` so the UI shows a loading state immediately |
24
24
  | `returnRefetchingStatus` | `false` | When `false`, maps `refetching` status to `success` so the UI doesn't flicker during background refetches |
25
- | `ensureIsLoaded` | `false` | Forces a high-priority fetch on mount and overrides status to `loading` until data is loaded. Useful for components that must show fresh data |
25
+ | `requireFreshData` | `false` | Unconditionally schedules a high-priority mount fetch and reports `loading` until it settles. Use sparingly because mounts can cause extra requests |
26
+
27
+ ## `requireFreshData`
28
+
29
+ Most components should use the default mount behavior. TSDF normally serves
30
+ cached data immediately and uses low-priority mount scheduling, which allows
31
+ the scheduler to throttle or skip redundant requests.
32
+
33
+ Set `requireFreshData: true` only when a component must not report itself as
34
+ ready until it has attempted to refresh from the server:
35
+
36
+ ```tsx
37
+ const result = store.useDocument({ requireFreshData: true });
38
+ ```
39
+
40
+ This option changes both fetching and the returned status:
41
+
42
+ - Every enabled hook mount unconditionally schedules a `highPriority` fetch,
43
+ even when the cache already contains successful data.
44
+ - Cached data remains available in `data`, but `status` is reported as
45
+ `loading` and `isLoading` as `true` until the refresh settles.
46
+ - A successful refresh reports `success`; a failed refresh reports `error`.
47
+ The option requires a refresh attempt—it cannot guarantee fresh data when
48
+ the request fails.
49
+ - It takes precedence over `disableRefetches` and `disableRefetchOnMount`.
50
+ Disabled hooks do not fetch.
51
+ - Scheduler coalescing can merge simultaneous work, but repeated mounts can
52
+ still produce repeated network requests.
53
+
54
+ Avoid enabling this broadly in shared hooks, list rows, or route-level
55
+ components. Doing so bypasses TSDF's normal low-priority mount throttling and
56
+ can significantly increase request volume. Prefer the default cache behavior,
57
+ targeted invalidation, or an explicit user-triggered refresh unless readiness
58
+ truly depends on a new server response.
26
59
 
27
60
  ## `debouncePayload`
28
61
 
@@ -44,7 +77,7 @@ Behavior:
44
77
  - Intermediate payloads are skipped if they are replaced before the debounce
45
78
  window ends
46
79
  - `useItem` and `useListQuery` throw if `debouncePayload` is combined with
47
- `ensureIsLoaded`
80
+ `requireFreshData`
48
81
 
49
82
  ### Basic trailing debounce
50
83
 
@@ -158,7 +191,8 @@ const item = store.useItem(selectedItemId, {
158
191
  This is useful when `selectedItemId` changes rapidly, such as typeahead-driven
159
192
  selection or fast keyboard navigation.
160
193
 
161
- `ensureIsLoaded` cannot be combined with `debouncePayload` on single hooks.
194
+ `requireFreshData` cannot be combined with `debouncePayload` on single hooks
195
+ because the required refresh must be scheduled immediately.
162
196
 
163
197
  ### List Query Store specific options
164
198
 
@@ -225,7 +259,8 @@ const result = store.useListQuery(
225
259
  );
226
260
  ```
227
261
 
228
- `ensureIsLoaded` cannot be combined with `debouncePayload` on `useListQuery`.
262
+ `requireFreshData` cannot be combined with `debouncePayload` on `useListQuery`
263
+ because the required refresh must be scheduled immediately.
229
264
 
230
265
  This is useful for search forms and filter panels where the query payload
231
266
  changes on every keystroke.
@@ -108,7 +108,8 @@ Important behavior:
108
108
  - If cached data already exists for the latest payload, the hook can still
109
109
  return it immediately while the fetch is deferred
110
110
  - `useItem` and `useListQuery` do not support combining `debouncePayload` with
111
- `ensureIsLoaded`
111
+ `requireFreshData`, because that option requires an immediate high-priority
112
+ refresh
112
113
 
113
114
  Example:
114
115
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tsdf",
3
- "version": "17.0.1",
3
+ "version": "17.0.2",
4
4
  "description": "A data fetching solution based on t-state",
5
5
  "license": "PolyForm-Noncommercial-1.0.0",
6
6
  "author": "Lucas Santos",