@tanstack/angular-query-experimental 5.60.0 → 5.60.2

package/src/inject-is-fetching.ts

@@ -0,0 +1,50 @@
+import { DestroyRef, NgZone, inject, signal } from '@angular/core'
+import { notifyManager } from '@tanstack/query-core'
+import { assertInjector } from './util/assert-injector/assert-injector'
+import { injectQueryClient } from './inject-query-client'
+import type { QueryFilters } from '@tanstack/query-core'
+import type { Injector, Signal } from '@angular/core'
+
+/**
+ * Injects a signal that tracks the number of queries that your application is loading or
+ * fetching in the background.
+ *
+ * Can be used for app-wide loading indicators
+ * @param filters - The filters to apply to the query.
+ * @param injector - The Angular injector to use.
+ * @returns signal with number of loading or fetching queries.
+ * @public
+ */
+export function injectIsFetching(
+  filters?: QueryFilters,
+  injector?: Injector,
+): Signal<number> {
+  return assertInjector(injectIsFetching, injector, () => {
+    const queryClient = injectQueryClient()
+    const destroyRef = inject(DestroyRef)
+    const ngZone = inject(NgZone)
+
+    const cache = queryClient.getQueryCache()
+    // isFetching is the prev value initialized on mount *
+    let isFetching = queryClient.isFetching(filters)
+
+    const result = signal(isFetching)
+
+    const unsubscribe = cache.subscribe(
+      notifyManager.batchCalls(() => {
+        const newIsFetching = queryClient.isFetching(filters)
+        if (isFetching !== newIsFetching) {
+          // * and update with each change
+          isFetching = newIsFetching
+          ngZone.run(() => {
+            result.set(isFetching)
+          })
+        }
+      }),
+    )
+
+    destroyRef.onDestroy(unsubscribe)
+
+    return result
+  })
+}

package/src/inject-is-mutating.ts

@@ -0,0 +1,49 @@
+import { DestroyRef, NgZone, inject, signal } from '@angular/core'
+import { notifyManager } from '@tanstack/query-core'
+import { assertInjector } from './util/assert-injector/assert-injector'
+import { injectQueryClient } from './inject-query-client'
+import type { MutationFilters } from '@tanstack/query-core'
+import type { Injector, Signal } from '@angular/core'
+
+/**
+ * Injects a signal that tracks the number of mutations that your application is fetching.
+ *
+ * Can be used for app-wide loading indicators
+ * @param filters - The filters to apply to the query.
+ * @param injector - The Angular injector to use.
+ * @returns signal with number of fetching mutations.
+ * @public
+ */
+export function injectIsMutating(
+  filters?: MutationFilters,
+  injector?: Injector,
+): Signal<number> {
+  return assertInjector(injectIsMutating, injector, () => {
+    const queryClient = injectQueryClient()
+    const destroyRef = inject(DestroyRef)
+    const ngZone = inject(NgZone)
+
+    const cache = queryClient.getMutationCache()
+    // isMutating is the prev value initialized on mount *
+    let isMutating = queryClient.isMutating(filters)
+
+    const result = signal(isMutating)
+
+    const unsubscribe = cache.subscribe(
+      notifyManager.batchCalls(() => {
+        const newIsMutating = queryClient.isMutating(filters)
+        if (isMutating !== newIsMutating) {
+          // * and update with each change
+          isMutating = newIsMutating
+          ngZone.run(() => {
+            result.set(isMutating)
+          })
+        }
+      }),
+    )
+
+    destroyRef.onDestroy(unsubscribe)
+
+    return result
+  })
+}

package/src/inject-mutation-state.ts

@@ -0,0 +1,99 @@
+import {
+  DestroyRef,
+  NgZone,
+  effect,
+  inject,
+  signal,
+  untracked,
+} from '@angular/core'
+import { notifyManager, replaceEqualDeep } from '@tanstack/query-core'
+import { assertInjector } from './util/assert-injector/assert-injector'
+import { injectQueryClient } from './inject-query-client'
+import { lazySignalInitializer } from './util/lazy-signal-initializer/lazy-signal-initializer'
+import type { Injector, Signal } from '@angular/core'
+import type {
+  Mutation,
+  MutationCache,
+  MutationFilters,
+  MutationState,
+} from '@tanstack/query-core'
+
+type MutationStateOptions<TResult = MutationState> = {
+  filters?: MutationFilters
+  select?: (mutation: Mutation) => TResult
+}
+
+function getResult<TResult = MutationState>(
+  mutationCache: MutationCache,
+  options: MutationStateOptions<TResult>,
+): Array<TResult> {
+  return mutationCache
+    .findAll(options.filters)
+    .map(
+      (mutation): TResult =>
+        (options.select ? options.select(mutation) : mutation.state) as TResult,
+    )
+}
+
+/**
+ * @public
+ */
+export interface InjectMutationStateOptions {
+  injector?: Injector
+}
+
+/**
+ * Injects a signal that tracks the state of all mutations.
+ * @param mutationStateOptionsFn - A function that returns mutation state options.
+ * @param options - The Angular injector to use.
+ * @returns The signal that tracks the state of all mutations.
+ * @public
+ */
+export function injectMutationState<TResult = MutationState>(
+  mutationStateOptionsFn: () => MutationStateOptions<TResult> = () => ({}),
+  options?: InjectMutationStateOptions,
+): Signal<Array<TResult>> {
+  return assertInjector(injectMutationState, options?.injector, () => {
+    const destroyRef = inject(DestroyRef)
+    const queryClient = injectQueryClient()
+    const ngZone = inject(NgZone)
+
+    const mutationCache = queryClient.getMutationCache()
+
+    return lazySignalInitializer((injector) => {
+      const result = signal<Array<TResult>>(
+        getResult(mutationCache, mutationStateOptionsFn()),
+      )
+
+      effect(
+        () => {
+          const mutationStateOptions = mutationStateOptionsFn()
+          untracked(() => {
+            // Setting the signal from an effect because it's both 'computed' from options()
+            // and needs to be set imperatively in the mutationCache listener.
+            result.set(getResult(mutationCache, mutationStateOptions))
+          })
+        },
+        { injector },
+      )
+
+      const unsubscribe = mutationCache.subscribe(
+        notifyManager.batchCalls(() => {
+          const nextResult = replaceEqualDeep(
+            result(),
+            getResult(mutationCache, mutationStateOptionsFn()),
+          )
+          if (result() !== nextResult) {
+            ngZone.run(() => {
+              result.set(nextResult)
+            })
+          }
+        }),
+      )
+
+      destroyRef.onDestroy(unsubscribe)
+
+      return result
+    })
+  })
+}

package/src/inject-mutation.ts

@@ -0,0 +1,122 @@
+import {
+  DestroyRef,
+  Injector,
+  NgZone,
+  computed,
+  effect,
+  inject,
+  runInInjectionContext,
+  signal,
+} from '@angular/core'
+import { MutationObserver, notifyManager } from '@tanstack/query-core'
+import { assertInjector } from './util/assert-injector/assert-injector'
+import { signalProxy } from './signal-proxy'
+import { injectQueryClient } from './inject-query-client'
+import { noop, shouldThrowError } from './util'
+
+import { lazyInit } from './util/lazy-init/lazy-init'
+import type {
+  DefaultError,
+  MutationObserverResult,
+  QueryClient,
+} from '@tanstack/query-core'
+import type {
+  CreateMutateFunction,
+  CreateMutationOptions,
+  CreateMutationResult,
+} from './types'
+
+/**
+ * Injects a mutation: an imperative function that can be invoked which typically performs server side effects.
+ *
+ * Unlike queries, mutations are not run automatically.
+ * @param optionsFn - A function that returns mutation options.
+ * @param injector - The Angular injector to use.
+ * @returns The mutation.
+ * @public
+ */
+export function injectMutation<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TContext = unknown,
+>(
+  optionsFn: (
+    client: QueryClient,
+  ) => CreateMutationOptions<TData, TError, TVariables, TContext>,
+  injector?: Injector,
+): CreateMutationResult<TData, TError, TVariables, TContext> {
+  return assertInjector(injectMutation, injector, () => {
+    const queryClient = injectQueryClient()
+    const currentInjector = inject(Injector)
+    const destroyRef = inject(DestroyRef)
+    const ngZone = inject(NgZone)
+
+    return lazyInit(() =>
+      runInInjectionContext(currentInjector, () => {
+        const observer = new MutationObserver<
+          TData,
+          TError,
+          TVariables,
+          TContext
+        >(queryClient, optionsFn(queryClient))
+        const mutate: CreateMutateFunction<
+          TData,
+          TError,
+          TVariables,
+          TContext
+        > = (variables, mutateOptions) => {
+          observer.mutate(variables, mutateOptions).catch(noop)
+        }
+
+        effect(() => {
+          observer.setOptions(
+            runInInjectionContext(currentInjector, () =>
+              optionsFn(queryClient),
+            ),
+          )
+        })
+
+        const result = signal(observer.getCurrentResult())
+
+        const unsubscribe = observer.subscribe(
+          notifyManager.batchCalls(
+            (
+              state: MutationObserverResult<
+                TData,
+                TError,
+                TVariables,
+                TContext
+              >,
+            ) => {
+              ngZone.run(() => {
+                if (
+                  state.isError &&
+                  shouldThrowError(observer.options.throwOnError, [state.error])
+                ) {
+                  throw state.error
+                }
+                result.set(state)
+              })
+            },
+          ),
+        )
+
+        destroyRef.onDestroy(unsubscribe)
+
+        const resultSignal = computed(() => ({
+          ...result(),
+          mutate,
+          mutateAsync: result().mutate,
+        }))
+
+        return signalProxy(resultSignal) as unknown as CreateMutationResult<
+          TData,
+          TError,
+          TVariables,
+          TContext
+        >
+      }),
+    )
+  })
+}

package/src/inject-queries.ts

@@ -0,0 +1,243 @@
+import { QueriesObserver, notifyManager } from '@tanstack/query-core'
+import { DestroyRef, computed, effect, inject, signal } from '@angular/core'
+import { assertInjector } from './util/assert-injector/assert-injector'
+import { injectQueryClient } from './inject-query-client'
+import type { Injector, Signal } from '@angular/core'
+import type {
+  DefaultError,
+  OmitKeyof,
+  QueriesObserverOptions,
+  QueriesPlaceholderDataFunction,
+  QueryFunction,
+  QueryKey,
+  QueryObserverOptions,
+  QueryObserverResult,
+  ThrowOnError,
+} from '@tanstack/query-core'
+
+// This defines the `CreateQueryOptions` that are accepted in `QueriesOptions` & `GetOptions`.
+// `placeholderData` function does not have a parameter
+type QueryObserverOptionsForCreateQueries<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = OmitKeyof<
+  QueryObserverOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>,
+  'placeholderData'
+> & {
+  placeholderData?: TQueryFnData | QueriesPlaceholderDataFunction<TQueryFnData>
+}
+
+// Avoid TS depth-limit error in case of large array literal
+type MAXIMUM_DEPTH = 20
+
+// Widen the type of the symbol to enable type inference even if skipToken is not immutable.
+type SkipTokenForUseQueries = symbol
+
+type GetOptions<T> =
+  // Part 1: responsible for applying explicit type parameter to function arguments, if object { queryFnData: TQueryFnData, error: TError, data: TData }
+  T extends {
+    queryFnData: infer TQueryFnData
+    error?: infer TError
+    data: infer TData
+  }
+    ? QueryObserverOptionsForCreateQueries<TQueryFnData, TError, TData>
+    : T extends { queryFnData: infer TQueryFnData; error?: infer TError }
+      ? QueryObserverOptionsForCreateQueries<TQueryFnData, TError>
+      : T extends { data: infer TData; error?: infer TError }
+        ? QueryObserverOptionsForCreateQueries<unknown, TError, TData>
+        : // Part 2: responsible for applying explicit type parameter to function arguments, if tuple [TQueryFnData, TError, TData]
+          T extends [infer TQueryFnData, infer TError, infer TData]
+          ? QueryObserverOptionsForCreateQueries<TQueryFnData, TError, TData>
+          : T extends [infer TQueryFnData, infer TError]
+            ? QueryObserverOptionsForCreateQueries<TQueryFnData, TError>
+            : T extends [infer TQueryFnData]
+              ? QueryObserverOptionsForCreateQueries<TQueryFnData>
+              : // Part 3: responsible for inferring and enforcing type if no explicit parameter was provided
+                T extends {
+                    queryFn?:
+                      | QueryFunction<infer TQueryFnData, infer TQueryKey>
+                      | SkipTokenForUseQueries
+                    select: (data: any) => infer TData
+                    throwOnError?: ThrowOnError<any, infer TError, any, any>
+                  }
+                ? QueryObserverOptionsForCreateQueries<
+                    TQueryFnData,
+                    unknown extends TError ? DefaultError : TError,
+                    unknown extends TData ? TQueryFnData : TData,
+                    TQueryKey
+                  >
+                : // Fallback
+                  QueryObserverOptionsForCreateQueries
+
+type GetResults<T> =
+  // Part 1: responsible for mapping explicit type parameter to function result, if object
+  T extends { queryFnData: any; error?: infer TError; data: infer TData }
+    ? QueryObserverResult<TData, TError>
+    : T extends { queryFnData: infer TQueryFnData; error?: infer TError }
+      ? QueryObserverResult<TQueryFnData, TError>
+      : T extends { data: infer TData; error?: infer TError }
+        ? QueryObserverResult<TData, TError>
+        : // Part 2: responsible for mapping explicit type parameter to function result, if tuple
+          T extends [any, infer TError, infer TData]
+          ? QueryObserverResult<TData, TError>
+          : T extends [infer TQueryFnData, infer TError]
+            ? QueryObserverResult<TQueryFnData, TError>
+            : T extends [infer TQueryFnData]
+              ? QueryObserverResult<TQueryFnData>
+              : // Part 3: responsible for mapping inferred type to results, if no explicit parameter was provided
+                T extends {
+                    queryFn?:
+                      | QueryFunction<infer TQueryFnData, any>
+                      | SkipTokenForUseQueries
+                    select: (data: any) => infer TData
+                    throwOnError?: ThrowOnError<any, infer TError, any, any>
+                  }
+                ? QueryObserverResult<
+                    unknown extends TData ? TQueryFnData : TData,
+                    unknown extends TError ? DefaultError : TError
+                  >
+                : // Fallback
+                  QueryObserverResult
+
+/**
+ * QueriesOptions reducer recursively unwraps function arguments to infer/enforce type param
+ * @public
+ */
+export type QueriesOptions<
+  T extends Array<any>,
+  TResult extends Array<any> = [],
+  TDepth extends ReadonlyArray<number> = [],
+> = TDepth['length'] extends MAXIMUM_DEPTH
+  ? Array<QueryObserverOptionsForCreateQueries>
+  : T extends []
+    ? []
+    : T extends [infer Head]
+      ? [...TResult, GetOptions<Head>]
+      : T extends [infer Head, ...infer Tail]
+        ? QueriesOptions<
+            [...Tail],
+            [...TResult, GetOptions<Head>],
+            [...TDepth, 1]
+          >
+        : ReadonlyArray<unknown> extends T
+          ? T
+          : // If T is *some* array but we couldn't assign unknown[] to it, then it must hold some known/homogenous type!
+            // use this to infer the param types in the case of Array.map() argument
+            T extends Array<
+                QueryObserverOptionsForCreateQueries<
+                  infer TQueryFnData,
+                  infer TError,
+                  infer TData,
+                  infer TQueryKey
+                >
+              >
+            ? Array<
+                QueryObserverOptionsForCreateQueries<
+                  TQueryFnData,
+                  TError,
+                  TData,
+                  TQueryKey
+                >
+              >
+            : // Fallback
+              Array<QueryObserverOptionsForCreateQueries>
+
+/**
+ * QueriesResults reducer recursively maps type param to results
+ * @public
+ */
+export type QueriesResults<
+  T extends Array<any>,
+  TResult extends Array<any> = [],
+  TDepth extends ReadonlyArray<number> = [],
+> = TDepth['length'] extends MAXIMUM_DEPTH
+  ? Array<QueryObserverResult>
+  : T extends []
+    ? []
+    : T extends [infer Head]
+      ? [...TResult, GetResults<Head>]
+      : T extends [infer Head, ...infer Tail]
+        ? QueriesResults<
+            [...Tail],
+            [...TResult, GetResults<Head>],
+            [...TDepth, 1]
+          >
+        : T extends Array<
+              QueryObserverOptionsForCreateQueries<
+                infer TQueryFnData,
+                infer TError,
+                infer TData,
+                any
+              >
+            >
+          ? // Dynamic-size (homogenous) CreateQueryOptions array: map directly to array of results
+            Array<
+              QueryObserverResult<
+                unknown extends TData ? TQueryFnData : TData,
+                unknown extends TError ? DefaultError : TError
+              >
+            >
+          : // Fallback
+            Array<QueryObserverResult>
+
+/**
+ * @public
+ */
+export function injectQueries<
+  T extends Array<any>,
+  TCombinedResult = QueriesResults<T>,
+>(
+  {
+    queries,
+    ...options
+  }: {
+    queries: Signal<[...QueriesOptions<T>]>
+    combine?: (result: QueriesResults<T>) => TCombinedResult
+  },
+  injector?: Injector,
+): Signal<TCombinedResult> {
+  return assertInjector(injectQueries, injector, () => {
+    const queryClient = injectQueryClient()
+    const destroyRef = inject(DestroyRef)
+
+    const defaultedQueries = computed(() => {
+      return queries().map((opts) => {
+        const defaultedOptions = queryClient.defaultQueryOptions(opts)
+        // Make sure the results are already in fetching state before subscribing or updating options
+        defaultedOptions._optimisticResults = 'optimistic'
+
+        return defaultedOptions as QueryObserverOptions
+      })
+    })
+
+    const observer = new QueriesObserver<TCombinedResult>(
+      queryClient,
+      defaultedQueries(),
+      options as QueriesObserverOptions<TCombinedResult>,
+    )
+
+    // Do not notify on updates because of changes in the options because
+    // these changes should already be reflected in the optimistic result.
+    effect(() => {
+      observer.setQueries(
+        defaultedQueries(),
+        options as QueriesObserverOptions<TCombinedResult>,
+        { listeners: false },
+      )
+    })
+
+    const [, getCombinedResult] = observer.getOptimisticResult(
+      defaultedQueries(),
+      (options as QueriesObserverOptions<TCombinedResult>).combine,
+    )
+
+    const result = signal(getCombinedResult() as any)
+
+    const unsubscribe = observer.subscribe(notifyManager.batchCalls(result.set))
+    destroyRef.onDestroy(unsubscribe)
+
+    return result
+  })
+}

package/src/inject-query-client.ts

@@ -0,0 +1,27 @@
+import { createNoopInjectionToken } from './util/create-injection-token/create-injection-token'
+import type { QueryClient } from '@tanstack/query-core'
+
+const tokens = createNoopInjectionToken<QueryClient>('QueryClientToken')
+
+/**
+ * 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 provideTanStackQuery} 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]
+
+export const QUERY_CLIENT = tokens[2]