@tanstack/angular-query-experimental 5.103.1 → 5.103.3

package/src/create-base-query.ts

@@ -0,0 +1,175 @@
+import {
+  NgZone,
+  VERSION,
+  computed,
+  effect,
+  inject,
+  signal,
+  untracked,
+} from '@angular/core'
+import {
+  QueryClient,
+  notifyManager,
+  shouldThrowError,
+} from '@tanstack/query-core'
+import { signalProxy } from './signal-proxy'
+import { injectIsRestoring } from './inject-is-restoring'
+import { PENDING_TASKS } from './pending-tasks-compat'
+import type { PendingTaskRef } from './pending-tasks-compat'
+import type {
+  QueryKey,
+  QueryObserver,
+  QueryObserverResult,
+} from '@tanstack/query-core'
+import type { CreateBaseQueryOptions } from './types'
+
+/**
+ * Base implementation for `injectQuery` and `injectInfiniteQuery`.
+ * @param optionsFn
+ * @param Observer
+ */
+export function createBaseQuery<
+  TQueryFnData,
+  TError,
+  TData,
+  TQueryData,
+  TQueryKey extends QueryKey,
+>(
+  optionsFn: () => CreateBaseQueryOptions<
+    TQueryFnData,
+    TError,
+    TData,
+    TQueryData,
+    TQueryKey
+  >,
+  Observer: typeof QueryObserver,
+) {
+  const ngZone = inject(NgZone)
+  const pendingTasks = inject(PENDING_TASKS)
+  const queryClient = inject(QueryClient)
+  const isRestoring = injectIsRestoring()
+
+  /**
+   * Signal that has the default options from query client applied
+   * computed() is used so signals can be inserted into the options
+   * making it reactive. Wrapping options in a function ensures embedded expressions
+   * are preserved and can keep being applied after signal changes
+   */
+  const defaultedOptionsSignal = computed(() => {
+    const defaultedOptions = queryClient.defaultQueryOptions(optionsFn())
+    defaultedOptions._optimisticResults = isRestoring()
+      ? 'isRestoring'
+      : 'optimistic'
+    return defaultedOptions
+  })
+
+  const observerSignal = (() => {
+    let instance: QueryObserver<
+      TQueryFnData,
+      TError,
+      TData,
+      TQueryData,
+      TQueryKey
+    > | null = null
+
+    return computed(() => {
+      return (instance ||= new Observer(queryClient, defaultedOptionsSignal()))
+    })
+  })()
+
+  const optimisticResultSignal = computed(() =>
+    observerSignal().getOptimisticResult(defaultedOptionsSignal()),
+  )
+
+  const resultFromSubscriberSignal = signal<QueryObserverResult<
+    TData,
+    TError
+  > | null>(null)
+
+  effect(
+    (onCleanup) => {
+      const observer = observerSignal()
+      const defaultedOptions = defaultedOptionsSignal()
+
+      untracked(() => {
+        observer.setOptions(defaultedOptions)
+      })
+      onCleanup(() => {
+        ngZone.run(() => resultFromSubscriberSignal.set(null))
+      })
+    },
+    {
+      // Set allowSignalWrites to support Angular < v19
+      // Set to undefined to avoid warning on newer versions
+      allowSignalWrites: VERSION.major < '19' || undefined,
+    },
+  )
+
+  effect((onCleanup) => {
+    // observer.trackResult is not used as this optimization is not needed for Angular
+    const observer = observerSignal()
+    let pendingTaskRef: PendingTaskRef | null = null
+
+    const unsubscribe = isRestoring()
+      ? () => undefined
+      : untracked(() =>
+          ngZone.runOutsideAngular(() => {
+            return observer.subscribe(
+              notifyManager.batchCalls((state) => {
+                ngZone.run(() => {
+                  if (state.fetchStatus === 'fetching' && !pendingTaskRef) {
+                    pendingTaskRef = pendingTasks.add()
+                  }
+
+                  if (state.fetchStatus === 'idle' && pendingTaskRef) {
+                    pendingTaskRef()
+                    pendingTaskRef = null
+                  }
+
+                  if (
+                    state.isError &&
+                    !state.isFetching &&
+                    shouldThrowError(observer.options.throwOnError, [
+                      state.error,
+                      observer.getCurrentQuery(),
+                    ])
+                  ) {
+                    ngZone.onError.emit(state.error)
+                    throw state.error
+                  }
+                  resultFromSubscriberSignal.set(state)
+                })
+              }),
+            )
+          }),
+        )
+
+    onCleanup(() => {
+      if (pendingTaskRef) {
+        pendingTaskRef()
+        pendingTaskRef = null
+      }
+      unsubscribe()
+    })
+  })
+
+  return signalProxy(
+    computed(() => {
+      const subscriberResult = resultFromSubscriberSignal()
+      const optimisticResult = optimisticResultSignal()
+      const result = subscriberResult ?? optimisticResult
+
+      // Wrap methods to ensure observer has latest options before execution
+      const observer = observerSignal()
+
+      const originalRefetch = result.refetch
+      return {
+        ...result,
+        refetch: ((...args: Parameters<typeof originalRefetch>) => {
+          observer.setOptions(defaultedOptionsSignal())
+          return originalRefetch(...args)
+        }) as typeof originalRefetch,
+      }
+    }),
+  )
+}

package/src/devtools/index.ts

@@ -0,0 +1,8 @@
+export type {
+  DevtoolsOptions,
+  WithDevtools,
+  WithDevtoolsFn,
+  WithDevtoolsOptions,
+} from './types'
+
+export { withDevtools } from './with-devtools'

package/src/devtools/production/index.ts

@@ -0,0 +1 @@
+export * from '..'

package/src/devtools/stub.ts

@@ -0,0 +1,7 @@
+import type { WithDevtools } from './types'
+
+// Stub which replaces `withDevtools` in production builds
+export const withDevtools: WithDevtools = () => ({
+  ɵkind: 'Devtools',
+  ɵproviders: [],
+})

package/src/devtools/types.ts

@@ -0,0 +1,116 @@
+import type { QueryClient } from '@tanstack/query-core'
+import type {
+  DevtoolsButtonPosition,
+  DevtoolsErrorType,
+  DevtoolsPosition,
+  Theme,
+} from '@tanstack/query-devtools'
+import type { DevtoolsFeature } from '../providers'
+
+/**
+ * Options for configuring withDevtools.
+ */
+export interface WithDevtoolsOptions {
+  /**
+   * An array of dependencies to be injected and passed to the `withDevtoolsFn` function.
+   *
+   * **Example**
+   * ```ts
+   * export const appConfig: ApplicationConfig = {
+   *   providers: [
+   *     provideTanStackQuery(
+   *       new QueryClient(),
+   *       withDevtools(
+   *         (devToolsOptionsManager: DevtoolsOptionsManager) => ({
+   *           loadDevtools: devToolsOptionsManager.loadDevtools(),
+   *         }),
+   *         {
+   *           deps: [DevtoolsOptionsManager],
+   *         },
+   *       ),
+   *     ),
+   *   ],
+   * }
+   * ```
+   */
+  deps?: Array<any>
+}
+
+/**
+ * Options for configuring the TanStack Query devtools.
+ */
+export interface DevtoolsOptions {
+  /**
+   * Set this true if you want the devtools to default to being open
+   */
+  initialIsOpen?: boolean
+  /**
+   * The position of the TanStack logo to open and close the devtools panel.
+   * `top-left` | `top-right` | `bottom-left` | `bottom-right` | `relative`
+   *
+   * @defaultValue bottom-right
+   */
+  buttonPosition?: DevtoolsButtonPosition
+  /**
+   * The position of the Angular Query devtools panel.
+   * `top` | `bottom` | `left` | `right`
+   *
+   * @defaultValue bottom
+   */
+  position?: DevtoolsPosition
+  /**
+   * Custom instance of QueryClient
+   */
+  client?: QueryClient
+  /**
+   * Use this so you can define custom errors that can be shown in the devtools.
+   */
+  errorTypes?: Array<DevtoolsErrorType>
+  /**
+   * Use this to pass a nonce to the style tag that is added to the document head. This is useful if you are using a Content Security Policy (CSP) nonce to allow inline styles.
+   */
+  styleNonce?: string
+  /**
+   * Use this so you can attach the devtool's styles to a specific element in the DOM.
+   */
+  shadowDOMTarget?: ShadowRoot
+  /**
+   * Set this to true to hide disabled queries from the devtools panel.
+   */
+  hideDisabledQueries?: boolean
+  /**
+   * Set this to 'light', 'dark', or 'system' to change the theme of the devtools panel.
+   *
+   * @defaultValue system
+   */
+  theme?: Theme
+
+  /**
+   * Whether the developer tools should load.
+   * - `auto`- (Default) Lazily loads devtools when in development mode. Skips loading in production mode.
+   * - `true`- Always load the devtools, regardless of the environment.
+   * - `false`- Never load the devtools, regardless of the environment.
+   *
+   * You can use `true` and `false` to override loading developer tools from an environment file.
+   * For example, a test environment might run in production mode but you may want to load developer tools.
+   *
+   * Additionally, you can use a signal in the callback to dynamically load the devtools based on a condition. For example,
+   * a signal created from a RxJS observable that listens for a keyboard shortcut.
+   *
+   * **Example**
+   * ```ts
+   *    withDevtools(() => ({
+   *      initialIsOpen: true,
+   *      loadDevtools: inject(ExampleService).loadDevtools()
+   *    }))
+   *  ```
+   */
+  loadDevtools?: 'auto' | boolean
+}
+
+export type WithDevtoolsFn = (...deps: Array<any>) => DevtoolsOptions
+
+export type WithDevtools = (
+  withDevtoolsFn?: WithDevtoolsFn,
+  options?: WithDevtoolsOptions,
+) => DevtoolsFeature

package/src/devtools/with-devtools.ts

@@ -0,0 +1,182 @@
+import { isPlatformBrowser } from '@angular/common'
+import {
+  DestroyRef,
+  ENVIRONMENT_INITIALIZER,
+  InjectionToken,
+  Injector,
+  PLATFORM_ID,
+  computed,
+  effect,
+  inject,
+  isDevMode,
+} from '@angular/core'
+import { QueryClient, noop, onlineManager } from '@tanstack/query-core'
+import { queryFeature } from '../providers'
+import type { Signal } from '@angular/core'
+import type {
+  DevtoolsOptions,
+  WithDevtools,
+  WithDevtoolsFn,
+  WithDevtoolsOptions,
+} from './types'
+import type { TanstackQueryDevtools } from '@tanstack/query-devtools'
+
+/**
+ * Internal token used to prevent double providing of devtools in child injectors
+ */
+const DEVTOOLS_PROVIDED = new InjectionToken('', {
+  factory: () => ({
+    isProvided: false,
+  }),
+})
+
+/**
+ * Internal token for providing devtools options
+ */
+const DEVTOOLS_OPTIONS_SIGNAL = new InjectionToken<Signal<DevtoolsOptions>>('')
+
+/**
+ * Enables developer tools in Angular development builds.
+ *
+ * **Example**
+ *
+ * ```ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideTanStackQuery(new QueryClient(), withDevtools())
+ *   ]
+ * }
+ * ```
+ * The devtools will be rendered in `<body>`.
+ *
+ * If you need more control over when devtools are loaded, you can use the `loadDevtools` option.
+ *
+ * If you need more control over where devtools are rendered, consider `injectDevtoolsPanel`. This allows rendering devtools inside your own devtools for example.
+ * @param withDevtoolsFn - A function that returns `DevtoolsOptions`.
+ * @param options - Additional options for configuring `withDevtools`.
+ * @returns A set of providers for use with `provideTanStackQuery`.
+ * @see {@link provideTanStackQuery}
+ * @see {@link DevtoolsOptions}
+ */
+export const withDevtools: WithDevtools = (
+  withDevtoolsFn?: WithDevtoolsFn,
+  options: WithDevtoolsOptions = {},
+) =>
+  queryFeature('Devtools', [
+    {
+      provide: DEVTOOLS_OPTIONS_SIGNAL,
+      useFactory: (...deps: Array<any>) =>
+        computed(() => withDevtoolsFn?.(...deps) ?? {}),
+      deps: options.deps || [],
+    },
+    {
+      // Do not use provideEnvironmentInitializer while Angular < v19 is supported
+      provide: ENVIRONMENT_INITIALIZER,
+      multi: true,
+      useFactory: () => {
+        const devtoolsProvided = inject(DEVTOOLS_PROVIDED)
+        if (
+          !isPlatformBrowser(inject(PLATFORM_ID)) ||
+          devtoolsProvided.isProvided
+        )
+          return noop
+
+        devtoolsProvided.isProvided = true
+        let injectorIsDestroyed = false
+        inject(DestroyRef).onDestroy(() => (injectorIsDestroyed = true))
+
+        return () => {
+          const injectedClient = inject(QueryClient, {
+            optional: true,
+          })
+          const destroyRef = inject(DestroyRef)
+          const devtoolsOptions = inject(DEVTOOLS_OPTIONS_SIGNAL)
+          const injector = inject(Injector)
+
+          let devtools: TanstackQueryDevtools | null = null
+          let el: HTMLElement | null = null
+
+          const shouldLoadToolsSignal = computed(() => {
+            const { loadDevtools } = devtoolsOptions()
+            return typeof loadDevtools === 'boolean'
+              ? loadDevtools
+              : isDevMode()
+          })
+
+          const getResolvedQueryClient = () => {
+            const client = devtoolsOptions().client ?? injectedClient
+            if (!client) {
+              throw new Error('No QueryClient found')
+            }
+            return client
+          }
+
+          const destroyDevtools = () => {
+            devtools?.unmount()
+            el?.remove()
+            devtools = null
+          }
+
+          effect(
+            () => {
+              const shouldLoadTools = shouldLoadToolsSignal()
+              const {
+                client,
+                position,
+                errorTypes,
+                buttonPosition,
+                initialIsOpen,
+                theme,
+              } = devtoolsOptions()
+
+              if (!shouldLoadTools) {
+                // Destroy or do nothing
+                devtools && destroyDevtools()
+                return
+              }
+
+              if (devtools) {
+                // Update existing devtools config
+                client && devtools.setClient(client)
+                position && devtools.setPosition(position)
+                errorTypes && devtools.setErrorTypes(errorTypes)
+                buttonPosition && devtools.setButtonPosition(buttonPosition)
+                typeof initialIsOpen === 'boolean' &&
+                  devtools.setInitialIsOpen(initialIsOpen)
+                theme && devtools.setTheme(theme)
+                return
+              }
+
+              // Create devtools
+              import('@tanstack/query-devtools')
+                .then((queryDevtools) => {
+                  // As this code runs async, the injector could have been destroyed
+                  if (injectorIsDestroyed) return
+
+                  devtools = new queryDevtools.TanstackQueryDevtools({
+                    ...devtoolsOptions(),
+                    client: getResolvedQueryClient(),
+                    queryFlavor: 'Angular Query',
+                    version: '5',
+                    onlineManager,
+                  })
+
+                  el = document.body.appendChild(document.createElement('div'))
+                  el.classList.add('tsqd-parent-container')
+                  devtools.mount(el)
+
+                  destroyRef.onDestroy(destroyDevtools)
+                })
+                .catch((error) => {
+                  console.error(
+                    'Install @tanstack/query-devtools or reinstall without --omit=optional.',
+                    error,
+                  )
+                })
+            },
+            { injector },
+          )
+        }
+      },
+    },
+  ])

package/src/devtools-panel/index.ts

@@ -0,0 +1,8 @@
+export type {
+  InjectDevtoolsPanel,
+  DevtoolsPanelOptions,
+  InjectDevtoolsPanelOptions,
+  DevtoolsPanelRef,
+} from './types'
+
+export { injectDevtoolsPanel } from './inject-devtools-panel'

package/src/devtools-panel/inject-devtools-panel.ts

@@ -0,0 +1,110 @@
+import {
+  DestroyRef,
+  Injector,
+  PLATFORM_ID,
+  assertInInjectionContext,
+  computed,
+  effect,
+  inject,
+  runInInjectionContext,
+  untracked,
+} from '@angular/core'
+import { QueryClient, onlineManager } from '@tanstack/query-core'
+import { isPlatformBrowser } from '@angular/common'
+import type { TanstackQueryDevtoolsPanel } from '@tanstack/query-devtools'
+import type {
+  DevtoolsPanelOptions,
+  InjectDevtoolsPanel,
+  InjectDevtoolsPanelOptions,
+} from './types'
+
+/**
+ * Inject a TanStack Query devtools panel and render it in the DOM.
+ *
+ * Devtools panel allows programmatic control over the devtools, for example if you want to render
+ * the devtools as part of your own devtools.
+ *
+ * Consider `withDevtools` instead if you don't need this.
+ * @param injectDevtoolsPanelFn - A function that returns devtools panel options.
+ * @param options - Additional configuration
+ * @returns DevtoolsPanelRef
+ * @see https://tanstack.com/query/v5/docs/framework/angular/devtools
+ */
+export const injectDevtoolsPanel: InjectDevtoolsPanel = (
+  injectDevtoolsPanelFn: () => DevtoolsPanelOptions,
+  options?: InjectDevtoolsPanelOptions,
+) => {
+  !options?.injector && assertInInjectionContext(injectDevtoolsPanel)
+  const currentInjector = options?.injector ?? inject(Injector)
+
+  return runInInjectionContext(currentInjector, () => {
+    const destroyRef = inject(DestroyRef)
+    const isBrowser = isPlatformBrowser(inject(PLATFORM_ID))
+    const injectedClient = inject(QueryClient, { optional: true })
+
+    const queryOptions = computed(injectDevtoolsPanelFn)
+    let devtools: TanstackQueryDevtoolsPanel | null = null
+
+    const destroy = () => {
+      devtools?.unmount()
+      devtools = null
+    }
+
+    if (!isBrowser)
+      return {
+        destroy,
+      }
+
+    effect(() => {
+      const {
+        client = injectedClient,
+        errorTypes = [],
+        styleNonce,
+        shadowDOMTarget,
+        onClose,
+        hostElement,
+      } = queryOptions()
+
+      untracked(() => {
+        if (!client) throw new Error('No QueryClient found')
+        if (!devtools && hostElement) {
+          import('@tanstack/query-devtools')
+            .then((queryDevtools) => {
+              devtools = new queryDevtools.TanstackQueryDevtoolsPanel({
+                client,
+                queryFlavor: 'Angular Query',
+                version: '5',
+                buttonPosition: 'bottom-left',
+                position: 'bottom',
+                initialIsOpen: true,
+                errorTypes,
+                styleNonce,
+                shadowDOMTarget,
+                onClose,
+                onlineManager,
+              })
+              devtools.mount(hostElement.nativeElement)
+            })
+            .catch((error) => {
+              console.error(
+                'Install @tanstack/query-devtools or reinstall without --omit=optional.',
+                error,
+              )
+            })
+        } else if (devtools && hostElement) {
+          devtools.setClient(client)
+          devtools.setErrorTypes(errorTypes)
+          onClose && devtools.setOnClose(onClose)
+        } else if (devtools && !hostElement) {
+          destroy()
+        }
+      })
+    })
+
+    destroyRef.onDestroy(destroy)
+
+    return {
+      destroy,
+    }
+  })
+}

package/src/devtools-panel/production/index.ts

@@ -0,0 +1 @@
+export * from '..'

package/src/devtools-panel/stub.ts

@@ -0,0 +1,7 @@
+import { noop } from '@tanstack/query-core'
+import type { InjectDevtoolsPanel } from './types'
+
+// Stub which replaces `injectDevtoolsPanel` in production builds
+export const injectDevtoolsPanel: InjectDevtoolsPanel = () => ({
+  destroy: noop,
+})

package/src/devtools-panel/types.ts

@@ -0,0 +1,57 @@
+import type { DevtoolsErrorType } from '@tanstack/query-devtools'
+import type { ElementRef, Injector } from '@angular/core'
+import type { QueryClient } from '@tanstack/query-core'
+
+export interface InjectDevtoolsPanelOptions {
+  /**
+   * The `Injector` in which to create the devtools panel.
+   *
+   * If this is not provided, the current injection context will be used instead (via `inject`).
+   */
+  injector?: Injector
+}
+
+/**
+ * A devtools panel, which can be manually destroyed.
+ */
+export interface DevtoolsPanelRef {
+  /**
+   * Destroy the panel, removing it from the DOM and stops listening to signal changes.
+   */
+  destroy: () => void
+}
+
+export interface DevtoolsPanelOptions {
+  /**
+   * Custom instance of QueryClient
+   */
+  client?: QueryClient
+  /**
+   * Use this so you can define custom errors that can be shown in the devtools.
+   */
+  errorTypes?: Array<DevtoolsErrorType>
+  /**
+   * Use this to pass a nonce to the style tag that is added to the document head. This is useful if you are using a Content Security Policy (CSP) nonce to allow inline styles.
+   */
+  styleNonce?: string
+  /**
+   * Use this so you can attach the devtool's styles to specific element in the DOM.
+   */
+  shadowDOMTarget?: ShadowRoot
+
+  /**
+   * Callback function that is called when the devtools panel is closed
+   */
+  onClose?: () => void
+
+  /**
+   * Element where to render the devtools panel. When set to undefined or null, the devtools panel will not be created, or destroyed if existing.
+   * If changed from undefined to an ElementRef, the devtools panel will be created.
+   */
+  hostElement?: ElementRef
+}
+
+export type InjectDevtoolsPanel = (
+  injectDevtoolsPanelFn: () => DevtoolsPanelOptions,
+  options?: InjectDevtoolsPanelOptions,
+) => DevtoolsPanelRef