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.
- package/dist/async-storage.d.ts +1 -1
- package/dist/{asyncStorageAdapter-CMohMeKm.d.ts → asyncStorageAdapter-DuAUANgu.d.ts} +1 -1
- package/dist/indexed-db-storage.d.ts +1 -1
- package/dist/main.d.ts +32 -28
- package/dist/main.js +46 -46
- package/dist/opfs-storage.d.ts +1 -1
- package/dist/{opfsPersistentStorage-Ci0JcCo5.d.ts → opfsPersistentStorage-BB0qqnRz.d.ts} +1 -1
- package/dist/{types-D0ttVGmj.d.ts → types-aWgyZHLj.d.ts} +1 -1
- package/docs/fetch-scheduling.md +6 -1
- package/docs/hooks.md +39 -4
- package/docs/shared-types.md +2 -1
- package/package.json +1 -1
package/dist/async-storage.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import { t as createAsyncStorageAdapter } from "./asyncStorageAdapter-
|
|
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-
|
|
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-
|
|
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-
|
|
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
|
-
*
|
|
145
|
-
* until
|
|
146
|
-
*
|
|
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
|
-
|
|
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; /**
|
|
376
|
-
|
|
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; /**
|
|
382
|
-
|
|
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; /**
|
|
389
|
-
|
|
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
|
-
*
|
|
602
|
-
* until
|
|
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
|
-
|
|
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; /**
|
|
611
|
-
|
|
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; /**
|
|
617
|
-
|
|
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; /**
|
|
624
|
-
|
|
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
|
-
*
|
|
669
|
-
* until
|
|
670
|
-
*
|
|
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
|
-
|
|
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
|
-
*
|
|
718
|
-
* until
|
|
719
|
-
*
|
|
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
|
-
|
|
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
|
|
8776
|
-
if (!import.meta.env.PROD &&
|
|
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/
|
|
8780
|
-
function
|
|
8781
|
-
const
|
|
8782
|
-
const [
|
|
8783
|
-
useOnChange(
|
|
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(
|
|
8787
|
-
if (
|
|
8786
|
+
useOnEvtmitterEvent(refreshSettledEvtEmitter, "refreshSettled", ({ payload: refreshSettled }) => {
|
|
8787
|
+
if (requireFreshData && enabled && refreshSettled) setIsWaitingForRefresh(false);
|
|
8788
8788
|
});
|
|
8789
8789
|
function useModifyResult(result) {
|
|
8790
|
-
return useGetModifyResult(result,
|
|
8790
|
+
return useGetModifyResult(result, requireFreshData, enabled, isWaitingForRefresh);
|
|
8791
8791
|
}
|
|
8792
|
-
return [useModifyResult, () =>
|
|
8792
|
+
return [useModifyResult, () => refreshSettledEvtEmitter.emit("refreshSettled", true)];
|
|
8793
8793
|
}
|
|
8794
|
-
function useGetModifyResult(result,
|
|
8794
|
+
function useGetModifyResult(result, requireFreshData, enabled, isWaitingForRefresh) {
|
|
8795
8795
|
return useMemo(() => {
|
|
8796
|
-
if (
|
|
8797
|
-
const newStatus = enabled &&
|
|
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
|
-
|
|
8807
|
-
|
|
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,
|
|
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
|
-
|
|
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,
|
|
8864
|
+
const [useModifyResult, markRefreshSettled] = useRequireFreshData(requireFreshData, hasPayload, () => {
|
|
8865
8865
|
if (fetchQuery) scheduleFetch("highPriority", fetchQuery.payload);
|
|
8866
8866
|
});
|
|
8867
8867
|
useSubscribeToStore(store, ({ observe }) => {
|
|
8868
|
-
if (!
|
|
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")
|
|
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,
|
|
9977
|
+
function useListItemIsLoading$2(payload, { itemId, selector, loadItemFallback, requireFreshData }) {
|
|
9978
9978
|
const item = useItem(payload, {
|
|
9979
9979
|
returnRefetchingStatus: true,
|
|
9980
9980
|
selector,
|
|
9981
|
-
|
|
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,
|
|
9996
|
+
function useListItemIsDeleted$2(payload, { itemId, selector, onDelete, requireFreshData }) {
|
|
9997
9997
|
const item = useItem(payload, {
|
|
9998
9998
|
returnRefetchingStatus: true,
|
|
9999
9999
|
selector,
|
|
10000
|
-
|
|
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,
|
|
10013
|
+
function useListItem$2(payload, { itemId, selector, loadItemFallback, onDelete, requireFreshData }) {
|
|
10014
10014
|
const item = useItem(payload, {
|
|
10015
10015
|
returnRefetchingStatus: true,
|
|
10016
10016
|
selector,
|
|
10017
|
-
|
|
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,
|
|
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,
|
|
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")
|
|
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,
|
|
10774
|
+
function useListItemIsLoading$1({ itemId, selector, loadItemFallback, requireFreshData }) {
|
|
10775
10775
|
const doc = useDocument({
|
|
10776
10776
|
returnRefetchingStatus: true,
|
|
10777
10777
|
selector,
|
|
10778
|
-
|
|
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,
|
|
10793
|
+
function useListItemIsDeleted$1({ itemId, selector, onDelete, requireFreshData }) {
|
|
10794
10794
|
const doc = useDocument({
|
|
10795
10795
|
returnRefetchingStatus: true,
|
|
10796
10796
|
selector,
|
|
10797
|
-
|
|
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,
|
|
10810
|
+
function useListItem$1({ itemId, selector, loadItemFallback, onDelete, requireFreshData }) {
|
|
10811
10811
|
const doc = useDocument({
|
|
10812
10812
|
returnRefetchingStatus: true,
|
|
10813
10813
|
selector,
|
|
10814
|
-
|
|
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,
|
|
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
|
-
|
|
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,
|
|
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 (!
|
|
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")
|
|
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,
|
|
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
|
-
|
|
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,
|
|
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 (!
|
|
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")
|
|
14923
|
+
if (current === "success" || current === "error") markRefreshSettled();
|
|
14924
14924
|
});
|
|
14925
14925
|
});
|
|
14926
14926
|
return useModifyResult(result);
|
package/dist/opfs-storage.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
import { t as opfsPersistentStorage } from "./opfsPersistentStorage-
|
|
1
|
+
import { t as opfsPersistentStorage } from "./opfsPersistentStorage-BB0qqnRz.js";
|
|
2
2
|
export { opfsPersistentStorage };
|
|
@@ -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 `
|
|
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;
|
package/docs/fetch-scheduling.md
CHANGED
|
@@ -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, `
|
|
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
|
-
| `
|
|
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
|
-
`
|
|
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
|
-
`
|
|
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
|
-
`
|
|
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.
|
package/docs/shared-types.md
CHANGED
|
@@ -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
|
-
`
|
|
111
|
+
`requireFreshData`, because that option requires an immediate high-priority
|
|
112
|
+
refresh
|
|
112
113
|
|
|
113
114
|
Example:
|
|
114
115
|
|