tsdf 17.0.4 → 17.0.6

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 (251) hide show
  1. package/dist/async-storage.d.ts +1 -1
  2. package/dist/async-storage.js +1 -1
  3. package/dist/{asyncStorageAdapter-CMohMeKm.d.ts → asyncStorageAdapter-DgsuE-T8.d.ts} +1 -1
  4. package/dist/{asyncStorageAdapter-BuGjbXYA.js → asyncStorageAdapter-URS9eulL.js} +165 -25
  5. package/dist/{asyncStorageAdapters-ClUvxNQA.js → asyncStorageAdapters-Bxrrj_Mt.js} +2 -2
  6. package/dist/indexed-db-storage.d.ts +1 -1
  7. package/dist/indexed-db-storage.js +1 -1
  8. package/dist/{indexedDbPersistentStorage-BSlgLveB.js → indexedDbPersistentStorage-BameJ4st.js} +11 -1
  9. package/dist/main.d.ts +34 -30
  10. package/dist/main.js +856 -257
  11. package/dist/opfs-storage.d.ts +1 -1
  12. package/dist/opfs-storage.js +1 -1
  13. package/dist/{opfsPersistentStorage-Ci0JcCo5.d.ts → opfsPersistentStorage-BngS1m0X.d.ts} +1 -1
  14. package/dist/{opfsPersistentStorage-D_k77Srq.js → opfsPersistentStorage-JsSCNBTr.js} +1 -1
  15. package/dist/{types-D0ttVGmj.d.ts → types-BlyGC_PO.d.ts} +3 -3
  16. package/package.json +5 -5
  17. package/dist/src/async-storage.d.ts +0 -1
  18. package/dist/src/cacheLimits/lruCacheRuntime.d.ts +0 -9
  19. package/dist/src/cacheLimits/scheduleIdleThrottled.d.ts +0 -1
  20. package/dist/src/cacheLimits/useRegisterActiveKeys.d.ts +0 -1
  21. package/dist/src/collectionStore/collectionCacheLimits.d.ts +0 -1
  22. package/dist/src/collectionStore/collectionStore.d.ts +0 -385
  23. package/dist/src/collectionStore/executeBatchFetch.d.ts +0 -6
  24. package/dist/src/collectionStore/useItem.d.ts +0 -15
  25. package/dist/src/collectionStore/useMultipleItems.d.ts +0 -35
  26. package/dist/src/debug.d.ts +0 -30
  27. package/dist/src/documentStore.d.ts +0 -290
  28. package/dist/src/hooks/useListItem.d.ts +0 -22
  29. package/dist/src/hooks/useListItemIsDeleted.d.ts +0 -13
  30. package/dist/src/hooks/useListItemIsLoading.d.ts +0 -16
  31. package/dist/src/indexed-db-storage.d.ts +0 -1
  32. package/dist/src/internal/offlineTestInstrumentation.d.ts +0 -12
  33. package/dist/src/internal/testTimelineTypes.d.ts +0 -1
  34. package/dist/src/invalidationUtils.d.ts +0 -8
  35. package/dist/src/isOffScreenContext.d.ts +0 -16
  36. package/dist/src/listQueryStore/createFetchApi.d.ts +0 -1
  37. package/dist/src/listQueryStore/createMutationApi.d.ts +0 -1
  38. package/dist/src/listQueryStore/executeItemBatchFetch.d.ts +0 -20
  39. package/dist/src/listQueryStore/executeQueryFetch.d.ts +0 -7
  40. package/dist/src/listQueryStore/itemFieldUtils.d.ts +0 -77
  41. package/dist/src/listQueryStore/listQueryCacheLimits.d.ts +0 -1
  42. package/dist/src/listQueryStore/listQueryStore.d.ts +0 -538
  43. package/dist/src/listQueryStore/types.d.ts +0 -347
  44. package/dist/src/listQueryStore/useFindItem.d.ts +0 -7
  45. package/dist/src/listQueryStore/useItem.d.ts +0 -29
  46. package/dist/src/listQueryStore/useListQuery.d.ts +0 -29
  47. package/dist/src/listQueryStore/useMultipleItems.d.ts +0 -44
  48. package/dist/src/listQueryStore/useMultipleListQueries.d.ts +0 -46
  49. package/dist/src/listQueryStore/usePendingOfflineItems.d.ts +0 -19
  50. package/dist/src/main.d.ts +0 -23
  51. package/dist/src/opfs-storage.d.ts +0 -1
  52. package/dist/src/persistentStorage/asyncStorageAdapter.d.ts +0 -95
  53. package/dist/src/persistentStorage/asyncStorageAdapters.d.ts +0 -2
  54. package/dist/src/persistentStorage/asyncStorageShared.d.ts +0 -23
  55. package/dist/src/persistentStorage/collectionStorePersistence.d.ts +0 -26
  56. package/dist/src/persistentStorage/compactListQueryLocalStorageEntry.d.ts +0 -11
  57. package/dist/src/persistentStorage/compactLocalStorageEntry.d.ts +0 -8
  58. package/dist/src/persistentStorage/documentEntryKey.d.ts +0 -1
  59. package/dist/src/persistentStorage/documentStorePersistence.d.ts +0 -17
  60. package/dist/src/persistentStorage/indexedDbAsyncStorageAdapter.d.ts +0 -165
  61. package/dist/src/persistentStorage/indexedDbPersistentStorage.d.ts +0 -6
  62. package/dist/src/persistentStorage/listQueryStorePersistence.d.ts +0 -37
  63. package/dist/src/persistentStorage/localStorageMetadata.d.ts +0 -126
  64. package/dist/src/persistentStorage/navigatorLocks.d.ts +0 -3
  65. package/dist/src/persistentStorage/offline/entityMetadata.d.ts +0 -12
  66. package/dist/src/persistentStorage/offline/fetchRuntime.d.ts +0 -35
  67. package/dist/src/persistentStorage/offline/mutationRuntime.d.ts +0 -31
  68. package/dist/src/persistentStorage/offline/offlineResolution.typeGuards.d.ts +0 -1
  69. package/dist/src/persistentStorage/offline/overlayStoreLifecycle.d.ts +0 -13
  70. package/dist/src/persistentStorage/offline/sessionCoordinator.d.ts +0 -94
  71. package/dist/src/persistentStorage/offline/sessionProtectionRegistry.d.ts +0 -11
  72. package/dist/src/persistentStorage/offline/storeController.d.ts +0 -86
  73. package/dist/src/persistentStorage/offline/types.d.ts +0 -1255
  74. package/dist/src/persistentStorage/offlineUploadRegistry.d.ts +0 -11
  75. package/dist/src/persistentStorage/offlineUploadTypes.d.ts +0 -97
  76. package/dist/src/persistentStorage/offlineUploadsShared.d.ts +0 -4
  77. package/dist/src/persistentStorage/opfsAsyncStorageAdapter.d.ts +0 -24
  78. package/dist/src/persistentStorage/opfsFileNaming.d.ts +0 -23
  79. package/dist/src/persistentStorage/opfsHelpers.d.ts +0 -3
  80. package/dist/src/persistentStorage/opfsOfflineUploadAdapter.d.ts +0 -2
  81. package/dist/src/persistentStorage/opfsPersistentStorage.d.ts +0 -2
  82. package/dist/src/persistentStorage/parsePersistedData.d.ts +0 -45
  83. package/dist/src/persistentStorage/persistenceUtils.d.ts +0 -52
  84. package/dist/src/persistentStorage/persistentStorageDefaults.d.ts +0 -4
  85. package/dist/src/persistentStorage/persistentStorageManager.d.ts +0 -197
  86. package/dist/src/persistentStorage/quotaDebug.d.ts +0 -16
  87. package/dist/src/persistentStorage/scheduleIdleCleanup.d.ts +0 -28
  88. package/dist/src/persistentStorage/storageAdapter.d.ts +0 -41
  89. package/dist/src/persistentStorage/storageEntryPrefixes.d.ts +0 -16
  90. package/dist/src/persistentStorage/types.d.ts +0 -412
  91. package/dist/src/persistentStorage/validateWithSchema.d.ts +0 -12
  92. package/dist/src/requestScheduler.d.ts +0 -81
  93. package/dist/src/storeManager.d.ts +0 -160
  94. package/dist/src/utils/automaticFetchPolicy.d.ts +0 -29
  95. package/dist/src/utils/browserTabsPriority.d.ts +0 -43
  96. package/dist/src/utils/browserTabsSync.d.ts +0 -33
  97. package/dist/src/utils/optimisticMutationTracker.d.ts +0 -20
  98. package/dist/src/utils/optimisticRollback.d.ts +0 -11
  99. package/dist/src/utils/payloadDebounce.d.ts +0 -5
  100. package/dist/src/utils/performMutation.d.ts +0 -19
  101. package/dist/src/utils/reusePrevIfEqual.d.ts +0 -1
  102. package/dist/src/utils/storeFocusLifecycle.d.ts +0 -1
  103. package/dist/src/utils/storeShared.d.ts +0 -126
  104. package/dist/src/utils/useEnsureIsLoaded.d.ts +0 -6
  105. package/dist/src/utils/useRequireFreshData.d.ts +0 -6
  106. package/dist/tests/basic-functionality/collection-store.test.d.ts +0 -1
  107. package/dist/tests/basic-functionality/document-store.test.d.ts +0 -1
  108. package/dist/tests/basic-functionality/list-query-state-manipulation.test.d.ts +0 -1
  109. package/dist/tests/basic-functionality/list-query-store.test.d.ts +0 -1
  110. package/dist/tests/browser-tabs/browser-tabs-background-rtu-batch.test.d.ts +0 -1
  111. package/dist/tests/browser-tabs/browser-tabs-background-rtu.test.d.ts +0 -1
  112. package/dist/tests/browser-tabs/browser-tabs-background-scheduling.test.d.ts +0 -1
  113. package/dist/tests/browser-tabs/browser-tabs-list-query-pagination.test.d.ts +0 -1
  114. package/dist/tests/browser-tabs/browser-tabs-non-cancelable-fetches.test.d.ts +0 -1
  115. package/dist/tests/browser-tabs/browser-tabs-optimistic-sync.test.d.ts +0 -1
  116. package/dist/tests/browser-tabs/browser-tabs-partial-resources.test.d.ts +0 -1
  117. package/dist/tests/browser-tabs/browser-tabs-priority.test.d.ts +0 -1
  118. package/dist/tests/browser-tabs/browser-tabs-snapshot-consistency.test.d.ts +0 -1
  119. package/dist/tests/browser-tabs/browser-tabs-state-methods.test.d.ts +0 -1
  120. package/dist/tests/browser-tabs/browser-tabs-sync-coordinator.test.d.ts +0 -1
  121. package/dist/tests/browser-tabs/browser-tabs-test-helpers.d.ts +0 -69
  122. package/dist/tests/browser-tabs/focus-coordinator.test.d.ts +0 -1
  123. package/dist/tests/hooks/collection-hooks-2.test.d.ts +0 -1
  124. package/dist/tests/hooks/collection-hooks.test.d.ts +0 -1
  125. package/dist/tests/hooks/collection-useListItem.test.d.ts +0 -1
  126. package/dist/tests/hooks/debounce-payload-hooks.test.d.ts +0 -1
  127. package/dist/tests/hooks/disable-refetches.test.d.ts +0 -1
  128. package/dist/tests/hooks/document-hooks-2.test.d.ts +0 -1
  129. package/dist/tests/hooks/document-hooks.test.d.ts +0 -1
  130. package/dist/tests/hooks/document-useListItem.test.d.ts +0 -1
  131. package/dist/tests/hooks/fetch-error-recovery.test.d.ts +0 -1
  132. package/dist/tests/hooks/hook-memoization.test.d.ts +0 -1
  133. package/dist/tests/hooks/list-query-hooks-2.test.d.ts +0 -1
  134. package/dist/tests/hooks/list-query-hooks-3.test.d.ts +0 -1
  135. package/dist/tests/hooks/list-query-hooks-mutations.test.d.ts +0 -1
  136. package/dist/tests/hooks/list-query-hooks.test.d.ts +0 -1
  137. package/dist/tests/hooks/list-query-pending-offline-items.test.d.ts +0 -1
  138. package/dist/tests/hooks/off-screen-context.test.d.ts +0 -1
  139. package/dist/tests/list-query-features/list-query-derived-queries.test.d.ts +0 -1
  140. package/dist/tests/list-query-features/list-query-offset-pagination.test.d.ts +0 -1
  141. package/dist/tests/list-query-features/list-query-optimistic-filters.test.d.ts +0 -1
  142. package/dist/tests/list-query-features/list-query-partial-resources-2.test.d.ts +0 -1
  143. package/dist/tests/list-query-features/list-query-partial-resources-3.test.d.ts +0 -1
  144. package/dist/tests/list-query-features/list-query-partial-resources-regressions.test.d.ts +0 -1
  145. package/dist/tests/list-query-features/list-query-partial-resources-show-partial-status.test.d.ts +0 -1
  146. package/dist/tests/list-query-features/list-query-partial-resources.test.d.ts +0 -1
  147. package/dist/tests/list-query-features/list-query-size-coalescing-partial-resources.test.d.ts +0 -1
  148. package/dist/tests/mocks/browserTabsTestUtils.d.ts +0 -17
  149. package/dist/tests/mocks/collectionStoreTestEnv.d.ts +0 -265
  150. package/dist/tests/mocks/documentStoreTestEnv.d.ts +0 -140
  151. package/dist/tests/mocks/duplicateStoreGuard.test.d.ts +0 -1
  152. package/dist/tests/mocks/listQueryStoreTestEnv.d.ts +0 -295
  153. package/dist/tests/mocks/mockBrowserOpfs.d.ts +0 -70
  154. package/dist/tests/mocks/mockBrowserOpfs.test.d.ts +0 -1
  155. package/dist/tests/mocks/mockLocalStorageStore.d.ts +0 -61
  156. package/dist/tests/mocks/seedScenarioPersistentStorage.d.ts +0 -51
  157. package/dist/tests/mocks/serverMock.d.ts +0 -56
  158. package/dist/tests/mocks/serverTableMock.d.ts +0 -174
  159. package/dist/tests/mocks/testEnvUtils.d.ts +0 -120
  160. package/dist/tests/mocks/testScenarioPersistentStorage.test.d.ts +0 -1
  161. package/dist/tests/offline/offline-fetching-scenarios.test.d.ts +0 -1
  162. package/dist/tests/offline/offline-mixed-adapter-storage.test.d.ts +0 -1
  163. package/dist/tests/offline/offline-mutation-fallback.test.d.ts +0 -1
  164. package/dist/tests/offline/offline-network-recovery.test.d.ts +0 -1
  165. package/dist/tests/offline/offline-outage.test.d.ts +0 -1
  166. package/dist/tests/offline/offline-overlays.test.d.ts +0 -1
  167. package/dist/tests/offline/offline-query-replay.test.d.ts +0 -1
  168. package/dist/tests/offline/offline-reads.test.d.ts +0 -1
  169. package/dist/tests/offline/offline-replay-conflicts.test.d.ts +0 -1
  170. package/dist/tests/offline/offline-replay-queueing.test.d.ts +0 -1
  171. package/dist/tests/offline/offline-resolution-dependencies.test.d.ts +0 -1
  172. package/dist/tests/offline/offline-runtime-controls.test.d.ts +0 -1
  173. package/dist/tests/offline/offline-session-and-global-state.test.d.ts +0 -1
  174. package/dist/tests/offline/offline-storage.test.d.ts +0 -1
  175. package/dist/tests/offline/offline-uploads.test.d.ts +0 -1
  176. package/dist/tests/offline/offlineReplayTestShared.d.ts +0 -292
  177. package/dist/tests/offline/offlineTestShared.d.ts +0 -156
  178. package/dist/tests/perform-mutation/mutation-error-rollback.test.d.ts +0 -1
  179. package/dist/tests/perform-mutation/perform-mutation-block-window-close.test.d.ts +0 -1
  180. package/dist/tests/perform-mutation/perform-mutation-debounce.test.d.ts +0 -1
  181. package/dist/tests/perform-mutation/store-events.test.d.ts +0 -1
  182. package/dist/tests/persistent-storage/async-storage-efficiency/collection.test.d.ts +0 -1
  183. package/dist/tests/persistent-storage/async-storage-efficiency/document.test.d.ts +0 -1
  184. package/dist/tests/persistent-storage/async-storage-efficiency/list-query.test.d.ts +0 -1
  185. package/dist/tests/persistent-storage/async-storage-efficiency/maintenance.test.d.ts +0 -1
  186. package/dist/tests/persistent-storage/async-storage-efficiency/shared.d.ts +0 -804
  187. package/dist/tests/persistent-storage/async-storage-shared.test.d.ts +0 -1
  188. package/dist/tests/persistent-storage/collection-store-persistence.converted.opfs.test.d.ts +0 -1
  189. package/dist/tests/persistent-storage/collection-store-persistence.converted.test.d.ts +0 -1
  190. package/dist/tests/persistent-storage/collection-store-persistence.opfs.test.d.ts +0 -1
  191. package/dist/tests/persistent-storage/collection-store-persistence.test.d.ts +0 -1
  192. package/dist/tests/persistent-storage/document-store-persistence.converted.opfs.test.d.ts +0 -1
  193. package/dist/tests/persistent-storage/document-store-persistence.converted.test.d.ts +0 -1
  194. package/dist/tests/persistent-storage/document-store-persistence.opfs.test.d.ts +0 -1
  195. package/dist/tests/persistent-storage/document-store-persistence.test.d.ts +0 -1
  196. package/dist/tests/persistent-storage/expiration-scan.test.d.ts +0 -1
  197. package/dist/tests/persistent-storage/indexeddb-async-storage-efficiency/collection.test.d.ts +0 -1
  198. package/dist/tests/persistent-storage/indexeddb-async-storage-efficiency/document.test.d.ts +0 -1
  199. package/dist/tests/persistent-storage/indexeddb-async-storage-efficiency/list-query.test.d.ts +0 -1
  200. package/dist/tests/persistent-storage/indexeddb-async-storage-efficiency/maintenance.test.d.ts +0 -1
  201. package/dist/tests/persistent-storage/indexeddb-async-storage-efficiency/shared.d.ts +0 -780
  202. package/dist/tests/persistent-storage/indexeddb-storage-adapter.test.d.ts +0 -1
  203. package/dist/tests/persistent-storage/list-query-store-persistence.converted.opfs.test.d.ts +0 -1
  204. package/dist/tests/persistent-storage/list-query-store-persistence.converted.test.d.ts +0 -1
  205. package/dist/tests/persistent-storage/list-query-store-persistence.opfs.test.d.ts +0 -1
  206. package/dist/tests/persistent-storage/list-query-store-persistence.test.d.ts +0 -1
  207. package/dist/tests/persistent-storage/persistence-with-tabs-sync.test.d.ts +0 -1
  208. package/dist/tests/persistent-storage/persistentStorageByteBudgetTestUtils.d.ts +0 -18
  209. package/dist/tests/persistent-storage/quota-exceeded-recovery-no-locks.test.d.ts +0 -1
  210. package/dist/tests/persistent-storage/quota-exceeded-recovery.test.d.ts +0 -1
  211. package/dist/tests/persistent-storage/quotaRecoveryTestUtils.d.ts +0 -228
  212. package/dist/tests/persistent-storage/storage-adapter.test.d.ts +0 -1
  213. package/dist/tests/persistent-storage/sync-storage-efficiency/collection.test.d.ts +0 -1
  214. package/dist/tests/persistent-storage/sync-storage-efficiency/document.test.d.ts +0 -1
  215. package/dist/tests/persistent-storage/sync-storage-efficiency/list-query.test.d.ts +0 -1
  216. package/dist/tests/persistent-storage/sync-storage-efficiency/maintenance.test.d.ts +0 -1
  217. package/dist/tests/persistent-storage/sync-storage-efficiency/shared.d.ts +0 -784
  218. package/dist/tests/playwright/browser-tabs.spec.d.ts +0 -1
  219. package/dist/tests/playwright/persistent-storage.spec.d.ts +0 -1
  220. package/dist/tests/request-schedulling/batch-medium-priority.test.d.ts +0 -1
  221. package/dist/tests/request-schedulling/batch-realtime-updates.test.d.ts +0 -1
  222. package/dist/tests/request-schedulling/collection-batch-coalescing.test.d.ts +0 -1
  223. package/dist/tests/request-schedulling/collection-batch-key-grouping.test.d.ts +0 -1
  224. package/dist/tests/request-schedulling/collection-fetch-orchestration.test.d.ts +0 -1
  225. package/dist/tests/request-schedulling/document-await-fetch.test.d.ts +0 -1
  226. package/dist/tests/request-schedulling/document-base-coalescing.test.d.ts +0 -1
  227. package/dist/tests/request-schedulling/document-fetch-orchestration.test.d.ts +0 -1
  228. package/dist/tests/request-schedulling/document-medium-priority-fetch.test.d.ts +0 -1
  229. package/dist/tests/request-schedulling/document-realtime-updates.test.d.ts +0 -1
  230. package/dist/tests/request-schedulling/list-query-item-batch-coalescing.test.d.ts +0 -1
  231. package/dist/tests/request-schedulling/list-query-item-batch-key-grouping.test.d.ts +0 -1
  232. package/dist/tests/request-schedulling/list-query-size-coalescing.test.d.ts +0 -1
  233. package/dist/tests/request-schedulling/medium-vs-realtime.test.d.ts +0 -1
  234. package/dist/tests/request-schedulling/request-scheduler-cross-tab-sync.test.d.ts +0 -1
  235. package/dist/tests/request-schedulling/window-focus.test.d.ts +0 -1
  236. package/dist/tests/store-manager.test.d.ts +0 -1
  237. package/dist/tests/user-facing-api/collection-offline-usage.test.d.ts +0 -1
  238. package/dist/tests/user-facing-api/document-offline-usage.test.d.ts +0 -1
  239. package/dist/tests/user-facing-api/list-query-offline-usage.test.d.ts +0 -1
  240. package/dist/tests/user-facing-api/result-returning-callbacks.test.d.ts +0 -1
  241. package/dist/tests/utils/genericTestUtils.d.ts +0 -6
  242. package/dist/tests/utils/indexedDbPersistentStorageOptimizationTestUtils.d.ts +0 -79
  243. package/dist/tests/utils/indexedDbPersistentStorageTestStore.d.ts +0 -181
  244. package/dist/tests/utils/listQueryHooksTestUtils.d.ts +0 -8
  245. package/dist/tests/utils/networkMock.d.ts +0 -11
  246. package/dist/tests/utils/opfsPersistentStorageTestStore.d.ts +0 -220
  247. package/dist/tests/utils/persistentStorageOptimizationTestUtils.d.ts +0 -54
  248. package/dist/tests/utils/persistentStorageOptimizationTestUtils.test.d.ts +0 -1
  249. package/dist/tests/utils/persistentStorageTestStore.d.ts +0 -66
  250. package/dist/tests/utils/resetSessionForTests.d.ts +0 -3
  251. package/dist/tests/utils/withSuppressedActError.d.ts +0 -4
@@ -1,538 +0,0 @@
1
- import { type Emitter } from 'evtmitter';
2
- import { type Result as ResultType } from 't-result';
3
- import { Store } from 't-state';
4
- import type { OfflineMutationResult } from '../persistentStorage/offline/mutationRuntime';
5
- import { type GlobalOfflineEntity, type OfflineMutationInput, type OfflineResolutionActionForOperation, type OfflineResolutionRecord, type ParsedOfflineResolutionConflictResultForStore } from '../persistentStorage/offline/types';
6
- import type { OfflineMutationUploadsInput } from '../persistentStorage/offlineUploadTypes';
7
- import type { ListQueryOfflineOperationsConfig, ListQueryPersistentStorageConfig, PersistentStoragePreloadResult } from '../persistentStorage/types';
8
- import { FetchType, RequestSchedulerEventData, RequestSchedulerEvents, ScheduleFetchOptions, ScheduleFetchResults } from '../requestScheduler';
9
- import { type StoreManager } from '../storeManager';
10
- import { StoreFetchError, StoreMutationError, type MaybeTSDFResult, type MutationSkipped, type StoreMutationErrorOptions, type UnwrapTSDFResult, type ValidPayload, type ValidStoreState } from '../utils/storeShared';
11
- import { type DerivedQueriesConfig, type FetchListFnReturn, type FieldsInput, type FieldsOption, type ListQueryUseMultipleItemsQuery, type ListQueryUseMultipleListQueriesQuery, type OffsetPaginationConfig, type OnListQueryInvalidate, type OnListQueryItemInvalidate, type OptimisticListUpdate, type PartialResourcesConfig, type TSFDListQuery, type TSFDListQueryState, type TSFDUseListItemReturn, type TSFDUseListQueryReturn, type TSFDUsePendingOfflineItemsReturn } from './types';
12
- import { UseItemOptions } from './useItem';
13
- import { UseListQueryOptions } from './useListQuery';
14
- import { UseMultipleItemsOptions } from './useMultipleItems';
15
- import { UseMultipleListQueriesOptions } from './useMultipleListQueries';
16
- import { type UsePendingOfflineItemsOptions } from './usePendingOfflineItems';
17
- /** Event payloads emitted by `ListQueryStore.events`. */
18
- export type ListQueryStoreEvents = {
19
- /** Emitted whenever one or more list queries are invalidated. */
20
- invalidateQuery: {
21
- /** Fetch priority requested by the invalidation. */
22
- priority: FetchType;
23
- /** Store key for the invalidated query. */
24
- queryKey: string;
25
- };
26
- /** Emitted whenever one or more list-query items are invalidated. */
27
- invalidateItem: {
28
- /** Fetch priority requested by the invalidation. */
29
- priority: FetchType;
30
- /** Store key for the invalidated item. */
31
- itemKey: string;
32
- /** Partial-resource fields invalidated on this item, when applicable. */
33
- invalidateFields?: string[];
34
- };
35
- };
36
- type ListQueryStoreStoreEvents<ItemPayload extends ValidPayload> = {
37
- mutationStart: {
38
- mutationId: number;
39
- items: ItemPayload[];
40
- };
41
- mutationEnd: {
42
- mutationId: number;
43
- items: ItemPayload[];
44
- status: 'success' | 'error' | 'skipped';
45
- };
46
- tempEntityReconciled: {
47
- tempId: ItemPayload;
48
- finalPayload: ItemPayload;
49
- };
50
- };
51
- type ResolvedListQueryOfflineOperations<TOfflineOperations> = TOfflineOperations extends null ? Record<never, never> : Exclude<TOfflineOperations, null>;
52
- type ListQueryHasPartialResources<TPartialResources extends boolean> = [
53
- TPartialResources
54
- ] extends [true] ? true : false;
55
- type ListQueryFetchFieldsOption<TPartialResources extends boolean> = ListQueryHasPartialResources<TPartialResources> extends true ? {
56
- /**
57
- * Partial-resource fields to request.
58
- *
59
- * Pass `'*'` to fetch complete items. This option is required when
60
- * `partialResources` is enabled.
61
- */
62
- fields: FieldsInput;
63
- } : {
64
- /**
65
- * Partial-resource fields to request.
66
- *
67
- * Pass `'*'` to fetch complete items. This option is optional when
68
- * `partialResources` is not enabled.
69
- */
70
- fields?: FieldsInput;
71
- };
72
- type ListQueryScheduleFetchWithFieldsOption<TPartialResources extends boolean> = ScheduleFetchOptions & ListQueryFetchFieldsOption<TPartialResources>;
73
- type ListQueryScheduleListQueryFetchApi<QueryPayload extends ValidPayload, TPartialResources extends boolean> = {
74
- (fetchType: FetchType, payload: QueryPayload, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [
75
- /** Number of items to request. Defaults to the store's `defaultQuerySize`. */
76
- size: number | undefined,
77
- options: ListQueryScheduleFetchWithFieldsOption<TPartialResources>
78
- ] : [
79
- /** Number of items to request. Defaults to the store's `defaultQuerySize`. */
80
- size?: number,
81
- options?: ListQueryScheduleFetchWithFieldsOption<TPartialResources>
82
- ]): ScheduleFetchResults;
83
- (fetchType: FetchType, payload: QueryPayload[], ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [
84
- /** Number of items to request. Defaults to the store's `defaultQuerySize`. */
85
- size: number | undefined,
86
- options: ListQueryScheduleFetchWithFieldsOption<TPartialResources>
87
- ] : [
88
- /** Number of items to request. Defaults to the store's `defaultQuerySize`. */
89
- size?: number,
90
- options?: ListQueryScheduleFetchWithFieldsOption<TPartialResources>
91
- ]): ScheduleFetchResults[];
92
- };
93
- type ListQueryScheduleItemFetchApi<ItemPayload extends ValidPayload, TPartialResources extends boolean> = {
94
- (fetchType: FetchType, itemPayload: ItemPayload, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [options: ListQueryScheduleFetchWithFieldsOption<TPartialResources>] : [options?: ListQueryScheduleFetchWithFieldsOption<TPartialResources>]): ScheduleFetchResults;
95
- (fetchType: FetchType, itemPayload: ItemPayload[], ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [options: ListQueryScheduleFetchWithFieldsOption<TPartialResources>] : [options?: ListQueryScheduleFetchWithFieldsOption<TPartialResources>]): ScheduleFetchResults[];
96
- };
97
- type ListQueryLoadMoreWithFieldsOptions<TPartialResources extends boolean> = {
98
- /** Number of additional items to request. Defaults to the store's `defaultQuerySize`. */
99
- size?: number;
100
- } & ListQueryFetchFieldsOption<TPartialResources>;
101
- type ListQueryLoadMoreApi<QueryPayload extends ValidPayload, TPartialResources extends boolean> = (params: QueryPayload, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [size: number, options: ListQueryFetchFieldsOption<TPartialResources>] | [options: ListQueryLoadMoreWithFieldsOptions<TPartialResources>] : [
102
- /** Number of additional items to request. Defaults to the store's `defaultQuerySize`. */
103
- size?: number,
104
- options?: ListQueryFetchFieldsOption<TPartialResources>
105
- ] | [options?: ListQueryLoadMoreWithFieldsOptions<TPartialResources>]) => ScheduleFetchResults;
106
- type ListQueryAwaitListQueryFetchOptions<TPartialResources extends boolean> = {
107
- /** Number of items to request. Defaults to the store's `defaultQuerySize`. */
108
- size?: number;
109
- timeoutMs?: number;
110
- } & ListQueryFetchFieldsOption<TPartialResources>;
111
- type ListQueryAwaitListQueryFetchApi<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean> = (params: QueryPayload, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [options: ListQueryAwaitListQueryFetchOptions<TPartialResources>] : [options?: ListQueryAwaitListQueryFetchOptions<TPartialResources>]) => Promise<{
112
- items: [];
113
- error: StoreFetchError;
114
- hasMore: boolean;
115
- } | {
116
- items: {
117
- data: ItemState;
118
- itemPayload: ItemPayload;
119
- }[];
120
- error: null;
121
- hasMore: boolean;
122
- }>;
123
- type ListQueryGetQueryFromStateOrFetchOptions<TPartialResources extends boolean> = {
124
- /** When `true`, stale cached queries are ignored and refetched before returning. Defaults to `false`. */
125
- ignoreStaleState?: boolean;
126
- /** Number of items to request when a fetch is needed. Defaults to the store's `defaultQuerySize`. */
127
- size?: number;
128
- timeoutMs?: number;
129
- } & ListQueryFetchFieldsOption<TPartialResources>;
130
- type ListQueryGetQueryFromStateOrFetchApi<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean> = (params: QueryPayload, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [options: ListQueryGetQueryFromStateOrFetchOptions<TPartialResources>] : [options?: ListQueryGetQueryFromStateOrFetchOptions<TPartialResources>]) => Promise<ResultType<{
131
- items: {
132
- data: ItemState;
133
- itemPayload: ItemPayload;
134
- }[];
135
- hasMore: boolean;
136
- }, StoreFetchError>>;
137
- type ListQueryAwaitItemFetchOptions<TPartialResources extends boolean> = {
138
- timeoutMs?: number;
139
- } & ListQueryFetchFieldsOption<TPartialResources>;
140
- type ListQueryAwaitItemFetchApi<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TPartialResources extends boolean> = (itemPayload: ItemPayload, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [options: ListQueryAwaitItemFetchOptions<TPartialResources>] : [options?: ListQueryAwaitItemFetchOptions<TPartialResources>]) => Promise<{
141
- data: null;
142
- error: StoreFetchError;
143
- } | {
144
- data: ItemState;
145
- error: null;
146
- }>;
147
- type ListQueryGetItemFromStateOrFetchOptions<TPartialResources extends boolean> = {
148
- /** When `true`, stale cached items are ignored and refetched before returning. Defaults to `false`. */
149
- ignoreStaleState?: boolean;
150
- timeoutMs?: number;
151
- } & ListQueryFetchFieldsOption<TPartialResources>;
152
- type ListQueryGetItemFromStateOrFetchApi<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TPartialResources extends boolean> = (itemPayload: ItemPayload, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [options: ListQueryGetItemFromStateOrFetchOptions<TPartialResources>] : [options?: ListQueryGetItemFromStateOrFetchOptions<TPartialResources>]) => Promise<ResultType<ItemState, StoreFetchError>>;
153
- type ListQueryUseMultipleListQueriesApi<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean> = {
154
- <SelectedItem = ItemState, QueryMetadata extends undefined | Record<string, unknown> = undefined>(queries: (ListQueryUseMultipleListQueriesQuery<QueryPayload, QueryMetadata> & FieldsOption<ListQueryHasPartialResources<TPartialResources>>)[], options?: UseMultipleListQueriesOptions<ItemState, ItemPayload, SelectedItem>): readonly TSFDUseListQueryReturn<SelectedItem, QueryPayload, QueryMetadata>[];
155
- <S = ItemState>(queries: ListQueryUseMultipleListQueriesQuery<QueryPayload, undefined>[], options: UseMultipleListQueriesOptions<ItemState, ItemPayload, S>): readonly TSFDUseListQueryReturn<S, QueryPayload, undefined>[];
156
- };
157
- type ListQueryUseListQueryApi<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean> = {
158
- <SelectedItem = ItemState>(payload: QueryPayload | false | null | undefined, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [
159
- options: UseListQueryOptions<ItemState, ItemPayload, SelectedItem> & FieldsOption<true>
160
- ] : [options?: UseListQueryOptions<ItemState, ItemPayload, SelectedItem>]): TSFDUseListQueryReturn<SelectedItem, QueryPayload, undefined>;
161
- };
162
- type ListQueryUseMultipleItemsApi<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TPartialResources extends boolean> = {
163
- <Selected = ItemState | null, QueryMetadata extends undefined | Record<string, unknown> = undefined>(items: (ListQueryUseMultipleItemsQuery<ItemPayload, QueryMetadata> & FieldsOption<ListQueryHasPartialResources<TPartialResources>>)[], options?: UseMultipleItemsOptions<ItemState, Selected>): readonly TSFDUseListItemReturn<Selected, ItemPayload, QueryMetadata>[];
164
- <S = ItemState | null>(items: ListQueryUseMultipleItemsQuery<ItemPayload, undefined>[], options: UseMultipleItemsOptions<ItemState, S>): readonly TSFDUseListItemReturn<S, ItemPayload, undefined>[];
165
- };
166
- type ListQueryUseItemApi<ItemState extends ValidStoreState, ItemPayload extends ValidPayload, TPartialResources extends boolean> = {
167
- <Selected = ItemState | null>(itemPayload: ItemPayload | false | null | undefined, ...args: ListQueryHasPartialResources<TPartialResources> extends true ? [options: UseItemOptions<ItemState, Selected> & FieldsOption<true>] : [options?: UseItemOptions<ItemState, Selected>]): TSFDUseListItemReturn<Selected, ItemPayload>;
168
- };
169
- type ListQueryUsePendingOfflineItemsApi<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = {
170
- <SelectedItem = ItemState>(options?: UsePendingOfflineItemsOptions<ItemState, ItemPayload, SelectedItem>): TSFDUsePendingOfflineItemsReturn<SelectedItem, ItemPayload>;
171
- };
172
- type ListQueryFilterQuery<QueryPayload extends ValidPayload> = (params: QueryPayload, data: TSFDListQuery<QueryPayload>, queryKey: string) => boolean;
173
- type ListQueryRevalidateOnSuccessOption<QueryPayload extends ValidPayload> = boolean | 'queries' | ListQueryFilterQuery<QueryPayload> | {
174
- queries: ListQueryFilterQuery<QueryPayload>;
175
- items?: boolean;
176
- };
177
- type ListQueryFilterItem<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = (itemPayload: ItemPayload, itemState: ItemState) => boolean;
178
- type ListQueryMutationPayload<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload> | null;
179
- type ListQueryMutationPayloadToUse<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload>;
180
- type ListQueryMutationArgsBase<T, ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = {
181
- /**
182
- * Applies optimistic updates for the affected item payloads before the
183
- * mutation runs. Return `false` to cancel the mutation before the async
184
- * mutation function is called.
185
- */
186
- optimisticUpdate?: (payload: ListQueryMutationPayloadToUse<ItemState, ItemPayload>) => void | boolean;
187
- /** Performs the server mutation for the affected item payloads. */
188
- mutation: (payload: ListQueryMutationPayloadToUse<ItemState, ItemPayload>) => Promise<T>;
189
- /**
190
- * Controls query and item invalidation after a successful online mutation.
191
- *
192
- * Use `true` to invalidate affected items and all queries, `'queries'` to
193
- * invalidate only queries, a query filter to invalidate affected items and
194
- * matching queries, or `{ queries, items }` to choose both explicitly.
195
- */
196
- revalidateOnSuccess?: ListQueryRevalidateOnSuccessOption<QueryPayload>;
197
- /** Called after a successful online mutation. */
198
- onSuccess?: (response: UnwrapTSDFResult<Awaited<T>>, payload: ListQueryMutationPayloadToUse<ItemState, ItemPayload>) => void;
199
- /** Called after a failed or skipped mutation. */
200
- onError?: (error: StoreMutationError | MutationSkipped) => void;
201
- /**
202
- * Passes `{ silentErrors: true }` to `onMutationError`.
203
- *
204
- * The handler is still called so centralized logging and recovery can run,
205
- * but UI handlers can suppress user-facing notifications.
206
- */
207
- silentErrors?: boolean;
208
- /** Debounces mutations with the same context and payload. Superseded calls are skipped. */
209
- debounce?: {
210
- context: string;
211
- payload: unknown;
212
- ms: number;
213
- };
214
- };
215
- type ListQueryOnlineMutationArgs<T, ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = ListQueryMutationArgsBase<T, ItemState, QueryPayload, ItemPayload> & {
216
- offline?: undefined;
217
- upload?: undefined;
218
- };
219
- type ListQueryOfflineMutationArgs<T, ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload>> = ListQueryMutationArgsBase<T, ItemState, QueryPayload, ItemPayload> & {
220
- /**
221
- * Queues this mutation through the store's registered offline operation when
222
- * the session is offline or the direct request fails with an offline outage.
223
- */
224
- offline: TOfflineOperations extends null ? never : OfflineMutationInput<Exclude<TOfflineOperations, null>>;
225
- /** Files to attach if this mutation is queued for offline replay. */
226
- upload?: OfflineMutationUploadsInput;
227
- };
228
- type ListQueryPerformMutationApi<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload>> = {
229
- /**
230
- * Runs a list-query mutation for existing item payloads or an item filter.
231
- *
232
- * Returns the direct server result when offline replay is not configured for
233
- * this call.
234
- */
235
- <T>(payload: ListQueryMutationPayloadToUse<ItemState, ItemPayload>, args: ListQueryOnlineMutationArgs<T, ItemState, QueryPayload, ItemPayload>): Promise<ResultType<UnwrapTSDFResult<Awaited<T>>, StoreMutationError | MutationSkipped>>;
236
- /**
237
- * Runs a list-query mutation for existing item payloads or an item filter,
238
- * with durable offline queueing as a fallback.
239
- *
240
- * When the mutation is queued, the result is `{ kind: 'queued' }` instead of
241
- * the server payload.
242
- */
243
- <T>(payload: ListQueryMutationPayloadToUse<ItemState, ItemPayload>, args: ListQueryOfflineMutationArgs<T, ItemState, QueryPayload, ItemPayload, TOfflineOperations>): Promise<ResultType<OfflineMutationResult<UnwrapTSDFResult<Awaited<T>>>, StoreMutationError | MutationSkipped>>;
244
- /**
245
- * Runs a list-query mutation with no current item target.
246
- *
247
- * Use this for create mutations that do not have a pre-generated item payload
248
- * yet. Optimistic updates are not available without a target payload.
249
- */
250
- <T>(payload: null, args: Omit<ListQueryOnlineMutationArgs<T, ItemState, QueryPayload, ItemPayload>, 'optimisticUpdate'>): Promise<ResultType<UnwrapTSDFResult<Awaited<T>>, StoreMutationError | MutationSkipped>>;
251
- /**
252
- * Runs an offline-capable list-query mutation with no current item target.
253
- *
254
- * Use this for create mutations that do not have a pre-generated item payload
255
- * yet. When the mutation is queued, the result is `{ kind: 'queued' }`.
256
- */
257
- <T>(payload: null, args: Omit<ListQueryOfflineMutationArgs<T, ItemState, QueryPayload, ItemPayload, TOfflineOperations>, 'optimisticUpdate'>): Promise<ResultType<OfflineMutationResult<UnwrapTSDFResult<Awaited<T>>>, StoreMutationError | MutationSkipped>>;
258
- <T>(payload: ListQueryMutationPayload<ItemState, ItemPayload>, args: ListQueryOnlineMutationArgs<T, ItemState, QueryPayload, ItemPayload> | ListQueryOfflineMutationArgs<T, ItemState, QueryPayload, ItemPayload, TOfflineOperations>): Promise<ResultType<UnwrapTSDFResult<Awaited<T>> | OfflineMutationResult<UnwrapTSDFResult<Awaited<T>>>, StoreMutationError | MutationSkipped>>;
259
- };
260
- type ListQueryUpdateItemStateApi<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = (itemIds: ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload>, produceNewData: (draftData: ItemState, itemPayload: ItemPayload) => void | ItemState, options?: {
261
- ifNothingWasUpdated?: () => void;
262
- }) => boolean;
263
- type ListQueryAddItemToStateApi<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = (itemPayload: ItemPayload, data: ItemState, options?: {
264
- addItemToQueries?: {
265
- queries: QueryPayload[] | ListQueryFilterQuery<QueryPayload> | QueryPayload;
266
- appendTo: 'start' | 'end' | ((itemsPayload: ItemPayload[]) => number);
267
- };
268
- }) => void;
269
- type ListQueryDeleteItemStateApi<ItemState extends ValidStoreState, ItemPayload extends ValidPayload> = (itemId: ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload>) => void;
270
- type ListQueryInvalidateQueryAndItemsArgs<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = {
271
- /** Invalidate every cached query and every cached item. */
272
- all: true;
273
- /** Fetch priority used for refetches triggered by this invalidation. Defaults to `highPriority`. */
274
- type?: FetchType;
275
- /**
276
- * Partial-resource fields to invalidate on matching items.
277
- *
278
- * Omit to invalidate the full item data.
279
- */
280
- fields?: string[];
281
- /** Not allowed when invalidating every query and item. */
282
- itemPayload?: undefined;
283
- /** Not allowed when invalidating every query and item. */
284
- queryPayload?: undefined;
285
- } | {
286
- /** Leave unset when invalidating selected queries or items. */
287
- all?: undefined;
288
- /**
289
- * Items to invalidate.
290
- *
291
- * Pass one payload, many payloads, a predicate over cached items, or
292
- * `false` to skip item invalidation.
293
- */
294
- itemPayload: ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload> | false;
295
- /**
296
- * Queries to invalidate.
297
- *
298
- * Pass one payload, many payloads, a predicate over cached queries, or
299
- * `false` to skip query invalidation.
300
- */
301
- queryPayload: QueryPayload | QueryPayload[] | ListQueryFilterQuery<QueryPayload> | false;
302
- /** Fetch priority used for refetches triggered by this invalidation. Defaults to `highPriority`. */
303
- type?: FetchType;
304
- /**
305
- * Partial-resource fields to invalidate on matching items.
306
- *
307
- * Omit to invalidate the full item data.
308
- */
309
- fields?: string[];
310
- };
311
- /** Public API returned by `createListQueryStore(...)`. */
312
- export type ListQueryStore<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean = false, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload> = null> = {
313
- /** Underlying t-state store containing raw cached queries and items. */
314
- store: Store<TSFDListQueryState<ItemState, QueryPayload, ItemPayload>>;
315
- /** Invalidation event emitter used by hooks and integrations. */
316
- events: Emitter<ListQueryStoreEvents>;
317
- /** Mutation lifecycle event emitter for observers and tests. */
318
- storeEvents: Emitter<ListQueryStoreStoreEvents<ItemPayload>>;
319
- /** Query keys that have been explicitly invalidated and are awaiting refresh. */
320
- readonly queryInvalidationWasTriggered: Set<string>;
321
- /** Item keys that have been explicitly invalidated and are awaiting refresh. */
322
- readonly itemInvalidationWasTriggered: Set<string>;
323
- /** Clears in-memory state and cancels store-local runtime state. */
324
- reset: () => void;
325
- /** Unregisters listeners and releases resources owned by this store. */
326
- dispose: () => void;
327
- /** Schedules a list-query fetch with the requested priority. */
328
- scheduleListQueryFetch: ListQueryScheduleListQueryFetchApi<QueryPayload, TPartialResources>;
329
- /** Reads one cached query directly from store state. */
330
- getQueryState: (params: QueryPayload) => TSFDListQuery<QueryPayload> | undefined;
331
- /** Returns the stable cache key for a query payload. */
332
- getQueryKey: (params: QueryPayload) => string;
333
- /** Reads many cached queries directly from store state. */
334
- getQueriesState: (params: QueryPayload[] | ListQueryFilterQuery<QueryPayload>) => {
335
- query: TSFDListQuery<QueryPayload>;
336
- key: string;
337
- }[];
338
- /** Finds cached queries that currently include the item payload. */
339
- getQueriesRelatedToItem: (itemPayload: ItemPayload) => {
340
- query: TSFDListQuery<QueryPayload>;
341
- key: string;
342
- }[];
343
- /** Waits for a list-query fetch to settle and returns query data or a fetch error. */
344
- awaitListQueryFetch: ListQueryAwaitListQueryFetchApi<ItemState, QueryPayload, ItemPayload, TPartialResources>;
345
- /** Returns a cached query when usable, otherwise fetches it first. */
346
- getQueryFromStateOrFetch: ListQueryGetQueryFromStateOrFetchApi<ItemState, QueryPayload, ItemPayload, TPartialResources>;
347
- /** Loads query payloads from persistent storage into memory when available. */
348
- preloadQueryFromStorage: (params: QueryPayload | QueryPayload[]) => Promise<PersistentStoragePreloadResult<QueryPayload>[]>;
349
- /** Fetches and appends the next page for a list query. */
350
- loadMore: ListQueryLoadMoreApi<QueryPayload, TPartialResources>;
351
- /** Returns the stable cache key for an item payload. */
352
- getItemKey: (params: ItemPayload) => string;
353
- /** Reads one or many cached items directly from store state. */
354
- getItemState: {
355
- (itemPayload: ItemPayload): ItemState | null | undefined;
356
- (itemPayload: ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload>): {
357
- payload: ItemPayload;
358
- data: ItemState;
359
- }[];
360
- };
361
- /** React hook for locally pending offline items in this store. */
362
- usePendingOfflineItems: ListQueryUsePendingOfflineItemsApi<ItemState, ItemPayload>;
363
- /** Returns offline sync metadata for this store's tracked entities. */
364
- getOfflineEntities: () => GlobalOfflineEntity[];
365
- /** React hook subscribing to this store's offline entity metadata. */
366
- useOfflineEntities: () => readonly GlobalOfflineEntity[];
367
- /** React hook subscribing to manual offline resolutions for this store. */
368
- useOfflineResolutions: () => readonly OfflineResolutionRecord[];
369
- /** Returns manual offline resolutions for this store. */
370
- getOfflineResolutions: () => OfflineResolutionRecord[];
371
- /** Parses a stored offline conflict into the operation-specific conflict shape. */
372
- parseOfflineResolutionConflict: (resolution: OfflineResolutionRecord) => ParsedOfflineResolutionConflictResultForStore<ResolvedListQueryOfflineOperations<TOfflineOperations>>;
373
- /** Applies a retry/discard/requeue/commit action to a pending offline resolution. */
374
- resolveOfflineResolution: <TName extends keyof ResolvedListQueryOfflineOperations<TOfflineOperations> & string>(resolutionId: string, operationName: TName, resolution: OfflineResolutionActionForOperation<ResolvedListQueryOfflineOperations<TOfflineOperations>, TName>) => Promise<void> | void;
375
- /** Loads item payloads from persistent storage into memory when available. */
376
- preloadItemFromStorage: (params: ItemPayload | ItemPayload[]) => Promise<PersistentStoragePreloadResult<ItemPayload>[]>;
377
- /** Schedules an item fetch with the requested priority. */
378
- scheduleItemFetch: ListQueryScheduleItemFetchApi<ItemPayload, TPartialResources>;
379
- /** Waits for an item fetch to settle and returns data or a fetch error. */
380
- awaitItemFetch: ListQueryAwaitItemFetchApi<ItemState, ItemPayload, TPartialResources>;
381
- /** Returns cached item data when usable, otherwise fetches it first. */
382
- getItemFromStateOrFetch: ListQueryGetItemFromStateOrFetchApi<ItemState, ItemPayload, TPartialResources>;
383
- /** Invalidates selected queries and items together. Defaults to `highPriority`. */
384
- invalidateQueryAndItems: (args: ListQueryInvalidateQueryAndItemsArgs<ItemState, QueryPayload, ItemPayload>) => void;
385
- /** Marks cached items stale and schedules refetches for active subscriptions. Defaults to `highPriority`. */
386
- invalidateItem: (itemId: ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload>,
387
- /** Fetch priority used for refetches triggered by this invalidation. Defaults to `highPriority`. */
388
- priority?: FetchType) => void;
389
- /** Marks one or more items as mutating and returns a function that ends the mutation. */
390
- startItemMutation: (itemId: ItemPayload | ItemPayload[] | ListQueryFilterItem<ItemState, ItemPayload>) => () => void;
391
- /** Applies an immutable update to one or more cached list-query items. */
392
- updateItemState: ListQueryUpdateItemStateApi<ItemState, ItemPayload>;
393
- /** Adds or replaces one cached item directly in state. */
394
- addItemToState: ListQueryAddItemToStateApi<ItemState, QueryPayload, ItemPayload>;
395
- /** Deletes one cached item directly from state and query membership. */
396
- deleteItemState: ListQueryDeleteItemStateApi<ItemState, ItemPayload>;
397
- /**
398
- * Runs the full mutation lifecycle: optional optimistic update, async
399
- * mutation, rollback/error handling, revalidation, and offline queue fallback.
400
- */
401
- performMutation: ListQueryPerformMutationApi<ItemState, QueryPayload, ItemPayload, TOfflineOperations>;
402
- /** React hook for subscribing to many list queries at once. */
403
- useMultipleListQueries: ListQueryUseMultipleListQueriesApi<ItemState, QueryPayload, ItemPayload, TPartialResources>;
404
- /** React hook for subscribing to one list query. */
405
- useListQuery: ListQueryUseListQueryApi<ItemState, QueryPayload, ItemPayload, TPartialResources>;
406
- /** React hook for subscribing to many list-query items at once. */
407
- useMultipleItems: ListQueryUseMultipleItemsApi<ItemState, ItemPayload, TPartialResources>;
408
- /** React hook for subscribing to one list-query item. */
409
- useItem: ListQueryUseItemApi<ItemState, ItemPayload, TPartialResources>;
410
- /** React hook for selecting the first cached item matching a predicate. */
411
- useFindItem: <SelectedItem = ItemState | null>(findItemFn: (item: ItemState, itemPayload: ItemPayload) => boolean, options?: {
412
- /** Maps the matched item before it is returned from the hook. */
413
- selector?: (data: ItemState, id: ItemPayload) => SelectedItem;
414
- }) => SelectedItem | null;
415
- /** Notifies the store that a shared transport reconnected and should revalidate active data. */
416
- onTransportReconnect: () => void;
417
- };
418
- /** Details passed when list-query cache-limit cleanup evicts cached items or queries. */
419
- export type ListQueryStateCleanup<QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = {
420
- /** Cleanup trigger that removed these records. */
421
- reason: 'cacheLimitEviction';
422
- /** Item store keys removed from state. */
423
- itemKeys: string[];
424
- /** Original item payloads removed from state. */
425
- itemPayloads: ItemPayload[];
426
- /** Query store keys removed from state. */
427
- queryKeys: string[];
428
- /** Original query payloads removed from state. */
429
- queryPayloads: QueryPayload[];
430
- };
431
- type FetchListFnSizeMode<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = (payload: QueryPayload, size: number, options: {
432
- signal: AbortSignal;
433
- fields?: string[];
434
- }) => Promise<MaybeTSDFResult<FetchListFnReturn<ItemState, ItemPayload>>>;
435
- type FetchListFnOffsetMode<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload> = (payload: QueryPayload, pagination: {
436
- offset: number;
437
- limit: number;
438
- }, options: {
439
- signal: AbortSignal;
440
- fields?: string[];
441
- }) => Promise<MaybeTSDFResult<FetchListFnReturn<ItemState, ItemPayload>>>;
442
- type ListQueryStoreOptionsBase<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean = false, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload> = null, StorageState = unknown> = {
443
- /**
444
- * Stable id for this logical list-query store. Used for debug labels,
445
- * persistence namespaces, and browser tab sync.
446
- */
447
- id: string;
448
- /** Shared global store manager providing session scoping and error normalization. */
449
- storeManager: StoreManager;
450
- /** Fetches one item by payload. Required when items can be loaded outside list pages. */
451
- fetchItemFn?: (payload: ItemPayload, options: {
452
- signal: AbortSignal;
453
- fields?: string[];
454
- }) => Promise<MaybeTSDFResult<ItemState>>;
455
- /** Optional batch fetch function for fetching multiple items at once. */
456
- batchFetchItemFn?: (requests: {
457
- payload: ItemPayload;
458
- fields?: string[];
459
- }[], options: {
460
- signal: AbortSignal;
461
- batchKey: string;
462
- }) => Promise<MaybeTSDFResult<Map<ItemPayload, MaybeTSDFResult<ItemState> | Error>>>;
463
- /** Optional function to group item batch fetches by key. When omitted, all batched items share one default batch key. Return false to fetch individually. */
464
- getItemsBatchKey?: (payload: ItemPayload) => string | false;
465
- /** Default number of items requested by list-query fetches. Defaults to 50. */
466
- defaultQuerySize?: number;
467
- /** Max items per item batch. Defaults to 50. Triggers an immediate fetch when reached. */
468
- maxItemBatchSize?: number;
469
- /** Maximum number of cached items kept in memory. Defaults to 5,000. Item pressure may evict whole inactive queries to avoid leaving cached queries partially loaded. */
470
- maxItems?: number;
471
- /** Maximum number of cached queries kept in memory. Defaults to 1,000. Inactive queries are evicted in LRU order while mounted hook queries stay protected. */
472
- maxQueries?: number;
473
- /** Called when cache-limit eviction removes items or queries from in-memory state. */
474
- onStateCleanup?: (cleanup: ListQueryStateCleanup<QueryPayload, ItemPayload>) => void;
475
- /** Treats refetches as real-time driven, disabling stale mount refetches by default. Defaults to `false`. */
476
- usesRealTimeUpdates?: boolean;
477
- /** Overrides the manager's default minimum interval between low-priority fetches for this store. */
478
- lowPriorityThrottleMs?: number;
479
- /** Overrides the manager's default coalescing window for this store. */
480
- baseCoalescingWindowMs?: number;
481
- /** Delay applied to medium-priority requests before they enter the scheduler. */
482
- mediumPriorityDelayMs?: number;
483
- /** Computes a per-fetch throttle for real-time updates using recent fetch cost and focus state. */
484
- dynamicRealtimeThrottleMs?: (params: {
485
- lastFetchDuration: number;
486
- windowIsNotFocused: boolean;
487
- }) => number;
488
- /** Store-level focus revalidation policy. Overrides the manager default. */
489
- revalidateOnWindowFocus?: boolean | (() => boolean);
490
- /** Reconnect-specific cooldown. Defaults to 2,000ms. The first reconnect revalidates immediately;
491
- * additional reconnects within the cooldown are coalesced into one trailing
492
- * revalidation. Set to `0` to disable this cooldown. */
493
- transportReconnectCooldownMs?: number;
494
- /** Rules that keep cached query membership in sync after item updates. */
495
- optimisticListUpdates?: OptimisticListUpdate<ItemState, QueryPayload, ItemPayload>[];
496
- /** Called when an already-loaded query is invalidated. */
497
- onInvalidateQuery?: OnListQueryInvalidate<QueryPayload>;
498
- /** Called when an already-loaded item is invalidated. */
499
- onInvalidateItem?: OnListQueryItemInvalidate<ItemState, ItemPayload>;
500
- /** Observes request scheduler lifecycle events for this store. */
501
- onSchedulerEvent?: (event: RequestSchedulerEvents, data?: RequestSchedulerEventData) => void;
502
- /**
503
- * Store-specific mutation error handler.
504
- *
505
- * Overrides the manager fallback. Use `null` to disable inherited mutation
506
- * error handling for this store.
507
- */
508
- onMutationError?: ((error: unknown, options: StoreMutationErrorOptions) => void) | null;
509
- /** Opt-in hook-level query derivation from locally materialized items. */
510
- derivedQueries?: DerivedQueriesConfig<ItemState, QueryPayload, ItemPayload>;
511
- /** Converts a query payload to the stable cache key used by this store. */
512
- getQueryKey?: (params: QueryPayload) => ValidPayload | unknown[];
513
- /** Converts an item payload to the stable cache key used by this store. */
514
- getItemKey?: (params: ItemPayload) => ValidPayload | unknown[];
515
- /** Opt-in persistent storage configuration. When provided, cached items and queries
516
- * are loaded from storage on first read and saved back on successful fetches.
517
- * Session scoping always reuses this store manager's `getSessionKey`, and the
518
- * persisted namespace always reuses this store's `id`. */
519
- persistentStorage?: ListQueryPersistentStorageConfig<ItemState, QueryPayload, ItemPayload, StorageState, TOfflineOperations>;
520
- } & ([TPartialResources] extends [true] ? {
521
- partialResources: PartialResourcesConfig<ItemState>;
522
- } : {
523
- partialResources?: undefined;
524
- });
525
- /** Options used to create a list-query store. */
526
- export type ListQueryStoreOptions<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean = false, TOffsetPagination extends boolean = false, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload> = null, StorageState = unknown> = ListQueryStoreOptionsBase<ItemState, QueryPayload, ItemPayload, TPartialResources, TOfflineOperations, StorageState> & ([TOffsetPagination] extends [true] ? {
527
- /** Fetches one offset-paginated list query page. */
528
- fetchListFn: FetchListFnOffsetMode<ItemState, QueryPayload, ItemPayload>;
529
- /** Enables offset-pagination behavior and invalidation sizing. */
530
- offsetPagination: OffsetPaginationConfig;
531
- } : {
532
- /** Fetches one size-based list query page. */
533
- fetchListFn: FetchListFnSizeMode<ItemState, QueryPayload, ItemPayload>;
534
- /** Not allowed unless offset pagination is enabled. */
535
- offsetPagination?: undefined;
536
- });
537
- export declare function createListQueryStore<ItemState extends ValidStoreState, QueryPayload extends ValidPayload, ItemPayload extends ValidPayload, TPartialResources extends boolean = false, TOffsetPagination extends boolean = false, TOfflineOperations extends ListQueryOfflineOperationsConfig<ItemState, QueryPayload, ItemPayload> = null, StorageState = unknown>(storeOptions: ListQueryStoreOptions<ItemState, QueryPayload, ItemPayload, TPartialResources, TOffsetPagination, TOfflineOperations, StorageState>): ListQueryStore<ItemState, QueryPayload, ItemPayload, TPartialResources, TOfflineOperations>;
538
- export {};