@tanstack/angular-query-experimental 5.103.2 → 5.104.0

package/src/inject-is-fetching.ts

@@ -0,0 +1,97 @@
+import {
+  DestroyRef,
+  Injector,
+  NgZone,
+  assertInInjectionContext,
+  inject,
+  signal,
+} from '@angular/core'
+import { QueryClient, notifyManager } from '@tanstack/query-core'
+import type { QueryFilters } from '@tanstack/query-core'
+import type { Signal } from '@angular/core'
+
+export interface InjectIsFetchingOptions {
+  /**
+   * The `Injector` in which to create the isFetching signal.
+   *
+   * If this is not provided, the current injection context will be used instead (via `inject`).
+   */
+  injector?: Injector
+}
+
+/**
+ * Injects a signal that tracks the number of queries that your application is loading or fetching in the
+ * background (useful for app-wide loading indicators).
+ *
+ * @param filters - The {@link QueryFilters} to narrow down the matched queries.
+ * @param options - Additional configuration
+ * @returns A `Signal` with the number of queries that your application is currently loading or fetching in
+ * the background.
+ *
+ * @example
+ * ```angular-ts
+ * @Component({
+ *   selector: 'posts-fetching-indicator',
+ *   template: `
+ *     @if (isFetchingPosts()) {
+ *       <span>Refreshing posts...</span>
+ *     }
+ *   `,
+ * })
+ * export class PostsFetchingIndicator {
+ *   // How many queries matching the posts prefix are fetching?
+ *   readonly isFetchingPosts = injectIsFetching({ queryKey: ['posts'] })
+ * }
+ * ```
+ *
+ * @example
+ * A global loading indicator for any query fetching in the background, not just the ones on screen:
+ * ```angular-ts
+ * @Component({
+ *   selector: 'global-loading-indicator',
+ *   template: `
+ *     @if (isFetching()) {
+ *       <div>Queries are fetching in the background...</div>
+ *     }
+ *   `,
+ * })
+ * export class GlobalLoadingIndicator {
+ *   readonly isFetching = injectIsFetching()
+ * }
+ * ```
+ */
+export function injectIsFetching(
+  filters?: QueryFilters,
+  options?: InjectIsFetchingOptions,
+): Signal<number> {
+  !options?.injector && assertInInjectionContext(injectIsFetching)
+  const injector = options?.injector ?? inject(Injector)
+  const destroyRef = injector.get(DestroyRef)
+  const ngZone = injector.get(NgZone)
+  const queryClient = injector.get(QueryClient)
+
+  const cache = queryClient.getQueryCache()
+  // isFetching is the prev value initialized on mount *
+  let isFetching = queryClient.isFetching(filters)
+
+  const result = signal(isFetching)
+
+  const unsubscribe = ngZone.runOutsideAngular(() =>
+    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,80 @@
+import {
+  DestroyRef,
+  Injector,
+  NgZone,
+  assertInInjectionContext,
+  inject,
+  signal,
+} from '@angular/core'
+import { QueryClient, notifyManager } from '@tanstack/query-core'
+import type { MutationFilters } from '@tanstack/query-core'
+import type { Signal } from '@angular/core'
+
+export interface InjectIsMutatingOptions {
+  /**
+   * The `Injector` in which to create the isMutating signal.
+   *
+   * If this is not provided, the current injection context will be used instead (via `inject`).
+   */
+  injector?: Injector
+}
+
+/**
+ * Injects a signal that tracks the number of mutations that your application currently has `pending`
+ * (useful for app-wide loading indicators).
+ *
+ * @param filters - The {@link MutationFilters} to narrow down the matched mutations.
+ * @param options - Additional configuration
+ * @returns A `Signal` with the number of mutations that your application currently has `pending`.
+ *
+ * @example
+ * ```angular-ts
+ * @Component({
+ *   selector: 'posts-mutating-indicator',
+ *   template: `
+ *     @if (isMutatingPosts()) {
+ *       <span>Saving posts...</span>
+ *     }
+ *   `,
+ * })
+ * export class PostsMutatingIndicator {
+ *   // How many mutations matching the posts prefix are in progress?
+ *   readonly isMutatingPosts = injectIsMutating({ mutationKey: ['posts'] })
+ * }
+ * ```
+ */
+export function injectIsMutating(
+  filters?: MutationFilters,
+  options?: InjectIsMutatingOptions,
+): Signal<number> {
+  !options?.injector && assertInInjectionContext(injectIsMutating)
+  const injector = options?.injector ?? inject(Injector)
+  const destroyRef = injector.get(DestroyRef)
+  const ngZone = injector.get(NgZone)
+  const queryClient = injector.get(QueryClient)
+
+  const cache = queryClient.getMutationCache()
+  // isMutating is the prev value initialized on mount *
+  let isMutating = queryClient.isMutating(filters)
+
+  const result = signal(isMutating)
+
+  const unsubscribe = ngZone.runOutsideAngular(() =>
+    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.asReadonly()
+}

package/src/inject-is-restoring.ts

@@ -0,0 +1,53 @@
+import {
+  InjectionToken,
+  Injector,
+  assertInInjectionContext,
+  inject,
+  signal,
+} from '@angular/core'
+import type { Provider, Signal } from '@angular/core'
+
+/**
+ * Internal token used to track isRestoring state, accessible in public API through `injectIsRestoring` and set via `provideIsRestoring`
+ */
+const IS_RESTORING = new InjectionToken('', {
+  // Default value when not provided
+  factory: () => signal(false).asReadonly(),
+})
+
+interface InjectIsRestoringOptions {
+  /**
+   * The `Injector` to use to get the isRestoring signal.
+   *
+   * If this is not provided, the current injection context will be used instead (via `inject`).
+   */
+  injector?: Injector
+}
+
+/**
+ * Injects a signal that tracks whether a restore (e.g. from a persisted client, wired up via
+ * `provideIsRestoring`) is currently in progress. `injectQuery` and friends also check this internally to
+ * avoid race conditions between the restore and initializing queries.
+ * @param options - Additional configuration
+ * @returns A readonly `Signal<boolean>` — `true` while a restore is in progress, `false` otherwise (the
+ * default when no `provideIsRestoring` provider is registered).
+ */
+export function injectIsRestoring(options?: InjectIsRestoringOptions) {
+  !options?.injector && assertInInjectionContext(injectIsRestoring)
+  const injector = options?.injector ?? inject(Injector)
+  return injector.get(IS_RESTORING)
+}
+
+/**
+ * Registers a provider for the restore state read by `injectIsRestoring`. Wire this up wherever you drive a
+ * restore yourself — e.g. a persist-client integration — so `injectQuery` and friends can defer subscribing
+ * to their observer (avoiding a race with the restore) until the restore signal flips back to `false`.
+ * @param isRestoring - A readonly `Signal<boolean>` that tracks the restore state.
+ * @returns A provider for the `isRestoring` signal.
+ */
+export function provideIsRestoring(isRestoring: Signal<boolean>): Provider {
+  return {
+    provide: IS_RESTORING,
+    useValue: isRestoring,
+  }
+}

package/src/inject-mutation-state.ts

@@ -0,0 +1,167 @@
+import {
+  DestroyRef,
+  Injector,
+  NgZone,
+  assertInInjectionContext,
+  computed,
+  inject,
+  signal,
+} from '@angular/core'
+import {
+  QueryClient,
+  notifyManager,
+  replaceEqualDeep,
+} from '@tanstack/query-core'
+import type { 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,
+    )
+}
+
+export interface InjectMutationStateOptions {
+  /**
+   * The `Injector` in which to create the mutation state signal.
+   *
+   * If this is not provided, the current injection context will be used instead (via `inject`).
+   */
+  injector?: Injector
+}
+
+/**
+ * Injects a signal that gives you access to all mutations in the `MutationCache`. You can pass `filters`
+ * ({@link MutationFilters}) to narrow down your mutations, and `select` to transform the mutation state.
+ *
+ * @param injectMutationStateFn - A function returning the `filters` to narrow down matched mutations, and an
+ * optional `select` to transform the mutation state. Similar to `computed` from Angular, this function runs
+ * in the reactive context, so signals read inside it re-narrow the matched mutations.
+ * @param options - Additional configuration
+ * @returns A `Signal` with an Array of whatever `select` returns for each matching mutation.
+ *
+ * @example
+ * Get all variables of all running mutations:
+ * ```angular-ts
+ * @Component({
+ *   selector: 'pending-posts',
+ *   template: `{{ pendingVariables().length }} posts saving...`,
+ * })
+ * export class PendingPosts {
+ *   readonly pendingVariables = injectMutationState(() => ({
+ *     filters: { status: 'pending' },
+ *     select: (mutation) => mutation.state.variables,
+ *   }))
+ * }
+ * ```
+ *
+ * @example
+ * Get all data for specific mutations via the `mutationKey`:
+ * ```angular-ts
+ * const mutationKey = ['posts']
+ *
+ * @Component({
+ *   selector: 'posts',
+ *   template: `
+ *     <button (click)="createPost()">
+ *       Create post ({{ savedPosts().length }} saved so far)
+ *     </button>
+ *   `,
+ * })
+ * export class Posts {
+ *   // Some mutation that we want to get the state for
+ *   readonly createPostMutation = injectMutation(() => ({
+ *     mutationKey,
+ *     mutationFn: createPosts,
+ *   }))
+ *
+ *   readonly savedPosts = injectMutationState(() => ({
+ *     // this mutation key needs to match the mutation key of the given mutation (see above)
+ *     filters: { mutationKey, status: 'success' },
+ *     select: (mutation) => mutation.state.data,
+ *   }))
+ *
+ *   createPost() {
+ *     this.createPostMutation.mutate(['New Post'])
+ *   }
+ * }
+ * ```
+ */
+export function injectMutationState<TResult = MutationState>(
+  injectMutationStateFn: () => MutationStateOptions<TResult> = () => ({}),
+  options?: InjectMutationStateOptions,
+): Signal<Array<TResult>> {
+  !options?.injector && assertInInjectionContext(injectMutationState)
+  const injector = options?.injector ?? inject(Injector)
+  const destroyRef = injector.get(DestroyRef)
+  const ngZone = injector.get(NgZone)
+  const queryClient = injector.get(QueryClient)
+  const mutationCache = queryClient.getMutationCache()
+
+  /**
+   * Computed signal that gets result from mutation cache based on passed options
+   * First element is the result, second element is the time when the result was set
+   */
+  const resultFromOptionsSignal = computed(() => {
+    return [
+      getResult(mutationCache, injectMutationStateFn()),
+      performance.now(),
+    ] as const
+  })
+
+  /**
+   * Signal that contains result set by subscriber
+   * First element is the result, second element is the time when the result was set
+   */
+  const resultFromSubscriberSignal = signal<[Array<TResult>, number] | null>(
+    null,
+  )
+
+  /**
+   * Returns the last result by either subscriber or options
+   */
+  const effectiveResultSignal = computed(() => {
+    const optionsResult = resultFromOptionsSignal()
+    const subscriberResult = resultFromSubscriberSignal()
+    return subscriberResult && subscriberResult[1] > optionsResult[1]
+      ? subscriberResult[0]
+      : optionsResult[0]
+  })
+
+  const unsubscribe = ngZone.runOutsideAngular(() =>
+    mutationCache.subscribe(
+      notifyManager.batchCalls(() => {
+        const [lastResult] = effectiveResultSignal()
+        const nextResult = replaceEqualDeep(
+          lastResult,
+          getResult(mutationCache, injectMutationStateFn()),
+        )
+        if (lastResult !== nextResult) {
+          ngZone.run(() => {
+            resultFromSubscriberSignal.set([nextResult, performance.now()])
+          })
+        }
+      }),
+    ),
+  )
+
+  destroyRef.onDestroy(unsubscribe)
+
+  return effectiveResultSignal
+}