@tanstack/angular-query-experimental 5.84.0 → 5.84.1

package/src/inject-query.ts

@@ -1,230 +0,0 @@
-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
-}
-
-/**
- * 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'),
- *   }))
- * }
- * ```
- *
- * Similar to `computed` from Angular, the function passed to `injectQuery` will be run in the reactive context.
- * In the example below, the query will be 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 will be disabled.
- *
- * **Reactive example**
- * ```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 injectQueryFn - A function that returns query options.
- * @param options - Additional configuration
- * @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,
->(
-  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.
- *
- * **Basic example**
- * ```ts
- * class ServiceOrComponent {
- *   query = injectQuery(() => ({
- *     queryKey: ['repoData'],
- *     queryFn: () =>
- *       this.#http.get<Response>('https://api.github.com/repos/tanstack/query'),
- *   }))
- * }
- * ```
- *
- * Similar to `computed` from Angular, the function passed to `injectQuery` will be run in the reactive context.
- * In the example below, the query will be 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 will be disabled.
- *
- * **Reactive example**
- * ```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 injectQueryFn - A function that returns query options.
- * @param options - Additional configuration
- * @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,
->(
-  injectQueryFn: () => UndefinedInitialDataOptions<
-    TQueryFnData,
-    TError,
-    TData,
-    TQueryKey
-  >,
-  options?: InjectQueryOptions,
-): 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'),
- *   }))
- * }
- * ```
- *
- * Similar to `computed` from Angular, the function passed to `injectQuery` will be run in the reactive context.
- * In the example below, the query will be 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 will be disabled.
- *
- * **Reactive example**
- * ```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 injectQueryFn - A function that returns query options.
- * @param options - Additional configuration
- * @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,
->(
-  injectQueryFn: () => CreateQueryOptions<
-    TQueryFnData,
-    TError,
-    TData,
-    TQueryKey
-  >,
-  options?: InjectQueryOptions,
-): 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'),
- *   }))
- * }
- * ```
- *
- * Similar to `computed` from Angular, the function passed to `injectQuery` will be run in the reactive context.
- * In the example below, the query will be 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 will be disabled.
- *
- * **Reactive example**
- * ```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 injectQueryFn - A function that returns query options.
- * @param options - Additional configuration
- * @returns The query result.
- * @public
- * @see https://tanstack.com/query/latest/docs/framework/angular/guides/queries
- */
-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

@@ -1,60 +0,0 @@
-import type {
-  DefaultError,
-  MutationObserverOptions,
-  OmitKeyof,
-} from '@tanstack/query-core'
-
-/**
- * Allows to share and re-use mutation options in a type-safe way.
- *
- * **Example**
- *
- * ```ts
- * export class QueriesService {
- *   private http = inject(HttpClient);
- *
- *   updatePost(id: number) {
- *     return mutationOptions({
- *       mutationFn: (post: Post) => Promise.resolve(post),
- *       mutationKey: ["updatePost", id],
- *       onSuccess: (newPost) => {
- *         //           ^? newPost: Post
- *         this.queryClient.setQueryData(["posts", id], newPost);
- *       },
- *     });
- *   }
- * }
- *
- * queries = inject(QueriesService)
- * idSignal = new Signal(0);
- * mutation = injectMutation(() => this.queries.updatePost(this.idSignal()))
- *
- * mutation.mutate({ title: 'New Title' })
- * ```
- * @param options - The mutation options.
- * @returns Mutation options.
- * @public
- */
-export function mutationOptions<
-  TData = unknown,
-  TError = DefaultError,
-  TVariables = void,
-  TContext = unknown,
->(
-  options: MutationObserverOptions<TData, TError, TVariables, TContext>,
-): CreateMutationOptions<TData, TError, TVariables, TContext> {
-  return options
-}
-
-/**
- * @public
- */
-export interface CreateMutationOptions<
-  TData = unknown,
-  TError = DefaultError,
-  TVariables = void,
-  TContext = unknown,
-> extends OmitKeyof<
-    MutationObserverOptions<TData, TError, TVariables, TContext>,
-    '_defaulted'
-  > {}

package/src/providers.ts

@@ -1,372 +0,0 @@
-import {
-  DestroyRef,
-  ENVIRONMENT_INITIALIZER,
-  InjectionToken,
-  PLATFORM_ID,
-  computed,
-  effect,
-  inject,
-} from '@angular/core'
-import { QueryClient, noop, onlineManager } from '@tanstack/query-core'
-import { isPlatformBrowser } from '@angular/common'
-import { isDevMode } from './util/is-dev-mode/is-dev-mode'
-import type { Provider } from '@angular/core'
-import type {
-  DevtoolsButtonPosition,
-  DevtoolsErrorType,
-  DevtoolsPosition,
-  TanstackQueryDevtools,
-} from '@tanstack/query-devtools'
-
-/**
- * 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. Internally it calls `provideQueryClient`.
- * You can use `provideQueryClient` to provide a different `QueryClient` instance for a part
- * of the application or for unit testing purposes.
- * @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.
- */
-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 to configure a `QueryClient` and optional features such as developer tools.
- *
- * **Example - standalone**
- *
- * ```ts
- * import {
- *   provideTanStackQuery,
- *   QueryClient,
- * } from '@tanstack/angular-query-experimental'
- *
- * bootstrapApplication(AppComponent, {
- *   providers: [provideTanStackQuery(new QueryClient())],
- * })
- * ```
- *
- * **Example - NgModule-based**
- *
- * ```ts
- * import {
- *   provideTanStackQuery,
- *   QueryClient,
- * } from '@tanstack/angular-query-experimental'
- *
- * @NgModule({
- *   declarations: [AppComponent],
- *   imports: [BrowserModule],
- *   providers: [provideTanStackQuery(new QueryClient())],
- *   bootstrap: [AppComponent],
- * })
- * export class AppModule {}
- * ```
- *
- * You can also enable optional developer tools by adding `withDevtools`. By
- * default the tools will then be 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**
- *
- * ```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)]
- * ```
- * @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.
- * @see https://tanstack.com/query/v5/docs/framework/angular/quick-start
- * @see withDevtools
- */
-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 to configure a `QueryClient`.
- * @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
- * @deprecated Use `provideTanStackQuery` instead.
- */
-export function provideAngularQuery(queryClient: QueryClient): Array<Provider> {
-  return provideTanStackQuery(queryClient)
-}
-
-/**
- * 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 -
- * @param providers -
- * @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.
- * @public
- * @see {@link withDevtools}
- */
-export type DeveloperToolsFeature = QueryFeature<'DeveloperTools'>
-
-/**
- * A type alias that represents a feature which enables persistence.
- * The type is used to describe the return value of the `withPersistQueryClient` function.
- * @public
- */
-export type PersistQueryClientFeature = QueryFeature<'PersistQueryClient'>
-
-/**
- * Options for configuring the TanStack Query devtools.
- * @public
- */
-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`
-   * Defaults to `bottom-right`.
-   */
-  buttonPosition?: DevtoolsButtonPosition
-  /**
-   * The position of the TanStack Query devtools panel.
-   * `top` | `bottom` | `left` | `right`
-   * Defaults to `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
-
-  /**
-   * 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
-}
-
-/**
- * Enables developer tools.
- *
- * **Example**
- *
- * ```ts
- * export const appConfig: ApplicationConfig = {
- *   providers: [
- *     provideTanStackQuery(new QueryClient(), withDevtools())
- *   ]
- * }
- * ```
- * By default the devtools will be loaded when Angular runs in development mode and rendered in `<body>`.
- *
- * If you need more control over when devtools are loaded, you can use the `loadDevtools` option. This is particularly useful if you want to load devtools based on environment configurations. For instance, you might have a test environment running in production mode but still require devtools to be available.
- *
- * 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`.
- * @returns A set of providers for use with `provideTanStackQuery`.
- * @public
- * @see {@link provideTanStackQuery}
- * @see {@link DevtoolsOptions}
- */
-export function withDevtools(
-  withDevtoolsFn?: () => DevtoolsOptions,
-): DeveloperToolsFeature {
-  let providers: Array<Provider> = []
-  if (!isDevMode() && !withDevtoolsFn) {
-    providers = []
-  } else {
-    providers = [
-      {
-        // Do not use provideEnvironmentInitializer while Angular < v19 is supported
-        provide: ENVIRONMENT_INITIALIZER,
-        multi: true,
-        useFactory: () => {
-          if (!isPlatformBrowser(inject(PLATFORM_ID))) return noop
-          const injectedClient = inject(QueryClient, {
-            optional: true,
-          })
-          const destroyRef = inject(DestroyRef)
-
-          const options = computed(() => withDevtoolsFn?.() ?? {})
-
-          let devtools: TanstackQueryDevtools | null = null
-          let el: HTMLElement | null = null
-
-          const shouldLoadToolsSignal = computed(() => {
-            const { loadDevtools } = options()
-            return typeof loadDevtools === 'boolean'
-              ? loadDevtools
-              : isDevMode()
-          })
-
-          const getResolvedQueryClient = () => {
-            const client = options().client ?? injectedClient
-            if (!client) {
-              throw new Error('No QueryClient found')
-            }
-            return client
-          }
-
-          const destroyDevtools = () => {
-            devtools?.unmount()
-            el?.remove()
-            devtools = null
-          }
-
-          return () =>
-            effect(() => {
-              const shouldLoadTools = shouldLoadToolsSignal()
-              const {
-                client,
-                position,
-                errorTypes,
-                buttonPosition,
-                initialIsOpen,
-              } = options()
-
-              if (devtools && !shouldLoadTools) {
-                destroyDevtools()
-                return
-              } else if (devtools && shouldLoadTools) {
-                client && devtools.setClient(client)
-                position && devtools.setPosition(position)
-                errorTypes && devtools.setErrorTypes(errorTypes)
-                buttonPosition && devtools.setButtonPosition(buttonPosition)
-                initialIsOpen && devtools.setInitialIsOpen(initialIsOpen)
-                return
-              } else if (!shouldLoadTools) {
-                return
-              }
-
-              el = document.body.appendChild(document.createElement('div'))
-              el.classList.add('tsqd-parent-container')
-
-              import('@tanstack/query-devtools').then((queryDevtools) => {
-                devtools = new queryDevtools.TanstackQueryDevtools({
-                  ...options(),
-                  client: getResolvedQueryClient(),
-                  queryFlavor: 'Angular Query',
-                  version: '5',
-                  onlineManager,
-                })
-
-                el && devtools.mount(el)
-
-                // Unmount the devtools on application destroy
-                destroyRef.onDestroy(destroyDevtools)
-              })
-            })
-        },
-      },
-    ]
-  }
-  return queryFeature('DeveloperTools', providers)
-}
-
-/**
- * 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.
- * @public
- * @see {@link provideTanStackQuery}
- */
-export type QueryFeatures = DeveloperToolsFeature | PersistQueryClientFeature
-
-export const queryFeatures = ['DeveloperTools', 'PersistQueryClient'] as const
-
-export type QueryFeatureKind = (typeof queryFeatures)[number]