tsdf 17.0.0-alpha.9 → 17.0.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/main.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { $ as OfflineResolutionRecord, A as DefineListQueryOfflineOperations, At as PayloadDebounce, B as OfflineEntityMutationKind, Bt as mutationSkipped, C as PersistentStorageSchema, Ct as OfflineUploadAdapter, D as CollectionOfflineOperationDefinition, Dt as OfflineUploadTransportContext, E as CollectionOfflineEntityRef, Et as OfflineUploadState, F as ListQueryOfflineEntityRef, Ft as TSDFStatus, G as OfflineMutationQueueingPolicy, Gt as ScheduleFetchResults, H as OfflineMutationInput, Ht as RequestSchedulerEventData, I as ListQueryOfflineOperationDefinition, It as UnwrapTSDFResult, J as OfflineReplayRetryConfig, Jt as TSDFDebugLogLevel, K as OfflineOperationKind, Kt as TSDFDebugLogArea, L as OfflineAccumulationConfig, Lt as ValidPayload, M as DocumentOfflineOperationDefinition, Mt as StoreFetchError, N as GlobalOfflineEntity, Nt as StoreMutationError, O as DefineCollectionOfflineOperations, Ot as MaybeTSDFResult, P as GlobalOfflineStatus, Pt as StoreMutationErrorOptions, Q as OfflineResolutionConflictParseErrorCode, R as OfflineAccumulationMergeContext, Rt as ValidStoreState, S as PersistentStoragePreloadResult, St as OfflineUpload, T as AnyOfflineOperationDefinition, Tt as OfflineUploadSource, U as OfflineMutationQueueingCause, Ut as RequestSchedulerEvents, V as OfflineMutationDescriptor, Vt as FetchType, W as OfflineMutationQueueingConfig, Wt as ScheduleFetchOptions, X as OfflineResolutionActionForOperation, Xt as TSDFDebugOptions, Y as OfflineResolutionAction, Yt as TSDFDebugLogger, Z as OfflineResolutionConflictParseError, _ as ListQueryOfflineOperationsConfig, _t as defaultOfflineRuntimeConfig, a as AsyncStorageMetadataOrder, at as OfflineSession, b as PersistentStorageDataSchema, bt as OfflineSessionUploadsConfig, c as AsyncStorageNamespaceCommitUpsert, ct as OfflineSyncState, d as AsyncStorageNamespaceKind, dt as OfflineTempEntityConfig, et as OfflineResolutionRecordForOperation, f as AsyncStorageNamespaceScope, ft as OfflineTempEntityPendingEntry, g as DocumentPersistentStorageConfig, gt as ParsedOfflineResolutionConflictResultForStore, h as ConvertedPersistentStorageDataSchema, ht as ParsedOfflineResolutionConflictResultForOperation, i as AsyncStorageDriverSetEntry, it as OfflineRuntimeConfigUpdate, j as DefineOfflineOperation, jt as StoreError, k as DefineDocumentOfflineOperations, kt as MutationSkipped, l as AsyncStorageNamespaceGetResult, lt as OfflineTempEntitiesConfig, m as CollectionPersistentStorageConfig, mt as OperationResult, n as AsyncStorageDiscoveredScope, nt as OfflineRetryExhaustedResolutionAction, o as AsyncStorageNamespaceCommitArgs, ot as OfflineSessionConfig, p as AsyncStorageReadOptions, pt as OperationConflict, q as OfflineQueueEntry, qt as TSDFDebugLogEntry, r as AsyncStorageDriver, rt as OfflineRuntimeConfig, s as AsyncStorageNamespaceCommitTouch, st as OfflineSupersedeConfig, t as AsyncStorageAdapter, tt as OfflineResolutionRecordForStore, u as AsyncStorageNamespaceHandle, ut as OfflineTempEntitiesReconciliation, v as ListQueryPersistentStorageConfig, vt as OfflineMutationUploadsInput, w as StorageAdapter, wt as OfflineUploadProgress, x as PersistentStorageErrorHandler, xt as OfflineStoredUploadRecord, y as PersistentStorageBaseConfig, yt as OfflineOperationUploadsContext, z as OfflineConflictResolutionAction, zt as fetchTypePriority } from "./types-2zQlbxtw.js";
1
+ import { $ as OfflineResolutionRecord, $t as StoreError, A as DefineListQueryOfflineOperations, At as DerivedQuerySource, B as OfflineEntityMutationKind, Bt as OptimisticListUpdate, C as PersistentStorageSchema, Ct as OfflineUploadAdapter, D as CollectionOfflineOperationDefinition, Dt as OfflineUploadTransportContext, E as CollectionOfflineEntityRef, Et as OfflineUploadState, F as ListQueryOfflineEntityRef, Ft as ListQueryUseMultipleItemsQuery, G as OfflineMutationQueueingPolicy, Gt as TSFDListQuery, H as OfflineMutationInput, Ht as QueryFetchPayload, I as ListQueryOfflineOperationDefinition, It as ListQueryUseMultipleListQueriesQuery, J as OfflineReplayRetryConfig, Jt as TSFDUseListQueryReturn, K as OfflineOperationKind, Kt as TSFDListQueryState, L as OfflineAccumulationConfig, Lt as OffsetPaginationConfig, M as DocumentOfflineOperationDefinition, Mt as FetchListFnReturnItem, N as GlobalOfflineEntity, Nt as FieldsInput, O as DefineCollectionOfflineOperations, Ot as DerivedQueriesConfig, P as GlobalOfflineStatus, Pt as FieldsOption, Q as OfflineResolutionConflictParseErrorCode, Qt as PayloadDebounce, R as OfflineAccumulationMergeContext, Rt as OnListQueryInvalidate, S as PersistentStoragePreloadResult, St as OfflineUpload, T as AnyOfflineOperationDefinition, Tt as OfflineUploadSource, U as OfflineMutationQueueingCause, Ut as QueryStatus, V as OfflineMutationDescriptor, Vt as PartialResourcesConfig, W as OfflineMutationQueueingConfig, Wt as TSDFItemQuery, X as OfflineResolutionActionForOperation, Xt as MaybeTSDFResult, Y as OfflineResolutionAction, Yt as TSFDUsePendingOfflineItemsReturn, Z as OfflineResolutionConflictParseError, Zt as MutationSkipped, _ as ListQueryOfflineOperationsConfig, _n as TSDFDebugLogger, _t as defaultOfflineRuntimeConfig, a as AsyncStorageMetadataOrder, an as ValidPayload, at as OfflineSession, b as PersistentStorageDataSchema, bt as OfflineSessionUploadsConfig, c as AsyncStorageNamespaceCommitUpsert, cn as mutationSkipped, ct as OfflineSyncState, d as AsyncStorageNamespaceKind, dn as RequestSchedulerEvents, dt as OfflineTempEntityConfig, en as StoreFetchError, et as OfflineResolutionRecordForOperation, f as AsyncStorageNamespaceScope, fn as ScheduleFetchOptions, ft as OfflineTempEntityPendingEntry, g as DocumentPersistentStorageConfig, gn as TSDFDebugLogLevel, gt as ParsedOfflineResolutionConflictResultForStore, h as ConvertedPersistentStorageDataSchema, hn as TSDFDebugLogEntry, ht as ParsedOfflineResolutionConflictResultForOperation, i as AsyncStorageDriverSetEntry, in as UnwrapTSDFResult, it as OfflineRuntimeConfigUpdate, j as DefineOfflineOperation, jt as FetchListFnReturn, k as DefineDocumentOfflineOperations, kt as DerivedQueryContext, l as AsyncStorageNamespaceGetResult, ln as FetchType, lt as OfflineTempEntitiesConfig, m as CollectionPersistentStorageConfig, mn as TSDFDebugLogArea, mt as OperationResult, n as AsyncStorageDiscoveredScope, nn as StoreMutationErrorOptions, nt as OfflineRetryExhaustedResolutionAction, o as AsyncStorageNamespaceCommitArgs, on as ValidStoreState, ot as OfflineSessionConfig, p as AsyncStorageReadOptions, pn as ScheduleFetchResults, pt as OperationConflict, q as OfflineQueueEntry, qt as TSFDUseListItemReturn, r as AsyncStorageDriver, rn as TSDFStatus, rt as OfflineRuntimeConfig, s as AsyncStorageNamespaceCommitTouch, sn as fetchTypePriority, st as OfflineSupersedeConfig, t as AsyncStorageAdapter, tn as StoreMutationError, tt as OfflineResolutionRecordForStore, u as AsyncStorageNamespaceHandle, un as RequestSchedulerEventData, ut as OfflineTempEntitiesReconciliation, v as ListQueryPersistentStorageConfig, vn as TSDFFocusDebugOperation, vt as OfflineMutationUploadsInput, w as StorageAdapter, wt as OfflineUploadProgress, x as PersistentStorageErrorHandler, xt as OfflineStoredUploadRecord, y as PersistentStorageBaseConfig, yn as TSDFLoggerOptions, yt as OfflineOperationUploadsContext, z as OfflineConflictResolutionAction, zt as OnListQueryItemInvalidate } from "./types-D0ttVGmj.js";
2
2
  import { __LEGIT_ANY__ } from "@ls-stack/utils/saferTyping";
3
3
  import { Emitter } from "evtmitter";
4
4
  import { Context } from "react";
@@ -32,13 +32,18 @@ type MutationDebounce = {
32
32
  };
33
33
  //#endregion
34
34
  //#region src/storeManager.d.ts
35
+ /** Minimum interval between realtime-update fetches, recomputed per fetch.
36
+ * When the window regains focus, a refetch still waiting on the unfocused
37
+ * interval is re-evaluated with the focused one, firing immediately if it has
38
+ * already elapsed. */
35
39
  type DynamicRealtimeThrottleMs = (params: {
36
40
  readonly lastFetchDuration: number;
37
41
  readonly windowIsNotFocused: boolean;
38
42
  }) => number;
39
43
  type StoreManagerStoreDefaults = {
40
44
  /** Default minimum interval between low-priority fetches for attached stores. */readonly lowPriorityThrottleMs: number; /** Default coalescing window used by attached stores when they do not override it. */
41
- readonly baseCoalescingWindowMs: number; /** Default adaptive throttle for real-time updates in attached stores. */
45
+ readonly baseCoalescingWindowMs: number; /** Extra browser-tab coalescing delay applied only while a tab is in the background. */
46
+ readonly backgroundCoalescingDelayMs: number; /** Default adaptive throttle for real-time updates in attached stores. */
42
47
  readonly dynamicRealtimeThrottleMs: DynamicRealtimeThrottleMs; /** Shared window-close blocker used by mutations in attached stores. */
43
48
  readonly blockWindowClose: BlockWindowCloseHandler | null; /** Default focus revalidation policy for attached stores. */
44
49
  readonly revalidateOnWindowFocus: boolean | (() => boolean) | undefined;
@@ -72,8 +77,9 @@ type StoreManagerOfflineApi<TUploadRef extends ValidPayload = ValidPayload> = {
72
77
  };
73
78
  /** Shared coordinator passed to every TSDF store instance in an app/session. */
74
79
  type StoreManager<TUploadRef extends ValidPayload = ValidPayload> = {
75
- /** Returns the active shared session / tenant key. */getSessionKey: () => string | false; /** Shared debug logger for browser-tab sync and persistent storage internals. */
76
- debugLogger?: TSDFDebugLogger; /** Normalizes raw exceptions into the shared StoreError shape. */
80
+ /** Returns the active shared session / tenant key. */getSessionKey: () => string | false; /** Shared debug logger for browser-tab sync, focus lifecycle, and persistent storage internals. */
81
+ debugLogger?: TSDFDebugLogger; /** Shared logger for low-volume production signals. */
82
+ logger?: TSDFDebugLogger; /** Normalizes raw exceptions into the shared StoreError shape. */
77
83
  errorNormalizer: (exception: Error) => StoreError; /** Global fallback for persistent storage failures in attached stores. */
78
84
  onPersistentStorageError: PersistentStorageErrorHandler | undefined; /** Global fallback for mutation failures in attached stores. */
79
85
  onMutationError: StoreManagerMutationErrorHandler | undefined; /** Shared defaults used by attached stores unless a store-level override exists. */
@@ -90,19 +96,17 @@ type CreateStoreManagerOptions<TUploadRef extends ValidPayload = ValidPayload> =
90
96
  * behavior while no account is loaded.
91
97
  */
92
98
  getSessionKey: () => string | false; /** Normalizes raw exceptions into the shared StoreError shape. */
93
- errorNormalizer: (exception: Error) => StoreError; /** Default minimum interval between low-priority fetches for attached stores. Defaults to 5ms. */
94
- lowPriorityThrottleMs?: number; /** Default coalescing window for attached stores. Defaults to 10ms. */
95
- baseCoalescingWindowMs?: number; /** Default adaptive throttle for real-time updates in attached stores. Store-level values override it. */
99
+ errorNormalizer: (exception: Error) => StoreError; /** Default minimum interval between low-priority fetches for attached stores. Defaults to 40 minutes. */
100
+ lowPriorityThrottleMs?: number; /** Default coalescing window for attached stores. Defaults to 16ms. */
101
+ baseCoalescingWindowMs?: number; /** Extra browser-tab coalescing delay applied only while a tab is in the background. Defaults to 3000ms. */
102
+ backgroundCoalescingDelayMs?: number; /** Default adaptive throttle for real-time updates in attached stores. Store-level values override it. */
96
103
  dynamicRealtimeThrottleMs?: DynamicRealtimeThrottleMs; /** Shared window-close blocker used by mutations in attached stores. Pass `null` to disable. */
97
104
  blockWindowClose?: BlockWindowCloseHandler | null; /** Global fallback for persistent storage failures when a store does not provide its own handler. */
98
105
  onPersistentStorageError?: PersistentStorageErrorHandler; /** Global fallback for mutation failures when a store does not provide its own handler. */
99
106
  onMutationError?: StoreManagerMutationErrorHandler; /** Default focus revalidation policy for attached stores. Store-level values override it. */
100
- revalidateOnWindowFocus?: boolean | (() => boolean);
101
- /**
102
- * Enables debug logs for browser-tab sync and persistent storage operations.
103
- * Pass `true` to use console logging, or pass a logger function.
104
- */
105
- debug?: TSDFDebugOptions; /** Optional shared offline session config for every attached store. */
107
+ revalidateOnWindowFocus?: boolean | (() => boolean); /** Enables verbose development-only logs. Pass `true` to use console logging, or pass a logger function. */
108
+ debugLogger?: TSDFLoggerOptions; /** Enables low-volume production-safe logs. Defaults to console logging; pass `false` to disable. */
109
+ logger?: TSDFLoggerOptions; /** Optional shared offline session config for every attached store. */
106
110
  offlineSession?: OfflineSessionConfig<TUploadRef>;
107
111
  };
108
112
  declare function createStoreManager<TUploadRef extends ValidPayload = ValidPayload>(options: CreateStoreManagerOptions<TUploadRef>): StoreManager<TUploadRef>;
@@ -626,235 +630,6 @@ type DocumentStore<State extends ValidStoreState, TOfflineOperations extends Doc
626
630
  };
627
631
  declare function createDocumentStore<State extends ValidStoreState, TOfflineOperations extends DocumentOfflineOperationsConfig<State> = null, StorageState = unknown>(storeOptions: DocumentStoreOptions<State, TOfflineOperations, StorageState>): DocumentStore<State, TOfflineOperations>;
628
632
  //#endregion
629
- //#region src/listQueryStore/types.d.ts
630
- /** Lifecycle status for a list query or list item query. */
631
- type QueryStatus = TSDFStatus | 'loadingMore';
632
- /** Raw cached state for one list query. */
633
- type TSFDListQuery<QueryPayload extends ValidPayload> = {
634
- /** Last fetch error for this query, when the latest fetch failed. */error: StoreError | null; /** Current fetch lifecycle status for this query. */
635
- status: QueryStatus; /** Payload used to identify and fetch this query. */
636
- payload: QueryPayload; /** Whether another page is available. */
637
- hasMore: boolean; /** Whether this query has ever loaded successfully. */
638
- wasLoaded: boolean; /** Pending automatic refetch priority for stale data mounted by hooks. */
639
- refetchOnMount: false | FetchType; /** Ordered item keys included in the cached query page. */
640
- items: string[];
641
- };
642
- /** Raw cached state for one item query in a list-query store. */
643
- type TSDFItemQuery<ItemPayload extends ValidPayload> = {
644
- /** Last item fetch error, if any. */error: StoreError | null; /** Current fetch lifecycle status for this item. */
645
- status: Exclude<QueryStatus, 'loadingMore'>; /** Whether this item has ever loaded successfully. */
646
- wasLoaded: boolean; /** Pending automatic refetch priority for stale data mounted by hooks. */
647
- refetchOnMount: false | FetchType; /** Payload used to identify and fetch this item. */
648
- payload: ItemPayload;
649
- };
650
- /** Raw t-state shape used by a list-query store. */
651
- type TSFDListQueryState<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = {
652
- /** Item data records keyed by item store key. */items: Record<string, ItemState | null>; /** List query records keyed by query store key. */
653
- queries: Record<string, TSFDListQuery<QueryPayload>>; /** Item query records keyed by item store key. */
654
- itemQueries: Record<string, TSDFItemQuery<ItemPayload> | null>; /** Loaded partial-resource fields for each item key. */
655
- itemLoadedFields: Record<string, string[]>; /** Pending field invalidations for each item key. */
656
- itemFieldInvalidationFields: Record<string, string[]>;
657
- };
658
- /**
659
- * Partial-resource fields to request.
660
- *
661
- * Pass a field-name array to load only those fields, or `'*'` to load the
662
- * complete item.
663
- */
664
- type FieldsInput = string[] | '*';
665
- /** Value returned by `ListQueryStore.useListQuery(...)` and `useMultipleListQueries(...)`. */
666
- type TSFDUseListQueryReturn<Selected, QueryPayload, QueryMetadata extends undefined | Record<string, unknown> = undefined, HasPartialResources extends boolean = false> = {
667
- /** Selected items included in the current query result. */items: Selected[]; /** Hook-visible query status, including `idle` before a query runs. */
668
- status: QueryStatus | 'idle'; /** Query payload for this result, unless omitted or unavailable. */
669
- payload: QueryPayload | undefined; /** Requested partial-resource fields for this query result. */
670
- fields: HasPartialResources extends true ? FieldsInput : FieldsInput | undefined; /** Requested partial-resource fields that are still pending. */
671
- loadingFields?: string[]; /** Last query fetch error, if any. */
672
- error: StoreError | null; /** Stable store key for the current query payload. */
673
- queryKey: string; /** Whether another page is available. */
674
- hasMore: boolean; /** Whether this result was derived from local items instead of fetched directly. */
675
- isDerived: boolean; /** Convenience flag for `loading` or `refetching` states. */
676
- isLoading: boolean; /** Whether a `loadMore(...)` request is currently active. */
677
- isLoadingMore: boolean; /** Whether this result has local offline changes that still need to sync to the server. */
678
- pendingSync: boolean; /** Caller-provided metadata copied from the query descriptor. */
679
- queryMetadata: QueryMetadata;
680
- };
681
- /** Value returned by `ListQueryStore.useItem(...)` and `useMultipleItems(...)`. */
682
- type TSFDUseListItemReturn<Selected, ItemPayload, QueryMetadata extends undefined | Record<string, unknown> = undefined> = {
683
- /** Selected item data. Defaults to the full item or `null`. */data: Selected; /** Hook-visible item status, including idle/deleted states for hook ergonomics. */
684
- status: QueryStatus | 'idle' | 'deleted'; /** Item payload for this result, or `null` when unavailable. */
685
- payload: ItemPayload | null; /** Requested partial-resource fields that are still pending. */
686
- loadingFields?: string[]; /** Last item fetch error, if any. */
687
- error: StoreError | null; /** Convenience flag for `loading` or `refetching` states. */
688
- isLoading: boolean; /** Stable store key for the current item payload. */
689
- itemStateKey: string; /** Whether this result has local offline changes that still need to sync to the server. */
690
- pendingSync: boolean; /** Caller-provided metadata copied from the query descriptor. */
691
- queryMetadata: QueryMetadata;
692
- };
693
- /** Value returned by `ListQueryStore.usePendingOfflineItems(...)`. */
694
- type TSFDUsePendingOfflineItemsReturn<Selected, ItemPayload extends ValidPayload> = {
695
- /** Locally created or updated offline items selected by the hook. */items: Selected[]; /** Payloads for locally deleted offline items. */
696
- deletedItems: ItemPayload[];
697
- };
698
- /** One item returned from a list query fetch function. */
699
- type FetchListFnReturnItem<ItemPayload extends ValidPayload, ItemState extends ValidStoreState> = {
700
- /** Item payload used to key and refetch the returned item. */itemPayload: ItemPayload; /** Item data returned by the server. */
701
- data: ItemState;
702
- };
703
- /** Return shape for list query fetch functions. */
704
- type FetchListFnReturn<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = {
705
- /** Items included in the fetched page. */items: FetchListFnReturnItem<ItemPayload, ItemState>[]; /** Whether the query has another page available. */
706
- hasMore: boolean;
707
- };
708
- /** Item descriptor accepted by `ListQueryStore.useMultipleItems(...)`. */
709
- type ListQueryUseMultipleItemsQuery<ItemPayload extends ValidPayload, QueryMetadata extends undefined | Record<string, unknown> = undefined> = {
710
- /** Item payload to subscribe to and fetch when needed. */payload: ItemPayload;
711
- /**
712
- * Partial-resource fields to request for this item.
713
- *
714
- * Pass `'*'` to fetch the complete item. This option is required when
715
- * `partialResources` is enabled and optional otherwise.
716
- */
717
- fields?: FieldsInput; /** Metadata returned with this item result for caller-side bookkeeping. */
718
- queryMetadata?: QueryMetadata;
719
- /**
720
- * Only fetches when the item is missing from state, skipping stale-state and
721
- * invalidation refetches.
722
- */
723
- disableRefetches?: boolean; /** Prevents the automatic mount refetch for stale loaded data. */
724
- disableRefetchOnMount?: boolean; /** Returns `idle` instead of `loading` while the item has not been fetched. */
725
- returnIdleStatus?: boolean; /** Returns `refetching` instead of keeping `loaded` status during refetches. */
726
- returnRefetchingStatus?: boolean;
727
- /**
728
- * When requested fields are missing but cached partial data exists, return
729
- * `refetching` instead of `loading`.
730
- */
731
- showPartialAsRefetching?: boolean; /** Marks this subscription as off-screen, lowering automatic fetch priority. */
732
- isOffScreen?: boolean;
733
- };
734
- /** Query descriptor accepted by `ListQueryStore.useMultipleListQueries(...)`. */
735
- type ListQueryUseMultipleListQueriesQuery<QueryPayload extends ValidPayload, QueryMetadata extends undefined | Record<string, unknown> = undefined> = {
736
- /** Query payload to subscribe to and fetch when needed. */payload: QueryPayload;
737
- /**
738
- * Partial-resource fields to request for each item in this query.
739
- *
740
- * Pass `'*'` to fetch complete items. This option is required when
741
- * `partialResources` is enabled and optional otherwise.
742
- */
743
- fields?: FieldsInput; /** Metadata returned with this query result for caller-side bookkeeping. */
744
- queryMetadata?: QueryMetadata; /** Omits `payload` from this query result. */
745
- omitPayload?: boolean;
746
- /**
747
- * Only fetches when the query is missing from state, skipping stale-state and
748
- * invalidation refetches.
749
- */
750
- disableRefetches?: boolean; /** Prevents the automatic mount refetch for stale loaded data. */
751
- disableRefetchOnMount?: boolean; /** Returns `idle` instead of `loading` while the query has not been fetched. */
752
- returnIdleStatus?: boolean; /** Returns `refetching` instead of keeping `loaded` status during refetches. */
753
- returnRefetchingStatus?: boolean;
754
- /**
755
- * When requested fields are missing but cached partial data exists, return
756
- * `refetching` instead of `loading`.
757
- */
758
- showPartialAsRefetching?: boolean; /** Marks this subscription as off-screen, lowering automatic fetch priority. */
759
- isOffScreen?: boolean; /** Number of items to request when fetching this query page. */
760
- loadSize?: number;
761
- };
762
- /** Callback invoked when an already-loaded list query is invalidated. */
763
- type OnListQueryInvalidate<QueryPayload extends ValidPayload> = (query: QueryPayload, priority: FetchType) => void;
764
- /** Callback invoked when an already-loaded list-query item is invalidated. */
765
- type OnListQueryItemInvalidate<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = (props: {
766
- /** Current cached item state at invalidation time. */itemState: ItemState; /** Payload of the invalidated item. */
767
- payload: ItemPayload; /** Fetch priority requested for the invalidation. */
768
- priority: FetchType;
769
- }) => void;
770
- /** Rule for keeping cached list query membership in sync after item updates. */
771
- type OptimisticListUpdate<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = {
772
- /** Query payloads, or a predicate over query payloads, affected by this rule. */queries: QueryPayload | ((query: QueryPayload) => boolean) | QueryPayload[]; /** Restricts this rule to items that should belong in the affected query set. */
773
- filterItem?: (item: ItemState) => boolean | null; /** Where newly matching items should be inserted in affected query pages. */
774
- appendNewTo?: 'start' | 'end'; /** Whether affected queries should still refetch after the optimistic list update. */
775
- invalidateQueries?: boolean; /** Sort order to maintain inside affected query pages. */
776
- sort?: {
777
- /** Selects sortable values from an item. */sortBy: (item: ItemState, itemPayload: ItemPayload) => string | number | (string | number)[]; /** Sort direction for each `sortBy` value. */
778
- order?: 'asc' | 'desc' | ('asc' | 'desc')[];
779
- };
780
- };
781
- /** Payload passed to list fetch functions. */
782
- type QueryFetchPayload<QueryPayload extends ValidPayload> = {
783
- /** Whether this request loads the first page or a later page. */type: 'load' | 'loadMore'; /** Query payload being fetched. */
784
- payload: QueryPayload; /** Offset used for offset-paginated fetches. */
785
- offset: number; /** Maximum number of items requested. */
786
- limit: number; /** Partial-resource fields requested for each item in the fetched query. */
787
- fields?: string[];
788
- };
789
- /** Options for offset-based list pagination. */
790
- type OffsetPaginationConfig = {
791
- /** Largest item count requested when refetching invalidated offset queries. */maxInvalidationLimit: number; /** Max parallel chunk requests during chunked invalidation (default: 3) */
792
- maxParallel?: number;
793
- };
794
- /** Partial-resource helpers used to merge and select field subsets. */
795
- type PartialResourcesConfig<ItemState extends ValidStoreState> = {
796
- /** Merges a partial fetch result into an existing item snapshot. */mergeItems: (prev: ItemState | undefined, fetched: ItemState) => ItemState; /** Returns an item containing only the requested fields. */
797
- selectFields: (fields: string[], item: ItemState) => ItemState;
798
- };
799
- type DerivedQuerySummary<QueryPayload extends ValidPayload> = {
800
- payload: QueryPayload;
801
- hasMore: boolean;
802
- itemCount: number;
803
- };
804
- type DerivedQueryItem<ItemState extends ValidStoreState> = {
805
- key: string;
806
- data: ItemState;
807
- };
808
- /** Why a derived query is currently being resolved. */
809
- type DerivedQuerySource = 'online' | 'offline' | 'sticky-offline';
810
- /** Runtime context passed to `derivedQueries.deriveQuery(...)`. */
811
- type DerivedQueryContext = {
812
- /** The requested hook fields for this query, when partial resources are enabled. */fields: FieldsInput | undefined; /** Whether the store is currently in offline mode. */
813
- isOfflineMode: boolean;
814
- /**
815
- * What caused derivation to run.
816
- * `sticky-offline` means a query that was derived offline is still sticking
817
- * to the local derived view after reconnect, until explicit invalidation.
818
- */
819
- deriveSource: DerivedQuerySource;
820
- };
821
- /** Configuration for deriving query membership from locally materialized items. */
822
- type DerivedQueriesConfig<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = {
823
- /** Extracts the domain/group key for a query payload. */getQueryGroup: (queryPayload: QueryPayload) => string; /** Extracts the domain/group key for a materialized item. */
824
- getItemGroup: (item: ItemState, itemPayload: ItemPayload) => string;
825
- /**
826
- * Returns whether the local data for the query group is complete enough to
827
- * derive from while online.
828
- */
829
- isComplete: (queryPayload: QueryPayload, context: {
830
- queries: DerivedQuerySummary<QueryPayload>[];
831
- }) => boolean;
832
- /**
833
- * Computes a derived ordered list of item keys for a query, or `false` to
834
- * fall back to the regular fetch/cache path. `context.fields` lets the
835
- * callback decide whether partial-resource queries should still derive.
836
- */
837
- deriveQuery: (queryPayload: QueryPayload, items: DerivedQueryItem<ItemState>[], context: DerivedQueryContext) => string[] | false;
838
- };
839
- /** Field option shape used by APIs that are conditional on `partialResources`. */
840
- type FieldsOption<HasPartialResources extends boolean> = HasPartialResources extends true ? {
841
- /**
842
- * Partial-resource fields to request.
843
- *
844
- * Pass `'*'` to fetch complete items. This option is required when
845
- * `partialResources` is enabled.
846
- */
847
- fields: FieldsInput;
848
- } : {
849
- /**
850
- * Partial-resource fields to request.
851
- *
852
- * Pass `'*'` to fetch complete items. This option is optional when
853
- * `partialResources` is not enabled.
854
- */
855
- fields?: FieldsInput;
856
- };
857
- //#endregion
858
633
  //#region src/listQueryStore/useMultipleItems.d.ts
859
634
  type UseMultipleItemsOptions<ItemState extends ValidStoreState, Selected> = {
860
635
  /** Maps each item before it is returned from the hook. */selector?: (data: ItemState | null, payload: ValidPayload | null) => Selected; /** Reads only from the current store state and never schedules fetches. */
@@ -1511,4 +1286,4 @@ declare function clearAllSessionStorage(sessionKey: string): Promise<void>;
1511
1286
  //#region src/persistentStorage/opfsOfflineUploadAdapter.d.ts
1512
1287
  declare const opfsOfflineUploadAdapter: OfflineUploadAdapter;
1513
1288
  //#endregion
1514
- export { type AsyncStorageAdapter, type AsyncStorageDiscoveredScope, type AsyncStorageDriver, type AsyncStorageDriverSetEntry, type AsyncStorageMetadataOrder, type AsyncStorageNamespaceCommitArgs, type AsyncStorageNamespaceCommitTouch, type AsyncStorageNamespaceCommitUpsert, type AsyncStorageNamespaceGetResult, type AsyncStorageNamespaceHandle, type AsyncStorageNamespaceKind, type AsyncStorageNamespaceScope, type AsyncStorageReadOptions, type BlockWindowCloseHandler, CollectionItemStatus, type CollectionOfflineEntityRef, type CollectionOfflineOperationDefinition, type CollectionPersistentStorageConfig, CollectionStateCleanup, CollectionStore, CollectionStoreEvents, CollectionStoreOptions, CollectionStoreStoreEvents, CollectionUseMultipleItemsQuery, type ConvertedPersistentStorageDataSchema, type CreateStoreManagerOptions, type DefineCollectionOfflineOperations, type DefineDocumentOfflineOperations, type DefineListQueryOfflineOperations, type DefineOfflineOperation, type DerivedQueriesConfig, type DerivedQueryContext, type DerivedQuerySource, type DocumentOfflineOperationDefinition, type DocumentPersistentStorageConfig, DocumentStatus, DocumentStore, DocumentStoreOptions, DocumentStoreState, DocumentStoreStoreEvents, type DynamicRealtimeThrottleMs, type FetchListFnReturn, type FetchListFnReturnItem, type FieldsInput, type FieldsOption, GET_ALL, type GlobalOfflineEntity, type GlobalOfflineStatus, IsOffScreenContext, type ListQueryOfflineEntityRef, type ListQueryOfflineOperationDefinition, type ListQueryPersistentStorageConfig, type ListQueryStore, type ListQueryStoreEvents, type ListQueryStoreOptions, type ListQueryUseMultipleItemsQuery, type ListQueryUseMultipleListQueriesQuery, type MaybeTSDFResult, type MutationDebounce, type MutationSkipped, type OfflineAccumulationConfig, type OfflineAccumulationMergeContext, type OfflineConflictResolutionAction, type OfflineEntityMutationKind, type OfflineMutationDescriptor, type OfflineMutationInput, type OfflineMutationQueueingCause, type OfflineMutationQueueingConfig, type OfflineMutationQueueingPolicy, type OfflineMutationResult, type OfflineMutationUploadsInput, type OfflineOperationKind, type OfflineOperationUploadsContext, type OfflineQueueEntry, type OfflineReplayRetryConfig, type OfflineResolutionAction, type OfflineResolutionActionForOperation, type OfflineResolutionConflictParseError, type OfflineResolutionConflictParseErrorCode, type OfflineResolutionRecord, type OfflineResolutionRecordForOperation, type OfflineResolutionRecordForStore, type OfflineRetryExhaustedResolutionAction, type OfflineRuntimeConfig, type OfflineRuntimeConfigUpdate, type OfflineSession, type OfflineSessionConfig, type OfflineSessionUploadsConfig, type OfflineStoredUploadRecord, type OfflineSupersedeConfig, type OfflineSyncState, type OfflineTempEntitiesConfig, type OfflineTempEntitiesReconciliation, type OfflineTempEntityConfig, type OfflineTempEntityPendingEntry, type OfflineUpload, type OfflineUploadAdapter, type OfflineUploadProgress, type OfflineUploadSource, type OfflineUploadState, type OfflineUploadTransportContext, type OffsetPaginationConfig, OnCollectionItemInvalidate, OnDocumentInvalidate, type OnListQueryInvalidate, type OnListQueryItemInvalidate, type OperationConflict, type OperationResult, type OptimisticListUpdate, type ParsedOfflineResolutionConflictResultForOperation, type PartialResourcesConfig, type PayloadDebounce, type PersistentStorageBaseConfig, type PersistentStorageDataSchema, type PersistentStoragePreloadResult, type PersistentStorageSchema, type QueryFetchPayload, type QueryStatus, type StorageAdapter, type StoreError, StoreFetchError, type StoreManager, StoreMutationError, type StoreMutationErrorOptions, type TSDFDebugLogArea, type TSDFDebugLogEntry, type TSDFDebugLogLevel, type TSDFDebugLogger, type TSDFDebugOptions, type TSDFItemQuery, type TSDFStatus, TSDFUseDocumentReturn, TSFDCollectionItem, TSFDCollectionState, type TSFDListQuery, type TSFDListQueryState, TSFDUseCollectionItemReturn, type TSFDUseListItemReturn, type TSFDUseListQueryReturn, type TSFDUsePendingOfflineItemsReturn, type ValidPayload, type ValidStoreState, clearAllSessionStorage, clearSessionStorage, createCollectionStore, createDocumentStore, createListQueryStore, createStoreManager, defaultOfflineRuntimeConfig, fetchTypePriority, getGlobalOfflineEntities, getGlobalOfflineResolutions, getGlobalOfflineStatus, localPersistentStorage, mutationSkipped, opfsOfflineUploadAdapter, useGlobalOfflineEntities, useGlobalOfflineResolutions, useGlobalOfflineStatus };
1289
+ export { type AsyncStorageAdapter, type AsyncStorageDiscoveredScope, type AsyncStorageDriver, type AsyncStorageDriverSetEntry, type AsyncStorageMetadataOrder, type AsyncStorageNamespaceCommitArgs, type AsyncStorageNamespaceCommitTouch, type AsyncStorageNamespaceCommitUpsert, type AsyncStorageNamespaceGetResult, type AsyncStorageNamespaceHandle, type AsyncStorageNamespaceKind, type AsyncStorageNamespaceScope, type AsyncStorageReadOptions, type BlockWindowCloseHandler, CollectionItemStatus, type CollectionOfflineEntityRef, type CollectionOfflineOperationDefinition, type CollectionPersistentStorageConfig, CollectionStateCleanup, CollectionStore, CollectionStoreEvents, CollectionStoreOptions, CollectionStoreStoreEvents, CollectionUseMultipleItemsQuery, type ConvertedPersistentStorageDataSchema, type CreateStoreManagerOptions, type DefineCollectionOfflineOperations, type DefineDocumentOfflineOperations, type DefineListQueryOfflineOperations, type DefineOfflineOperation, type DerivedQueriesConfig, type DerivedQueryContext, type DerivedQuerySource, type DocumentOfflineOperationDefinition, type DocumentPersistentStorageConfig, DocumentStatus, DocumentStore, DocumentStoreOptions, DocumentStoreState, DocumentStoreStoreEvents, type DynamicRealtimeThrottleMs, type FetchListFnReturn, type FetchListFnReturnItem, type FieldsInput, type FieldsOption, GET_ALL, type GlobalOfflineEntity, type GlobalOfflineStatus, IsOffScreenContext, type ListQueryOfflineEntityRef, type ListQueryOfflineOperationDefinition, type ListQueryPersistentStorageConfig, type ListQueryStore, type ListQueryStoreEvents, type ListQueryStoreOptions, type ListQueryUseMultipleItemsQuery, type ListQueryUseMultipleListQueriesQuery, type MaybeTSDFResult, type MutationDebounce, type MutationSkipped, type OfflineAccumulationConfig, type OfflineAccumulationMergeContext, type OfflineConflictResolutionAction, type OfflineEntityMutationKind, type OfflineMutationDescriptor, type OfflineMutationInput, type OfflineMutationQueueingCause, type OfflineMutationQueueingConfig, type OfflineMutationQueueingPolicy, type OfflineMutationResult, type OfflineMutationUploadsInput, type OfflineOperationKind, type OfflineOperationUploadsContext, type OfflineQueueEntry, type OfflineReplayRetryConfig, type OfflineResolutionAction, type OfflineResolutionActionForOperation, type OfflineResolutionConflictParseError, type OfflineResolutionConflictParseErrorCode, type OfflineResolutionRecord, type OfflineResolutionRecordForOperation, type OfflineResolutionRecordForStore, type OfflineRetryExhaustedResolutionAction, type OfflineRuntimeConfig, type OfflineRuntimeConfigUpdate, type OfflineSession, type OfflineSessionConfig, type OfflineSessionUploadsConfig, type OfflineStoredUploadRecord, type OfflineSupersedeConfig, type OfflineSyncState, type OfflineTempEntitiesConfig, type OfflineTempEntitiesReconciliation, type OfflineTempEntityConfig, type OfflineTempEntityPendingEntry, type OfflineUpload, type OfflineUploadAdapter, type OfflineUploadProgress, type OfflineUploadSource, type OfflineUploadState, type OfflineUploadTransportContext, type OffsetPaginationConfig, OnCollectionItemInvalidate, OnDocumentInvalidate, type OnListQueryInvalidate, type OnListQueryItemInvalidate, type OperationConflict, type OperationResult, type OptimisticListUpdate, type ParsedOfflineResolutionConflictResultForOperation, type PartialResourcesConfig, type PayloadDebounce, type PersistentStorageBaseConfig, type PersistentStorageDataSchema, type PersistentStoragePreloadResult, type PersistentStorageSchema, type QueryFetchPayload, type QueryStatus, type StorageAdapter, type StoreError, StoreFetchError, type StoreManager, StoreMutationError, type StoreMutationErrorOptions, type TSDFDebugLogArea, type TSDFDebugLogEntry, type TSDFDebugLogLevel, type TSDFDebugLogger, type TSDFFocusDebugOperation, type TSDFItemQuery, type TSDFLoggerOptions, type TSDFStatus, TSDFUseDocumentReturn, TSFDCollectionItem, TSFDCollectionState, type TSFDListQuery, type TSFDListQueryState, TSFDUseCollectionItemReturn, type TSFDUseListItemReturn, type TSFDUseListQueryReturn, type TSFDUsePendingOfflineItemsReturn, type ValidPayload, type ValidStoreState, clearAllSessionStorage, clearSessionStorage, createCollectionStore, createDocumentStore, createListQueryStore, createStoreManager, defaultOfflineRuntimeConfig, fetchTypePriority, getGlobalOfflineEntities, getGlobalOfflineResolutions, getGlobalOfflineStatus, localPersistentStorage, mutationSkipped, opfsOfflineUploadAdapter, useGlobalOfflineEntities, useGlobalOfflineResolutions, useGlobalOfflineStatus };