@tanstack/lit-query 0.0.1 → 0.2.0

package/src/createQueryController.ts

@@ -0,0 +1,342 @@
+import {
+  QueryObserver,
+  type DefaultError,
+  type DefaultedQueryObserverOptions,
+  type QueryKey,
+  type QueryObserverOptions,
+  type QueryObserverResult,
+} 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 accepted by `createQueryController`.
+ *
+ * This is the Lit adapter shape for `QueryObserverOptions`. It can be passed
+ * directly to `createQueryController`, or wrapped in an `Accessor` when the
+ * options depend on Lit host state.
+ */
+export type CreateQueryOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+
+/**
+ * Accessor returned by `createQueryController`.
+ *
+ * Call the accessor or read its `current` property to get the latest query
+ * result. The attached methods delegate to the active query observer.
+ */
+export type QueryResultAccessor<TData, TError> = ValueAccessor<
+  QueryObserverResult<TData, TError>
+> & {
+  /** Refetches the current query. */
+  refetch: QueryObserverResult<TData, TError>['refetch']
+  /** Resolves with an optimistic query result, fetching first when needed. */
+  suspense: () => Promise<QueryObserverResult<TData, TError>>
+  /** Removes the controller from its Lit host and unsubscribes observers. */
+  destroy: () => void
+}
+
+function createPendingQueryResult<TData, TError>(): QueryObserverResult<
+  TData,
+  TError
+> {
+  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<
+      TData,
+      TError
+    >['refetch'],
+    promise: Promise.resolve(undefined as never),
+  } as unknown as QueryObserverResult<TData, TError>
+}
+
+class QueryController<
+  TQueryFnData,
+  TError,
+  TData,
+  TQueryData,
+  TQueryKey extends QueryKey,
+> extends BaseController<QueryObserverResult<TData, TError>> {
+  private readonly options: Accessor<
+    CreateQueryOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+  >
+  private observer:
+    | QueryObserver<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+    | undefined
+  private unsubscribe: (() => void) | undefined
+  private queryClient: QueryClient | undefined
+
+  constructor(
+    host: ReactiveControllerHost,
+    options: Accessor<
+      CreateQueryOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+    >,
+    queryClient?: QueryClient,
+  ) {
+    const initialClient = queryClient
+    super(host, createPendingQueryResult(), queryClient)
+    this.options = options
+
+    if (!initialClient) {
+      return
+    }
+
+    if (typeof options === 'function') {
+      return
+    }
+
+    const defaulted = this.defaultOptions(initialClient)
+    const observer = new QueryObserver(initialClient, defaulted)
+    this.queryClient = initialClient
+    this.observer = observer
+    this.result = observer.getOptimisticResult(defaulted)
+  }
+
+  protected onConnected(): void {
+    if (!this.syncClient()) {
+      return
+    }
+
+    this.refreshOptions()
+    this.subscribe()
+    this.observer?.updateResult()
+    if (this.observer) {
+      this.setResult(this.observer.getCurrentResult())
+    }
+  }
+
+  protected onDisconnected(): void {
+    this.unsubscribeObserver()
+    this.syncClient()
+  }
+
+  protected onHostUpdate(): void {
+    if (typeof this.options !== 'function') {
+      return
+    }
+
+    this.refreshOptions()
+  }
+
+  protected onQueryClientChanged(): void {
+    if (!this.syncClient()) {
+      return
+    }
+
+    if (!this.connectedState) {
+      return
+    }
+
+    this.refreshOptions()
+    this.subscribe()
+    this.observer?.updateResult()
+    if (this.observer) {
+      this.setResult(this.observer.getCurrentResult())
+    }
+  }
+
+  refetch: QueryObserverResult<TData, TError>['refetch'] = (...args) => {
+    if (!this.refreshOptions()) {
+      return Promise.reject(createMissingQueryClientError())
+    }
+
+    return this.result.refetch(...args)
+  }
+
+  suspense = async (): Promise<QueryObserverResult<TData, TError>> => {
+    if (!this.syncClient() || !this.observer || !this.queryClient) {
+      throw createMissingQueryClientError()
+    }
+
+    const options = this.defaultOptions(this.queryClient)
+    this.observer.setOptions(options)
+    const optimistic = this.observer.getOptimisticResult(options)
+    if (options.enabled !== false && optimistic.isStale) {
+      return this.observer.fetchOptimistic(options)
+    }
+
+    return optimistic
+  }
+
+  private subscribe(): void {
+    if (!this.observer) {
+      return
+    }
+
+    if (this.unsubscribe) {
+      return
+    }
+
+    this.unsubscribe = this.observer.subscribe((next) => {
+      this.setResult(next)
+    })
+  }
+
+  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.setResult(createPendingQueryResult())
+      return false
+    }
+
+    if (nextClient === this.queryClient && this.observer) {
+      return true
+    }
+
+    this.unsubscribeObserver()
+    this.queryClient = nextClient
+    const options = this.defaultOptions()
+    this.observer = new QueryObserver(this.queryClient, options)
+    this.setResult(this.observer.getOptimisticResult(options))
+    return true
+  }
+
+  private refreshOptions(): boolean {
+    if (!this.syncClient() || !this.observer) {
+      return false
+    }
+
+    const options = this.defaultOptions(this.queryClient)
+    this.observer.setOptions(options)
+    this.setResult(this.observer.getOptimisticResult(options))
+    return true
+  }
+
+  private defaultOptions(
+    client = this.queryClient,
+  ): DefaultedQueryObserverOptions<
+    TQueryFnData,
+    TError,
+    TData,
+    TQueryData,
+    TQueryKey
+  > {
+    const resolvedClient = client ?? this.tryGetQueryClient()
+    if (!resolvedClient) {
+      throw createMissingQueryClientError()
+    }
+
+    this.queryClient = resolvedClient
+    const defaulted = resolvedClient.defaultQueryOptions(
+      readAccessor(this.options),
+    ) as DefaultedQueryObserverOptions<
+      TQueryFnData,
+      TError,
+      TData,
+      TQueryData,
+      TQueryKey
+    >
+    ;(defaulted as { _optimisticResults?: 'optimistic' })._optimisticResults =
+      'optimistic'
+    return defaulted
+  }
+}
+
+/**
+ * Creates a Lit reactive controller that subscribes the host to a single query.
+ *
+ * The returned accessor is callable and also exposes `current`, `refetch`,
+ * `suspense`, and `destroy`. When `options` is a function, it is re-read during
+ * host updates so query keys and options 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 query
+ * subscription.
+ * @param options - Query observer 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 result with query helper methods.
+ *
+ * @example
+ * ```ts
+ * import { LitElement, html } from 'lit'
+ * import { createQueryController } from '@tanstack/lit-query'
+ *
+ * class TodosView extends LitElement {
+ *   private readonly todos = createQueryController(this, {
+ *     queryKey: ['todos'],
+ *     queryFn: async () => fetch('/api/todos').then((r) => r.json()),
+ *   })
+ *
+ *   render() {
+ *     const query = this.todos()
+ *
+ *     if (query.isPending) return html`Loading...`
+ *     if (query.isError) return html`Error`
+ *
+ *     return html`<ul>${query.data.map((todo) => html`<li>${todo.title}</li>`)}</ul>`
+ *   }
+ * }
+ * ```
+ */
+export function createQueryController<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  host: ReactiveControllerHost,
+  options: Accessor<
+    CreateQueryOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+  >,
+  queryClient?: QueryClient,
+): QueryResultAccessor<TData, TError> {
+  const controller = new QueryController(host, options, queryClient)
+
+  return Object.assign(
+    createValueAccessor(() => controller.current),
+    {
+      refetch: controller.refetch,
+      suspense: controller.suspense,
+      destroy: () => controller.destroy(),
+    },
+  )
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+/* istanbul ignore file */
+
+export * from '@tanstack/query-core'
+
+export type { Accessor, ValueAccessor } from './accessor.js'
+
+export {
+  getDefaultQueryClient,
+  queryClientContext,
+  registerDefaultQueryClient,
+  resolveQueryClient,
+  unregisterDefaultQueryClient,
+  useQueryClient,
+} from './context.js'
+
+export { QueryClientProvider } from './QueryClientProvider.js'
+
+export type {
+  CreateInfiniteQueryOptions,
+  InfiniteQueryResultAccessor,
+} from './createInfiniteQueryController.js'
+export { createInfiniteQueryController } from './createInfiniteQueryController.js'
+
+export type {
+  CreateMutationOptions,
+  MutationResultAccessor,
+} from './createMutationController.js'
+export { createMutationController } from './createMutationController.js'
+
+export type {
+  CreateQueriesControllerOptions,
+  CreateQueriesInput,
+  QueriesResultAccessor,
+} from './createQueriesController.js'
+export { createQueriesController } from './createQueriesController.js'
+
+export type {
+  CreateQueryOptions,
+  QueryResultAccessor,
+} from './createQueryController.js'
+export { createQueryController } from './createQueryController.js'
+
+export type { IsFetchingAccessor } from './useIsFetching.js'
+export { useIsFetching } from './useIsFetching.js'
+
+export type { IsMutatingAccessor } from './useIsMutating.js'
+export { useIsMutating } from './useIsMutating.js'
+
+export type {
+  MutationStateAccessor,
+  MutationStateOptions,
+} from './useMutationState.js'
+export { useMutationState } from './useMutationState.js'
+
+export type {
+  DefinedInitialDataOptions,
+  UndefinedInitialDataOptions,
+  UnusedSkipTokenOptions,
+} from './queryOptions.js'
+export { queryOptions } from './queryOptions.js'
+
+export { infiniteQueryOptions } from './infiniteQueryOptions.js'
+export { mutationOptions } from './mutationOptions.js'
+
+export type {
+  InfiniteQueryControllerOptions,
+  MutationControllerOptions,
+  MutationControllerResult,
+  QueriesControllerOptions,
+  QueryControllerOptions,
+  QueryControllerResult,
+} from './types.js'

package/src/infiniteQueryOptions.ts

@@ -0,0 +1,48 @@
+import type {
+  DefaultError,
+  InfiniteData,
+  InfiniteQueryObserverOptions,
+  QueryKey,
+} from '@tanstack/query-core'
+
+/**
+ * Preserves and types infinite query options for reuse across Lit Query APIs.
+ *
+ * @param options - Infinite query options to preserve.
+ * @returns The same options object.
+ *
+ * @example
+ * ```ts
+ * import { infiniteQueryOptions } from '@tanstack/lit-query'
+ *
+ * const projectsOptions = infiniteQueryOptions({
+ *   queryKey: ['projects'],
+ *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextCursor,
+ * })
+ * ```
+ */
+export function infiniteQueryOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = InfiniteData<TQueryFnData>,
+  TQueryKey extends QueryKey = QueryKey,
+  TPageParam = unknown,
+>(
+  options: InfiniteQueryObserverOptions<
+    TQueryFnData,
+    TError,
+    TData,
+    TQueryKey,
+    TPageParam
+  >,
+): InfiniteQueryObserverOptions<
+  TQueryFnData,
+  TError,
+  TData,
+  TQueryKey,
+  TPageParam
+> {
+  return options
+}

package/src/mutationOptions.ts

@@ -0,0 +1,31 @@
+import type {
+  DefaultError,
+  MutationObserverOptions,
+} from '@tanstack/query-core'
+
+/**
+ * Preserves and types mutation options for reuse across Lit Query APIs.
+ *
+ * @param options - Mutation options to preserve.
+ * @returns The same options object.
+ *
+ * @example
+ * ```ts
+ * import { mutationOptions } from '@tanstack/lit-query'
+ *
+ * const addTodoOptions = mutationOptions({
+ *   mutationKey: ['add-todo'],
+ *   mutationFn: (title: string) => addTodo(title),
+ * })
+ * ```
+ */
+export function mutationOptions<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TOnMutateResult = unknown,
+>(
+  options: MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>,
+): MutationObserverOptions<TData, TError, TVariables, TOnMutateResult> {
+  return options
+}

package/src/queryOptions.ts

@@ -0,0 +1,143 @@
+import type {
+  DataTag,
+  DefaultError,
+  InitialDataFunction,
+  NonUndefinedGuard,
+  OmitKeyof,
+  QueryFunction,
+  QueryKey,
+  QueryObserverOptions,
+  SkipToken,
+} from '@tanstack/query-core'
+
+/**
+ * Query options with `initialData` that guarantees defined query data.
+ */
+export type DefinedInitialDataOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = Omit<
+  QueryObserverOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>,
+  'queryFn'
+> & {
+  initialData:
+    | NonUndefinedGuard<TQueryFnData>
+    | (() => NonUndefinedGuard<TQueryFnData>)
+  queryFn?: QueryFunction<TQueryFnData, TQueryKey>
+}
+
+/**
+ * Query options where `queryFn` is present and not a `skipToken`.
+ */
+export type UnusedSkipTokenOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = OmitKeyof<
+  QueryObserverOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>,
+  'queryFn'
+> & {
+  queryFn?: Exclude<
+    QueryObserverOptions<
+      TQueryFnData,
+      TError,
+      TData,
+      TQueryFnData,
+      TQueryKey
+    >['queryFn'],
+    SkipToken | undefined
+  >
+}
+
+/**
+ * Query options where `initialData` can be omitted or undefined.
+ */
+export type UndefinedInitialDataOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = QueryObserverOptions<
+  TQueryFnData,
+  TError,
+  TData,
+  TQueryFnData,
+  TQueryKey
+> & {
+  initialData?:
+    | undefined
+    | InitialDataFunction<NonUndefinedGuard<TQueryFnData>>
+    | NonUndefinedGuard<TQueryFnData>
+}
+
+/**
+ * Brands query options so the `queryKey` carries the query function data and
+ * error types across TanStack Query APIs.
+ *
+ * @param options - Query options to preserve and brand.
+ * @returns The same options object with a typed `queryKey`.
+ *
+ * @example
+ * ```ts
+ * import { queryOptions } from '@tanstack/lit-query'
+ *
+ * const todosOptions = queryOptions({
+ *   queryKey: ['todos'],
+ *   queryFn: fetchTodos,
+ *   initialData: [],
+ * })
+ * ```
+ */
+export function queryOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & {
+  queryKey: DataTag<TQueryKey, TQueryFnData, TError>
+}
+
+/**
+ * Brands query options so the `queryKey` carries the query function data and
+ * error types across TanStack Query APIs.
+ *
+ * @param options - Query options to preserve and brand.
+ * @returns The same options object with a typed `queryKey`.
+ */
+export function queryOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  options: UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey>,
+): UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey> & {
+  queryKey: DataTag<TQueryKey, TQueryFnData, TError>
+}
+
+/**
+ * Brands query options so the `queryKey` carries the query function data and
+ * error types across TanStack Query APIs.
+ *
+ * @param options - Query options to preserve and brand.
+ * @returns The same options object with a typed `queryKey`.
+ */
+export function queryOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+): UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & {
+  queryKey: DataTag<TQueryKey, TQueryFnData, TError>
+}
+
+export function queryOptions(options: unknown) {
+  return options
+}

package/src/types.ts

@@ -0,0 +1,77 @@
+import type {
+  DefaultError,
+  InfiniteData,
+  MutationObserverResult,
+  QueryKey,
+  QueryObserverResult,
+} from '@tanstack/query-core'
+import type { Accessor } from './accessor.js'
+import type { CreateInfiniteQueryOptions } from './createInfiniteQueryController.js'
+import type { CreateMutationOptions } from './createMutationController.js'
+import type {
+  CreateQueriesControllerOptions,
+  CreateQueriesResults,
+} from './createQueriesController.js'
+import type { CreateQueryOptions } from './createQueryController.js'
+
+/**
+ * Accessor-wrapped options accepted by `createQueryController`.
+ */
+export type QueryControllerOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = Accessor<
+  CreateQueryOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+>
+
+/**
+ * Result object produced by a Lit query controller.
+ */
+export type QueryControllerResult<
+  TData = unknown,
+  TError = DefaultError,
+> = QueryObserverResult<TData, TError>
+
+/**
+ * Accessor-wrapped options accepted by `createInfiniteQueryController`.
+ */
+export type InfiniteQueryControllerOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = InfiniteData<TQueryFnData>,
+  TQueryKey extends QueryKey = QueryKey,
+  TPageParam = unknown,
+> = Accessor<
+  CreateInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
+>
+
+/**
+ * Accessor-wrapped options accepted by `createMutationController`.
+ */
+export type MutationControllerOptions<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TOnMutateResult = unknown,
+> = Accessor<CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>>
+
+/**
+ * Result object produced by a Lit mutation controller.
+ */
+export type MutationControllerResult<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TOnMutateResult = unknown,
+> = MutationObserverResult<TData, TError, TVariables, TOnMutateResult>
+
+/**
+ * Accessor-wrapped options accepted by `createQueriesController`.
+ */
+export type QueriesControllerOptions<
+  TQueryOptions extends Array<any> = Array<any>,
+  TCombinedResult = CreateQueriesResults<TQueryOptions>,
+> = Accessor<CreateQueriesControllerOptions<TQueryOptions, TCombinedResult>>