tsdf 17.0.0-alpha.11 → 17.0.0-alpha.12

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-BMYAF6rt.js";
1
+ import { t as createAsyncStorageAdapter } from "./asyncStorageAdapter-CYxABChu.js";
2
2
  export { createAsyncStorageAdapter };
@@ -1,4 +1,4 @@
1
- import { r as AsyncStorageDriver, t as AsyncStorageAdapter } from "./types-2zQlbxtw.js";
1
+ import { r as AsyncStorageDriver, t as AsyncStorageAdapter } from "./types-DqUm_Sv7.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-2zQlbxtw.js";
1
+ import { t as AsyncStorageAdapter } from "./types-DqUm_Sv7.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, 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, 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, Zt as TSDFFocusDebugOperation, _ 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-DqUm_Sv7.js";
2
2
  import { __LEGIT_ANY__ } from "@ls-stack/utils/saferTyping";
3
3
  import { Emitter } from "evtmitter";
4
4
  import { Context } from "react";
@@ -38,7 +38,8 @@ type DynamicRealtimeThrottleMs = (params: {
38
38
  }) => number;
39
39
  type StoreManagerStoreDefaults = {
40
40
  /** 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. */
41
+ readonly baseCoalescingWindowMs: number; /** Extra browser-tab coalescing delay applied only while a tab is in the background. */
42
+ readonly backgroundCoalescingDelayMs: number; /** Default adaptive throttle for real-time updates in attached stores. */
42
43
  readonly dynamicRealtimeThrottleMs: DynamicRealtimeThrottleMs; /** Shared window-close blocker used by mutations in attached stores. */
43
44
  readonly blockWindowClose: BlockWindowCloseHandler | null; /** Default focus revalidation policy for attached stores. */
44
45
  readonly revalidateOnWindowFocus: boolean | (() => boolean) | undefined;
@@ -72,7 +73,7 @@ type StoreManagerOfflineApi<TUploadRef extends ValidPayload = ValidPayload> = {
72
73
  };
73
74
  /** Shared coordinator passed to every TSDF store instance in an app/session. */
74
75
  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
+ /** Returns the active shared session / tenant key. */getSessionKey: () => string | false; /** Shared debug logger for browser-tab sync, focus lifecycle, and persistent storage internals. */
76
77
  debugLogger?: TSDFDebugLogger; /** Normalizes raw exceptions into the shared StoreError shape. */
77
78
  errorNormalizer: (exception: Error) => StoreError; /** Global fallback for persistent storage failures in attached stores. */
78
79
  onPersistentStorageError: PersistentStorageErrorHandler | undefined; /** Global fallback for mutation failures in attached stores. */
@@ -90,16 +91,17 @@ type CreateStoreManagerOptions<TUploadRef extends ValidPayload = ValidPayload> =
90
91
  * behavior while no account is loaded.
91
92
  */
92
93
  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. */
94
+ errorNormalizer: (exception: Error) => StoreError; /** Default minimum interval between low-priority fetches for attached stores. Defaults to 40 minutes. */
95
+ lowPriorityThrottleMs?: number; /** Default coalescing window for attached stores. Defaults to 16ms. */
96
+ baseCoalescingWindowMs?: number; /** Extra browser-tab coalescing delay applied only while a tab is in the background. Defaults to 3000ms. */
97
+ backgroundCoalescingDelayMs?: number; /** Default adaptive throttle for real-time updates in attached stores. Store-level values override it. */
96
98
  dynamicRealtimeThrottleMs?: DynamicRealtimeThrottleMs; /** Shared window-close blocker used by mutations in attached stores. Pass `null` to disable. */
97
99
  blockWindowClose?: BlockWindowCloseHandler | null; /** Global fallback for persistent storage failures when a store does not provide its own handler. */
98
100
  onPersistentStorageError?: PersistentStorageErrorHandler; /** Global fallback for mutation failures when a store does not provide its own handler. */
99
101
  onMutationError?: StoreManagerMutationErrorHandler; /** Default focus revalidation policy for attached stores. Store-level values override it. */
100
102
  revalidateOnWindowFocus?: boolean | (() => boolean);
101
103
  /**
102
- * Enables debug logs for browser-tab sync and persistent storage operations.
104
+ * Enables debug logs for browser-tab sync, focus revalidation, and persistent storage operations.
103
105
  * Pass `true` to use console logging, or pass a logger function.
104
106
  */
105
107
  debug?: TSDFDebugOptions; /** Optional shared offline session config for every attached store. */
@@ -1511,4 +1513,4 @@ declare function clearAllSessionStorage(sessionKey: string): Promise<void>;
1511
1513
  //#region src/persistentStorage/opfsOfflineUploadAdapter.d.ts
1512
1514
  declare const opfsOfflineUploadAdapter: OfflineUploadAdapter;
1513
1515
  //#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 };
1516
+ 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 TSDFFocusDebugOperation, 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 };
package/dist/main.js CHANGED
@@ -3017,6 +3017,7 @@ function captureOfflineOverlayEntries(overlayStore, itemKeys, createOverlay) {
3017
3017
  //#endregion
3018
3018
  //#region src/utils/browserTabsPriority.ts
3019
3019
  const DEFAULT_FETCH_LEASE_MS = 1e4;
3020
+ const DEFAULT_BACKGROUND_COALESCING_DELAY_MS$1 = 3e3;
3020
3021
  const COALESCING_WINDOW_STEP_MS = 1e3;
3021
3022
  /** @internal */
3022
3023
  function createBrowserTabsPriority(transportEnabled, getIsEnabled, tabId, getWindowIsFocused, onWindowFocusChange, publishStatus, timings, onLeaderChange) {
@@ -3112,7 +3113,7 @@ function createBrowserTabsPriority(transportEnabled, getIsEnabled, tabId, getWin
3112
3113
  if (baseCoalescingWindowMs <= 0) return baseCoalescingWindowMs;
3113
3114
  const coalescingRank = getCoalescingRank();
3114
3115
  if (coalescingRank <= 0) return baseCoalescingWindowMs;
3115
- return baseCoalescingWindowMs + coalescingRank * COALESCING_WINDOW_STEP_MS;
3116
+ return baseCoalescingWindowMs + Math.max(0, timings?.backgroundCoalescingDelayMs ?? DEFAULT_BACKGROUND_COALESCING_DELAY_MS$1) + (coalescingRank - 1) * COALESCING_WINDOW_STEP_MS;
3116
3117
  }
3117
3118
  function onTabStatusMessage(remoteTabId, message) {
3118
3119
  if (!getIsEnabled()) return;
@@ -7504,8 +7505,9 @@ var RequestScheduler = class {
7504
7505
  };
7505
7506
  //#endregion
7506
7507
  //#region src/storeManager.ts
7507
- const DEFAULT_LOW_PRIORITY_THROTTLE_MS = 5;
7508
- const DEFAULT_BASE_COALESCING_WINDOW_MS = 10;
7508
+ const DEFAULT_LOW_PRIORITY_THROTTLE_MS = 2400 * 1e3;
7509
+ const DEFAULT_BASE_COALESCING_WINDOW_MS = 16;
7510
+ const DEFAULT_BACKGROUND_COALESCING_DELAY_MS = 3e3;
7509
7511
  function defaultDynamicRealtimeThrottleMs({ windowIsNotFocused }) {
7510
7512
  return windowIsNotFocused ? 1e3 : 100;
7511
7513
  }
@@ -7600,6 +7602,7 @@ function createStoreManager(options) {
7600
7602
  storeDefaults: Object.freeze({
7601
7603
  lowPriorityThrottleMs: options.lowPriorityThrottleMs ?? DEFAULT_LOW_PRIORITY_THROTTLE_MS,
7602
7604
  baseCoalescingWindowMs: options.baseCoalescingWindowMs ?? DEFAULT_BASE_COALESCING_WINDOW_MS,
7605
+ backgroundCoalescingDelayMs: options.backgroundCoalescingDelayMs ?? DEFAULT_BACKGROUND_COALESCING_DELAY_MS,
7603
7606
  dynamicRealtimeThrottleMs: options.dynamicRealtimeThrottleMs ?? defaultDynamicRealtimeThrottleMs,
7604
7607
  blockWindowClose: options.blockWindowClose ?? null,
7605
7608
  revalidateOnWindowFocus: options.revalidateOnWindowFocus
@@ -7654,7 +7657,10 @@ function getOrCreateStoreManagerBrowserTabsPresence(storeManager, options) {
7654
7657
  onWindowFocusChange: options.onWindowFocusChange,
7655
7658
  transportFactory: options.transportFactory,
7656
7659
  ...import.meta.env.DEV ? { debugLogger: storeManager.debugLogger } : void 0,
7657
- priorityTimings: options.priorityTimings
7660
+ priorityTimings: {
7661
+ backgroundCoalescingDelayMs: storeManager.storeDefaults.backgroundCoalescingDelayMs,
7662
+ ...options.priorityTimings
7663
+ }
7658
7664
  });
7659
7665
  return {
7660
7666
  priority: presence.priority,
@@ -7707,7 +7713,7 @@ async function performMutationWithLifecycle(startMutation, mutation, onError, op
7707
7713
  //#endregion
7708
7714
  //#region src/utils/storeFocusLifecycle.ts
7709
7715
  /** @internal */
7710
- function createStoreFocusLifecycle(revalidateOnWindowFocus, usesRealTimeUpdates, transportReconnectCooldownMs, getWindowIsFocused, onWindowFocus, onWindowFocusRevalidate, onTransportReconnectRevalidate) {
7716
+ function createStoreFocusLifecycle(revalidateOnWindowFocus, usesRealTimeUpdates, transportReconnectCooldownMs, getWindowIsFocused, onWindowFocus, onWindowFocusRevalidate, onTransportReconnectRevalidate, debug) {
7711
7717
  let cleanupFocusListener = null;
7712
7718
  let cleanupReconnectFocusListener = null;
7713
7719
  let reconnectCooldownTimeoutId = null;
@@ -7727,6 +7733,19 @@ function createStoreFocusLifecycle(revalidateOnWindowFocus, usesRealTimeUpdates,
7727
7733
  if (typeof revalidateOnWindowFocus === "function") return revalidateOnWindowFocus();
7728
7734
  return !!revalidateOnWindowFocus;
7729
7735
  }
7736
+ const logWindowFocusRevalidate = import.meta.env.DEV && debug?.debugLogger ? (message, details) => {
7737
+ emitTSDFDebugLog(debug.debugLogger, {
7738
+ area: "focus",
7739
+ level: "log",
7740
+ message,
7741
+ operation: "window-focus-revalidate",
7742
+ details: {
7743
+ storeId: debug.storeId,
7744
+ storeType: debug.storeType,
7745
+ ...details
7746
+ }
7747
+ });
7748
+ } : void 0;
7730
7749
  function runTransportReconnectRevalidate() {
7731
7750
  lastTransportReconnectRevalidateAt = Date.now();
7732
7751
  onTransportReconnectRevalidate();
@@ -7765,9 +7784,28 @@ function createStoreFocusLifecycle(revalidateOnWindowFocus, usesRealTimeUpdates,
7765
7784
  clearReconnectCooldownTimeout();
7766
7785
  hasPendingReconnectRevalidateOnFocus = false;
7767
7786
  lastTransportReconnectRevalidateAt = Number.NEGATIVE_INFINITY;
7768
- if (!revalidateOnWindowFocus || usesRealTimeUpdates) return;
7787
+ if (!revalidateOnWindowFocus) return;
7788
+ if (usesRealTimeUpdates) {
7789
+ logWindowFocusRevalidate?.("window focus revalidation skipped", {
7790
+ reason: "real-time-updates",
7791
+ status: "skipped"
7792
+ });
7793
+ return;
7794
+ }
7769
7795
  cleanupFocusListener = onWindowFocus(() => {
7770
- if (isFocusRevalidationEnabled()) onWindowFocusRevalidate();
7796
+ if (!isFocusRevalidationEnabled()) {
7797
+ logWindowFocusRevalidate?.("window focus revalidation skipped", {
7798
+ policy: "dynamic",
7799
+ reason: "dynamic-disabled",
7800
+ status: "skipped"
7801
+ });
7802
+ return;
7803
+ }
7804
+ logWindowFocusRevalidate?.("window focus revalidation triggered", {
7805
+ policy: typeof revalidateOnWindowFocus === "function" ? "dynamic" : "enabled",
7806
+ status: "triggered"
7807
+ });
7808
+ onWindowFocusRevalidate();
7771
7809
  });
7772
7810
  }
7773
7811
  function dispose() {
@@ -9176,7 +9214,11 @@ function createCollectionStore(storeOptions) {
9176
9214
  invalidateItem(() => true, "lowPriority");
9177
9215
  }, () => {
9178
9216
  invalidateItem(() => true, "realtimeUpdate");
9179
- });
9217
+ }, import.meta.env.DEV ? {
9218
+ debugLogger: storeManager.debugLogger,
9219
+ storeId: id,
9220
+ storeType: "collection"
9221
+ } : void 0);
9180
9222
  const { enforceCacheLimits } = createCollectionCacheLimits(store, maxItems, itemCacheRuntime, isProtectedFromEviction, cleanupItemResources, onStateCleanup);
9181
9223
  const cacheLimitEnforcementScheduler = createIdleThrottledScheduler(CACHE_LIMIT_ENFORCEMENT_THROTTLE_MS, enforceCacheLimits);
9182
9224
  function scheduleCacheLimitEnforcement() {
@@ -9802,7 +9844,11 @@ function createDocumentStore(storeOptions) {
9802
9844
  invalidateData("lowPriority");
9803
9845
  }, () => {
9804
9846
  invalidateData("realtimeUpdate");
9805
- });
9847
+ }, import.meta.env.DEV ? {
9848
+ debugLogger: storeManager.debugLogger,
9849
+ storeId: id,
9850
+ storeType: "document"
9851
+ } : void 0);
9806
9852
  persistence?.attach(store);
9807
9853
  initializeOfflineStoreController(offlineController);
9808
9854
  function scheduleFetch(fetchType, options) {
@@ -15269,7 +15315,11 @@ function createListQueryStore(storeOptions) {
15269
15315
  all: true,
15270
15316
  type: "realtimeUpdate"
15271
15317
  });
15272
- });
15318
+ }, import.meta.env.DEV ? {
15319
+ debugLogger: storeManager.debugLogger,
15320
+ storeId: id,
15321
+ storeType: "listQuery"
15322
+ } : void 0);
15273
15323
  const { enforceCacheLimits } = createListQueryCacheLimits(store, maxItems, maxQueries, itemCacheRuntime, queryCacheRuntime, isQueryProtectedFromEviction, isStandaloneItemProtectedFromEviction, cleanupItemStateMetadata, cleanupQueryStateMetadata, deleteQueryFetchResources, deleteItemFetchResources, onStateCleanup);
15274
15324
  const cacheLimitEnforcementScheduler = createIdleThrottledScheduler(CACHE_LIMIT_ENFORCEMENT_THROTTLE_MS, enforceCacheLimits);
15275
15325
  function scheduleCacheLimitEnforcement() {
@@ -1,2 +1,2 @@
1
- import { t as opfsPersistentStorage } from "./opfsPersistentStorage-CBnUebnf.js";
1
+ import { t as opfsPersistentStorage } from "./opfsPersistentStorage-C6KKLdos.js";
2
2
  export { opfsPersistentStorage };
@@ -1,4 +1,4 @@
1
- import { t as AsyncStorageAdapter } from "./types-2zQlbxtw.js";
1
+ import { t as AsyncStorageAdapter } from "./types-DqUm_Sv7.js";
2
2
 
3
3
  //#region src/persistentStorage/opfsPersistentStorage.d.ts
4
4
  declare const opfsPersistentStorage: AsyncStorageAdapter;
@@ -7,7 +7,9 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
7
7
  /** Debug log severity used to choose the default console method. */
8
8
  type TSDFDebugLogLevel = 'log' | 'warn' | 'error';
9
9
  /** Internal subsystem that emitted a debug log entry. */
10
- type TSDFDebugLogArea = 'browser-tabs' | 'persistent-storage';
10
+ type TSDFDebugLogArea = 'browser-tabs' | 'focus' | 'persistent-storage';
11
+ /** Operations emitted by focus lifecycle handling. */
12
+ type TSDFFocusDebugOperation = 'window-focus-revalidate';
11
13
  /** Operations emitted by the persistent storage subsystem. */
12
14
  type TSDFPersistentStorageDebugOperation = 'clear' | 'commit' | 'list-keys' | 'list-metadata' | 'list-metadata-by-filter' | 'load' | 'load-many' | 'read-entry' | 'read-protected-keys' | 'remove' | 'save' | 'schedule-save' | 'sync-load' | 'sync-protected-keys' | 'write';
13
15
  /** Operations emitted by the browser-tab sync subsystem. */
@@ -17,7 +19,7 @@ type TSDFDebugLogEntry = {
17
19
  /** Subsystem that emitted the entry. */area: TSDFDebugLogArea; /** Severity of the entry. */
18
20
  level: TSDFDebugLogLevel; /** Human-readable summary of the operation. */
19
21
  message: string; /** Stable operation id, such as `publish`, `load`, or `write`. */
20
- operation: TSDFPersistentStorageDebugOperation | TSDFBrowserTabsDebugOperation; /** Structured operation metadata for filtering and diagnostics. */
22
+ operation: TSDFFocusDebugOperation | TSDFPersistentStorageDebugOperation | TSDFBrowserTabsDebugOperation; /** Structured operation metadata for filtering and diagnostics. */
21
23
  details?: Readonly<Record<string, unknown>>;
22
24
  };
23
25
  /** Custom debug logger invoked for each emitted TSDF debug entry. */
@@ -1472,4 +1474,4 @@ type ListQueryPersistentStorageFields<QueryPayload extends ValidPayload, ItemPay
1472
1474
  /** Persistent storage config for ListQueryStore. */
1473
1475
  type ListQueryPersistentStorageConfig<ItemState extends ValidStoreState, QueryPayload extends ValidPayload = ValidPayload, ItemPayload extends ValidPayload = ValidPayload, StorageState = unknown, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload> = null> = StorePersistentStorageBaseConfig<ItemState, StorageState> & PublicStoreOfflineConfigField<TOfflineOperations> & ListQueryPersistentStorageFields<QueryPayload, ItemPayload>;
1474
1476
  //#endregion
1475
- export { OfflineResolutionRecord as $, DefineListQueryOfflineOperations as A, PayloadDebounce as At, OfflineEntityMutationKind as B, mutationSkipped as Bt, PersistentStorageSchema as C, OfflineUploadAdapter as Ct, CollectionOfflineOperationDefinition as D, OfflineUploadTransportContext as Dt, CollectionOfflineEntityRef as E, OfflineUploadState as Et, ListQueryOfflineEntityRef as F, TSDFStatus as Ft, OfflineMutationQueueingPolicy as G, ScheduleFetchResults as Gt, OfflineMutationInput as H, RequestSchedulerEventData as Ht, ListQueryOfflineOperationDefinition as I, UnwrapTSDFResult as It, OfflineReplayRetryConfig as J, TSDFDebugLogLevel as Jt, OfflineOperationKind as K, TSDFDebugLogArea as Kt, OfflineAccumulationConfig as L, ValidPayload as Lt, DocumentOfflineOperationDefinition as M, StoreFetchError as Mt, GlobalOfflineEntity as N, StoreMutationError as Nt, DefineCollectionOfflineOperations as O, MaybeTSDFResult as Ot, GlobalOfflineStatus as P, StoreMutationErrorOptions as Pt, OfflineResolutionConflictParseErrorCode as Q, OfflineAccumulationMergeContext as R, ValidStoreState as Rt, PersistentStoragePreloadResult as S, OfflineUpload as St, AnyOfflineOperationDefinition as T, OfflineUploadSource as Tt, OfflineMutationQueueingCause as U, RequestSchedulerEvents as Ut, OfflineMutationDescriptor as V, FetchType as Vt, OfflineMutationQueueingConfig as W, ScheduleFetchOptions as Wt, OfflineResolutionActionForOperation as X, TSDFDebugOptions as Xt, OfflineResolutionAction as Y, TSDFDebugLogger as Yt, OfflineResolutionConflictParseError as Z, ListQueryOfflineOperationsConfig as _, defaultOfflineRuntimeConfig as _t, AsyncStorageMetadataOrder as a, OfflineSession as at, PersistentStorageDataSchema as b, OfflineSessionUploadsConfig as bt, AsyncStorageNamespaceCommitUpsert as c, OfflineSyncState as ct, AsyncStorageNamespaceKind as d, OfflineTempEntityConfig as dt, OfflineResolutionRecordForOperation as et, AsyncStorageNamespaceScope as f, OfflineTempEntityPendingEntry as ft, DocumentPersistentStorageConfig as g, ParsedOfflineResolutionConflictResultForStore as gt, ConvertedPersistentStorageDataSchema as h, ParsedOfflineResolutionConflictResultForOperation as ht, AsyncStorageDriverSetEntry as i, OfflineRuntimeConfigUpdate as it, DefineOfflineOperation as j, StoreError as jt, DefineDocumentOfflineOperations as k, MutationSkipped as kt, AsyncStorageNamespaceGetResult as l, OfflineTempEntitiesConfig as lt, CollectionPersistentStorageConfig as m, OperationResult as mt, AsyncStorageDiscoveredScope as n, OfflineRetryExhaustedResolutionAction as nt, AsyncStorageNamespaceCommitArgs as o, OfflineSessionConfig as ot, AsyncStorageReadOptions as p, OperationConflict as pt, OfflineQueueEntry as q, TSDFDebugLogEntry as qt, AsyncStorageDriver as r, OfflineRuntimeConfig as rt, AsyncStorageNamespaceCommitTouch as s, OfflineSupersedeConfig as st, AsyncStorageAdapter as t, OfflineResolutionRecordForStore as tt, AsyncStorageNamespaceHandle as u, OfflineTempEntitiesReconciliation as ut, ListQueryPersistentStorageConfig as v, OfflineMutationUploadsInput as vt, StorageAdapter as w, OfflineUploadProgress as wt, PersistentStorageErrorHandler as x, OfflineStoredUploadRecord as xt, PersistentStorageBaseConfig as y, OfflineOperationUploadsContext as yt, OfflineConflictResolutionAction as z, fetchTypePriority as zt };
1477
+ export { OfflineResolutionRecord as $, DefineListQueryOfflineOperations as A, PayloadDebounce as At, OfflineEntityMutationKind as B, mutationSkipped as Bt, PersistentStorageSchema as C, OfflineUploadAdapter as Ct, CollectionOfflineOperationDefinition as D, OfflineUploadTransportContext as Dt, CollectionOfflineEntityRef as E, OfflineUploadState as Et, ListQueryOfflineEntityRef as F, TSDFStatus as Ft, OfflineMutationQueueingPolicy as G, ScheduleFetchResults as Gt, OfflineMutationInput as H, RequestSchedulerEventData as Ht, ListQueryOfflineOperationDefinition as I, UnwrapTSDFResult as It, OfflineReplayRetryConfig as J, TSDFDebugLogLevel as Jt, OfflineOperationKind as K, TSDFDebugLogArea as Kt, OfflineAccumulationConfig as L, ValidPayload as Lt, DocumentOfflineOperationDefinition as M, StoreFetchError as Mt, GlobalOfflineEntity as N, StoreMutationError as Nt, DefineCollectionOfflineOperations as O, MaybeTSDFResult as Ot, GlobalOfflineStatus as P, StoreMutationErrorOptions as Pt, OfflineResolutionConflictParseErrorCode as Q, OfflineAccumulationMergeContext as R, ValidStoreState as Rt, PersistentStoragePreloadResult as S, OfflineUpload as St, AnyOfflineOperationDefinition as T, OfflineUploadSource as Tt, OfflineMutationQueueingCause as U, RequestSchedulerEvents as Ut, OfflineMutationDescriptor as V, FetchType as Vt, OfflineMutationQueueingConfig as W, ScheduleFetchOptions as Wt, OfflineResolutionActionForOperation as X, TSDFDebugOptions as Xt, OfflineResolutionAction as Y, TSDFDebugLogger as Yt, OfflineResolutionConflictParseError as Z, TSDFFocusDebugOperation as Zt, ListQueryOfflineOperationsConfig as _, defaultOfflineRuntimeConfig as _t, AsyncStorageMetadataOrder as a, OfflineSession as at, PersistentStorageDataSchema as b, OfflineSessionUploadsConfig as bt, AsyncStorageNamespaceCommitUpsert as c, OfflineSyncState as ct, AsyncStorageNamespaceKind as d, OfflineTempEntityConfig as dt, OfflineResolutionRecordForOperation as et, AsyncStorageNamespaceScope as f, OfflineTempEntityPendingEntry as ft, DocumentPersistentStorageConfig as g, ParsedOfflineResolutionConflictResultForStore as gt, ConvertedPersistentStorageDataSchema as h, ParsedOfflineResolutionConflictResultForOperation as ht, AsyncStorageDriverSetEntry as i, OfflineRuntimeConfigUpdate as it, DefineOfflineOperation as j, StoreError as jt, DefineDocumentOfflineOperations as k, MutationSkipped as kt, AsyncStorageNamespaceGetResult as l, OfflineTempEntitiesConfig as lt, CollectionPersistentStorageConfig as m, OperationResult as mt, AsyncStorageDiscoveredScope as n, OfflineRetryExhaustedResolutionAction as nt, AsyncStorageNamespaceCommitArgs as o, OfflineSessionConfig as ot, AsyncStorageReadOptions as p, OperationConflict as pt, OfflineQueueEntry as q, TSDFDebugLogEntry as qt, AsyncStorageDriver as r, OfflineRuntimeConfig as rt, AsyncStorageNamespaceCommitTouch as s, OfflineSupersedeConfig as st, AsyncStorageAdapter as t, OfflineResolutionRecordForStore as tt, AsyncStorageNamespaceHandle as u, OfflineTempEntitiesReconciliation as ut, ListQueryPersistentStorageConfig as v, OfflineMutationUploadsInput as vt, StorageAdapter as w, OfflineUploadProgress as wt, PersistentStorageErrorHandler as x, OfflineStoredUploadRecord as xt, PersistentStorageBaseConfig as y, OfflineOperationUploadsContext as yt, OfflineConflictResolutionAction as z, fetchTypePriority as zt };
package/docs/README.md CHANGED
@@ -50,8 +50,8 @@ const storeManager = createStoreManager({
50
50
  id: 'fetch-error',
51
51
  message: err.message,
52
52
  }),
53
- lowPriorityThrottleMs: 5,
54
- baseCoalescingWindowMs: 10,
53
+ lowPriorityThrottleMs: 40 * 60 * 1_000,
54
+ baseCoalescingWindowMs: 16,
55
55
  blockWindowClose: null,
56
56
  revalidateOnWindowFocus: true,
57
57
  onMutationError: (error) => {
@@ -24,7 +24,7 @@ Tabs use a versioned message model so later snapshots do not overwrite fresher r
24
24
 
25
25
  - Tab status messages include focus and presence timestamp data.
26
26
  - Focused tabs keep the base `baseCoalescingWindowMs`.
27
- - Background tabs are ranked and may receive an extended coalescing window (`base` + rank \* `1000ms`), which helps avoid duplicate background refetch work.
27
+ - Background tabs are ranked and may receive an extended coalescing window (`base` + `backgroundCoalescingDelayMs` + background rank \* `1000ms`), which helps avoid duplicate background refetch work. The first background tab uses rank `0`, so the default first background window is `base + 3000ms`.
28
28
  - `fetch-start` messages let sibling tabs drop duplicate scheduled work when another tab is already fetching the same request IDs.
29
29
  - Confirmed snapshots from one tab are only applied to others when remote ordering says they are newer than the current version.
30
30
 
@@ -47,6 +47,7 @@ const storeManager = createStoreManager({
47
47
  return isLoggedIn ? `tenant:${tenantId}` : false;
48
48
  },
49
49
  errorNormalizer: normalizeError,
50
+ backgroundCoalescingDelayMs: 3_000,
50
51
  });
51
52
 
52
53
  const store = createDocumentStore({
@@ -14,8 +14,8 @@ const storeManager = createStoreManager({
14
14
  getSessionKey: () =>
15
15
  authState.userId ? `tenant:${authState.tenantId}` : false,
16
16
  errorNormalizer: normalizeError,
17
- lowPriorityThrottleMs: 5,
18
- baseCoalescingWindowMs: 10,
17
+ lowPriorityThrottleMs: 40 * 60 * 1_000,
18
+ baseCoalescingWindowMs: 16,
19
19
  blockWindowClose: null,
20
20
  });
21
21
 
@@ -14,8 +14,8 @@ const storeManager = createStoreManager({
14
14
  getSessionKey: () =>
15
15
  authState.userId ? `tenant:${authState.tenantId}` : false,
16
16
  errorNormalizer: normalizeError,
17
- lowPriorityThrottleMs: 5,
18
- baseCoalescingWindowMs: 10,
17
+ lowPriorityThrottleMs: 40 * 60 * 1_000,
18
+ baseCoalescingWindowMs: 16,
19
19
  blockWindowClose: null,
20
20
  });
21
21
 
@@ -116,8 +116,8 @@ const storeManager = createStoreManager({
116
116
  getSessionKey: () =>
117
117
  authState.userId ? `tenant:${authState.tenantId}` : false,
118
118
  errorNormalizer: normalizeError,
119
- lowPriorityThrottleMs: 5,
120
- baseCoalescingWindowMs: 10,
119
+ lowPriorityThrottleMs: 40 * 60 * 1_000,
120
+ baseCoalescingWindowMs: 16,
121
121
  blockWindowClose: null,
122
122
  });
123
123
 
@@ -18,7 +18,7 @@ Every fetch request has a priority that determines its behavior:
18
18
  Low-priority fetches are throttled to avoid redundant requests:
19
19
 
20
20
  ```
21
- lowPriorityThrottleMs: 5
21
+ lowPriorityThrottleMs: 40 * 60 * 1_000
22
22
  ```
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.
@@ -28,14 +28,14 @@ If a hook mounts within the configured throttle window after the last fetch comp
28
28
  When multiple fetch requests arrive in a short window, they are coalesced into a single batch:
29
29
 
30
30
  ```
31
- baseCoalescingWindowMs: 10
31
+ baseCoalescingWindowMs: 16
32
32
  ```
33
33
 
34
34
  If three `useItem` hooks mount within the configured coalescing window, their fetches are grouped and executed as one request (when using batch fetching) or sequentially but without duplicate requests for the same item.
35
35
 
36
36
  ### Background Tabs
37
37
 
38
- When synced browser tabs are open, TSDF can extend coalescing internally for background tabs based on focus ranking. Focused tabs keep `baseCoalescingWindowMs`; background tabs may wait longer so duplicate background work can be dropped when another tab is already fetching the same data.
38
+ When synced browser tabs are open, TSDF can extend coalescing internally for background tabs based on focus ranking. Focused tabs keep `baseCoalescingWindowMs`; background tabs use `baseCoalescingWindowMs + backgroundCoalescingDelayMs + backgroundRank * 1000ms`, where the first background tab has rank `0`. This gives sibling tabs time to drop duplicate background work when another tab is already fetching the same data.
39
39
 
40
40
  See [Browser Tabs Sync](./browser-tabs-sync.md) for focus ranking and request deduplication behavior across tabs.
41
41
 
@@ -71,8 +71,9 @@ This is useful for background refetches that should yield to user-initiated acti
71
71
 
72
72
  | Option | Required | Description |
73
73
  | ----------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
74
- | `lowPriorityThrottleMs` | No | Manager default minimum interval between low-priority fetches, or a store-level override. Defaults to `5` |
75
- | `baseCoalescingWindowMs` | No | Manager default time window to group multiple requests into a single batch, or a store-level override. Defaults to `10` |
74
+ | `lowPriorityThrottleMs` | No | Manager default minimum interval between low-priority fetches, or a store-level override. Defaults to 40 minutes (`2_400_000ms`) |
75
+ | `baseCoalescingWindowMs` | No | Manager default time window to group multiple requests into a single batch, or a store-level override. Defaults to `16ms` |
76
+ | `backgroundCoalescingDelayMs` | No | Manager-level delay added only for background browser tabs before the per-rank `1000ms` step. Defaults to `3000ms` |
76
77
  | `mediumPriorityDelayMs` | No | Delay before medium-priority fetches execute |
77
78
  | `dynamicRealtimeThrottleMs` | No | Manager default or store override returning throttle duration for real-time updates. Built-in default: `100ms` focused, `1000ms` background. See [Real-Time Updates](./real-time-updates.md) |
78
79
  | `maxBatchSize` / `maxItemBatchSize` | No | Collection/ListQuery batch cap. List Query `maxItemBatchSize` defaults to `50`. Triggers immediate fetch when reached |
@@ -81,11 +82,14 @@ This is useful for background refetches that should yield to user-initiated acti
81
82
 
82
83
  ```ts
83
84
  {
84
- // Skip refetch if one happened in the last 5ms
85
- lowPriorityThrottleMs: 5,
85
+ // Skip refetch if one happened in the last 40 minutes
86
+ lowPriorityThrottleMs: 40 * 60 * 1_000,
86
87
 
87
- // Group fetches within 10ms
88
- baseCoalescingWindowMs: 10,
88
+ // Group fetches within 16ms
89
+ baseCoalescingWindowMs: 16,
90
+
91
+ // Add 3s before background browser-tab rank staggering
92
+ backgroundCoalescingDelayMs: 3_000,
89
93
 
90
94
  // Wait 300ms before executing medium-priority fetches
91
95
  mediumPriorityDelayMs: 300,
@@ -20,8 +20,8 @@ const storeManager = createStoreManager({
20
20
  getSessionKey: () =>
21
21
  authState.userId ? `tenant:${authState.tenantId}` : false,
22
22
  errorNormalizer: normalizeError,
23
- lowPriorityThrottleMs: 5,
24
- baseCoalescingWindowMs: 10,
23
+ lowPriorityThrottleMs: 40 * 60 * 1_000,
24
+ baseCoalescingWindowMs: 16,
25
25
  blockWindowClose: null,
26
26
  });
27
27
 
package/docs/offline.md CHANGED
@@ -34,8 +34,8 @@ type UserOfflineOperations = DefineListQueryOfflineOperations<
34
34
  const storeManager = createStoreManager({
35
35
  getSessionKey: () => currentTenantId ?? false,
36
36
  errorNormalizer: normalizeError,
37
- lowPriorityThrottleMs: 5,
38
- baseCoalescingWindowMs: 10,
37
+ lowPriorityThrottleMs: 40 * 60 * 1_000,
38
+ baseCoalescingWindowMs: 16,
39
39
  blockWindowClose: null,
40
40
  offlineSession: {
41
41
  network: { enabled: true },
@@ -137,8 +137,8 @@ They are **not** triggered by:
137
137
  const storeManager = createStoreManager({
138
138
  getSessionKey: () => currentTenantId ?? false,
139
139
  errorNormalizer: normalizeError,
140
- lowPriorityThrottleMs: 5,
141
- baseCoalescingWindowMs: 10,
140
+ lowPriorityThrottleMs: 40 * 60 * 1_000,
141
+ baseCoalescingWindowMs: 16,
142
142
  blockWindowClose: null,
143
143
  });
144
144
 
@@ -202,8 +202,8 @@ const getSessionKey = () => (userId ? `tenant:${userId}` : false);
202
202
  const storeManager = createStoreManager({
203
203
  getSessionKey,
204
204
  errorNormalizer: normalizeError,
205
- lowPriorityThrottleMs: 5,
206
- baseCoalescingWindowMs: 10,
205
+ lowPriorityThrottleMs: 40 * 60 * 1_000,
206
+ baseCoalescingWindowMs: 16,
207
207
  blockWindowClose: null,
208
208
  onPersistentStorageError: (error) => {
209
209
  console.error('TSDF persistence failed', error);
@@ -16,8 +16,9 @@ const storeManager = createStoreManager({
16
16
  id: 'unknown-error',
17
17
  message: error.message,
18
18
  }),
19
- lowPriorityThrottleMs: 5,
20
- baseCoalescingWindowMs: 10,
19
+ lowPriorityThrottleMs: 40 * 60 * 1_000,
20
+ baseCoalescingWindowMs: 16,
21
+ backgroundCoalescingDelayMs: 3_000,
21
22
  dynamicRealtimeThrottleMs: ({ lastFetchDuration, windowIsNotFocused }) =>
22
23
  windowIsNotFocused ? lastFetchDuration * 10 : lastFetchDuration * 2,
23
24
  blockWindowClose: null,
@@ -34,29 +35,30 @@ const storeManager = createStoreManager({
34
35
 
35
36
  Options:
36
37
 
37
- | Option | Required | Description |
38
- | --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
39
- | `getSessionKey` | Yes | Returns the active tenant/account key. Return `false` while no session is ready. |
40
- | `errorNormalizer` | Yes | Converts thrown `Error` values into TSDF's shared `StoreError` shape. |
41
- | `lowPriorityThrottleMs` | No | Default minimum interval between low-priority fetches for attached stores. Defaults to `5`. |
42
- | `baseCoalescingWindowMs` | No | Default window to group fetch requests for attached stores. Defaults to `10`. |
43
- | `dynamicRealtimeThrottleMs` | No | Default adaptive throttle for real-time updates in attached stores. Defaults to `100ms` focused and `1000ms` in the background. Store options override it. |
44
- | `blockWindowClose` | No | Shared window-close blocker for mutations in attached stores. Defaults to `null`. |
45
- | `revalidateOnWindowFocus` | No | Default focus revalidation policy for attached stores. Store options override it. |
46
- | `onMutationError` | No | Global fallback for mutation failures when a store does not provide its own handler. |
47
- | `onPersistentStorageError` | No | Global fallback for persistent storage failures when a store does not provide its own handler. |
48
- | `debug` | No | Enables browser-tab sync and persistent-storage debug logs. Pass `true` or a logger function. |
49
- | `offlineSession` | No | Shared offline config used by stores with `persistentStorage.offline`. |
38
+ | Option | Required | Description |
39
+ | ----------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
40
+ | `getSessionKey` | Yes | Returns the active tenant/account key. Return `false` while no session is ready. |
41
+ | `errorNormalizer` | Yes | Converts thrown `Error` values into TSDF's shared `StoreError` shape. |
42
+ | `lowPriorityThrottleMs` | No | Default minimum interval between low-priority fetches for attached stores. Defaults to 40 minutes (`2_400_000ms`). |
43
+ | `baseCoalescingWindowMs` | No | Default window to group fetch requests for attached stores. Defaults to `16ms`. |
44
+ | `backgroundCoalescingDelayMs` | No | Extra browser-tab coalescing delay applied only while a tab is in the background. Defaults to `3000ms`. |
45
+ | `dynamicRealtimeThrottleMs` | No | Default adaptive throttle for real-time updates in attached stores. Defaults to `100ms` focused and `1000ms` in the background. Store options override it. |
46
+ | `blockWindowClose` | No | Shared window-close blocker for mutations in attached stores. Defaults to `null`. |
47
+ | `revalidateOnWindowFocus` | No | Default focus revalidation policy for attached stores. Store options override it. |
48
+ | `onMutationError` | No | Global fallback for mutation failures when a store does not provide its own handler. |
49
+ | `onPersistentStorageError` | No | Global fallback for persistent storage failures when a store does not provide its own handler. |
50
+ | `debug` | No | Enables browser-tab sync, focus revalidation, and persistent-storage debug logs. Pass `true` or a logger function. |
51
+ | `offlineSession` | No | Shared offline config used by stores with `persistentStorage.offline`. |
50
52
 
51
53
  The session key is used by browser-tab sync, persistent storage, and offline state. Stores with the same `id` but different session keys are isolated.
52
54
 
53
- Stores inherit the manager's `lowPriorityThrottleMs`, `baseCoalescingWindowMs`, and `dynamicRealtimeThrottleMs` unless they provide their own store-level overrides. The built-in `dynamicRealtimeThrottleMs` default returns `100ms` while focused and `1000ms` while the window is in the background. `blockWindowClose` is manager-only so window-close mutation protection is consistent across attached stores.
55
+ Stores inherit the manager's `lowPriorityThrottleMs`, `baseCoalescingWindowMs`, and `dynamicRealtimeThrottleMs` unless they provide their own store-level overrides. `backgroundCoalescingDelayMs` and `blockWindowClose` are manager-only so browser-tab background coordination and window-close mutation protection stay consistent across attached stores. The built-in `dynamicRealtimeThrottleMs` default returns `100ms` while focused and `1000ms` while the window is in the background.
54
56
 
55
57
  Store-level options can explicitly disable inherited defaults when the option supports disabling: use `revalidateOnWindowFocus: false`, `onMutationError: null`, or `persistentStorage.onPersistentStorageError: null`.
56
58
 
57
59
  ## Debug Logging
58
60
 
59
- Pass `debug: true` to log browser-tab sync operations and persistent-storage operations through `console.log`, `console.warn`, and `console.error`. Browser-tab sync logs include lifecycle, leader changes, publish/receive events, and skipped messages. Store data sync uses store-specific channels, while tab-presence status uses one shared `presence` channel per manager/session. Presence prioritizes the focused tab; background tabs announce open/focus/blur changes and keep their last known fallback rank during quiet periods. Async persistent storage logs include `durationMs` so slow OPFS, IndexedDB, or custom driver paths can be inspected.
61
+ Pass `debug: true` to log browser-tab sync operations, focus revalidation decisions, and persistent-storage operations through `console.log`, `console.warn`, and `console.error`. Browser-tab sync logs include lifecycle, leader changes, publish/receive events, and skipped messages. Focus revalidation logs report when `revalidateOnWindowFocus` triggers, is dynamically disabled, or is skipped because real-time updates own freshness. Store data sync uses store-specific channels, while tab-presence status uses one shared `presence` channel per manager/session. Presence prioritizes the focused tab; background tabs announce open/focus/blur changes and keep their last known fallback rank during quiet periods. Async persistent storage logs include `durationMs` so slow OPFS, IndexedDB, or custom driver paths can be inspected.
60
62
 
61
63
  ```ts
62
64
  const storeManager = createStoreManager({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tsdf",
3
- "version": "17.0.0-alpha.11",
3
+ "version": "17.0.0-alpha.12",
4
4
  "description": "A data fetching solution based on t-state",
5
5
  "license": "PolyForm-Noncommercial-1.0.0",
6
6
  "author": "Lucas Santos",