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,412 @@
1
+ import type { __LEGIT_ANY__ } from '@ls-stack/utils/saferTyping';
2
+ import type { StandardSchemaV1 } from '@standard-schema/spec';
3
+ import { type RcType } from 'runcheck';
4
+ import type { TSDFDebugLogger } from '../debug';
5
+ import type { ItemLoadedFields } from '../listQueryStore/types';
6
+ import type { ValidPayload, ValidStoreState } from '../utils/storeShared';
7
+ import type { AnyOfflineOperationDefinition, CollectionOfflineEntityRef, ListQueryOfflineEntityRef, OfflineSession } from './offline/types';
8
+ /** Logical namespaces used by managed async persistent storage. */
9
+ export type AsyncStorageNamespaceKind = 'document' | 'collection.item' | 'listQuery.item' | 'listQuery.query' | 'offline.queue' | 'offline.conflict' | 'offline.entity' | '__internal.protected';
10
+ export declare function parseAsyncStorageNamespaceKind(value: string): AsyncStorageNamespaceKind | null;
11
+ /** Identifies one logical persistent-storage namespace. */
12
+ export type AsyncStorageNamespaceScope = {
13
+ /** Session key owning this namespace. */
14
+ sessionKey: string;
15
+ /** Store id owning this namespace. */
16
+ storeName: string;
17
+ /** Type of records stored in this namespace. */
18
+ kind: AsyncStorageNamespaceKind;
19
+ };
20
+ export type AsyncStorageProtectedEntryRef = AsyncStorageNamespaceScope & {
21
+ key: string;
22
+ };
23
+ export type AsyncStorageTouchMode = 'never' | 'coarse' | 'force';
24
+ /** Read behavior for managed async namespace operations. */
25
+ export type AsyncStorageReadOptions = {
26
+ /** Whether reading should update LRU access metadata. */
27
+ touch?: AsyncStorageTouchMode;
28
+ };
29
+ /** Sort order for listing async storage metadata. */
30
+ export type AsyncStorageMetadataOrder = 'key' | 'lru-asc' | 'lru-desc';
31
+ export type AsyncStorageEntryMetadataBase = {
32
+ key: string;
33
+ payloadRef: string;
34
+ writtenAt: number;
35
+ lastAccessAt: number;
36
+ /** Serialized JSON size used for persistence budgeting for this entry. */
37
+ sizeBytes?: number;
38
+ version: number;
39
+ };
40
+ export type AsyncStorageEntryMetadata<TCustomMetadata extends Record<string, unknown> = Record<string, unknown>> = AsyncStorageEntryMetadataBase & {
41
+ customMetadata: TCustomMetadata;
42
+ };
43
+ /** Value and metadata returned from a managed async namespace read. */
44
+ export type AsyncStorageNamespaceGetResult<TValue, TCustomMetadata extends Record<string, unknown> = Record<string, unknown>> = {
45
+ /** Stored value decoded from the namespace. */
46
+ value: TValue;
47
+ /** Managed metadata associated with the stored value. */
48
+ metadata: AsyncStorageEntryMetadata<TCustomMetadata>;
49
+ };
50
+ /** Upsert entry committed to a managed async namespace. */
51
+ export type AsyncStorageNamespaceCommitUpsert<TValue, TCustomMetadata extends Record<string, unknown> = Record<string, unknown>> = {
52
+ /** Raw namespace key to write. */
53
+ key: string;
54
+ /** Decoded value to store. */
55
+ value: TValue;
56
+ /** Pre-serialized JSON string, when the caller already has it. */
57
+ serializedValue?: string;
58
+ /** Serialized JSON size used for persistence budgeting. */
59
+ sizeBytes?: number;
60
+ /** Cache version associated with this value. */
61
+ version: number;
62
+ /** Custom metadata stored alongside the value. */
63
+ metadata?: TCustomMetadata;
64
+ };
65
+ /** Touch entry committed to update managed async namespace LRU metadata. */
66
+ export type AsyncStorageNamespaceCommitTouch = {
67
+ /** Raw namespace key to touch. */
68
+ key: string;
69
+ /** Explicit access timestamp. Defaults to the adapter's current time. */
70
+ lastAccessAt?: number;
71
+ };
72
+ /**
73
+ * Remove committed only while the stored entry still has the metadata the
74
+ * caller last read, so cleanup never acts on an outdated view of an entry.
75
+ */
76
+ export type AsyncStorageNamespaceCommitConditionalRemove = {
77
+ /** Raw namespace key to remove. */
78
+ key: string;
79
+ /** Expected access timestamp. */
80
+ lastAccessAt: number;
81
+ /** Expected serialized size, `undefined` when the entry has none. */
82
+ sizeBytes: number | undefined;
83
+ /** Expected cache version. */
84
+ version: number;
85
+ /** Expected offline protection state. */
86
+ offlineProtected: boolean;
87
+ };
88
+ export type AsyncStorageNamespaceStaticPolicy = {
89
+ maxBytes?: number;
90
+ pinnedKeys?: string[];
91
+ };
92
+ /** Batched write/remove/touch operation for a managed async namespace. */
93
+ export type AsyncStorageNamespaceCommitArgs<TValue, TCustomMetadata extends Record<string, unknown> = Record<string, unknown>> = {
94
+ /** Entries to create or replace. */
95
+ upserts?: AsyncStorageNamespaceCommitUpsert<TValue, TCustomMetadata>[];
96
+ /** Raw namespace keys to remove. */
97
+ removes?: string[];
98
+ /** Static cleanup policy applied during this commit. */
99
+ staticPolicy?: AsyncStorageNamespaceStaticPolicy | null;
100
+ /** Existing entries whose access metadata should be updated. */
101
+ touches?: AsyncStorageNamespaceCommitTouch[];
102
+ };
103
+ /**
104
+ * Internal commit args used by adapters built with `createAsyncStorageAdapter`
105
+ * and their managed drivers.
106
+ */
107
+ export type ManagedAsyncStorageNamespaceCommitArgs<TValue, TCustomMetadata extends Record<string, unknown> = Record<string, unknown>> = AsyncStorageNamespaceCommitArgs<TValue, TCustomMetadata> & {
108
+ /**
109
+ * Keys to remove only if their stored metadata still matches, checked in the
110
+ * same write as the removal. Entries that changed meanwhile, or that the
111
+ * driver cannot verify, are kept and reported back as stale.
112
+ */
113
+ conditionalRemoves?: AsyncStorageNamespaceCommitConditionalRemove[];
114
+ };
115
+ export type AsyncStorageMaintenanceState = {
116
+ lastSuccessfulCleanupAt: number | null;
117
+ };
118
+ /** Raw entry passed to low-level async storage driver bulk writes. */
119
+ export type AsyncStorageDriverSetEntry = {
120
+ /** Raw record key to write. */
121
+ key: string;
122
+ /** Raw value to store. */
123
+ value: unknown;
124
+ /** Pre-serialized JSON string, when available. */
125
+ serializedValue?: string;
126
+ /** Serialized value size used for budgeting. */
127
+ sizeBytes?: number;
128
+ };
129
+ /** Scope discovered by a low-level async storage driver. */
130
+ export type AsyncStorageDiscoveredScope = {
131
+ /** Known raw record keys for this scope. `null` if keys were not enumerated during discovery. */
132
+ knownRecordKeys: string[] | null;
133
+ /** Discovered namespace scope. */
134
+ scope: AsyncStorageNamespaceScope;
135
+ };
136
+ /** Low-level async backend contract implemented by custom storage drivers. */
137
+ export type AsyncStorageDriver = {
138
+ /** Mutable debug logger used by concrete adapters to emit operation timings. */
139
+ debugLogger?: TSDFDebugLogger;
140
+ /** Mutable logger used for low-volume production signals. */
141
+ logger?: TSDFDebugLogger;
142
+ /** Read a single raw record from a logical namespace. */
143
+ get(scope: AsyncStorageNamespaceScope, key: string): Promise<unknown>;
144
+ /** Write a single raw record to a logical namespace. */
145
+ set(scope: AsyncStorageNamespaceScope, key: string, value: unknown): Promise<void>;
146
+ /** Remove a single raw record from a logical namespace. */
147
+ remove(scope: AsyncStorageNamespaceScope, key: string): Promise<void>;
148
+ /** List raw record keys within a logical namespace. */
149
+ listKeys(scope: AsyncStorageNamespaceScope): Promise<string[]>;
150
+ /** Remove every record from a logical namespace. */
151
+ clear(scope: AsyncStorageNamespaceScope): Promise<void>;
152
+ /** Namespace discovery used for cold cleanup, protected-key restore, and session clearing. */
153
+ listScopes(sessionKey?: string): Promise<AsyncStorageNamespaceScope[]>;
154
+ /** Returns discovered scopes together with known raw record keys. Used for cleanup. */
155
+ listScopesWithKnownRecordKeys(sessionKey?: string): Promise<AsyncStorageDiscoveredScope[]>;
156
+ /** Bulk read for multiple keys in a single call. */
157
+ getMany(scope: AsyncStorageNamespaceScope, keys: string[]): Promise<unknown[]>;
158
+ /** Bulk write for multiple entries in a single call. */
159
+ setMany(scope: AsyncStorageNamespaceScope, entries: AsyncStorageDriverSetEntry[]): Promise<void>;
160
+ /** Bulk remove for multiple keys in a single call. */
161
+ removeMany(scope: AsyncStorageNamespaceScope, keys: string[]): Promise<void>;
162
+ };
163
+ /** Managed namespace handle opened by an async storage adapter. */
164
+ export type AsyncStorageNamespaceHandle<TValue, TCustomMetadata extends Record<string, unknown> = Record<string, unknown>> = {
165
+ /** Reads one decoded value and metadata by raw namespace key. */
166
+ get(key: string, options?: AsyncStorageReadOptions): Promise<AsyncStorageNamespaceGetResult<TValue, TCustomMetadata> | null>;
167
+ /** Reads many decoded values and metadata records by raw namespace key. */
168
+ getMany(keys: string[], options?: AsyncStorageReadOptions): Promise<Array<AsyncStorageNamespaceGetResult<TValue, TCustomMetadata> | null>>;
169
+ /** Lists raw record keys in this namespace. */
170
+ listKeys(): Promise<string[]>;
171
+ /** Applies batched writes, removes, touches, and cleanup policy changes. */
172
+ commit(args: AsyncStorageNamespaceCommitArgs<TValue, TCustomMetadata>): Promise<void>;
173
+ /** Lists metadata for all records in this namespace. */
174
+ listMetadata(args?: {
175
+ order?: AsyncStorageMetadataOrder;
176
+ }): Promise<AsyncStorageEntryMetadata<TCustomMetadata>[]>;
177
+ /** Lists metadata matching a custom metadata equality filter. */
178
+ listMetadataByFilter?(args: {
179
+ filter: {
180
+ equals: unknown;
181
+ key: string;
182
+ };
183
+ order?: AsyncStorageMetadataOrder;
184
+ }): Promise<AsyncStorageEntryMetadata<TCustomMetadata>[]>;
185
+ /** Removes every record in this namespace. */
186
+ clear(): Promise<void>;
187
+ };
188
+ /** Managed async adapter consumed by TSDF persistence internals. */
189
+ export type AsyncStorageAdapter = {
190
+ /** Adapter mode marker used by persistence internals to pick async behavior. */
191
+ kind: 'async';
192
+ /** Mutable debug logger used by concrete adapters to emit operation timings. */
193
+ debugLogger?: TSDFDebugLogger;
194
+ /** Mutable logger used for low-volume production signals. */
195
+ logger?: TSDFDebugLogger;
196
+ /** Open a logical namespace with managed batching and touch guarantees. */
197
+ openNamespace<TValue, TCustomMetadata extends Record<string, unknown> = Record<string, unknown>>(scope: AsyncStorageNamespaceScope): AsyncStorageNamespaceHandle<TValue, TCustomMetadata>;
198
+ /** Reconstruct offline-protected entry refs for a session from persisted metadata. */
199
+ readProtectedStorageKeys(sessionKey: string): Promise<Set<string>>;
200
+ /** Eagerly sync offline protection changes into persisted metadata for already-cached entries. */
201
+ syncSessionProtectedKeys(sessionKey: string, protectedKeys: Iterable<string>, previousProtectedKeys?: Iterable<string>): Promise<void>;
202
+ /** Remove all namespaces for a session key. */
203
+ clearSession(sessionKey: string): Promise<void>;
204
+ /** Test-only reset hook used by TSDF internals. */
205
+ resetForTests?(): void;
206
+ };
207
+ /** Injected persistent storage adapter. */
208
+ export type StorageAdapter = 'local-sync' | AsyncStorageAdapter;
209
+ /** Standard Schema v1 (zod, valibot, arktype, etc.). */
210
+ export type StandardSchemaLike<T> = StandardSchemaV1<unknown, T>;
211
+ /** Union of supported schema types for persistent storage validation. */
212
+ export type PersistentStorageSchema<T> = RcType<T> | StandardSchemaLike<T>;
213
+ /**
214
+ * Converts between the in-memory store data shape and the persisted storage shape.
215
+ * Use this when the cached representation should differ from the API store format.
216
+ */
217
+ export type ConvertedPersistentStorageDataSchema<TFinal, TStorage> = {
218
+ /** Schema for the final in-memory store data after hydration. */
219
+ storeSchema: PersistentStorageSchema<TFinal>;
220
+ /** Schema for the raw persisted storage representation. */
221
+ storageSchema: PersistentStorageSchema<TStorage>;
222
+ /** Converts in-memory store data into the persisted storage representation. */
223
+ convertToStorage: (value: TFinal) => TStorage;
224
+ /** Converts persisted storage data into the final in-memory store representation. */
225
+ convertFromStorage: (value: TStorage) => TFinal;
226
+ };
227
+ /**
228
+ * Schema configuration for persisted store data.
229
+ * Accept either the final store schema directly or a converted storage format.
230
+ */
231
+ export type PersistentStorageDataSchema<TFinal, TStorage = unknown> = PersistentStorageSchema<TFinal> | ConvertedPersistentStorageDataSchema<TFinal, TStorage>;
232
+ export type StorageCacheEntry<T> = {
233
+ /** Cached payload persisted for this key. */
234
+ data: T;
235
+ /** Epoch timestamp used for age-based maintenance. */
236
+ timestamp: number;
237
+ /** Optional user-configured cache version used for migration-safe hydration. */
238
+ version?: number;
239
+ };
240
+ /** Result entry returned by explicit persistent-storage preload APIs. */
241
+ export type PersistentStoragePreloadResult<Payload extends ValidPayload = ValidPayload> = {
242
+ /** Payload loaded from storage or fresh store initialization result. */
243
+ payload: Payload;
244
+ /** `true` when payload came from storage cache, `false` when loaded from source. */
245
+ preloaded: boolean;
246
+ };
247
+ export type PersistentStorageErrorHandler = (error: unknown) => void;
248
+ /** Base config shared by all store types. */
249
+ export type PersistentStorageBaseConfig<TFinal, TStorage = unknown> = {
250
+ /** Unique storage namespace used internally for this store's persisted entries. Must not contain `.`. */
251
+ storeName: string;
252
+ /** Injected adapter used to save and restore persistent data. Use `'local-sync'` for built-in localStorage or provide a custom async adapter. */
253
+ adapter: StorageAdapter;
254
+ /** Schema used to validate cached data on load and optionally convert persisted data. */
255
+ schema: PersistentStorageDataSchema<TFinal, TStorage>;
256
+ /** Optional version number for cache invalidation. When omitted, no version is persisted or checked. */
257
+ version?: number;
258
+ /**
259
+ * Returns a session key scoping storage per org/tenant.
260
+ * Return `false` to indicate the session is not ready — all storage
261
+ * operations (load, save, clear) will be skipped until it returns a string.
262
+ */
263
+ getSessionKey: () => string | false;
264
+ /**
265
+ * Called when a storage write operation fails (e.g. quota exceeded, OPFS write error).
266
+ * Use this to log or report persistence failures to your error tracking service.
267
+ */
268
+ onPersistentStorageError?: PersistentStorageErrorHandler | null;
269
+ };
270
+ /** Store-level persistent storage config. Session scoping comes from the parent store. */
271
+ type StorePersistentStorageBaseConfig<TFinal, TStorage = unknown> = Omit<PersistentStorageBaseConfig<TFinal, TStorage>, 'getSessionKey' | 'storeName'>;
272
+ type InternalDocumentOfflineOperations<State extends ValidStoreState> = Record<string, AnyOfflineOperationDefinition<__LEGIT_ANY__>> & ([State] extends [never] ? never : unknown);
273
+ type DocumentOfflineOperationsConfig<State extends ValidStoreState> = InternalDocumentOfflineOperations<State> | null;
274
+ type PublicStoreOfflineConfig<TOperations extends Record<string, AnyOfflineOperationDefinition<__LEGIT_ANY__>> = Record<never, never>> = {
275
+ /** Store-local offline operation definitions. Optional when only session-level offline controls are used. */
276
+ operations?: TOperations;
277
+ };
278
+ type PublicStoreOfflineConfigField<TOfflineOperations extends Record<string, AnyOfflineOperationDefinition<__LEGIT_ANY__>> | null> = {
279
+ /** Optional offline sync/replay configuration for mutations. */
280
+ offline?: TOfflineOperations extends null ? PublicStoreOfflineConfig : PublicStoreOfflineConfig<Exclude<TOfflineOperations, null>>;
281
+ };
282
+ type ResolvedStoreOfflineConfig<TOperations extends Record<string, AnyOfflineOperationDefinition> = Record<never, never>> = PublicStoreOfflineConfig<TOperations> & {
283
+ /** Shared session-level offline policy and runtime controls. */
284
+ session: OfflineSession;
285
+ };
286
+ type ResolvedStoreOfflineConfigField<TOfflineOperations extends Record<string, AnyOfflineOperationDefinition> | null> = {
287
+ /** Internal resolved offline config with the manager-owned session attached. */
288
+ offline?: TOfflineOperations extends null ? ResolvedStoreOfflineConfig : ResolvedStoreOfflineConfig<Exclude<TOfflineOperations, null>>;
289
+ };
290
+ /** Persistent storage config for DocumentStore. */
291
+ export type DocumentPersistentStorageConfig<State extends ValidStoreState, StorageState = unknown, TOfflineOperations extends DocumentOfflineOperationsConfig<State> = null> = StorePersistentStorageBaseConfig<State, StorageState> & PublicStoreOfflineConfigField<TOfflineOperations>;
292
+ type ResolvedStorePersistentStorageBaseConfig<TFinal, TStorage = unknown> = Omit<StorePersistentStorageBaseConfig<TFinal, TStorage>, 'onPersistentStorageError'> & {
293
+ /** Internal resolved namespace reused from the parent store id. */
294
+ storeName: string;
295
+ /** Internal resolved session scoping reused from the parent store. */
296
+ getSessionKey: () => string | false;
297
+ /** Store-specific handler or manager fallback. `undefined` means errors are ignored. */
298
+ onPersistentStorageError?: PersistentStorageErrorHandler;
299
+ /** Manager-owned debug logger for persistence internals. */
300
+ debugLogger?: TSDFDebugLogger;
301
+ /** Manager-owned logger for low-volume production signals. */
302
+ logger?: TSDFDebugLogger;
303
+ };
304
+ export type ResolvedDocumentPersistentStorageConfig<State extends ValidStoreState, StorageState = unknown, TOfflineOperations extends DocumentOfflineOperationsConfig<State> = null> = ResolvedStorePersistentStorageBaseConfig<State, StorageState> & ResolvedStoreOfflineConfigField<TOfflineOperations>;
305
+ type InternalCollectionOfflineOperations<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = Record<string, AnyOfflineOperationDefinition<__LEGIT_ANY__> & {
306
+ getEntityRefs: (ctx: {
307
+ input: __LEGIT_ANY__;
308
+ }) => CollectionOfflineEntityRef<ItemPayload>[];
309
+ dependsOn?: (ctx: {
310
+ input: __LEGIT_ANY__;
311
+ }) => CollectionOfflineEntityRef<ItemPayload>[];
312
+ }> & ([ItemState | ItemPayload] extends [never] ? never : unknown);
313
+ type CollectionOfflineOperationsConfig<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = InternalCollectionOfflineOperations<ItemState, ItemPayload> | null;
314
+ type CollectionPersistentStorageFields<ItemPayload extends ValidPayload> = {
315
+ /** Schema used to validate cached item payloads on load. */
316
+ payloadSchema: PersistentStorageSchema<ItemPayload>;
317
+ /**
318
+ * Maximum serialized JSON size to persist for collection items. Budgeting
319
+ * uses the serialized string length, not browser quota bytes. Items are
320
+ * evicted via LRU. Defaults to 64 KB in `local-sync` and 128 KB in async
321
+ * adapters.
322
+ */
323
+ maxBytes?: number;
324
+ /** Item payloads that should never be evicted from storage. */
325
+ pinnedItems?: ItemPayload[];
326
+ /**
327
+ * Item payloads that should never be persisted or restored.
328
+ * Accepts either an explicit payload list or a predicate function.
329
+ * Takes precedence over `pinnedItems`.
330
+ */
331
+ ignoreItems?: ItemPayload[] | ((payload: ItemPayload) => boolean);
332
+ };
333
+ /** Persistent storage config for CollectionStore. */
334
+ export type CollectionPersistentStorageConfig<ItemState extends ValidStoreState, ItemPayload extends ValidPayload = ValidPayload, StorageState = unknown, TOfflineOperations extends CollectionOfflineOperationsConfig<ItemState, ItemPayload> = null> = StorePersistentStorageBaseConfig<ItemState, StorageState> & PublicStoreOfflineConfigField<TOfflineOperations> & CollectionPersistentStorageFields<ItemPayload>;
335
+ export type ResolvedCollectionPersistentStorageConfig<ItemState extends ValidStoreState, ItemPayload extends ValidPayload = ValidPayload, StorageState = unknown, TOfflineOperations extends CollectionOfflineOperationsConfig<ItemState, ItemPayload> = null> = ResolvedStorePersistentStorageBaseConfig<ItemState, StorageState> & ResolvedStoreOfflineConfigField<TOfflineOperations> & CollectionPersistentStorageFields<ItemPayload>;
336
+ export type InternalListQueryOfflineOperations<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = Record<string, AnyOfflineOperationDefinition<__LEGIT_ANY__> & {
337
+ getEntityRefs: (ctx: {
338
+ input: __LEGIT_ANY__;
339
+ }) => ListQueryOfflineEntityRef<ItemPayload>[];
340
+ dependsOn?: (ctx: {
341
+ input: __LEGIT_ANY__;
342
+ }) => ListQueryOfflineEntityRef<ItemPayload>[];
343
+ }> & ([ItemState | QueryPayload | ItemPayload] extends [never] ? never : unknown);
344
+ export type ListQueryOfflineOperationsConfig<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = InternalListQueryOfflineOperations<ItemState, QueryPayload, ItemPayload> | null;
345
+ type ListQueryPersistentStorageFields<QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = {
346
+ /** Schema used to validate cached item payloads on load. */
347
+ itemPayloadSchema: PersistentStorageSchema<ItemPayload>;
348
+ /** Schema used to validate cached query payloads on load. */
349
+ queryPayloadSchema: PersistentStorageSchema<QueryPayload>;
350
+ /**
351
+ * Maximum serialized JSON size to persist for list items. Budgeting uses the
352
+ * serialized string length, not browser quota bytes. Defaults to 64 KB in
353
+ * `local-sync` and 128 KB in async adapters.
354
+ */
355
+ maxItemBytes?: number;
356
+ /**
357
+ * Maximum serialized JSON size to persist for list queries. Budgeting uses
358
+ * the serialized string length, not browser quota bytes. Defaults to 32 KB
359
+ * in `local-sync` and 64 KB in async adapters.
360
+ */
361
+ maxQueryBytes?: number;
362
+ /** Maximum number of items per query to persist. Defaults to 100. */
363
+ maxQuerySize?: number;
364
+ /** Item payloads that should never be evicted from storage. */
365
+ pinnedItems?: ItemPayload[];
366
+ /** Query payloads that should never be evicted from storage. */
367
+ pinnedQueries?: QueryPayload[];
368
+ /**
369
+ * Item payloads that should never be persisted or restored.
370
+ * Accepts either an explicit payload list or a predicate function.
371
+ * Takes precedence over `pinnedItems`.
372
+ */
373
+ ignoreItems?: ItemPayload[] | ((payload: ItemPayload) => boolean);
374
+ };
375
+ /** Persistent storage config for ListQueryStore. */
376
+ export 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>;
377
+ export type ResolvedListQueryPersistentStorageConfig<ItemState extends ValidStoreState, QueryPayload extends ValidPayload = ValidPayload, ItemPayload extends ValidPayload = ValidPayload, StorageState = unknown, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload> = null> = ResolvedStorePersistentStorageBaseConfig<ItemState, StorageState> & ResolvedStoreOfflineConfigField<TOfflineOperations> & ListQueryPersistentStorageFields<QueryPayload, ItemPayload>;
378
+ /** Shape of persisted data for DocumentStore. */
379
+ export type PersistedDocumentData<State> = {
380
+ /** Persisted document state snapshot. */
381
+ data: State;
382
+ };
383
+ /** Shape of a single persisted collection item entry. */
384
+ export type PersistedCollectionItemData<State> = {
385
+ /** Persisted collection item state snapshot. */
386
+ data: State;
387
+ /** Payload stored alongside the item for validation and retrieval. */
388
+ payload: unknown;
389
+ };
390
+ /** Shape of a single persisted list item entry. */
391
+ export type PersistedListQueryItemData<State> = {
392
+ /** Persisted list item state snapshot. */
393
+ data: State;
394
+ /** Payload stored to validate and rehydrate item queries. */
395
+ payload: unknown;
396
+ /**
397
+ * Loaded-fields metadata for the item: a list of selected fields that were
398
+ * loaded, or `'*'` when the item is fully loaded. Absent when the item has
399
+ * no loaded-fields metadata (`inferFields` governs such snapshots).
400
+ */
401
+ loadedFields?: ItemLoadedFields;
402
+ };
403
+ /** Shape of a single persisted list query entry. */
404
+ export type PersistedListQueryData = {
405
+ /** Persisted query payload. */
406
+ payload: unknown;
407
+ /** Ordered list of item IDs included in the cached query page. */
408
+ items: string[];
409
+ /** Whether the query has additional pages available. */
410
+ hasMore: boolean;
411
+ };
412
+ export {};
@@ -0,0 +1,12 @@
1
+ import type { StandardSchemaV1 } from '@standard-schema/spec';
2
+ import { type Result as ResultType } from 't-result';
3
+ import type { PersistentStorageSchema } from './types';
4
+ export type SchemaValidationError = readonly string[] | StandardSchemaV1.FailureResult['issues'];
5
+ export declare function parseWithSchema<T>(schema: PersistentStorageSchema<T>, data: unknown): ResultType<T, SchemaValidationError>;
6
+ /**
7
+ * Validates data against a schema.
8
+ * Supports runcheck (RcType) and Standard Schema v1 (~standard.validate()).
9
+ *
10
+ * @returns The validated data if valid, or null if validation fails.
11
+ */
12
+ export declare function validateWithSchema<T>(schema: PersistentStorageSchema<T>, data: unknown): T | null;
@@ -0,0 +1,81 @@
1
+ export type FetchContext = {
2
+ shouldAbort: () => boolean;
3
+ getStartTime: () => number;
4
+ signal: AbortSignal;
5
+ };
6
+ export type RequestSchedulerEvents = 'scheduled-fetch-started' | 'rt-fetch-scheduled' | 'rt-fetch-cancelled' | 'scheduled-rt-fetch-started' | 'medium-priority-scheduled' | 'medium-priority-fetch-started' | 'medium-priority-cancelled' | 'batch-size-triggered';
7
+ export type RequestSchedulerEventData = {
8
+ /** Delay in ms for scheduled events (medium-priority-scheduled, rt-fetch-scheduled) */
9
+ delayMs?: number;
10
+ };
11
+ export type ScheduleFetchResults = 'skipped' | 'started' | 'scheduled' | 'rt-scheduled' | 'triggered' | 'coalesced' | 'medium-scheduled' | 'added-to-batch' | 'batch-triggered';
12
+ export type FetchType = 'lowPriority' | 'mediumPriority' | 'highPriority' | 'realtimeUpdate';
13
+ /** Request with ID for batch fetching */
14
+ export type BatchRequest<T> = {
15
+ requestId: string;
16
+ payload: T;
17
+ };
18
+ type PendingRequestMatcher<T> = (request: {
19
+ requestId: string;
20
+ payload: T;
21
+ priority: FetchType;
22
+ addedAt: number;
23
+ }) => boolean;
24
+ type RequestSchedulerOptions<T> = {
25
+ /** Fetch function receives array of requests (even for single request) */
26
+ fetchFn: (requests: BatchRequest<T>[], fetchContext: FetchContext) => Promise<Map<string, boolean>>;
27
+ on?: (event: RequestSchedulerEvents, data?: RequestSchedulerEventData) => void;
28
+ lowPriorityThrottleMs: number;
29
+ getCoalescingWindowMs: () => number;
30
+ dynamicRealtimeThrottleMs?: (lastFetchDuration: number) => number;
31
+ mediumPriorityDelayMs?: number;
32
+ /** Max batch size - triggers immediate fetch when reached */
33
+ maxBatchSize?: number;
34
+ /** Initial last fetch start time for throttling (e.g., from a query that already loaded this item) */
35
+ initialLastFetchStartTime?: number;
36
+ /** Coalesce payloads when the same requestId is scheduled multiple times.
37
+ * Called with (existing, incoming) and should return the merged payload. */
38
+ coalescePayload?: (existing: T, incoming: T) => T;
39
+ /** for validation of realtimeUpdate fetch type */
40
+ usesRealTimeUpdates: boolean;
41
+ };
42
+ export type ScheduleFetchOptions = {
43
+ mediumPriorityDelayMs?: number;
44
+ };
45
+ export declare function getAutoIncrementId(): number;
46
+ export declare class RequestScheduler<T> {
47
+ #private;
48
+ constructor(options: RequestSchedulerOptions<T>);
49
+ get hasPendingFetch(): boolean;
50
+ /** Whether the request has a fetch in flight, queued or delayed */
51
+ hasPendingRequest(requestId: string): boolean;
52
+ get fetchIsInProgress(): boolean;
53
+ get mutationIsInProgress(): boolean;
54
+ isMutationInProgress(requestId: string): boolean;
55
+ setLastFetchDuration(duration: number): void;
56
+ setLastFetchStartTime(startTime: number): void;
57
+ setLastFetchStartTimeForRequest(requestId: string, startTime: number): void;
58
+ syncExternalFetchStart(requestIds: string[], startedAt: number): void;
59
+ syncExternalFetchSuccess(requestIds: string[], startedAt: number, duration: number): void;
60
+ getFetchIsInProgress(): boolean;
61
+ getCurrentBatchSize(): number;
62
+ scheduleFetch(requestId: string, fetchType: FetchType, payload: T, options?: ScheduleFetchOptions): ScheduleFetchResults;
63
+ awaitFetch(requestId: string, payload: T, options?: {
64
+ timeoutMs?: number;
65
+ }): Promise<boolean | 'timeout'>;
66
+ startMutation(requestId: string): () => boolean;
67
+ /** `markWaitersAborted` resolves callers awaiting the discarded requests as
68
+ * aborted, for store resets where the cleared state says nothing about the
69
+ * resource. Without it they read the store's current state, e.g. not found
70
+ * for a deleted item. */
71
+ reset(markWaitersAborted?: boolean): void;
72
+ /** Re-evaluates the pending delayed realtime update fetch against the
73
+ * current dynamic throttle, rescheduling it sooner (or firing it right away
74
+ * when the recomputed interval has already elapsed). Used when the window
75
+ * regains focus so a refetch priced with the background throttle doesn't
76
+ * keep the tab stale. Never extends the pending delay. */
77
+ reevaluateDelayedRTU(): void;
78
+ cancelCoalescingRequests(requestIds: string[]): boolean;
79
+ cancelPendingRequests(requestIds: string[], shouldCancel?: PendingRequestMatcher<T>): boolean;
80
+ }
81
+ export {};