@tanstack/angular-query-experimental 5.103.2 → 5.104.0

package/src/inject-query.ts

@@ -0,0 +1,208 @@
+import { QueryObserver } from '@tanstack/query-core'
+import {
+  Injector,
+  assertInInjectionContext,
+  inject,
+  runInInjectionContext,
+} from '@angular/core'
+import { createBaseQuery } from './create-base-query'
+import type { DefaultError, QueryKey } from '@tanstack/query-core'
+import type {
+  CreateQueryOptions,
+  CreateQueryResult,
+  DefinedCreateQueryResult,
+} from './types'
+import type {
+  DefinedInitialDataOptions,
+  UndefinedInitialDataOptions,
+} from './query-options'
+
+export interface InjectQueryOptions {
+  /**
+   * The `Injector` in which to create the query.
+   *
+   * If this is not provided, the current injection context will be used instead (via `inject`).
+   */
+  injector?: Injector
+}
+
+/**
+ * This overload is selected when `initialData` is set on the options returned by `injectQueryFn`, so the
+ * resulting `data` signal is never `undefined` (unless a `select` changes `TData` to include `undefined`).
+ *
+ * @see https://tanstack.com/query/latest/docs/framework/angular/guides/queries
+ * @see {@link queryOptions} to share these options between `injectQuery` and imperative APIs like
+ * `queryClient.fetchQuery`.
+ * @param injectQueryFn - A function returning the {@link DefinedInitialDataOptions} to use — everything you
+ * can pass to `injectQuery`, with `initialData` set. Similar to `computed` from Angular, this function runs
+ * in the reactive context, so signals read inside it (in `queryKey`, `enabled`, etc.) drive the query.
+ * @param options - Additional configuration
+ * @returns The query result, typed so that `data` is never `undefined` (unless a `select` changes `TData` to
+ * include `undefined`).
+ *
+ * @example
+ * ```angular-ts
+ * @Component({
+ *   selector: 'posts',
+ *   template: `
+ *     <!-- `postsQuery.data()` is `Post[]`, never `undefined`, thanks to `initialData` — even if a
+ *     refetch fails, so the list stays visible alongside the error. -->
+ *     @if (postsQuery.isError()) {
+ *       <span>Error: {{ postsQuery.error()?.message }}</span>
+ *     }
+ *     <ul>
+ *       @for (post of postsQuery.data(); track post.id) {
+ *         <li>{{ post.title }}</li>
+ *       }
+ *     </ul>
+ *   `,
+ * })
+ * export class Posts {
+ *   readonly postsQuery = injectQuery(() => ({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *     initialData: [],
+ *   }))
+ * }
+ * ```
+ */
+export function injectQuery<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  injectQueryFn: () => DefinedInitialDataOptions<
+    TQueryFnData,
+    TError,
+    TData,
+    TQueryKey
+  >,
+  options?: InjectQueryOptions,
+): DefinedCreateQueryResult<TData, TError>
+
+/**
+ * Injects a query: a declarative dependency on an asynchronous source of data that is tied to a unique key.
+ *
+ * @see https://tanstack.com/query/latest/docs/framework/angular/guides/queries
+ * @see {@link queryOptions} to share these options between `injectQuery` and imperative APIs like
+ * `queryClient.fetchQuery`.
+ * @param injectQueryFn - A function returning the {@link UndefinedInitialDataOptions} to use — everything
+ * you can pass to `injectQuery`. Similar to `computed` from Angular, this function runs in the reactive
+ * context, so signals read inside it (in `queryKey`, `enabled`, etc.) drive the query.
+ * @param options - Additional configuration
+ * @returns The query result. `status()` is `'pending'` if there is no cached data to display, `'error'` if
+ * the last fetch attempt failed, or `'success'` if the query has data to display. `isPending`/`isSuccess`/
+ * `isError` are type-guard methods for convenience.
+ *
+ * @example
+ * ```angular-ts
+ * @Component({
+ *   selector: 'posts',
+ *   template: `
+ *     @if (postsQuery.isPending()) {
+ *       Loading...
+ *     } @else if (postsQuery.isError()) {
+ *       <span>Error: {{ postsQuery.error()?.message }}</span>
+ *     } @else {
+ *       <ul>
+ *         @for (post of postsQuery.data(); track post.id) {
+ *           <li>{{ post.title }}</li>
+ *         }
+ *       </ul>
+ *     }
+ *   `,
+ * })
+ * export class Posts {
+ *   readonly postsQuery = injectQuery(() => ({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *   }))
+ * }
+ * ```
+ *
+ * @example
+ * Similar to `computed` from Angular, the function passed to `injectQuery` runs in the reactive context. In
+ * the example below, the query is automatically enabled and executed when the filter signal changes to a
+ * truthy value. When the filter signal changes back to a falsy value, the query is disabled.
+ * ```angular-ts
+ * @Component({
+ *   selector: 'posts',
+ *   template: `
+ *     <input [ngModel]="filter()" (ngModelChange)="filter.set($event)" />
+ *     @if (postsQuery.isPending()) {
+ *       Loading...
+ *     } @else if (postsQuery.isError()) {
+ *       <span>Error: {{ postsQuery.error()?.message }}</span>
+ *     } @else {
+ *       <ul>
+ *         @for (post of postsQuery.data(); track post.id) {
+ *           <li>{{ post.title }}</li>
+ *         }
+ *       </ul>
+ *     }
+ *   `,
+ * })
+ * export class Posts {
+ *   readonly filter = signal('')
+ *
+ *   readonly postsQuery = injectQuery(() => ({
+ *     queryKey: ['posts', this.filter()],
+ *     queryFn: () => fetchPosts(this.filter()),
+ *     // Signals can be combined with expressions
+ *     enabled: !!this.filter(),
+ *   }))
+ * }
+ * ```
+ */
+export function injectQuery<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  injectQueryFn: () => UndefinedInitialDataOptions<
+    TQueryFnData,
+    TError,
+    TData,
+    TQueryKey
+  >,
+  options?: InjectQueryOptions,
+): CreateQueryResult<TData, TError>
+
+/**
+ * This overload accepts the general {@link CreateQueryOptions} shape rather than the `initialData`-aware
+ * overloads above, so whether `data` is defined can't be inferred from the call site — useful when wrapping
+ * `injectQuery` in your own helper function that forwards caller-provided options.
+ *
+ * @see https://tanstack.com/query/latest/docs/framework/angular/guides/queries
+ * @param injectQueryFn - A function that returns query options. Similar to `computed` from Angular, this
+ * function runs in the reactive context, so signals read inside it (in `queryKey`, `enabled`, etc.) drive
+ * the query.
+ * @param options - Additional configuration
+ * @returns The query result.
+ */
+export function injectQuery<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  injectQueryFn: () => CreateQueryOptions<
+    TQueryFnData,
+    TError,
+    TData,
+    TQueryKey
+  >,
+  options?: InjectQueryOptions,
+): CreateQueryResult<TData, TError>
+
+export function injectQuery(
+  injectQueryFn: () => CreateQueryOptions,
+  options?: InjectQueryOptions,
+) {
+  !options?.injector && assertInInjectionContext(injectQuery)
+  return runInInjectionContext(options?.injector ?? inject(Injector), () =>
+    createBaseQuery(injectQueryFn, QueryObserver),
+  ) as unknown as CreateQueryResult
+}

package/src/mutation-options.ts

@@ -0,0 +1,121 @@
+import type { DefaultError, WithRequired } from '@tanstack/query-core'
+import type { CreateMutationOptions } from './types'
+
+/**
+ * You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. A
+ * `mutationKey` is required on this overload so the mutation can be looked up later, e.g. with
+ * `injectMutationState`.
+ *
+ * @see {@link injectMutation} to run the mutation these options describe.
+ * @param options - The mutation options to use, identical to what you'd pass to `injectMutation`, with a
+ * required `mutationKey`.
+ * @returns The same options object, unchanged.
+ *
+ * @example
+ * Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "saving…" indicator:
+ * ```angular-ts
+ * import { mutationOptions, injectMutationState } from '@tanstack/angular-query-experimental'
+ *
+ * const createPostOptions = mutationOptions({
+ *   mutationKey: ['posts', 'create'],
+ *   mutationFn: createPost,
+ * })
+ *
+ * @Component({
+ *   selector: 'saving-indicator',
+ *   template: `
+ *     @if (isCreatingPost()) {
+ *       <span>Saving…</span>
+ *     }
+ *   `,
+ * })
+ * export class SavingIndicator {
+ *   readonly #pendingCreates = injectMutationState(() => ({
+ *     filters: { mutationKey: createPostOptions.mutationKey, status: 'pending' },
+ *   }))
+ *   readonly isCreatingPost = computed(() => this.#pendingCreates().length > 0)
+ * }
+ * ```
+ */
+export function mutationOptions<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TOnMutateResult = unknown,
+>(
+  options: WithRequired<
+    CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>,
+    'mutationKey'
+  >,
+): WithRequired<
+  CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>,
+  'mutationKey'
+>
+/**
+ * You can generally pass everything to `mutationOptions` that you can also pass to `injectMutation`. No
+ * `mutationKey` is required on this overload — use this when you don't need to target the mutation via a
+ * `mutationKey` filter later (e.g. with `injectMutationState`); it can still be observed through other
+ * filters, such as `status`.
+ *
+ * @see {@link injectMutation} to run the mutation these options describe.
+ * @param options - The mutation options to use, identical to what you'd pass to `injectMutation`, without a
+ * `mutationKey`.
+ * @returns The same options object, unchanged.
+ * @remarks See the other overload's example for looking a mutation up via `injectMutationState`.
+ *
+ * @example
+ * Sharing options across services, so `QueriesService` stays the single place a mutation is defined:
+ * ```angular-ts
+ * import { mutationOptions, injectMutation } from '@tanstack/angular-query-experimental'
+ *
+ * @Injectable({ providedIn: 'root' })
+ * export class QueriesService {
+ *   readonly #queryClient = inject(QueryClient)
+ *
+ *   updatePost(id: number) {
+ *     return mutationOptions({
+ *       mutationFn: (post: Partial<Post>) => putPost(id, post),
+ *       onSuccess: (newPost) => this.#queryClient.setQueryData(['posts', id], newPost),
+ *     })
+ *   }
+ * }
+ *
+ * @Component({
+ *   selector: 'post',
+ *   template: `<button (click)="save()">Save</button>`,
+ * })
+ * export class Post {
+ *   readonly queries = inject(QueriesService)
+ *   readonly id = signal(0)
+ *   readonly updatePostMutation = injectMutation(() => this.queries.updatePost(this.id()))
+ *
+ *   save() {
+ *     this.updatePostMutation.mutate({ title: 'New Title' })
+ *   }
+ * }
+ * ```
+ */
+export function mutationOptions<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TOnMutateResult = unknown,
+>(
+  options: Omit<
+    CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>,
+    'mutationKey'
+  >,
+): Omit<
+  CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>,
+  'mutationKey'
+>
+export function mutationOptions<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TOnMutateResult = unknown,
+>(
+  options: CreateMutationOptions<TData, TError, TVariables, TOnMutateResult>,
+): CreateMutationOptions<TData, TError, TVariables, TOnMutateResult> {
+  return options
+}

package/src/pending-tasks-compat.ts

@@ -0,0 +1,27 @@
+import { InjectionToken, inject } from '@angular/core'
+import * as ng from '@angular/core'
+import { noop } from '@tanstack/query-core'
+
+type PendingTasksCompat = { add: () => PendingTaskRef }
+
+export type PendingTaskRef = () => void
+
+export const PENDING_TASKS = new InjectionToken<PendingTasksCompat>(
+  'PENDING_TASKS',
+  {
+    factory: (): PendingTasksCompat => {
+      // Access via Reflect so bundlers stay quiet when the token is absent (Angular < 19).
+      const token = Reflect.get(ng, 'PendingTasks') as unknown as
+        Parameters<typeof inject>[0] | undefined
+
+      const svc: PendingTasksCompat | null = token
+        ? (inject(token, { optional: true }) as PendingTasksCompat | null)
+        : null
+
+      // Without PendingTasks we fall back to a stable no-op shim.
+      return {
+        add: svc ? () => svc.add() : () => noop,
+      }
+    },
+  },
+)

package/src/providers.ts

@@ -0,0 +1,170 @@
+import { DestroyRef, InjectionToken, inject } from '@angular/core'
+import { QueryClient } from '@tanstack/query-core'
+import type { Provider } from '@angular/core'
+
+/**
+ * Usually {@link provideTanStackQuery} is used once to set up TanStack Query and the
+ * [`QueryClient`](https://tanstack.com/query/latest/docs/reference/QueryClient) for the entire application —
+ * it calls `provideQueryClient` internally. Use `provideQueryClient` directly to provide a different
+ * `QueryClient` instance for part of the application, or for unit testing.
+ * @param queryClient - A `QueryClient` instance, or an `InjectionToken` which provides a `QueryClient`.
+ * @returns A provider object that can be used to provide the `QueryClient` instance.
+ *
+ * @example
+ * Providing a test-only `QueryClient` in a component test, without wiring up `provideTanStackQuery`'s other
+ * defaults:
+ * ```ts
+ * TestBed.configureTestingModule({
+ *   providers: [provideQueryClient(new QueryClient())],
+ * })
+ * ```
+ */
+export function provideQueryClient(
+  queryClient: QueryClient | InjectionToken<QueryClient>,
+): Provider {
+  return {
+    provide: QueryClient,
+    useFactory: () => {
+      const client =
+        queryClient instanceof InjectionToken
+          ? inject(queryClient)
+          : queryClient
+      // Unmount the query client on injector destroy
+      inject(DestroyRef).onDestroy(() => client.unmount())
+      client.mount()
+      return client
+    },
+  }
+}
+
+/**
+ * Sets up providers necessary to enable TanStack Query functionality for Angular applications. Allows
+ * configuring a `QueryClient` and optional features such as developer tools.
+ *
+ * @see https://tanstack.com/query/v5/docs/framework/angular/quick-start
+ * @see {@link withDevtools}
+ * @param queryClient - A `QueryClient` instance, or an `InjectionToken` which provides a `QueryClient`.
+ * @param features - Optional features to configure additional Query functionality.
+ * @returns A set of providers to set up TanStack Query.
+ *
+ * @example
+ * ```ts
+ * import { provideTanStackQuery, QueryClient } from '@tanstack/angular-query-experimental'
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideTanStackQuery(new QueryClient())],
+ * })
+ * ```
+ *
+ * @example
+ * The same, in an `NgModule`-based application:
+ * ```ts
+ * import { provideTanStackQuery, QueryClient } from '@tanstack/angular-query-experimental'
+ *
+ * @NgModule({
+ *   declarations: [AppComponent],
+ *   imports: [BrowserModule],
+ *   providers: [provideTanStackQuery(new QueryClient())],
+ *   bootstrap: [AppComponent],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * @example
+ * Enabling optional developer tools by adding `withDevtools` — by default, the tools are then loaded when
+ * your app is in development mode:
+ * ```ts
+ * import {
+ *   provideTanStackQuery,
+ *   withDevtools,
+ *   QueryClient,
+ * } from '@tanstack/angular-query-experimental'
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideTanStackQuery(new QueryClient(), withDevtools())],
+ * })
+ * ```
+ *
+ * @example
+ * Using an `InjectionToken` for the `QueryClient` — an advanced optimization that lets TanStack Query be
+ * absent from the main application bundle, useful for including it on lazy-loaded routes only while still
+ * sharing a `QueryClient`. This is a small optimization; for most applications it's preferable to provide
+ * the `QueryClient` in the main application config, as in the examples above:
+ * ```ts
+ * export const MY_QUERY_CLIENT = new InjectionToken('', {
+ *   factory: () => new QueryClient(),
+ * })
+ *
+ * // In a lazy loaded route or lazy loaded component's providers array:
+ * providers: [provideTanStackQuery(MY_QUERY_CLIENT)]
+ * ```
+ */
+export function provideTanStackQuery(
+  queryClient: QueryClient | InjectionToken<QueryClient>,
+  ...features: Array<QueryFeatures>
+): Array<Provider> {
+  return [
+    provideQueryClient(queryClient),
+    features.map((feature) => feature.ɵproviders),
+  ]
+}
+
+/**
+ * Sets up providers necessary to enable TanStack Query functionality for Angular applications.
+ *
+ * Allows configuring a `QueryClient`.
+ * @see https://tanstack.com/query/v5/docs/framework/angular/quick-start
+ * @param queryClient - A `QueryClient` instance.
+ * @returns A set of providers to set up TanStack Query.
+ * @deprecated Use `provideTanStackQuery` instead.
+ */
+export function provideAngularQuery(queryClient: QueryClient): Array<Provider> {
+  return provideTanStackQuery(queryClient)
+}
+
+const queryFeatures = ['Devtools', 'PersistQueryClient'] as const
+
+type QueryFeatureKind = (typeof queryFeatures)[number]
+
+/**
+ * Helper type to represent a Query feature.
+ */
+export interface QueryFeature<TFeatureKind extends QueryFeatureKind> {
+  ɵkind: TFeatureKind
+  ɵproviders: Array<Provider>
+}
+
+/**
+ * Helper function to create an object that represents a Query feature.
+ * @param kind - The kind of feature, e.g. `'Devtools'`.
+ * @param providers - The Angular providers this feature contributes to `provideTanStackQuery`.
+ * @returns A Query feature.
+ */
+export function queryFeature<TFeatureKind extends QueryFeatureKind>(
+  kind: TFeatureKind,
+  providers: Array<Provider>,
+): QueryFeature<TFeatureKind> {
+  return { ɵkind: kind, ɵproviders: providers }
+}
+
+/**
+ * A type alias that represents a feature which enables developer tools.
+ * The type is used to describe the return value of the `withDevtools` function.
+ * @see {@link withDevtools}
+ */
+export type DevtoolsFeature = QueryFeature<'Devtools'>
+
+/**
+ * A type alias that represents a feature which enables persistence.
+ * The type is used to describe the return value of the `withPersistQueryClient` function.
+ */
+export type PersistQueryClientFeature = QueryFeature<'PersistQueryClient'>
+
+/**
+ * A type alias that represents all Query features available for use with `provideTanStackQuery`.
+ * Features can be enabled by adding special functions to the `provideTanStackQuery` call.
+ * See documentation for each symbol to find corresponding function name. See also `provideTanStackQuery`
+ * documentation on how to use those functions.
+ * @see {@link provideTanStackQuery}
+ */
+export type QueryFeatures = DevtoolsFeature | PersistQueryClientFeature