Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

index.ts

322 lines10.3 KB

1import {
2 DestroyRef,
3 assertInInjectionContext,
4 computed,
5 effect,
6 inject,
7 signal,
8} from '@angular/core'
9import {
10 BaseQueryBuilder,
11 createLiveQueryCollection,
12 createLiveQueryObserver,
13 getPublicCollection,
14 isCollection,
15 isSingleResultCollection,
16 resolveLiveQueryValue,
17} from '@tanstack/db'
18import type {
19 Collection,
20 CollectionStatus,
21 Context,
22 GetResult,
23 InferResultType,
24 InitialQueryBuilder,
25 LiveQueryCollectionConfig,
26 LiveQueryObserver,
27 LiveQueryPersistedStatus,
28 NonSingleResult,
29 QueryBuilder,
30 SingleResult,
31} from '@tanstack/db'
32import type { Signal } from '@angular/core'
33​
34export * from '@tanstack/db'
35​
36/**
37 * The result of calling `injectLiveQuery`.
38 * Contains reactive signals for the query state and data.
39 */
40export interface InjectLiveQueryResult<TContext extends Context> {
41 /** A signal containing the complete state map of results keyed by their ID */
42 state: Signal<Map<string | number, GetResult<TContext>>>
43 /** A signal containing the results as an array, or single result for findOne queries */
44 data: Signal<InferResultType<TContext>>
45 /** A signal containing the underlying collection instance (null for disabled queries) */
46 collection: Signal<Collection<
47 GetResult<TContext>,
48 string | number,
49 {}
50 > | null>
51 /** A signal containing the current status of the collection */
52 status: Signal<CollectionStatus | `disabled`>
53 /** A signal indicating whether the collection is currently loading */
54 isLoading: Signal<boolean>
55 /** A signal indicating whether the collection is ready */
56 isReady: Signal<boolean>
57 persistedStatus: Signal<LiveQueryPersistedStatus>
58 isPersistedReady: Signal<boolean>
59 persistedError: Signal<unknown | undefined>
60 /** A signal indicating whether the collection is idle */
61 isIdle: Signal<boolean>
62 /** A signal indicating whether the collection has an error */
63 isError: Signal<boolean>
64 /** A signal indicating whether the collection has been cleaned up */
65 isCleanedUp: Signal<boolean>
67​
68type InferConditionalResultType<TContext extends Context> =
69 TContext extends SingleResult
70 ? InferResultType<TContext> | []
71 : InferResultType<TContext>
72​
73export type InjectConditionalLiveQueryResult<TContext extends Context> = Omit<
74 InjectLiveQueryResult<TContext>,
75 `data`
76> & {
77 data: Signal<InferConditionalResultType<TContext>>
79​
80export interface InjectLiveQueryResultWithCollection<
81 TResult extends object = any,
82 TKey extends string | number = string | number,
83 TUtils extends Record<string, any> = {},
84> {
85 state: Signal<Map<TKey, TResult>>
86 data: Signal<Array<TResult>>
87 collection: Signal<Collection<TResult, TKey, TUtils> | null>
88 status: Signal<CollectionStatus | `disabled`>
89 isLoading: Signal<boolean>
90 isReady: Signal<boolean>
91 persistedStatus: Signal<LiveQueryPersistedStatus>
92 isPersistedReady: Signal<boolean>
93 persistedError: Signal<unknown | undefined>
94 isIdle: Signal<boolean>
95 isError: Signal<boolean>
96 isCleanedUp: Signal<boolean>
98​
99export interface InjectLiveQueryResultWithSingleResultCollection<
100 TResult extends object = any,
101 TKey extends string | number = string | number,
102 TUtils extends Record<string, any> = {},
103> {
104 state: Signal<Map<TKey, TResult>>
105 data: Signal<TResult | undefined>
106 collection: Signal<(Collection<TResult, TKey, TUtils> & SingleResult) | null>
107 status: Signal<CollectionStatus | `disabled`>
108 isLoading: Signal<boolean>
109 isReady: Signal<boolean>
110 persistedStatus: Signal<LiveQueryPersistedStatus>
111 isPersistedReady: Signal<boolean>
112 persistedError: Signal<unknown | undefined>
113 isIdle: Signal<boolean>
114 isError: Signal<boolean>
115 isCleanedUp: Signal<boolean>
117​
118export function injectLiveQuery<
119 TContext extends Context,
120 TParams extends any,
121>(options: {
122 params: () => TParams
123 query: (args: {
124 params: TParams
125 q: InitialQueryBuilder
126 }) => QueryBuilder<TContext>
127}): InjectLiveQueryResult<TContext>
128export function injectLiveQuery<
129 TContext extends Context,
130 TParams extends any,
131>(options: {
132 params: () => TParams
133 query: (args: {
134 params: TParams
135 q: InitialQueryBuilder
136 }) => QueryBuilder<TContext> | undefined | null
137}): InjectConditionalLiveQueryResult<TContext>
138export function injectLiveQuery<TContext extends Context>(
139 queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
140): InjectLiveQueryResult<TContext>
141export function injectLiveQuery<TContext extends Context>(
142 queryFn: (
143 q: InitialQueryBuilder,
144 ) => QueryBuilder<TContext> | undefined | null,
145): InjectConditionalLiveQueryResult<TContext>
146export function injectLiveQuery<TContext extends Context>(
147 config: LiveQueryCollectionConfig<TContext>,
148): InjectLiveQueryResult<TContext>
149// Pre-created collection without singleResult
150export function injectLiveQuery<
151 TResult extends object,
152 TKey extends string | number,
153 TUtils extends Record<string, any>,
154>(
155 liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,
156): InjectLiveQueryResultWithCollection<TResult, TKey, TUtils>
157// Pre-created collection with singleResult
158export function injectLiveQuery<
159 TResult extends object,
160 TKey extends string | number,
161 TUtils extends Record<string, any>,
162>(
163 liveQueryCollection: Collection<TResult, TKey, TUtils> & SingleResult,
164): InjectLiveQueryResultWithSingleResultCollection<TResult, TKey, TUtils>
165export function injectLiveQuery(opts: any) {
166 assertInInjectionContext(injectLiveQuery)
167 const destroyRef = inject(DestroyRef)
168​
169 const collection = computed(() => {
170 // Check if it's an existing collection
171 if (isCollection(opts)) {
172 return opts
173 }
174​
175 if (typeof opts === `function`) {
176 // Check if query function returns null/undefined (disabled query)
177 const queryBuilder = new BaseQueryBuilder() as InitialQueryBuilder
178 const result = opts(queryBuilder)
179​
180 if (result === undefined || result === null) {
181 // Disabled query - return null
182 return null
183 }
184​
185 return resolveLiveQueryValue(result, { gcTime: 0 })
186 }
187​
188 // Check if it's reactive query options
189 const isReactiveQueryOptions =
190 opts &&
191 typeof opts === `object` &&
192 typeof opts.query === `function` &&
193 typeof opts.params === `function`
194​
195 if (isReactiveQueryOptions) {
196 const { params, query } = opts
197 const currentParams = params()
198​
199 // Check if query function returns null/undefined (disabled query)
200 const queryBuilder = new BaseQueryBuilder() as InitialQueryBuilder
201 const result = query({ params: currentParams, q: queryBuilder })
202​
203 if (result === undefined || result === null) {
204 // Disabled query - return null
205 return null
206 }
207​
208 return resolveLiveQueryValue(result, { gcTime: 0 })
209 }
210​
211 // Handle LiveQueryCollectionConfig objects. Default startSync/gcTime to
212 // match the query-fn and reactive-options paths, but let an explicit value
213 // in the config win — otherwise a bare `{ query }` never syncs.
214 if (opts && typeof opts === `object` && typeof opts.query === `function`) {
215 return createLiveQueryCollection({ startSync: true, gcTime: 0, ...opts })
216 }
217​
218 throw new Error(`Invalid options provided to injectLiveQuery`)
219 })
220​
221 const state = signal(new Map<string | number, any>())
222 const internalData = signal<Array<any>>([])
223 const statusValue = signal<CollectionStatus | `disabled`>(`idle`)
224 const status = computed(() => {
225 const value = statusValue()
226 return value === `idle` && !collection() ? `disabled` : value
227 })
228 const persistedStatus = signal<LiveQueryPersistedStatus>(`unavailable`)
229 const persistedError = signal<unknown>(undefined)
230​
231 // Returns single item for singleResult collections, array otherwise
232 const data = computed(() => {
233 const currentCollection = collection()
234 if (!currentCollection) {
235 return internalData()
236 }
237 return isSingleResultCollection(currentCollection)
238 ? internalData()[0]
239 : internalData()
240 })
241​
242 const syncDataFromCollection = (
243 currentCollection: Collection<any, any, any>,
244 observer: LiveQueryObserver<any, any>,
245 ) => {
246 const newState = new Map(currentCollection.entries())
247 const newData = Array.from(newState.values())
248​
249 state.set(newState)
250 internalData.set(newData)
251 const snapshot = observer.getSnapshot()
252 statusValue.set(snapshot.status)
253 persistedStatus.set(snapshot.persistedStatus)
254 persistedError.set(snapshot.persistedError)
255 }
256​
257 let unsub: (() => void) | null = null
258 const cleanup = () => {
259 unsub?.()
260 unsub = null
261 }
262​
263 effect((onCleanup) => {
264 const currentCollection = collection()
265​
266 // Handle null collection (disabled query)
267 if (!currentCollection) {
268 statusValue.set(`disabled` as const)
269 persistedStatus.set(`unavailable`)
270 persistedError.set(undefined)
271 state.set(new Map())
272 internalData.set([])
273 cleanup()
274 return
275 }
276​
277 cleanup()
278​
279 // The shared observer owns sync start, subscription, the ready-race, and
280 // status transitions; Angular re-reads the whole collection on each notify
281 // (wholesale) into its signals.
282 // Angular re-reads the collection on notify; wholesale mode preserves its
283 // pre-observer loading policy (no initial-state snapshot request).
284 const observer = createLiveQueryObserver(currentCollection, {
285 mode: `wholesale`,
286 })
287​
288 const unsubscribe = observer.subscribe(() => {
289 syncDataFromCollection(currentCollection, observer)
290 })
291 // Wholesale attach suppresses listener calls raised by synchronous sync
292 // startup. Read once after subscribe returns to capture that final state.
293 syncDataFromCollection(currentCollection, observer)
294 unsub = () => {
295 unsubscribe()
296 observer.dispose()
297 }
298​
299 onCleanup(cleanup)
300 })
301​
302 destroyRef.onDestroy(cleanup)
303​
304 return {
305 state,
306 data,
307 // Loosely typed so the impl return stays compatible with every overload
308 // (the shared `isCollection` guard narrows the computed to `Collection | null`).
309 collection: computed(() =>
310 getPublicCollection(collection()),
311 ) as Signal<any>,
312 status,
313 isLoading: computed(() => status() === `loading`),
314 isReady: computed(() => status() === `ready` || status() === `disabled`),
315 persistedStatus,
316 isPersistedReady: computed(() => persistedStatus() === `ready`),
317 persistedError,
318 isIdle: computed(() => status() === `idle`),
319 isError: computed(() => status() === `error`),
320 isCleanedUp: computed(() => status() === `cleaned-up`),
321 }