@tanstack/angular-query-experimental 5.34.1 → 5.34.2

package/src/inject-query-client.ts

@@ -1,7 +1,25 @@
 import { createNoopInjectionToken } from './util/create-injection-token/create-injection-token'
 import type { QueryClient } from '@tanstack/query-core'
 
-const [injectQueryClient, provideQueryClient, QUERY_CLIENT] =
-  createNoopInjectionToken<QueryClient>('QueryClientToken')
+const tokens = createNoopInjectionToken<QueryClient>('QueryClientToken')
 
-export { injectQueryClient, provideQueryClient, QUERY_CLIENT }
+/**
+ * Injects the `QueryClient` instance into the component or service.
+ *
+ * **Example**
+ * ```ts
+ * const queryClient = injectQueryClient();
+ * ```
+ * @returns The `QueryClient` instance.
+ * @public
+ */
+export const injectQueryClient = tokens[0]
+
+/**
+ * Usually {@link provideAngularQuery} is used once to set up TanStack Query and the
+ * {@link https://tanstack.com/query/latest/docs/reference/QueryClient|QueryClient}
+ * for the entire application. You can use `provideQueryClient` to provide a
+ * different `QueryClient` instance for a part of the application.
+ * @public
+ */
+export const provideQueryClient = tokens[1]

package/src/inject-query.ts

@@ -15,44 +15,176 @@ import type {
   UndefinedInitialDataOptions,
 } from './query-options'
 
+/**
+ * Injects a query: a declarative dependency on an asynchronous source of data that is tied to a unique key.
+ *
+ * **Basic example**
+ * ```ts
+ * class ServiceOrComponent {
+ *   query = injectQuery(() => ({
+ *     queryKey: ['repoData'],
+ *     queryFn: () =>
+ *       this.#http.get<Response>('https://api.github.com/repos/tanstack/query'),
+ *   }))
+ * }
+ * ```
+ *
+ * **The options function can utilize signals**
+ * ```ts
+ * class ServiceOrComponent {
+ *   filter = signal('')
+ *
+ *   todosQuery = injectQuery(() => ({
+ *     queryKey: ['todos', this.filter()],
+ *     queryFn: () => fetchTodos(this.filter()),
+ *     // Signals can be combined with expressions
+ *     enabled: !!this.filter(),
+ *   }))
+ * }
+ * ```
+ * @param optionsFn - A function that returns query options.
+ * @param injector - The Angular injector to use.
+ * @returns The query result.
+ * @public
+ * @see https://tanstack.com/query/latest/docs/framework/angular/guides/queries
+ */
 export function injectQuery<
   TQueryFnData = unknown,
   TError = DefaultError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 >(
-  options: (
+  optionsFn: (
     client: QueryClient,
-  ) => UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+  ) => DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
   injector?: Injector,
-): CreateQueryResult<TData, TError>
+): DefinedCreateQueryResult<TData, TError>
 
+/**
+ * Injects a query: a declarative dependency on an asynchronous source of data that is tied to a unique key.
+ *
+ * **Basic example**
+ * ```ts
+ * class ServiceOrComponent {
+ *   query = injectQuery(() => ({
+ *     queryKey: ['repoData'],
+ *     queryFn: () =>
+ *       this.#http.get<Response>('https://api.github.com/repos/tanstack/query'),
+ *   }))
+ * }
+ * ```
+ *
+ * **The options function can utilize signals**
+ * ```ts
+ * class ServiceOrComponent {
+ *   filter = signal('')
+ *
+ *   todosQuery = injectQuery(() => ({
+ *     queryKey: ['todos', this.filter()],
+ *     queryFn: () => fetchTodos(this.filter()),
+ *     // Signals can be combined with expressions
+ *     enabled: !!this.filter(),
+ *   }))
+ * }
+ * ```
+ * @param optionsFn - A function that returns query options.
+ * @param injector - The Angular injector to use.
+ * @returns The query result.
+ * @public
+ * @see https://tanstack.com/query/latest/docs/framework/angular/guides/queries
+ */
 export function injectQuery<
   TQueryFnData = unknown,
   TError = DefaultError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 >(
-  options: (
+  optionsFn: (
     client: QueryClient,
-  ) => DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+  ) => UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
   injector?: Injector,
-): DefinedCreateQueryResult<TData, TError>
+): CreateQueryResult<TData, TError>
 
+/**
+ * Injects a query: a declarative dependency on an asynchronous source of data that is tied to a unique key.
+ *
+ * **Basic example**
+ * ```ts
+ * class ServiceOrComponent {
+ *   query = injectQuery(() => ({
+ *     queryKey: ['repoData'],
+ *     queryFn: () =>
+ *       this.#http.get<Response>('https://api.github.com/repos/tanstack/query'),
+ *   }))
+ * }
+ * ```
+ *
+ * **The options function can utilize signals**
+ * ```ts
+ * class ServiceOrComponent {
+ *   filter = signal('')
+ *
+ *   todosQuery = injectQuery(() => ({
+ *     queryKey: ['todos', this.filter()],
+ *     queryFn: () => fetchTodos(this.filter()),
+ *     // Signals can be combined with expressions
+ *     enabled: !!this.filter(),
+ *   }))
+ * }
+ * ```
+ * @param optionsFn - A function that returns query options.
+ * @param injector - The Angular injector to use.
+ * @returns The query result.
+ * @public
+ * @see https://tanstack.com/query/latest/docs/framework/angular/guides/queries
+ */
 export function injectQuery<
   TQueryFnData = unknown,
   TError = DefaultError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 >(
-  options: (
+  optionsFn: (
     client: QueryClient,
   ) => CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
   injector?: Injector,
 ): CreateQueryResult<TData, TError>
 
+/**
+ * Injects a query: a declarative dependency on an asynchronous source of data that is tied to a unique key.
+ *
+ * **Basic example**
+ * ```ts
+ * class ServiceOrComponent {
+ *   query = injectQuery(() => ({
+ *     queryKey: ['repoData'],
+ *     queryFn: () =>
+ *       this.#http.get<Response>('https://api.github.com/repos/tanstack/query'),
+ *   }))
+ * }
+ * ```
+ *
+ * **The options function can utilize signals**
+ * ```ts
+ * class ServiceOrComponent {
+ *   filter = signal('')
+ *
+ *   todosQuery = injectQuery(() => ({
+ *     queryKey: ['todos', this.filter()],
+ *     queryFn: () => fetchTodos(this.filter()),
+ *     // Signals can be combined with expressions
+ *     enabled: !!this.filter(),
+ *   }))
+ * }
+ * ```
+ * @param optionsFn - A function that returns query options.
+ * @param injector - The Angular injector to use.
+ * @returns The query result.
+ * @public
+ * @see https://tanstack.com/query/latest/docs/framework/angular/guides/queries
+ */
 export function injectQuery(
-  options: (client: QueryClient) => CreateQueryOptions,
+  optionsFn: (client: QueryClient) => CreateQueryOptions,
   injector?: Injector,
 ) {
   const assertedInjector = assertInjector(injectQuery, injector)
@@ -60,7 +192,7 @@ export function injectQuery(
     const queryClient = injectQueryClient()
     return createBaseQuery(
       (client) =>
-        runInInjectionContext(assertedInjector, () => options(client)),
+        runInInjectionContext(assertedInjector, () => optionsFn(client)),
       QueryObserver,
       queryClient,
     )

package/src/providers.ts

@@ -8,6 +8,45 @@ import { provideQueryClient } from './inject-query-client'
 import type { EnvironmentProviders } from '@angular/core'
 import type { QueryClient } from '@tanstack/query-core'
 
+/**
+ * Sets up providers necessary to enable TanStack Query functionality for Angular applications.
+ *
+ * Allows to configure a `QueryClient`.
+ *
+ * **Example - standalone**
+ *
+ * ```ts
+ * import {
+ *   provideAngularQuery,
+ *   QueryClient,
+ * } from '@tanstack/angular-query-experimental'
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideAngularQuery(new QueryClient())],
+ * })
+ * ```
+ *
+ * **Example - NgModule-based**
+ *
+ * ```ts
+ * import {
+ *   provideAngularQuery,
+ *   QueryClient,
+ * } from '@tanstack/angular-query-experimental'
+ *
+ * @NgModule({
+ *   declarations: [AppComponent],
+ *   imports: [BrowserModule],
+ *   providers: [provideAngularQuery(new QueryClient())],
+ *   bootstrap: [AppComponent],
+ * })
+ * export class AppModule {}
+ * ```
+ * @param queryClient - A `QueryClient` instance.
+ * @returns A set of providers to set up TanStack Query.
+ * @public
+ * @see https://tanstack.com/query/v5/docs/framework/angular/quick-start
+ */
 export function provideAngularQuery(
   queryClient: QueryClient,
 ): EnvironmentProviders {

package/src/query-options.ts

@@ -1,6 +1,9 @@
 import type { DataTag, DefaultError, QueryKey } from '@tanstack/query-core'
 import type { CreateQueryOptions } from './types'
 
+/**
+ * @public
+ */
 export type UndefinedInitialDataOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -12,6 +15,9 @@ export type UndefinedInitialDataOptions<
 
 type NonUndefinedGuard<T> = T extends undefined ? never : T
 
+/**
+ * @public
+ */
 export type DefinedInitialDataOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -23,6 +29,28 @@ export type DefinedInitialDataOptions<
     | (() => NonUndefinedGuard<TQueryFnData>)
 }
 
+/**
+ * Allows to share and re-use query options in a type-safe way.
+ *
+ * The `queryKey` will be tagged with the type from `queryFn`.
+ *
+ * **Example**
+ *
+ * ```ts
+ *  const { queryKey } = queryOptions({
+ *     queryKey: ['key'],
+ *     queryFn: () => Promise.resolve(5),
+ *     //  ^?  Promise<number>
+ *   })
+ *
+ *   const queryClient = new QueryClient()
+ *   const data = queryClient.getQueryData(queryKey)
+ *   //    ^?  number | undefined
+ * ```
+ * @param options - The query options to tag with the type from `queryFn`.
+ * @returns The tagged query options.
+ * @public
+ */
 export function queryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -34,6 +62,28 @@ export function queryOptions<
   queryKey: DataTag<TQueryKey, TQueryFnData>
 }
 
+/**
+ * Allows to share and re-use query options in a type-safe way.
+ *
+ * The `queryKey` will be tagged with the type from `queryFn`.
+ *
+ * **Example**
+ *
+ * ```ts
+ *  const { queryKey } = queryOptions({
+ *     queryKey: ['key'],
+ *     queryFn: () => Promise.resolve(5),
+ *     //  ^?  Promise<number>
+ *   })
+ *
+ *   const queryClient = new QueryClient()
+ *   const data = queryClient.getQueryData(queryKey)
+ *   //    ^?  number | undefined
+ * ```
+ * @param options - The query options to tag with the type from `queryFn`.
+ * @returns The tagged query options.
+ * @public
+ */
 export function queryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -45,6 +95,28 @@ export function queryOptions<
   queryKey: DataTag<TQueryKey, TQueryFnData>
 }
 
+/**
+ * Allows to share and re-use query options in a type-safe way.
+ *
+ * The `queryKey` will be tagged with the type from `queryFn`.
+ *
+ * **Example**
+ *
+ * ```ts
+ *  const { queryKey } = queryOptions({
+ *     queryKey: ['key'],
+ *     queryFn: () => Promise.resolve(5),
+ *     //  ^?  Promise<number>
+ *   })
+ *
+ *   const queryClient = new QueryClient()
+ *   const data = queryClient.getQueryData(queryKey)
+ *   //    ^?  number | undefined
+ * ```
+ * @param options - The query options to tag with the type from `queryFn`.
+ * @returns The tagged query options.
+ * @public
+ */
 export function queryOptions(options: unknown) {
   return options
 }

package/src/signal-proxy.ts

@@ -7,11 +7,9 @@ export type MapToSignals<T> = {
 
 /**
  * Exposes fields of an object passed via an Angular `Signal` as `Computed` signals.
- *
  * Functions on the object are passed through as-is.
- *
  * @param inputSignal - `Signal` that must return an object.
- *
+ * @returns A proxy object with the same fields as the input object, but with each field wrapped in a `Computed` signal.
  */
 export function signalProxy<TInput extends Record<string | symbol, any>>(
   inputSignal: Signal<TInput>,

package/src/types.ts

@@ -16,6 +16,9 @@ import type {
 } from '@tanstack/query-core'
 import type { MapToSignals } from './signal-proxy'
 
+/**
+ * @public
+ */
 export interface CreateBaseQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -30,6 +33,9 @@ export interface CreateBaseQueryOptions<
     TQueryKey
   > {}
 
+/**
+ * @public
+ */
 export interface CreateQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -46,12 +52,18 @@ export interface CreateQueryOptions<
     'suspense'
   > {}
 
+/**
+ * @public
+ */
 type CreateStatusBasedQueryResult<
   TStatus extends QueryObserverResult['status'],
   TData = unknown,
   TError = DefaultError,
 > = Extract<QueryObserverResult<TData, TError>, { status: TStatus }>
 
+/**
+ * @public
+ */
 export interface BaseQueryNarrowing<TData = unknown, TError = DefaultError> {
   isSuccess: (
     this: CreateBaseQueryResult<TData, TError>,
@@ -76,6 +88,9 @@ export interface BaseQueryNarrowing<TData = unknown, TError = DefaultError> {
   >
 }
 
+/**
+ * @public
+ */
 export interface CreateInfiniteQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -95,6 +110,9 @@ export interface CreateInfiniteQueryOptions<
     'suspense'
   > {}
 
+/**
+ * @public
+ */
 export type CreateBaseQueryResult<
   TData = unknown,
   TError = DefaultError,
@@ -102,22 +120,34 @@ export type CreateBaseQueryResult<
 > = BaseQueryNarrowing<TData, TError> &
   MapToSignals<OmitKeyof<TState, keyof BaseQueryNarrowing, 'safely'>>
 
+/**
+ * @public
+ */
 export type CreateQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = CreateBaseQueryResult<TData, TError>
 
+/**
+ * @public
+ */
 export type DefinedCreateQueryResult<
   TData = unknown,
   TError = DefaultError,
   TDefinedQueryObserver = DefinedQueryObserverResult<TData, TError>,
 > = MapToSignals<TDefinedQueryObserver>
 
+/**
+ * @public
+ */
 export type CreateInfiniteQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = MapToSignals<InfiniteQueryObserverResult<TData, TError>>
 
+/**
+ * @public
+ */
 export type DefinedCreateInfiniteQueryResult<
   TData = unknown,
   TError = DefaultError,
@@ -127,6 +157,9 @@ export type DefinedCreateInfiniteQueryResult<
   >,
 > = MapToSignals<TDefinedInfiniteQueryObserver>
 
+/**
+ * @public
+ */
 export interface CreateMutationOptions<
   TData = unknown,
   TError = DefaultError,
@@ -137,6 +170,9 @@ export interface CreateMutationOptions<
     '_defaulted'
   > {}
 
+/**
+ * @public
+ */
 export type CreateMutateFunction<
   TData = unknown,
   TError = DefaultError,
@@ -146,6 +182,9 @@ export type CreateMutateFunction<
   ...args: Parameters<MutateFunction<TData, TError, TVariables, TContext>>
 ) => void
 
+/**
+ * @public
+ */
 export type CreateMutateAsyncFunction<
   TData = unknown,
   TError = DefaultError,
@@ -153,6 +192,9 @@ export type CreateMutateAsyncFunction<
   TContext = unknown,
 > = MutateFunction<TData, TError, TVariables, TContext>
 
+/**
+ * @public
+ */
 export type CreateBaseMutationResult<
   TData = unknown,
   TError = DefaultError,
@@ -165,6 +207,9 @@ export type CreateBaseMutationResult<
   mutateAsync: CreateMutateAsyncFunction<TData, TError, TVariables, TContext>
 }
 
+/**
+ * @public
+ */
 type CreateStatusBasedMutationResult<
   TStatus extends CreateBaseMutationResult['status'],
   TData = unknown,
@@ -176,6 +221,9 @@ type CreateStatusBasedMutationResult<
   { status: TStatus }
 >
 
+/**
+ * @public
+ */
 export interface BaseMutationNarrowing<
   TData = unknown,
   TError = DefaultError,
@@ -238,6 +286,9 @@ export interface BaseMutationNarrowing<
   >
 }
 
+/**
+ * @public
+ */
 export type CreateMutationResult<
   TData = unknown,
   TError = DefaultError,