tsdf 17.0.2 → 17.0.4

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.
Files changed (247) hide show
  1. package/dist/async-storage.d.ts +1 -1
  2. package/dist/{asyncStorageAdapter-DuAUANgu.d.ts → asyncStorageAdapter-CMohMeKm.d.ts} +1 -1
  3. package/dist/indexed-db-storage.d.ts +1 -1
  4. package/dist/main.d.ts +28 -32
  5. package/dist/main.js +46 -46
  6. package/dist/opfs-storage.d.ts +1 -1
  7. package/dist/{opfsPersistentStorage-BB0qqnRz.d.ts → opfsPersistentStorage-Ci0JcCo5.d.ts} +1 -1
  8. package/dist/src/async-storage.d.ts +1 -0
  9. package/dist/src/cacheLimits/lruCacheRuntime.d.ts +9 -0
  10. package/dist/src/cacheLimits/scheduleIdleThrottled.d.ts +1 -0
  11. package/dist/src/cacheLimits/useRegisterActiveKeys.d.ts +1 -0
  12. package/dist/src/collectionStore/collectionCacheLimits.d.ts +1 -0
  13. package/dist/src/collectionStore/collectionStore.d.ts +385 -0
  14. package/dist/src/collectionStore/executeBatchFetch.d.ts +6 -0
  15. package/dist/src/collectionStore/useItem.d.ts +15 -0
  16. package/dist/src/collectionStore/useMultipleItems.d.ts +35 -0
  17. package/dist/src/debug.d.ts +30 -0
  18. package/dist/src/documentStore.d.ts +290 -0
  19. package/dist/src/hooks/useListItem.d.ts +22 -0
  20. package/dist/src/hooks/useListItemIsDeleted.d.ts +13 -0
  21. package/dist/src/hooks/useListItemIsLoading.d.ts +16 -0
  22. package/dist/src/indexed-db-storage.d.ts +1 -0
  23. package/dist/src/internal/offlineTestInstrumentation.d.ts +12 -0
  24. package/dist/src/internal/testTimelineTypes.d.ts +1 -0
  25. package/dist/src/invalidationUtils.d.ts +8 -0
  26. package/dist/src/isOffScreenContext.d.ts +16 -0
  27. package/dist/src/listQueryStore/createFetchApi.d.ts +1 -0
  28. package/dist/src/listQueryStore/createMutationApi.d.ts +1 -0
  29. package/dist/src/listQueryStore/executeItemBatchFetch.d.ts +20 -0
  30. package/dist/src/listQueryStore/executeQueryFetch.d.ts +7 -0
  31. package/dist/src/listQueryStore/itemFieldUtils.d.ts +77 -0
  32. package/dist/src/listQueryStore/listQueryCacheLimits.d.ts +1 -0
  33. package/dist/src/listQueryStore/listQueryStore.d.ts +538 -0
  34. package/dist/src/listQueryStore/types.d.ts +347 -0
  35. package/dist/src/listQueryStore/useFindItem.d.ts +7 -0
  36. package/dist/src/listQueryStore/useItem.d.ts +29 -0
  37. package/dist/src/listQueryStore/useListQuery.d.ts +29 -0
  38. package/dist/src/listQueryStore/useMultipleItems.d.ts +44 -0
  39. package/dist/src/listQueryStore/useMultipleListQueries.d.ts +46 -0
  40. package/dist/src/listQueryStore/usePendingOfflineItems.d.ts +19 -0
  41. package/dist/src/main.d.ts +23 -0
  42. package/dist/src/opfs-storage.d.ts +1 -0
  43. package/dist/src/persistentStorage/asyncStorageAdapter.d.ts +95 -0
  44. package/dist/src/persistentStorage/asyncStorageAdapters.d.ts +2 -0
  45. package/dist/src/persistentStorage/asyncStorageShared.d.ts +23 -0
  46. package/dist/src/persistentStorage/collectionStorePersistence.d.ts +26 -0
  47. package/dist/src/persistentStorage/compactListQueryLocalStorageEntry.d.ts +11 -0
  48. package/dist/src/persistentStorage/compactLocalStorageEntry.d.ts +8 -0
  49. package/dist/src/persistentStorage/documentEntryKey.d.ts +1 -0
  50. package/dist/src/persistentStorage/documentStorePersistence.d.ts +17 -0
  51. package/dist/src/persistentStorage/indexedDbAsyncStorageAdapter.d.ts +165 -0
  52. package/dist/src/persistentStorage/indexedDbPersistentStorage.d.ts +6 -0
  53. package/dist/src/persistentStorage/listQueryStorePersistence.d.ts +37 -0
  54. package/dist/src/persistentStorage/localStorageMetadata.d.ts +126 -0
  55. package/dist/src/persistentStorage/navigatorLocks.d.ts +3 -0
  56. package/dist/src/persistentStorage/offline/entityMetadata.d.ts +12 -0
  57. package/dist/src/persistentStorage/offline/fetchRuntime.d.ts +35 -0
  58. package/dist/src/persistentStorage/offline/mutationRuntime.d.ts +31 -0
  59. package/dist/src/persistentStorage/offline/offlineResolution.typeGuards.d.ts +1 -0
  60. package/dist/src/persistentStorage/offline/overlayStoreLifecycle.d.ts +13 -0
  61. package/dist/src/persistentStorage/offline/sessionCoordinator.d.ts +94 -0
  62. package/dist/src/persistentStorage/offline/sessionProtectionRegistry.d.ts +11 -0
  63. package/dist/src/persistentStorage/offline/storeController.d.ts +86 -0
  64. package/dist/src/persistentStorage/offline/types.d.ts +1255 -0
  65. package/dist/src/persistentStorage/offlineUploadRegistry.d.ts +11 -0
  66. package/dist/src/persistentStorage/offlineUploadTypes.d.ts +97 -0
  67. package/dist/src/persistentStorage/offlineUploadsShared.d.ts +4 -0
  68. package/dist/src/persistentStorage/opfsAsyncStorageAdapter.d.ts +24 -0
  69. package/dist/src/persistentStorage/opfsFileNaming.d.ts +23 -0
  70. package/dist/src/persistentStorage/opfsHelpers.d.ts +3 -0
  71. package/dist/src/persistentStorage/opfsOfflineUploadAdapter.d.ts +2 -0
  72. package/dist/src/persistentStorage/opfsPersistentStorage.d.ts +2 -0
  73. package/dist/src/persistentStorage/parsePersistedData.d.ts +45 -0
  74. package/dist/src/persistentStorage/persistenceUtils.d.ts +52 -0
  75. package/dist/src/persistentStorage/persistentStorageDefaults.d.ts +4 -0
  76. package/dist/src/persistentStorage/persistentStorageManager.d.ts +197 -0
  77. package/dist/src/persistentStorage/quotaDebug.d.ts +16 -0
  78. package/dist/src/persistentStorage/scheduleIdleCleanup.d.ts +28 -0
  79. package/dist/src/persistentStorage/storageAdapter.d.ts +41 -0
  80. package/dist/src/persistentStorage/storageEntryPrefixes.d.ts +16 -0
  81. package/dist/src/persistentStorage/types.d.ts +412 -0
  82. package/dist/src/persistentStorage/validateWithSchema.d.ts +12 -0
  83. package/dist/src/requestScheduler.d.ts +81 -0
  84. package/dist/src/storeManager.d.ts +160 -0
  85. package/dist/src/utils/automaticFetchPolicy.d.ts +29 -0
  86. package/dist/src/utils/browserTabsPriority.d.ts +43 -0
  87. package/dist/src/utils/browserTabsSync.d.ts +33 -0
  88. package/dist/src/utils/optimisticMutationTracker.d.ts +20 -0
  89. package/dist/src/utils/optimisticRollback.d.ts +11 -0
  90. package/dist/src/utils/payloadDebounce.d.ts +5 -0
  91. package/dist/src/utils/performMutation.d.ts +19 -0
  92. package/dist/src/utils/reusePrevIfEqual.d.ts +1 -0
  93. package/dist/src/utils/storeFocusLifecycle.d.ts +1 -0
  94. package/dist/src/utils/storeShared.d.ts +126 -0
  95. package/dist/src/utils/useEnsureIsLoaded.d.ts +6 -0
  96. package/dist/src/utils/useRequireFreshData.d.ts +6 -0
  97. package/dist/tests/basic-functionality/collection-store.test.d.ts +1 -0
  98. package/dist/tests/basic-functionality/document-store.test.d.ts +1 -0
  99. package/dist/tests/basic-functionality/list-query-state-manipulation.test.d.ts +1 -0
  100. package/dist/tests/basic-functionality/list-query-store.test.d.ts +1 -0
  101. package/dist/tests/browser-tabs/browser-tabs-background-rtu-batch.test.d.ts +1 -0
  102. package/dist/tests/browser-tabs/browser-tabs-background-rtu.test.d.ts +1 -0
  103. package/dist/tests/browser-tabs/browser-tabs-background-scheduling.test.d.ts +1 -0
  104. package/dist/tests/browser-tabs/browser-tabs-list-query-pagination.test.d.ts +1 -0
  105. package/dist/tests/browser-tabs/browser-tabs-non-cancelable-fetches.test.d.ts +1 -0
  106. package/dist/tests/browser-tabs/browser-tabs-optimistic-sync.test.d.ts +1 -0
  107. package/dist/tests/browser-tabs/browser-tabs-partial-resources.test.d.ts +1 -0
  108. package/dist/tests/browser-tabs/browser-tabs-priority.test.d.ts +1 -0
  109. package/dist/tests/browser-tabs/browser-tabs-snapshot-consistency.test.d.ts +1 -0
  110. package/dist/tests/browser-tabs/browser-tabs-state-methods.test.d.ts +1 -0
  111. package/dist/tests/browser-tabs/browser-tabs-sync-coordinator.test.d.ts +1 -0
  112. package/dist/tests/browser-tabs/browser-tabs-test-helpers.d.ts +69 -0
  113. package/dist/tests/browser-tabs/focus-coordinator.test.d.ts +1 -0
  114. package/dist/tests/hooks/collection-hooks-2.test.d.ts +1 -0
  115. package/dist/tests/hooks/collection-hooks.test.d.ts +1 -0
  116. package/dist/tests/hooks/collection-useListItem.test.d.ts +1 -0
  117. package/dist/tests/hooks/debounce-payload-hooks.test.d.ts +1 -0
  118. package/dist/tests/hooks/disable-refetches.test.d.ts +1 -0
  119. package/dist/tests/hooks/document-hooks-2.test.d.ts +1 -0
  120. package/dist/tests/hooks/document-hooks.test.d.ts +1 -0
  121. package/dist/tests/hooks/document-useListItem.test.d.ts +1 -0
  122. package/dist/tests/hooks/fetch-error-recovery.test.d.ts +1 -0
  123. package/dist/tests/hooks/hook-memoization.test.d.ts +1 -0
  124. package/dist/tests/hooks/list-query-hooks-2.test.d.ts +1 -0
  125. package/dist/tests/hooks/list-query-hooks-3.test.d.ts +1 -0
  126. package/dist/tests/hooks/list-query-hooks-mutations.test.d.ts +1 -0
  127. package/dist/tests/hooks/list-query-hooks.test.d.ts +1 -0
  128. package/dist/tests/hooks/list-query-pending-offline-items.test.d.ts +1 -0
  129. package/dist/tests/hooks/off-screen-context.test.d.ts +1 -0
  130. package/dist/tests/list-query-features/list-query-derived-queries.test.d.ts +1 -0
  131. package/dist/tests/list-query-features/list-query-offset-pagination.test.d.ts +1 -0
  132. package/dist/tests/list-query-features/list-query-optimistic-filters.test.d.ts +1 -0
  133. package/dist/tests/list-query-features/list-query-partial-resources-2.test.d.ts +1 -0
  134. package/dist/tests/list-query-features/list-query-partial-resources-3.test.d.ts +1 -0
  135. package/dist/tests/list-query-features/list-query-partial-resources-regressions.test.d.ts +1 -0
  136. package/dist/tests/list-query-features/list-query-partial-resources-show-partial-status.test.d.ts +1 -0
  137. package/dist/tests/list-query-features/list-query-partial-resources.test.d.ts +1 -0
  138. package/dist/tests/list-query-features/list-query-size-coalescing-partial-resources.test.d.ts +1 -0
  139. package/dist/tests/mocks/browserTabsTestUtils.d.ts +17 -0
  140. package/dist/tests/mocks/collectionStoreTestEnv.d.ts +265 -0
  141. package/dist/tests/mocks/documentStoreTestEnv.d.ts +140 -0
  142. package/dist/tests/mocks/duplicateStoreGuard.test.d.ts +1 -0
  143. package/dist/tests/mocks/listQueryStoreTestEnv.d.ts +295 -0
  144. package/dist/tests/mocks/mockBrowserOpfs.d.ts +70 -0
  145. package/dist/tests/mocks/mockBrowserOpfs.test.d.ts +1 -0
  146. package/dist/tests/mocks/mockLocalStorageStore.d.ts +61 -0
  147. package/dist/tests/mocks/seedScenarioPersistentStorage.d.ts +51 -0
  148. package/dist/tests/mocks/serverMock.d.ts +56 -0
  149. package/dist/tests/mocks/serverTableMock.d.ts +174 -0
  150. package/dist/tests/mocks/testEnvUtils.d.ts +120 -0
  151. package/dist/tests/mocks/testScenarioPersistentStorage.test.d.ts +1 -0
  152. package/dist/tests/offline/offline-fetching-scenarios.test.d.ts +1 -0
  153. package/dist/tests/offline/offline-mixed-adapter-storage.test.d.ts +1 -0
  154. package/dist/tests/offline/offline-mutation-fallback.test.d.ts +1 -0
  155. package/dist/tests/offline/offline-network-recovery.test.d.ts +1 -0
  156. package/dist/tests/offline/offline-outage.test.d.ts +1 -0
  157. package/dist/tests/offline/offline-overlays.test.d.ts +1 -0
  158. package/dist/tests/offline/offline-query-replay.test.d.ts +1 -0
  159. package/dist/tests/offline/offline-reads.test.d.ts +1 -0
  160. package/dist/tests/offline/offline-replay-conflicts.test.d.ts +1 -0
  161. package/dist/tests/offline/offline-replay-queueing.test.d.ts +1 -0
  162. package/dist/tests/offline/offline-resolution-dependencies.test.d.ts +1 -0
  163. package/dist/tests/offline/offline-runtime-controls.test.d.ts +1 -0
  164. package/dist/tests/offline/offline-session-and-global-state.test.d.ts +1 -0
  165. package/dist/tests/offline/offline-storage.test.d.ts +1 -0
  166. package/dist/tests/offline/offline-uploads.test.d.ts +1 -0
  167. package/dist/tests/offline/offlineReplayTestShared.d.ts +292 -0
  168. package/dist/tests/offline/offlineTestShared.d.ts +156 -0
  169. package/dist/tests/perform-mutation/mutation-error-rollback.test.d.ts +1 -0
  170. package/dist/tests/perform-mutation/perform-mutation-block-window-close.test.d.ts +1 -0
  171. package/dist/tests/perform-mutation/perform-mutation-debounce.test.d.ts +1 -0
  172. package/dist/tests/perform-mutation/store-events.test.d.ts +1 -0
  173. package/dist/tests/persistent-storage/async-storage-efficiency/collection.test.d.ts +1 -0
  174. package/dist/tests/persistent-storage/async-storage-efficiency/document.test.d.ts +1 -0
  175. package/dist/tests/persistent-storage/async-storage-efficiency/list-query.test.d.ts +1 -0
  176. package/dist/tests/persistent-storage/async-storage-efficiency/maintenance.test.d.ts +1 -0
  177. package/dist/tests/persistent-storage/async-storage-efficiency/shared.d.ts +804 -0
  178. package/dist/tests/persistent-storage/async-storage-shared.test.d.ts +1 -0
  179. package/dist/tests/persistent-storage/collection-store-persistence.converted.opfs.test.d.ts +1 -0
  180. package/dist/tests/persistent-storage/collection-store-persistence.converted.test.d.ts +1 -0
  181. package/dist/tests/persistent-storage/collection-store-persistence.opfs.test.d.ts +1 -0
  182. package/dist/tests/persistent-storage/collection-store-persistence.test.d.ts +1 -0
  183. package/dist/tests/persistent-storage/document-store-persistence.converted.opfs.test.d.ts +1 -0
  184. package/dist/tests/persistent-storage/document-store-persistence.converted.test.d.ts +1 -0
  185. package/dist/tests/persistent-storage/document-store-persistence.opfs.test.d.ts +1 -0
  186. package/dist/tests/persistent-storage/document-store-persistence.test.d.ts +1 -0
  187. package/dist/tests/persistent-storage/expiration-scan.test.d.ts +1 -0
  188. package/dist/tests/persistent-storage/indexeddb-async-storage-efficiency/collection.test.d.ts +1 -0
  189. package/dist/tests/persistent-storage/indexeddb-async-storage-efficiency/document.test.d.ts +1 -0
  190. package/dist/tests/persistent-storage/indexeddb-async-storage-efficiency/list-query.test.d.ts +1 -0
  191. package/dist/tests/persistent-storage/indexeddb-async-storage-efficiency/maintenance.test.d.ts +1 -0
  192. package/dist/tests/persistent-storage/indexeddb-async-storage-efficiency/shared.d.ts +780 -0
  193. package/dist/tests/persistent-storage/indexeddb-storage-adapter.test.d.ts +1 -0
  194. package/dist/tests/persistent-storage/list-query-store-persistence.converted.opfs.test.d.ts +1 -0
  195. package/dist/tests/persistent-storage/list-query-store-persistence.converted.test.d.ts +1 -0
  196. package/dist/tests/persistent-storage/list-query-store-persistence.opfs.test.d.ts +1 -0
  197. package/dist/tests/persistent-storage/list-query-store-persistence.test.d.ts +1 -0
  198. package/dist/tests/persistent-storage/persistence-with-tabs-sync.test.d.ts +1 -0
  199. package/dist/tests/persistent-storage/persistentStorageByteBudgetTestUtils.d.ts +18 -0
  200. package/dist/tests/persistent-storage/quota-exceeded-recovery-no-locks.test.d.ts +1 -0
  201. package/dist/tests/persistent-storage/quota-exceeded-recovery.test.d.ts +1 -0
  202. package/dist/tests/persistent-storage/quotaRecoveryTestUtils.d.ts +228 -0
  203. package/dist/tests/persistent-storage/storage-adapter.test.d.ts +1 -0
  204. package/dist/tests/persistent-storage/sync-storage-efficiency/collection.test.d.ts +1 -0
  205. package/dist/tests/persistent-storage/sync-storage-efficiency/document.test.d.ts +1 -0
  206. package/dist/tests/persistent-storage/sync-storage-efficiency/list-query.test.d.ts +1 -0
  207. package/dist/tests/persistent-storage/sync-storage-efficiency/maintenance.test.d.ts +1 -0
  208. package/dist/tests/persistent-storage/sync-storage-efficiency/shared.d.ts +784 -0
  209. package/dist/tests/playwright/browser-tabs.spec.d.ts +1 -0
  210. package/dist/tests/playwright/persistent-storage.spec.d.ts +1 -0
  211. package/dist/tests/request-schedulling/batch-medium-priority.test.d.ts +1 -0
  212. package/dist/tests/request-schedulling/batch-realtime-updates.test.d.ts +1 -0
  213. package/dist/tests/request-schedulling/collection-batch-coalescing.test.d.ts +1 -0
  214. package/dist/tests/request-schedulling/collection-batch-key-grouping.test.d.ts +1 -0
  215. package/dist/tests/request-schedulling/collection-fetch-orchestration.test.d.ts +1 -0
  216. package/dist/tests/request-schedulling/document-await-fetch.test.d.ts +1 -0
  217. package/dist/tests/request-schedulling/document-base-coalescing.test.d.ts +1 -0
  218. package/dist/tests/request-schedulling/document-fetch-orchestration.test.d.ts +1 -0
  219. package/dist/tests/request-schedulling/document-medium-priority-fetch.test.d.ts +1 -0
  220. package/dist/tests/request-schedulling/document-realtime-updates.test.d.ts +1 -0
  221. package/dist/tests/request-schedulling/list-query-item-batch-coalescing.test.d.ts +1 -0
  222. package/dist/tests/request-schedulling/list-query-item-batch-key-grouping.test.d.ts +1 -0
  223. package/dist/tests/request-schedulling/list-query-size-coalescing.test.d.ts +1 -0
  224. package/dist/tests/request-schedulling/medium-vs-realtime.test.d.ts +1 -0
  225. package/dist/tests/request-schedulling/request-scheduler-cross-tab-sync.test.d.ts +1 -0
  226. package/dist/tests/request-schedulling/window-focus.test.d.ts +1 -0
  227. package/dist/tests/store-manager.test.d.ts +1 -0
  228. package/dist/tests/user-facing-api/collection-offline-usage.test.d.ts +1 -0
  229. package/dist/tests/user-facing-api/document-offline-usage.test.d.ts +1 -0
  230. package/dist/tests/user-facing-api/list-query-offline-usage.test.d.ts +1 -0
  231. package/dist/tests/user-facing-api/result-returning-callbacks.test.d.ts +1 -0
  232. package/dist/tests/utils/genericTestUtils.d.ts +6 -0
  233. package/dist/tests/utils/indexedDbPersistentStorageOptimizationTestUtils.d.ts +79 -0
  234. package/dist/tests/utils/indexedDbPersistentStorageTestStore.d.ts +181 -0
  235. package/dist/tests/utils/listQueryHooksTestUtils.d.ts +8 -0
  236. package/dist/tests/utils/networkMock.d.ts +11 -0
  237. package/dist/tests/utils/opfsPersistentStorageTestStore.d.ts +220 -0
  238. package/dist/tests/utils/persistentStorageOptimizationTestUtils.d.ts +54 -0
  239. package/dist/tests/utils/persistentStorageOptimizationTestUtils.test.d.ts +1 -0
  240. package/dist/tests/utils/persistentStorageTestStore.d.ts +66 -0
  241. package/dist/tests/utils/resetSessionForTests.d.ts +3 -0
  242. package/dist/tests/utils/withSuppressedActError.d.ts +4 -0
  243. package/dist/{types-aWgyZHLj.d.ts → types-D0ttVGmj.d.ts} +1 -1
  244. package/docs/browser-tabs-sync.md +2 -0
  245. package/docs/mutations.md +7 -3
  246. package/docs/persistent-storage.md +2 -0
  247. package/package.json +6 -3
@@ -0,0 +1,385 @@
1
+ import { __LEGIT_ANY__ } from '@ls-stack/utils/saferTyping';
2
+ import { type Emitter } from 'evtmitter';
3
+ import { type Result as ResultType } from 't-result';
4
+ import { Store } from 't-state';
5
+ import { type OfflineMutationResult } from '../persistentStorage/offline/mutationRuntime';
6
+ import { type AnyOfflineOperationDefinition, type CollectionOfflineEntityRef, type GlobalOfflineEntity, type OfflineMutationInput, type OfflineResolutionActionForOperation, type OfflineResolutionRecord, type ParsedOfflineResolutionConflictResultForStore } from '../persistentStorage/offline/types';
7
+ import type { OfflineMutationUploadsInput } from '../persistentStorage/offlineUploadTypes';
8
+ import type { CollectionPersistentStorageConfig, PersistentStoragePreloadResult } from '../persistentStorage/types';
9
+ import { FetchType, RequestSchedulerEventData, RequestSchedulerEvents, ScheduleFetchOptions, ScheduleFetchResults } from '../requestScheduler';
10
+ import { type StoreManager } from '../storeManager';
11
+ import { StoreFetchError, StoreMutationError, type MaybeTSDFResult, type MutationSkipped, type StoreError, type StoreMutationErrorOptions, type TSDFStatus, type UnwrapTSDFResult, type ValidPayload, type ValidStoreState } from '../utils/storeShared';
12
+ import { UseItemOptions } from './useItem';
13
+ import { UseMultipleItemsOptions } from './useMultipleItems';
14
+ /** Lifecycle status for a cached collection item. */
15
+ export type CollectionItemStatus = TSDFStatus;
16
+ /** Raw cached state for one collection item. */
17
+ export type TSFDCollectionItem<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = {
18
+ /** Latest loaded item data, or `null` before the item is available. */
19
+ data: ItemState | null;
20
+ /** Last fetch error for this item, when the latest fetch failed. */
21
+ error: StoreError | null;
22
+ /** Current fetch lifecycle status for this item. */
23
+ status: CollectionItemStatus;
24
+ /** Payload used to identify and fetch this item. */
25
+ payload: ItemPayload;
26
+ /** Pending automatic refetch priority for stale data mounted by hooks. */
27
+ refetchOnMount: false | FetchType;
28
+ /** Whether this item has ever loaded successfully. */
29
+ wasLoaded: boolean;
30
+ };
31
+ /** Raw t-state shape used by a collection store. */
32
+ export type TSFDCollectionState<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = Record<string, TSFDCollectionItem<ItemState, ItemPayload> | null>;
33
+ /** Value returned by `CollectionStore.useItem(...)` and `useMultipleItems(...)`. */
34
+ export type TSFDUseCollectionItemReturn<Selected, ItemPayload, QueryMetadata extends undefined | Record<string, unknown> = undefined> = {
35
+ /** Selected item data. Defaults to the full item or `null`. */
36
+ data: Selected;
37
+ /** Hook-visible item status, including idle/deleted states for hook ergonomics. */
38
+ status: CollectionItemStatus | 'idle' | 'deleted';
39
+ /** Item payload for this result, unless omitted or unavailable. */
40
+ payload: ItemPayload | undefined;
41
+ /** Last item fetch error, if any. */
42
+ error: StoreError | null;
43
+ /** Stable store key for the current item payload. */
44
+ itemStateKey: string;
45
+ /** Shorthand for `status === 'loading'`. Stays `false` while loaded data is `refetching`. */
46
+ isLoading: boolean;
47
+ /** Whether this result has local offline changes that still need to sync to the server. */
48
+ pendingSync: boolean;
49
+ /** Caller-provided metadata copied from the query descriptor. */
50
+ queryMetadata: QueryMetadata;
51
+ };
52
+ /** Item descriptor accepted by `CollectionStore.useMultipleItems(...)`. */
53
+ export type CollectionUseMultipleItemsQuery<ItemPayload extends ValidPayload, QueryMetadata extends undefined | Record<string, unknown> = undefined> = {
54
+ /** Item payload to subscribe to and fetch when needed. */
55
+ payload: ItemPayload;
56
+ /** Metadata returned with this query result for caller-side bookkeeping. */
57
+ queryMetadata?: QueryMetadata;
58
+ /** Omits `payload` from this query result. */
59
+ omitPayload?: boolean;
60
+ /**
61
+ * Only fetches when the item is missing from state, skipping stale-state and
62
+ * invalidation refetches.
63
+ */
64
+ disableRefetches?: boolean;
65
+ /** Prevents the automatic mount refetch for stale loaded data. */
66
+ disableRefetchOnMount?: boolean;
67
+ /** Returns `idle` instead of `loading` while the item has not been fetched. */
68
+ returnIdleStatus?: boolean;
69
+ /** Returns `refetching` instead of keeping `loaded` status during refetches. */
70
+ returnRefetchingStatus?: boolean;
71
+ /** Marks this subscription as off-screen, lowering automatic fetch priority. */
72
+ isOffScreen?: boolean;
73
+ };
74
+ /** Callback invoked when an already-loaded collection item is invalidated. */
75
+ export type OnCollectionItemInvalidate<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = (props: {
76
+ /** Current cached item state at invalidation time. */
77
+ itemState: ItemState;
78
+ /** Payload of the invalidated item. */
79
+ payload: ItemPayload;
80
+ /** Fetch priority requested for the invalidation. */
81
+ priority: FetchType;
82
+ }) => void;
83
+ /** Events emitted by collection mutation lifecycle helpers. */
84
+ export type CollectionStoreStoreEvents<ItemPayload extends ValidPayload> = {
85
+ /** Emitted when a mutation begins executing */
86
+ mutationStart: {
87
+ mutationId: number;
88
+ items: ItemPayload[];
89
+ };
90
+ /** Emitted when a mutation completes, fails, or is skipped */
91
+ mutationEnd: {
92
+ mutationId: number;
93
+ items: ItemPayload[];
94
+ status: 'success' | 'error' | 'skipped';
95
+ };
96
+ /** Emitted when an offline temp item is reconciled to its final payload. */
97
+ tempEntityReconciled: {
98
+ tempId: ItemPayload;
99
+ finalPayload: ItemPayload;
100
+ };
101
+ };
102
+ /** Details passed when collection cache-limit cleanup evicts cached items. */
103
+ export type CollectionStateCleanup<ItemPayload extends ValidPayload> = {
104
+ /** Cleanup trigger that removed these items. */
105
+ reason: 'cacheLimitEviction';
106
+ /** Store keys removed from the collection state. */
107
+ itemKeys: string[];
108
+ /** Original item payloads removed from the collection state. */
109
+ payloads: ItemPayload[];
110
+ };
111
+ type InternalCollectionOfflineOperations<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = Record<string, AnyOfflineOperationDefinition & {
112
+ getEntityRefs: (ctx: {
113
+ input: __LEGIT_ANY__;
114
+ }) => CollectionOfflineEntityRef<ItemPayload>[];
115
+ }> & ([ItemState | ItemPayload] extends [never] ? never : unknown);
116
+ type CollectionOfflineOperationsConfig<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = InternalCollectionOfflineOperations<ItemState, ItemPayload> | null;
117
+ /** Options used to create a collection store. */
118
+ export type CollectionStoreOptions<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TOfflineOperations extends CollectionOfflineOperationsConfig<ItemState, ItemPayload> = null, StorageState = unknown> = {
119
+ /**
120
+ * Stable id for this logical collection store. Used for debug labels,
121
+ * persistence namespaces, and browser tab sync.
122
+ */
123
+ id: string;
124
+ /** Shared global store manager providing session scoping and error normalization. */
125
+ storeManager: StoreManager;
126
+ /** Fetches one item by payload. */
127
+ fetchFn: (params: ItemPayload, signal: AbortSignal) => Promise<MaybeTSDFResult<ItemState>>;
128
+ /** Optional batch fetch function for fetching multiple items at once */
129
+ batchFetchFn?: (payloads: ItemPayload[], signal: AbortSignal, batchKey: string) => Promise<MaybeTSDFResult<Map<ItemPayload, MaybeTSDFResult<ItemState> | Error>>>;
130
+ /** Optional function to group batch fetches by key. When omitted, all batched items share one default batch key. Return false to fall back to individual fetchFn */
131
+ getItemsBatchKey?: (payload: ItemPayload) => string | false;
132
+ /** Max items per batch - triggers immediate fetch when reached */
133
+ maxBatchSize?: number;
134
+ /** Maximum number of cached items kept in memory. Defaults to 5,000. Inactive items are evicted in LRU order, while mounted hook items stay protected. */
135
+ maxItems?: number;
136
+ /** Called when cache-limit eviction removes items from in-memory state. */
137
+ onStateCleanup?: (cleanup: CollectionStateCleanup<ItemPayload>) => void;
138
+ /** Converts an item payload to the stable cache key used by this store. */
139
+ getCollectionItemKey?: (params: ItemPayload) => ValidPayload | unknown[];
140
+ /** Overrides the manager's default minimum interval between low-priority fetches for this store. */
141
+ lowPriorityThrottleMs?: number;
142
+ /** Overrides the manager's default coalescing window for this store. */
143
+ baseCoalescingWindowMs?: number;
144
+ /** Delay applied to medium-priority requests before they enter the scheduler. */
145
+ mediumPriorityDelayMs?: number;
146
+ /** Computes a per-fetch throttle for real-time updates using recent fetch cost and focus state. */
147
+ dynamicRealtimeThrottleMs?: (params: {
148
+ lastFetchDuration: number;
149
+ windowIsNotFocused: boolean;
150
+ }) => number;
151
+ /** Store-level focus revalidation policy. Overrides the manager default. */
152
+ revalidateOnWindowFocus?: boolean | (() => boolean);
153
+ /** Reconnect-specific cooldown. Defaults to 2,000ms. The first reconnect revalidates immediately;
154
+ * additional reconnects within the cooldown are coalesced into one trailing
155
+ * revalidation. Set to `0` to disable this cooldown. */
156
+ transportReconnectCooldownMs?: number;
157
+ /** Called when an already-loaded item is invalidated. */
158
+ onInvalidate?: OnCollectionItemInvalidate<ItemState, ItemPayload>;
159
+ /** Observes request scheduler lifecycle events for this store. */
160
+ onSchedulerEvent?: (event: RequestSchedulerEvents, data?: RequestSchedulerEventData) => void;
161
+ /**
162
+ * Store-specific mutation error handler.
163
+ *
164
+ * Overrides the manager fallback. Use `null` to disable inherited mutation
165
+ * error handling for this store.
166
+ */
167
+ onMutationError?: ((error: unknown, options: StoreMutationErrorOptions) => void) | null;
168
+ /** Treats refetches as real-time driven, disabling stale mount refetches by default. Defaults to `false`. */
169
+ usesRealTimeUpdates?: boolean;
170
+ /** Opt-in persistent storage configuration. When provided, cached items are loaded
171
+ * from storage on first read and saved back on successful fetches.
172
+ * Session scoping always reuses this store manager's `getSessionKey`, and the
173
+ * persisted namespace always reuses this store's `id`. */
174
+ persistentStorage?: CollectionPersistentStorageConfig<ItemState, ItemPayload, StorageState, TOfflineOperations>;
175
+ };
176
+ /** Event payloads emitted by `CollectionStore.events`. */
177
+ export type CollectionStoreEvents = {
178
+ /** Emitted whenever one or more cached items are invalidated. */
179
+ invalidateData: {
180
+ /** Fetch priority requested by the invalidation. */
181
+ priority: FetchType;
182
+ /** Store key for the invalidated item. */
183
+ itemKey: string;
184
+ };
185
+ };
186
+ type CollectionFilterItemsFn<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = (params: ItemPayload, data: ItemState | null) => boolean;
187
+ type ResolvedCollectionOfflineOperations<TOfflineOperations> = TOfflineOperations extends null ? Record<never, never> : Exclude<TOfflineOperations, null>;
188
+ type CollectionMutationPayload<ItemPayload extends ValidPayload> = ItemPayload | ItemPayload[] | null;
189
+ type CollectionMutationTarget<ItemPayload extends ValidPayload> = ItemPayload | ItemPayload[];
190
+ type CollectionMutationPayloadToUse<ItemPayload extends ValidPayload> = CollectionMutationTarget<ItemPayload>;
191
+ type CollectionMutationArgsBase<T, ItemPayload extends ValidPayload> = {
192
+ /**
193
+ * Applies optimistic updates for the affected item payloads before the
194
+ * mutation runs. Return `false` to cancel the mutation before the async
195
+ * mutation function is called.
196
+ */
197
+ optimisticUpdate?: (payload: CollectionMutationPayloadToUse<ItemPayload>) => void | boolean;
198
+ /** Performs the server mutation for the affected item payloads. */
199
+ mutation: (payload: CollectionMutationPayloadToUse<ItemPayload>) => Promise<T>;
200
+ /** Called after a successful online mutation. */
201
+ onSuccess?: (response: UnwrapTSDFResult<Awaited<T>>, payload: CollectionMutationPayloadToUse<ItemPayload>) => void;
202
+ /** Invalidates affected items after a successful online mutation. */
203
+ revalidateOnSuccess?: boolean;
204
+ /**
205
+ * Passes `{ silentErrors: true }` to `onMutationError`.
206
+ *
207
+ * The handler is still called so centralized logging and recovery can run,
208
+ * but UI handlers can suppress user-facing notifications.
209
+ */
210
+ silentErrors?: boolean;
211
+ /** Debounces mutations with the same context and payload. Superseded calls are skipped. */
212
+ debounce?: {
213
+ context: string;
214
+ payload: __LEGIT_ANY__;
215
+ ms: number;
216
+ };
217
+ };
218
+ type CollectionOnlineMutationArgs<T, ItemPayload extends ValidPayload> = CollectionMutationArgsBase<T, ItemPayload> & {
219
+ offline?: undefined;
220
+ upload?: undefined;
221
+ };
222
+ type CollectionOfflineMutationArgs<T, ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TOfflineOperations extends CollectionOfflineOperationsConfig<ItemState, ItemPayload>> = CollectionMutationArgsBase<T, ItemPayload> & {
223
+ /**
224
+ * Queues this mutation through the store's registered offline operation when
225
+ * the session is offline or the direct request fails with an offline outage.
226
+ */
227
+ offline: TOfflineOperations extends null ? never : OfflineMutationInput<Exclude<TOfflineOperations, null>>;
228
+ /** Files to attach if this mutation is queued for offline replay. */
229
+ upload?: OfflineMutationUploadsInput;
230
+ };
231
+ type CollectionPerformMutation<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TOfflineOperations extends CollectionOfflineOperationsConfig<ItemState, ItemPayload>> = {
232
+ /**
233
+ * Runs a collection mutation for one or more existing item payloads.
234
+ *
235
+ * Returns the direct server result when offline replay is not configured for
236
+ * this call.
237
+ */
238
+ <T>(payload: CollectionMutationTarget<ItemPayload>, args: CollectionOnlineMutationArgs<T, ItemPayload>): Promise<ResultType<UnwrapTSDFResult<Awaited<T>>, StoreMutationError | MutationSkipped>>;
239
+ /**
240
+ * Runs a collection mutation for one or more existing item payloads, with
241
+ * durable offline queueing as a fallback.
242
+ *
243
+ * When the mutation is queued, the result is `{ kind: 'queued' }` instead of
244
+ * the server payload.
245
+ */
246
+ <T>(payload: CollectionMutationTarget<ItemPayload>, args: CollectionOfflineMutationArgs<T, ItemState, ItemPayload, TOfflineOperations>): Promise<ResultType<OfflineMutationResult<UnwrapTSDFResult<Awaited<T>>>, StoreMutationError | MutationSkipped>>;
247
+ /**
248
+ * Runs a collection mutation with no current item target.
249
+ *
250
+ * Use this for create mutations that do not have a pre-generated item payload
251
+ * yet. Optimistic updates are not available without a target payload.
252
+ */
253
+ <T>(payload: null, args: Omit<CollectionOnlineMutationArgs<T, ItemPayload>, 'optimisticUpdate'>): Promise<ResultType<UnwrapTSDFResult<Awaited<T>>, StoreMutationError | MutationSkipped>>;
254
+ /**
255
+ * Runs an offline-capable collection mutation with no current item target.
256
+ *
257
+ * Use this for create mutations that do not have a pre-generated item payload
258
+ * yet. When the mutation is queued, the result is `{ kind: 'queued' }`.
259
+ */
260
+ <T>(payload: null, args: Omit<CollectionOfflineMutationArgs<T, ItemState, ItemPayload, TOfflineOperations>, 'optimisticUpdate'>): Promise<ResultType<OfflineMutationResult<UnwrapTSDFResult<Awaited<T>>>, StoreMutationError | MutationSkipped>>;
261
+ <T>(payload: CollectionMutationPayload<ItemPayload>, args: CollectionOnlineMutationArgs<T, ItemPayload> | CollectionOfflineMutationArgs<T, ItemState, ItemPayload, TOfflineOperations>): Promise<ResultType<UnwrapTSDFResult<Awaited<T>> | OfflineMutationResult<UnwrapTSDFResult<Awaited<T>>>, StoreMutationError | MutationSkipped>>;
262
+ };
263
+ /** Public API returned by `createCollectionStore(...)`. */
264
+ export type CollectionStore<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TOfflineOperations extends CollectionOfflineOperationsConfig<ItemState, ItemPayload> = null> = {
265
+ /** Underlying t-state store containing raw cached items. */
266
+ store: Store<TSFDCollectionState<ItemState, ItemPayload>>;
267
+ /** Invalidation event emitter used by hooks and integrations. */
268
+ events: Emitter<CollectionStoreEvents>;
269
+ /** Mutation lifecycle event emitter for observers and tests. */
270
+ storeEvents: Emitter<CollectionStoreStoreEvents<ItemPayload>>;
271
+ /** Item keys that have been explicitly invalidated and are awaiting refresh. */
272
+ readonly invalidationWasTriggered: Set<string>;
273
+ /** Schedules a fetch for one item or a batch of item payloads. */
274
+ scheduleFetch: {
275
+ (fetchType: FetchType, payload: ItemPayload, options?: ScheduleFetchOptions): ScheduleFetchResults;
276
+ (fetchType: FetchType, payload: ItemPayload[], options?: ScheduleFetchOptions): ScheduleFetchResults[];
277
+ };
278
+ /** Waits for an item fetch to settle and returns data or a fetch error. */
279
+ awaitFetch: (params: ItemPayload, options?: {
280
+ timeoutMs?: number;
281
+ }) => Promise<{
282
+ data: ItemState;
283
+ error: null;
284
+ } | {
285
+ data: null;
286
+ error: StoreFetchError;
287
+ }>;
288
+ /** Returns cached item data when usable, otherwise fetches it first. */
289
+ getItemFromStateOrFetch: (params: ItemPayload, options?: {
290
+ /** When `true`, stale cached data is ignored and refetched before returning. Defaults to `false`. */
291
+ ignoreStaleState?: boolean;
292
+ timeoutMs?: number;
293
+ }) => Promise<ResultType<ItemState, StoreFetchError>>;
294
+ /** React hook for subscribing to many collection items at once. */
295
+ useMultipleItems: <Selected = ItemState | null, QueryMetadata extends undefined | Record<string, unknown> = undefined>(items: CollectionUseMultipleItemsQuery<ItemPayload, QueryMetadata>[], options?: UseMultipleItemsOptions<ItemState, Selected>) => readonly TSFDUseCollectionItemReturn<Selected, ItemPayload, QueryMetadata>[];
296
+ /** React hook for subscribing to one collection item. */
297
+ useItem: <Selected = ItemState | null>(payload: ItemPayload | undefined | false | null, options?: UseItemOptions<ItemState, Selected>) => TSFDUseCollectionItemReturn<Selected, ItemPayload>;
298
+ /** React hook that tracks whether a nested list item is still loading. */
299
+ useListItemIsLoading: (payload: ItemPayload, args: {
300
+ /** Unique identifier of the sub-item within the collection item. */
301
+ itemId: string;
302
+ /** Extracts the sub-item from the collection item data. */
303
+ selector: (data: ItemState | null) => unknown;
304
+ /** Called if the sub-item is still missing and no refetch is in progress. */
305
+ loadItemFallback?: () => void;
306
+ /** Requires a mount refresh before reporting ready. May cause an extra request. */
307
+ requireFreshData?: boolean;
308
+ }) => boolean;
309
+ /** React hook that tracks whether a nested list item has been deleted. */
310
+ useListItemIsDeleted: (payload: ItemPayload, args: {
311
+ /** Unique identifier of the sub-item within the collection item. */
312
+ itemId: string;
313
+ /** Extracts the sub-item from the collection item data. */
314
+ selector: (data: ItemState | null) => unknown;
315
+ /** Called once when deletion is detected. */
316
+ onDelete?: () => void;
317
+ /** Requires a mount refresh before reporting ready. May cause an extra request. */
318
+ requireFreshData?: boolean;
319
+ }) => boolean;
320
+ /** React hook for selecting one nested list item plus loading/deleted flags. */
321
+ useListItem: <Selected>(payload: ItemPayload, args: {
322
+ /** Unique identifier of the sub-item within the collection item. */
323
+ itemId: string;
324
+ /** Extracts and maps the sub-item from the collection item data. */
325
+ selector: (data: ItemState | null) => Selected;
326
+ /** Called if the sub-item is still missing and no refetch is in progress. */
327
+ loadItemFallback?: () => void;
328
+ /** Called once when deletion is detected. */
329
+ onDelete?: () => void;
330
+ /** Requires a mount refresh before reporting ready. May cause an extra request. */
331
+ requireFreshData?: boolean;
332
+ }) => {
333
+ isLoading: boolean;
334
+ isDeleted: boolean;
335
+ data: Selected;
336
+ };
337
+ /** Clears in-memory state and cancels store-local runtime state. */
338
+ reset: () => void;
339
+ /** Unregisters listeners and releases resources owned by this store. */
340
+ dispose: () => void;
341
+ /** Loads item payloads from persistent storage into memory when available. */
342
+ preloadItemFromStorage: (params: ItemPayload | ItemPayload[]) => Promise<PersistentStoragePreloadResult<ItemPayload>[]>;
343
+ /** Returns the stable cache key for an item payload. */
344
+ getItemKey: (params: ItemPayload) => string;
345
+ /** Reads one or many cached items directly from store state. */
346
+ getItemState: {
347
+ (params: ItemPayload): TSFDCollectionItem<ItemState, ItemPayload> | undefined | null;
348
+ (params: ItemPayload[] | CollectionFilterItemsFn<ItemState, ItemPayload>): TSFDCollectionItem<ItemState, ItemPayload>[];
349
+ };
350
+ /** Returns offline sync metadata for this store's tracked entities. */
351
+ getOfflineEntities: () => GlobalOfflineEntity[];
352
+ /** React hook subscribing to this store's offline entity metadata. */
353
+ useOfflineEntities: () => readonly GlobalOfflineEntity[];
354
+ /** React hook subscribing to manual offline resolutions for this store. */
355
+ useOfflineResolutions: () => readonly OfflineResolutionRecord[];
356
+ /** Returns manual offline resolutions for this store. */
357
+ getOfflineResolutions: () => OfflineResolutionRecord[];
358
+ /** Parses a stored offline conflict into the operation-specific conflict shape. */
359
+ parseOfflineResolutionConflict: (resolution: OfflineResolutionRecord) => ParsedOfflineResolutionConflictResultForStore<ResolvedCollectionOfflineOperations<TOfflineOperations>>;
360
+ /** Applies a retry/discard/requeue/commit action to a pending offline resolution. */
361
+ resolveOfflineResolution: <TName extends keyof ResolvedCollectionOfflineOperations<TOfflineOperations> & string>(resolutionId: string, operationName: TName, resolution: OfflineResolutionActionForOperation<ResolvedCollectionOfflineOperations<TOfflineOperations>, TName>) => Promise<void> | void;
362
+ /** Marks one or more items as mutating and returns a function that ends the mutation. */
363
+ startMutation: (fetchParams: ItemPayload | ItemPayload[] | CollectionFilterItemsFn<ItemState, ItemPayload>) => () => void;
364
+ /** Marks cached items stale and schedules refetches for active subscriptions. Defaults to `highPriority`. */
365
+ invalidateItem: (itemPayload: ItemPayload | ItemPayload[] | CollectionFilterItemsFn<ItemState, ItemPayload>,
366
+ /** Fetch priority used for refetches triggered by this invalidation. Defaults to `highPriority`. */
367
+ priority?: FetchType) => void;
368
+ /** Applies an immutable update to one or more cached collection items. */
369
+ updateItemState: (fetchParams: ItemPayload | ItemPayload[] | CollectionFilterItemsFn<ItemState, ItemPayload>, produceNewData: (draftData: ItemState, collectionItem: TSFDCollectionItem<ItemState, ItemPayload>) => void | ItemState, options?: {
370
+ ifNothingWasUpdated?: () => void;
371
+ }) => boolean;
372
+ /** Adds or replaces one cached item directly in state. */
373
+ addItemToState: (fetchParams: ItemPayload, data: ItemState) => void;
374
+ /** Deletes one or more cached items directly from state. */
375
+ deleteItemState: (fetchParams: ItemPayload | ItemPayload[] | CollectionFilterItemsFn<ItemState, ItemPayload>) => void;
376
+ /**
377
+ * Runs the full mutation lifecycle: optional optimistic update, async
378
+ * mutation, rollback/error handling, revalidation, and offline queue fallback.
379
+ */
380
+ performMutation: CollectionPerformMutation<ItemState, ItemPayload, TOfflineOperations>;
381
+ /** Notifies the store that a shared transport reconnected and should revalidate active data. */
382
+ onTransportReconnect: () => void;
383
+ };
384
+ export declare function createCollectionStore<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TOfflineOperations extends CollectionOfflineOperationsConfig<ItemState, ItemPayload> = null, StorageState = unknown>(storeOptions: CollectionStoreOptions<ItemState, ItemPayload, TOfflineOperations, StorageState>): CollectionStore<ItemState, ItemPayload, TOfflineOperations>;
385
+ export {};
@@ -0,0 +1,6 @@
1
+ import { Store } from 't-state';
2
+ import { type OfflineAwareFetchController } from '../persistentStorage/offline/fetchRuntime';
3
+ import { BatchRequest, FetchContext } from '../requestScheduler';
4
+ import { type MaybeTSDFResult, StoreError, ValidPayload, ValidStoreState } from '../utils/storeShared';
5
+ import type { TSFDCollectionState } from './collectionStore';
6
+ export declare function executeBatchFetch<ItemState extends ValidStoreState, ItemPayload extends ValidPayload>(requests: BatchRequest<ItemPayload>[], fetchCtx: FetchContext, store: Store<TSFDCollectionState<ItemState, ItemPayload>>, fetchFn: (params: ItemPayload, signal: AbortSignal) => Promise<MaybeTSDFResult<ItemState>>, batchFetchFn: ((payloads: ItemPayload[], signal: AbortSignal, batchKey: string) => Promise<MaybeTSDFResult<Map<ItemPayload, MaybeTSDFResult<ItemState> | Error>>>) | undefined, errorNormalizer: (exception: Error) => StoreError, batchKey?: string, offlineController?: OfflineAwareFetchController | null): Promise<Map<string, boolean>>;
@@ -0,0 +1,15 @@
1
+ import { Store } from 't-state';
2
+ import { FetchType } from '../requestScheduler';
3
+ import { ValidPayload, ValidStoreState } from '../utils/storeShared';
4
+ import type { CollectionUseMultipleItemsQuery, TSFDCollectionState, TSFDUseCollectionItemReturn } from './collectionStore';
5
+ import { UseMultipleItemsOptions } from './useMultipleItems';
6
+ export type UseItemOptions<ItemState extends ValidStoreState, Selected> = UseMultipleItemsOptions<ItemState, Selected> & {
7
+ /**
8
+ * Unconditionally schedules a high-priority fetch on mount and reports
9
+ * `loading` until that refresh succeeds or fails, even when cached data
10
+ * exists. Use sparingly because each mount can cause an extra request.
11
+ * Cannot be combined with `debouncePayload`.
12
+ */
13
+ requireFreshData?: boolean;
14
+ };
15
+ export declare function useItem<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, Selected = ItemState | null>(payload: ItemPayload | undefined | false | null, { omitPayload, selector, requireFreshData, returnRefetchingStatus, disableRefetches, disableRefetchOnMount, returnIdleStatus, isOffScreen, debouncePayload }: UseItemOptions<ItemState, Selected>, store: Store<TSFDCollectionState<ItemState, ItemPayload>>, scheduleFetch: (fetchType: FetchType, payload: ItemPayload) => void, useMultipleItems: <S = ItemState | null>(items: CollectionUseMultipleItemsQuery<ItemPayload, undefined>[], options: UseMultipleItemsOptions<ItemState, S>) => readonly TSFDUseCollectionItemReturn<S, ItemPayload, undefined>[]): TSFDUseCollectionItemReturn<Selected, ItemPayload>;
@@ -0,0 +1,35 @@
1
+ import { type Emitter } from 'evtmitter';
2
+ import { Store } from 't-state';
3
+ import type { GlobalOfflineEntity } from '../persistentStorage/offline/types';
4
+ import { FetchType } from '../requestScheduler';
5
+ import { type PayloadDebounce, ValidPayload, ValidStoreState } from '../utils/storeShared';
6
+ import type { CollectionStoreEvents, CollectionUseMultipleItemsQuery, TSFDCollectionItem, TSFDCollectionState, TSFDUseCollectionItemReturn } from './collectionStore';
7
+ export type UseMultipleItemsOptions<ItemState extends ValidStoreState, Selected> = {
8
+ /** Maps each item before it is returned from the hook. */
9
+ selector?: (data: ItemState | null) => Selected;
10
+ /** Returns `idle` instead of `loading` while items have not been fetched. */
11
+ returnIdleStatus?: boolean;
12
+ /** Returns `refetching` instead of keeping `loaded` status during refetches. */
13
+ returnRefetchingStatus?: boolean;
14
+ /** Omits `payload` from each query result unless overridden per item. */
15
+ omitPayload?: boolean;
16
+ /**
17
+ * Only fetches when an item is missing from state, skipping stale-state and
18
+ * invalidation refetches.
19
+ */
20
+ disableRefetches?: boolean;
21
+ /** Prevents automatic mount refetches for stale loaded data. */
22
+ disableRefetchOnMount?: boolean;
23
+ /** Marks these subscriptions as off-screen, lowering automatic fetch priority. */
24
+ isOffScreen?: boolean;
25
+ /**
26
+ * Debounces automatic fetches caused by payload changes, while selection
27
+ * still reads from the latest payload. Supports trailing debounce via `ms`,
28
+ * optional `leading`, and optional `maxWait`.
29
+ */
30
+ debouncePayload?: PayloadDebounce;
31
+ };
32
+ export declare function useMultipleItems<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, Selected = ItemState | null, QueryMetadata extends undefined | Record<string, unknown> = undefined>(items: CollectionUseMultipleItemsQuery<ItemPayload, QueryMetadata>[], { selector, returnIdleStatus: allItemsReturnIdleStatus, returnRefetchingStatus: allItemsReturnRefetchingStatus, omitPayload: allItemsOmitPayload, disableRefetches: allItemsDisableRefetches, disableRefetchOnMount: allItemsDisableRefetchOnMount, isOffScreen: allItemsIsOffScreen, debouncePayload }: UseMultipleItemsOptions<ItemState, Selected>, store: Store<TSFDCollectionState<ItemState, ItemPayload>>, events: Emitter<CollectionStoreEvents>, getItemKey: (params: ItemPayload) => string, getItemState: (payload: ItemPayload) => TSFDCollectionItem<ItemState, ItemPayload> | null | undefined, readFallbackItemState: ((itemKey: string) => TSFDCollectionItem<ItemState, ItemPayload> | null | undefined) | undefined, registerActiveItems: (itemKeys: string[]) => () => void, touchItems: (itemKeys: string[]) => void, preloadItems: ((payloads: ItemPayload[]) => Promise<boolean[]>) | undefined, preloadItemsBeforePaint: boolean, scheduleAutomaticFetch: (fetchType: FetchType, payload: ItemPayload) => void, invalidationWasTriggered: Set<string>, globalDisableRefetchOnMount: boolean | undefined, offlineEntities: readonly GlobalOfflineEntity[], offlineOverlays: Readonly<Record<string, {
33
+ data: ItemState | null;
34
+ payload?: ItemPayload;
35
+ }>>): readonly TSFDUseCollectionItemReturn<Selected, ItemPayload, QueryMetadata>[];
@@ -0,0 +1,30 @@
1
+ /** Debug log severity used to choose the default console method. */
2
+ export type TSDFDebugLogLevel = 'log' | 'warn' | 'error';
3
+ /** Internal subsystem that emitted a debug log entry. */
4
+ export type TSDFDebugLogArea = 'browser-tabs' | 'focus' | 'persistent-storage';
5
+ /** Operations emitted by focus lifecycle handling. */
6
+ export type TSDFFocusDebugOperation = 'window-focus-revalidate';
7
+ /** Operations emitted by the persistent storage subsystem. */
8
+ export type TSDFPersistentStorageDebugOperation = 'clear' | 'commit' | 'list-keys' | 'list-metadata' | 'list-metadata-by-filter' | 'load' | 'load-many' | 'adapter-operation' | 'quota-cleanup' | 'read-entry' | 'read-protected-keys' | 'remove' | 'save' | 'schedule-save' | 'sync-load' | 'sync-protected-keys' | 'write';
9
+ /** Operations emitted by the browser-tab sync subsystem. */
10
+ export type TSDFBrowserTabsDebugOperation = 'leader-change' | 'publish' | 'publish-skipped' | 'receive' | 'receive-skipped' | 'session-change' | 'transport-close' | 'transport-open' | 'transport-unavailable';
11
+ /** Structured debug log entry emitted by TSDF internals. */
12
+ export type TSDFDebugLogEntry = {
13
+ /** Subsystem that emitted the entry. */
14
+ area: TSDFDebugLogArea;
15
+ /** Severity of the entry. */
16
+ level: TSDFDebugLogLevel;
17
+ /** Human-readable summary of the operation. */
18
+ message: string;
19
+ /** Stable operation id, such as `publish`, `load`, or `write`. */
20
+ operation: TSDFFocusDebugOperation | TSDFPersistentStorageDebugOperation | TSDFBrowserTabsDebugOperation;
21
+ /** Structured operation metadata for filtering and diagnostics. */
22
+ details?: Readonly<Record<string, unknown>>;
23
+ };
24
+ /** Custom debug logger invoked for each emitted TSDF debug entry. */
25
+ export type TSDFDebugLogger = (entry: TSDFDebugLogEntry) => void;
26
+ /** Logger option used by manager-wide debug and production-signal logging. */
27
+ export type TSDFLoggerOptions = boolean | TSDFDebugLogger;
28
+ export declare function resolveTSDFLogger(logger: TSDFLoggerOptions | undefined): TSDFDebugLogger | undefined;
29
+ export declare function emitTSDFDebugLog(logger: TSDFDebugLogger | undefined, entry: TSDFDebugLogEntry): void;
30
+ export declare function getTSDFDebugTimingMs(): number;