@tanstack/angular-query-experimental 5.59.20 → 5.60.0

package/build/rollup.d.ts

@@ -2,11 +2,15 @@ import type { DataTag } from '@tanstack/query-core';
 import type { DefaultError } from '@tanstack/query-core';
 import type { DefinedInfiniteQueryObserverResult } from '@tanstack/query-core';
 import type { DefinedQueryObserverResult } from '@tanstack/query-core';
+import type { DevtoolsButtonPosition } from '@tanstack/query-devtools';
+import type { DevtoolsErrorType } from '@tanstack/query-devtools';
+import type { DevtoolsPosition } from '@tanstack/query-devtools';
 import type { EnvironmentProviders } from '@angular/core';
 import type { InfiniteData } from '@tanstack/query-core';
 import type { InfiniteQueryObserverOptions } from '@tanstack/query-core';
 import type { InfiniteQueryObserverResult } from '@tanstack/query-core';
 import type { InitialDataFunction } from '@tanstack/query-core';
+import { InjectionToken } from '@angular/core';
 import { InjectOptions } from '@angular/core';
 import { Injector } from '@angular/core';
 import type { MutateFunction } from '@tanstack/query-core';
@@ -148,6 +152,74 @@ export declare type DefinedInitialDataOptions<TQueryFnData = unknown, TError = D
     initialData: NonUndefinedGuard<TQueryFnData> | (() => NonUndefinedGuard<TQueryFnData>);
 };
 
+/**
+ * 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 declare type DeveloperToolsFeature = QueryFeature<'DeveloperTools'>;
+
+/**
+ * Options for configuring the TanStack Query devtools.
+ * @public
+ */
+export declare 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;
+    /**
+     * 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;
+}
+
 declare type GetOptions<T> = T extends {
     queryFnData: infer TQueryFnData;
     error?: infer TError;
@@ -451,17 +523,38 @@ export declare type NonUndefinedGuard<T> = T extends undefined ? never : T;
  * 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 declare function provideAngularQuery(queryClient: QueryClient): EnvironmentProviders;
+
+/**
+ * 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 declare const provideQueryClient: ((value: QueryClient | (() => QueryClient)) => Provider) & ((value: QueryClient | (() => QueryClient)) => Provider);
+
+/**
+ * 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 {
- *   provideAngularQuery,
+ *   provideTanStackQuery,
  *   QueryClient,
  * } from '@tanstack/angular-query-experimental'
  *
  * bootstrapApplication(AppComponent, {
- *   providers: [provideAngularQuery(new QueryClient())],
+ *   providers: [provideTanStackQuery(new QueryClient())],
  * })
  * ```
  *
@@ -469,33 +562,44 @@ export declare type NonUndefinedGuard<T> = T extends undefined ? never : T;
  *
  * ```ts
  * import {
- *   provideAngularQuery,
+ *   provideTanStackQuery,
  *   QueryClient,
  * } from '@tanstack/angular-query-experimental'
  *
  * @NgModule({
  *   declarations: [AppComponent],
  *   imports: [BrowserModule],
- *   providers: [provideAngularQuery(new QueryClient())],
+ *   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())
+ *     ]
+ *   }
+ * )
+ * ```
  * @param queryClient - A `QueryClient` instance.
+ * @param features - Optional features to configure additional Query functionality.
  * @returns A set of providers to set up TanStack Query.
  * @public
  * @see https://tanstack.com/query/v5/docs/framework/angular/quick-start
+ * @see withDevtools
  */
-export declare function provideAngularQuery(queryClient: QueryClient): EnvironmentProviders;
-
-/**
- * Usually {@link provideAngularQuery} 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 declare const provideQueryClient: ((value: QueryClient | (() => QueryClient)) => Provider) & ((value: QueryClient | (() => QueryClient)) => Provider);
+export declare function provideTanStackQuery(queryClient: QueryClient, ...features: Array<QueryFeatures>): EnvironmentProviders;
 
 /**
  * QueriesOptions reducer recursively unwraps function arguments to infer/enforce type param
@@ -525,6 +629,30 @@ GetResults<Head>
 1
 ]> : T extends Array<QueryObserverOptionsForCreateQueries<infer TQueryFnData, infer TError, infer TData, any>> ? Array<QueryObserverResult<unknown extends TData ? TQueryFnData : TData, unknown extends TError ? DefaultError : TError>> : Array<QueryObserverResult>;
 
+export declare const QUERY_CLIENT: InjectionToken<QueryClient>;
+
+/**
+ * Helper type to represent a Query feature.
+ */
+export declare interface QueryFeature<TFeatureKind extends QueryFeatureKind> {
+    ɵkind: TFeatureKind;
+    ɵproviders: Array<Provider>;
+}
+
+export declare type QueryFeatureKind = (typeof queryFeatures)[number];
+
+/**
+ * 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 declare type QueryFeatures = DeveloperToolsFeature;
+
+export declare const queryFeatures: readonly ["DeveloperTools"];
+
 declare type QueryObserverOptionsForCreateQueries<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = OmitKeyof<QueryObserverOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>, 'placeholderData'> & {
     placeholderData?: TQueryFnData | QueriesPlaceholderDataFunction<TQueryFnData>;
 };
@@ -599,6 +727,31 @@ export declare type UndefinedInitialDataOptions<TQueryFnData = unknown, TError =
     initialData?: undefined | InitialDataFunction<NonUndefinedGuard<TQueryFnData>>;
 };
 
+/**
+ * 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 optionsFn - A function that returns `DevtoolsOptions`.
+ * @returns A set of providers for use with `provideTanStackQuery`.
+ * @public
+ * @see {@link provideTanStackQuery}
+ * @see {@link DevtoolsOptions}
+ */
+export declare function withDevtools(optionsFn?: () => DevtoolsOptions): DeveloperToolsFeature;
+
 
 export * from "@tanstack/query-core";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/angular-query-experimental",
-  "version": "5.59.20",
+  "version": "5.60.0",
   "description": "Signals for managing, caching and syncing asynchronous and remote data in Angular",
   "author": "Arnoud de Vries",
   "license": "MIT",
@@ -49,6 +49,7 @@
   ],
   "dependencies": {
     "tslib": "^2.6.3",
+    "@tanstack/query-devtools": "5.59.20",
     "@tanstack/query-core": "5.59.20"
   },
   "devDependencies": {
@@ -64,6 +65,7 @@
     "typescript": "5.3.3"
   },
   "peerDependencies": {
+    "@angular/common": ">=16.0.0",
     "@angular/core": ">=16.0.0"
   },
   "scripts": {}