import { QueriesObserver, type DefaultError, type DefinedQueryObserverResult, type OmitKeyof, type QueriesObserverOptions, type QueryFunction, type QueryKey, type QueryObserverOptions, type QueryObserverResult, type ThrowOnError, } from '@tanstack/query-core' import type { QueryClient } from '@tanstack/query-core' import type { ReactiveControllerHost } from 'lit' import { createValueAccessor, readAccessor, type Accessor, type ValueAccessor, } from './accessor.js' import { createMissingQueryClientError } from './context.js' import { BaseController } from './controllers/BaseController.js' /** * Options for one query inside `createQueriesController`. * * This mirrors `QueryObserverOptions` and is used by the tuple inference that * maps each input query to its corresponding result. */ export type CreateQueriesInput< TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, > = QueryObserverOptions type CreateQueriesInputForController< TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, > = OmitKeyof, never> type MAXIMUM_DEPTH = 20 type SkipTokenForCreateQueries = symbol type GetCreateQueriesInput = T extends { queryFnData: infer TQueryFnData error?: infer TError data: infer TData } ? CreateQueriesInputForController : T extends { queryFnData: infer TQueryFnData; error?: infer TError } ? CreateQueriesInputForController : T extends { data: infer TData; error?: infer TError } ? CreateQueriesInputForController : T extends [infer TQueryFnData, infer TError, infer TData] ? CreateQueriesInputForController : T extends [infer TQueryFnData, infer TError] ? CreateQueriesInputForController : T extends [infer TQueryFnData] ? CreateQueriesInputForController : T extends { queryFn?: | QueryFunction | SkipTokenForCreateQueries select?: (data: any) => infer TData throwOnError?: ThrowOnError } ? CreateQueriesInputForController< TQueryFnData, unknown extends TError ? DefaultError : TError, unknown extends TData ? TQueryFnData : TData, TQueryKey > : CreateQueriesInputForController type GetDefinedOrUndefinedCreateQueriesResult< T, TData, TError = unknown, > = T extends { initialData?: infer TInitialData } ? unknown extends TInitialData ? QueryObserverResult : TInitialData extends TData ? DefinedQueryObserverResult : TInitialData extends () => infer TInitialDataResult ? unknown extends TInitialDataResult ? QueryObserverResult : TInitialDataResult extends TData ? DefinedQueryObserverResult : QueryObserverResult : QueryObserverResult : QueryObserverResult type GetCreateQueriesResult = T extends { queryFnData: any error?: infer TError data: infer TData } ? GetDefinedOrUndefinedCreateQueriesResult : T extends { queryFnData: infer TQueryFnData; error?: infer TError } ? GetDefinedOrUndefinedCreateQueriesResult : T extends { data: infer TData; error?: infer TError } ? GetDefinedOrUndefinedCreateQueriesResult : T extends [any, infer TError, infer TData] ? GetDefinedOrUndefinedCreateQueriesResult : T extends [infer TQueryFnData, infer TError] ? GetDefinedOrUndefinedCreateQueriesResult : T extends [infer TQueryFnData] ? GetDefinedOrUndefinedCreateQueriesResult : T extends { queryFn?: | QueryFunction | SkipTokenForCreateQueries select?: (data: any) => infer TData throwOnError?: ThrowOnError } ? GetDefinedOrUndefinedCreateQueriesResult< T, unknown extends TData ? TQueryFnData : TData, unknown extends TError ? DefaultError : TError > : QueryObserverResult export type CreateQueriesOptions< T extends Array, TResults extends Array = [], TDepth extends ReadonlyArray = [], > = TDepth['length'] extends MAXIMUM_DEPTH ? Array : T extends [] ? [] : T extends [infer Head] ? [...TResults, GetCreateQueriesInput] : T extends [infer Head, ...infer Tails] ? CreateQueriesOptions< [...Tails], [...TResults, GetCreateQueriesInput], [...TDepth, 1] > : ReadonlyArray extends T ? T : T extends Array< CreateQueriesInputForController< infer TQueryFnData, infer TError, infer TData, infer TQueryKey > > ? Array< CreateQueriesInputForController< TQueryFnData, TError, TData, TQueryKey > > : Array /** * Tuple of query results inferred from the query inputs passed to * `createQueriesController`. */ export type CreateQueriesResults< T extends Array, TResults extends Array = [], TDepth extends ReadonlyArray = [], > = TDepth['length'] extends MAXIMUM_DEPTH ? Array : T extends [] ? [] : T extends [infer Head] ? [...TResults, GetCreateQueriesResult] : T extends [infer Head, ...infer Tails] ? CreateQueriesResults< [...Tails], [...TResults, GetCreateQueriesResult], [...TDepth, 1] > : { [K in keyof T]: GetCreateQueriesResult } /** * Options accepted by `createQueriesController`. * * `queries` can be a static list or a getter that returns the current list. * `combine` can reshape the array of query results into a single value for the * returned accessor. */ export type CreateQueriesControllerOptions< TQueryOptions extends Array = Array, TCombinedResult = CreateQueriesResults, > = { /** Query options to observe, or a getter that returns the current options. */ queries: Accessor< | readonly [...CreateQueriesOptions] | readonly [ ...{ [K in keyof TQueryOptions]: GetCreateQueriesInput }, ] > /** Optional function that combines the query result array into one value. */ combine?: (result: CreateQueriesResults) => TCombinedResult } /** * Accessor returned by `createQueriesController`. * * Call the accessor or read its `current` property to get the latest combined * value. */ export type QueriesResultAccessor = ValueAccessor & { /** Removes the controller from its Lit host and unsubscribes observers. */ destroy: () => void } function createPendingQueryObserverResult(): QueryObserverResult { return { data: undefined, dataUpdatedAt: 0, error: null, errorUpdatedAt: 0, failureCount: 0, failureReason: null, errorUpdateCount: 0, isError: false, isFetched: false, isFetchedAfterMount: false, isFetching: false, isInitialLoading: false, isLoading: false, isLoadingError: false, isPaused: false, isPending: true, isPlaceholderData: false, isRefetchError: false, isRefetching: false, isStale: true, isEnabled: true, isSuccess: false, fetchStatus: 'idle', status: 'pending', refetch: (() => Promise.reject( createMissingQueryClientError(), )) as QueryObserverResult['refetch'], promise: Promise.resolve(undefined as never), } as unknown as QueryObserverResult } function createPlaceholderQueryObserverResult( query: QueryObserverOptions, ): QueryObserverResult { const initialData = typeof query.initialData === 'function' ? query.initialData() : query.initialData if (initialData === undefined) { return createPendingQueryObserverResult() } const data = query.select ? query.select(initialData) : initialData const initialDataUpdatedAt = typeof query.initialDataUpdatedAt === 'function' ? query.initialDataUpdatedAt() : query.initialDataUpdatedAt return { ...createPendingQueryObserverResult(), data, dataUpdatedAt: initialDataUpdatedAt ?? Date.now(), isPending: false, isInitialLoading: false, isLoading: false, isSuccess: true, status: 'success', promise: Promise.resolve(data as never), } as QueryObserverResult } function resolveQueriesOptions( optionsAccessor: Accessor< CreateQueriesControllerOptions >, client: QueryClient, ): { queries: Array combine: QueriesObserverOptions['combine'] } { const resolvedOptions = readAccessor(optionsAccessor) const resolvedQueries = readAccessor(resolvedOptions.queries) const combine = resolvedOptions.combine as QueriesObserverOptions['combine'] return { queries: resolvedQueries.map((query) => { const defaulted = client.defaultQueryOptions( query as QueryObserverOptions, ) ;(defaulted as { _optimisticResults?: 'optimistic' })._optimisticResults = 'optimistic' return defaulted }), combine, } } class QueriesController< TQueryOptions extends Array, TCombinedResult, > extends BaseController { private readonly options: Accessor< CreateQueriesControllerOptions > private observer: QueriesObserver | undefined private unsubscribe: (() => void) | undefined private queryClient: QueryClient | undefined private explicitInitializationError: unknown | undefined private placeholderInitialized = false private placeholderRetryableFailure = true constructor( host: ReactiveControllerHost, options: Accessor< CreateQueriesControllerOptions >, queryClient?: QueryClient, ) { super(host, [] as unknown as TCombinedResult, queryClient) this.options = options queueMicrotask(() => { this.placeholderRetryableFailure = false }) if (!queryClient) { return } if (this.shouldRefreshOnHostUpdate()) { return } this.tryInitializeExplicitClient(queryClient) } protected onConnected(): void { if (!this.syncClient()) { return } this.refreshOptions() this.subscribe() } protected onDisconnected(): void { this.unsubscribeObserver() this.syncClient() } protected onHostUpdate(): void { if (!this.shouldRefreshOnHostUpdate()) { return } if (!this.refreshOptions()) { this.setPlaceholderResult() } } protected onQueryClientChanged(): void { if (!this.syncClient() || !this.connectedState) { return } this.refreshOptions() this.subscribe() } private subscribe(): void { if (!this.observer) { return } if (this.unsubscribe) { return } this.unsubscribe = this.observer.subscribe((next) => { const { combine } = this.readResolvedOptions() this.setResult(this.computeResult(next, combine)) }) } private tryInitializeExplicitClient(queryClient: QueryClient): boolean { try { const { queries, combine } = resolveQueriesOptions( this.options, queryClient, ) const observer = new QueriesObserver(queryClient, queries, { combine, } as QueriesObserverOptions) this.queryClient = queryClient this.observer = observer this.result = this.computeResult(observer.getCurrentResult(), combine) this.explicitInitializationError = undefined this.placeholderInitialized = true return true } catch (error) { // Retry after construction completes so late host fields used by // static queries/combine callbacks can finish initializing first. this.explicitInitializationError = error this.queryClient = undefined this.observer = undefined return false } } private retryExplicitInitializationIfNeeded(): boolean { if (!this.explicitInitializationError || this.shouldRefreshOnHostUpdate()) { return false } const explicitClient = this.tryGetQueryClient() if (!explicitClient) { return false } return this.tryInitializeExplicitClient(explicitClient) } private unsubscribeObserver(): void { this.unsubscribe?.() this.unsubscribe = undefined } private syncClient(): boolean { const nextClient = this.tryGetQueryClient() if (!nextClient) { this.unsubscribeObserver() this.queryClient = undefined this.observer = undefined this.setPlaceholderResult() return false } if (nextClient === this.queryClient) { return true } this.unsubscribeObserver() this.queryClient = nextClient const { queries, combine } = this.readResolvedOptions() this.observer = new QueriesObserver(this.queryClient, queries, { combine, } as QueriesObserverOptions) this.setResult( this.computeResult(this.observer.getCurrentResult(), combine), ) this.placeholderInitialized = true return true } private refreshOptions(): boolean { if (!this.syncClient() || !this.observer) { return false } const { queries, combine } = this.readResolvedOptions() this.observer.setQueries(queries, { combine, } as QueriesObserverOptions) const [rawResult, getCombinedResult] = this.observer.getOptimisticResult( queries, combine, ) this.setResult(getCombinedResult(rawResult)) return true } private readResolvedOptions(client = this.queryClient): { queries: Array combine: QueriesObserverOptions['combine'] } { if (!client) { throw createMissingQueryClientError() } return resolveQueriesOptions( this.options as Accessor< CreateQueriesControllerOptions >, client, ) } private shouldRefreshOnHostUpdate(): boolean { if (typeof this.options === 'function') { return true } return typeof this.options.queries === 'function' } private computeResult( rawResult: Array, combine: QueriesObserverOptions['combine'], ): TCombinedResult { return (combine ? combine(rawResult) : rawResult) as TCombinedResult } private static createPlaceholderResult( optionsAccessor: Accessor< CreateQueriesControllerOptions >, ): TCombinedResult { const resolvedOptions = readAccessor(optionsAccessor) const queries = readAccessor(resolvedOptions.queries) const placeholders = queries.map((query) => createPlaceholderQueryObserverResult(query as QueryObserverOptions), ) return ( resolvedOptions.combine ? resolvedOptions.combine(placeholders as never) : placeholders ) as TCombinedResult } readCurrent(): TCombinedResult { if (this.retryExplicitInitializationIfNeeded()) { return this.current } if (this.explicitInitializationError && !this.placeholderRetryableFailure) { throw this.explicitInitializationError } if (!this.queryClient && !this.observer && !this.placeholderInitialized) { try { // Early reads can happen during class-field initialization, before // accessors referenced by queries/combine are ready. Retry normally // after construction finishes and only surface errors after that point. this.setPlaceholderResult() } catch (error) { if (!this.placeholderRetryableFailure) { throw error } } } return this.current } private setPlaceholderResult(): void { this.result = QueriesController.createPlaceholderResult(this.options) this.placeholderInitialized = true } } /** * Creates a Lit reactive controller that subscribes the host to multiple * queries. * * The returned accessor is callable and also exposes `current` and `destroy`. * When `options` or `options.queries` is a function, it is re-read during host * updates so the query list can follow reactive host state. * * If `queryClient` is omitted, the controller resolves the client from the * nearest connected `QueryClientProvider`. * * @param host - The Lit reactive controller host that owns the queries * subscription. * @param options - Queries controller options, or a getter that returns options. * @param queryClient - Optional explicit query client. Provide this for * controllers that should not resolve a client from Lit context. * @returns An accessor for the latest query results, or the value returned by * `combine`. * * @example * ```ts * import { LitElement, html } from 'lit' * import { createQueriesController } from '@tanstack/lit-query' * * class DashboardView extends LitElement { * private readonly dashboard = createQueriesController(this, { * queries: [ * { queryKey: ['stats'], queryFn: fetchStats }, * { queryKey: ['projects'], queryFn: fetchProjects }, * ], * combine: ([stats, projects]) => ({ * stats: stats.data, * projects: projects.data ?? [], * isPending: stats.isPending || projects.isPending, * }), * }) * * render() { * const dashboard = this.dashboard() * return html`

Projects: ${dashboard.projects.length}

` * } * } * ``` */ export function createQueriesController< TQueryOptions extends Array, TCombinedResult = CreateQueriesResults, >( host: ReactiveControllerHost, options: Accessor< CreateQueriesControllerOptions >, queryClient?: QueryClient, ): QueriesResultAccessor { const controller = new QueriesController(host, options, queryClient) return Object.assign( createValueAccessor(() => controller.readCurrent()), { destroy: () => controller.destroy(), }, ) }