@tanstack/angular-query-experimental 5.102.8 → 5.103.0

package/query-options.d.ts

@@ -1,78 +1,221 @@
 import { DefaultError, InitialDataFunction, NonUndefinedGuard, OmitKeyof, QueryFunction, QueryKey, QueryKeyWithDataTag, SkipToken } from '@tanstack/query-core';
 import { CreateQueryOptions } from './types.js';
+/**
+ * The options accepted by the `queryOptions` overload selected when no `initialData` is set — `data` may be
+ * `undefined` while the query is `pending`.
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export type UndefinedInitialDataOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey> & {
+    /**
+     * If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
+     * created or cached yet). If set to a function, the function will be called **once** during the shared/root
+     * query initialization, and be expected to synchronously return the initial data. Initial data is
+     * considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
+     * cache.
+     */
     initialData?: undefined | InitialDataFunction<NonUndefinedGuard<TQueryFnData>> | NonUndefinedGuard<TQueryFnData>;
 };
+/**
+ * The options accepted by the `queryOptions` overload selected when no `initialData` is set and `queryFn` is
+ * not `skipToken` — same as {@link UndefinedInitialDataOptions}, but `queryFn` may not be `skipToken`.
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export type UnusedSkipTokenOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = OmitKeyof<CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>, 'queryFn'> & {
+    /**
+     * `skipToken` is not allowed as a value here — this overload is selected when no `initialData` is set. If
+     * you don't intend to run the query yet, set `enabled: false` — omitting `queryFn` alone still triggers a
+     * fetch that fails with "Missing queryFn" unless `enabled` is `false` or a default query function has been
+     * defined. A default query function only supplies `queryFn`; it doesn't defer the fetch on its own.
+     */
     queryFn?: Exclude<CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>['queryFn'], SkipToken | undefined>;
 };
+/**
+ * The options accepted by the `queryOptions` overload selected when `initialData` is set — `data` is never
+ * `undefined` (unless a `select` changes `TData` to include `undefined`).
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export type DefinedInitialDataOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = Omit<CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>, 'queryFn'> & {
+    /**
+     * If set, this value will be used as the initial data for the query cache (as long as the query hasn't been
+     * created or cached yet). If set to a function, the function will be called **once** during the shared/root
+     * query initialization, and be expected to synchronously return the initial data. Initial data is
+     * considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the
+     * cache.
+     */
     initialData: NonUndefinedGuard<TQueryFnData> | (() => NonUndefinedGuard<TQueryFnData>);
+    /**
+     * Optional here, but omitting it is only safe when no fetch will be attempted — for example with
+     * `enabled: false`, or when a default query function has been defined. Otherwise, an enabled query with no
+     * `queryFn` still tries to fetch and fails with a "Missing queryFn" error; `initialData` does not prevent this.
+     */
     queryFn?: QueryFunction<TQueryFnData, TQueryKey>;
 };
 /**
- * Allows sharing and re-using query options in a type-safe way.
+ * You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options
+ * can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is
+ * required and is the query key to generate options for.
  *
- * The `queryKey` will be tagged with the type from `queryFn`.
+ * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless
+ * a `select` changes `TData` to include `undefined`).
  *
- * **Example**
+ * @see {@link injectQuery} to run a query with these options.
+ * @see [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.
+ * @param options - The {@link DefinedInitialDataOptions} to use — everything you can pass to `injectQuery`,
+ * with `initialData` set.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
  *
- * ```ts
- *  const { queryKey } = queryOptions({
- *     queryKey: ['key'],
- *     queryFn: () => Promise.resolve(5),
- *     //  ^?  Promise<number>
- *   })
+ * @example
+ * ```angular-ts
+ * import { queryOptions, injectQuery } from '@tanstack/angular-query-experimental'
  *
- *   const queryClient = new QueryClient()
- *   const data = queryClient.getQueryData(queryKey)
- *   //    ^?  number | undefined
+ * export const postsOptions = queryOptions({
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
+ *   initialData: [],
+ * })
+ *
+ * @Component({
+ *   selector: 'posts',
+ *   template: `
+ *     <!-- `postsQuery.data()` is never `undefined`, thanks to `initialData` — even if a refetch
+ *     fails, so the list stays visible alongside the error. -->
+ *     @if (postsQuery.isError()) {
+ *       <span>Error: {{ postsQuery.error()?.message }}</span>
+ *     }
+ *     <ul>
+ *       @for (post of postsQuery.data(); track post.id) {
+ *         <li>{{ post.title }}</li>
+ *       }
+ *     </ul>
+ *   `,
+ * })
+ * export class Posts {
+ *   readonly postsQuery = injectQuery(() => postsOptions)
+ * }
  * ```
- * @param options - The query options to tag with the type from `queryFn`.
- * @returns The tagged query options.
  */
 export declare function queryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 /**
- * Allows sharing and re-using query options in a type-safe way.
+ * You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options
+ * can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is
+ * required and is the query key to generate options for.
  *
- * The `queryKey` will be tagged with the type from `queryFn`.
+ * @see {@link injectQuery} to run a query with these options.
+ * @see [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.
+ * @param options - The {@link UnusedSkipTokenOptions} to use — everything you can pass to `injectQuery`.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
  *
- * **Example**
+ * @example
+ * A parameterized factory, so the same options object can be reused per `id`:
+ * ```angular-ts
+ * import { queryOptions, injectQuery } from '@tanstack/angular-query-experimental'
  *
- * ```ts
- *  const { queryKey } = queryOptions({
- *     queryKey: ['key'],
- *     queryFn: () => Promise.resolve(5),
- *     //  ^?  Promise<number>
+ * export const postOptions = (id: string) =>
+ *   queryOptions({
+ *     queryKey: ['post', id],
+ *     queryFn: () => fetchPost(id),
  *   })
  *
- *   const queryClient = new QueryClient()
- *   const data = queryClient.getQueryData(queryKey)
- *   //    ^?  number | undefined
+ * @Component({
+ *   selector: 'post',
+ *   template: `
+ *     @if (postQuery.isPending()) {
+ *       Loading...
+ *     } @else if (postQuery.isError()) {
+ *       <span>Error: {{ postQuery.error()?.message }}</span>
+ *     } @else {
+ *       <h1>{{ postQuery.data().title }}</h1>
+ *     }
+ *   `,
+ * })
+ * export class Post {
+ *   readonly id = signal('1')
+ *   readonly postQuery = injectQuery(() => postOptions(this.id()))
+ * }
  * ```
- * @param options - The query options to tag with the type from `queryFn`.
- * @returns The tagged query options.
  */
 export declare function queryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey>): UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
 /**
- * Allows sharing and re-using query options in a type-safe way.
+ * You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options
+ * can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is
+ * required and is the query key to generate options for.
+ *
+ * @see {@link injectQuery} to run a query with these options.
+ * @see [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.
+ * @param options - The {@link UndefinedInitialDataOptions} to use — everything you can pass to `injectQuery`.
+ * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ * @remarks This is the only overload that accepts `queryFn: skipToken`, shown below.
  *
- * The `queryKey` will be tagged with the type from `queryFn`.
+ * @example
+ * A parameterized factory, so the same options object can be reused per `id`:
+ * ```angular-ts
+ * import { queryOptions, injectQuery } from '@tanstack/angular-query-experimental'
+ *
+ * export const postOptions = (id: string) =>
+ *   queryOptions({
+ *     queryKey: ['post', id],
+ *     queryFn: () => fetchPost(id),
+ *   })
+ *
+ * @Component({
+ *   selector: 'post',
+ *   template: `
+ *     @if (postQuery.isPending()) {
+ *       Loading...
+ *     } @else if (postQuery.isError()) {
+ *       <span>Error: {{ postQuery.error()?.message }}</span>
+ *     } @else {
+ *       <h1>{{ postQuery.data().title }}</h1>
+ *     }
+ *   `,
+ * })
+ * export class Post {
+ *   readonly id = signal('1')
+ *   readonly postQuery = injectQuery(() => postOptions(this.id()))
+ * }
+ * ```
  *
- * **Example**
+ * @example
+ * A factory that disables the query, type safe, until `postId` is set:
+ * ```angular-ts
+ * import { queryOptions, skipToken, injectQuery } from '@tanstack/angular-query-experimental'
  *
- * ```ts
- *  const { queryKey } = queryOptions({
- *     queryKey: ['key'],
- *     queryFn: () => Promise.resolve(5),
- *     //  ^?  Promise<number>
+ * export const postOptions = (postId: number | undefined) =>
+ *   queryOptions({
+ *     queryKey: ['post', postId],
+ *     queryFn: postId != null ? () => fetchPost(postId) : skipToken,
  *   })
  *
- *   const queryClient = new QueryClient()
- *   const data = queryClient.getQueryData(queryKey)
- *   //    ^?  number | undefined
+ * @Component({
+ *   selector: 'post',
+ *   template: `
+ *     @if (postId() == null) {
+ *       Select a post
+ *     } @else if (postQuery.isPending()) {
+ *       Loading...
+ *     } @else if (postQuery.isError()) {
+ *       <span>Error: {{ postQuery.error()?.message }}</span>
+ *     } @else {
+ *       <h1>{{ postQuery.data().title }}</h1>
+ *     }
+ *   `,
+ * })
+ * export class Post {
+ *   readonly postId = signal<number | undefined>(undefined)
+ *   readonly postQuery = injectQuery(() => postOptions(this.postId()))
+ * }
  * ```
- * @param options - The query options to tag with the type from `queryFn`.
- * @returns The tagged query options.
  */
 export declare function queryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>): UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;

package/query-options.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"query-options.mjs","sources":["../src/query-options.ts"],"sourcesContent":["import type {\n  DefaultError,\n  InitialDataFunction,\n  NonUndefinedGuard,\n  OmitKeyof,\n  QueryFunction,\n  QueryKey,\n  QueryKeyWithDataTag,\n  SkipToken,\n} from '@tanstack/query-core'\nimport type { CreateQueryOptions } from './types'\n\nexport type UndefinedInitialDataOptions<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n> = CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey> & {\n  initialData?:\n    | undefined\n    | InitialDataFunction<NonUndefinedGuard<TQueryFnData>>\n    | NonUndefinedGuard<TQueryFnData>\n}\n\nexport type UnusedSkipTokenOptions<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n> = OmitKeyof<\n  CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>,\n  'queryFn'\n> & {\n  queryFn?: Exclude<\n    CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>['queryFn'],\n    SkipToken | undefined\n  >\n}\n\nexport type DefinedInitialDataOptions<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n> = Omit<\n  CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>,\n  'queryFn'\n> & {\n  initialData:\n    | NonUndefinedGuard<TQueryFnData>\n    | (() => NonUndefinedGuard<TQueryFnData>)\n  queryFn?: QueryFunction<TQueryFnData, TQueryKey>\n}\n\n/**\n * Allows sharing and re-using query options in a type-safe way.\n *\n * The `queryKey` will be tagged with the type from `queryFn`.\n *\n * **Example**\n *\n * ```ts\n *  const { queryKey } = queryOptions({\n *     queryKey: ['key'],\n *     queryFn: () => Promise.resolve(5),\n *     //  ^?  Promise<number>\n *   })\n *\n *   const queryClient = new QueryClient()\n *   const data = queryClient.getQueryData(queryKey)\n *   //    ^?  number | undefined\n * ```\n * @param options - The query options to tag with the type from `queryFn`.\n * @returns The tagged query options.\n */\nexport function queryOptions<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n>(\n  options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,\n): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> &\n  QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>\n\n/**\n * Allows sharing and re-using query options in a type-safe way.\n *\n * The `queryKey` will be tagged with the type from `queryFn`.\n *\n * **Example**\n *\n * ```ts\n *  const { queryKey } = queryOptions({\n *     queryKey: ['key'],\n *     queryFn: () => Promise.resolve(5),\n *     //  ^?  Promise<number>\n *   })\n *\n *   const queryClient = new QueryClient()\n *   const data = queryClient.getQueryData(queryKey)\n *   //    ^?  number | undefined\n * ```\n * @param options - The query options to tag with the type from `queryFn`.\n * @returns The tagged query options.\n */\nexport function queryOptions<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n>(\n  options: UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey>,\n): UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey> &\n  QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>\n\n/**\n * Allows sharing and re-using query options in a type-safe way.\n *\n * The `queryKey` will be tagged with the type from `queryFn`.\n *\n * **Example**\n *\n * ```ts\n *  const { queryKey } = queryOptions({\n *     queryKey: ['key'],\n *     queryFn: () => Promise.resolve(5),\n *     //  ^?  Promise<number>\n *   })\n *\n *   const queryClient = new QueryClient()\n *   const data = queryClient.getQueryData(queryKey)\n *   //    ^?  number | undefined\n * ```\n * @param options - The query options to tag with the type from `queryFn`.\n * @returns The tagged query options.\n */\nexport function queryOptions<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n>(\n  options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,\n): UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> &\n  QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>\n\n/**\n * Allows sharing and re-using query options in a type-safe way.\n *\n * The `queryKey` will be tagged with the type from `queryFn`.\n *\n * **Example**\n *\n * ```ts\n *  const { queryKey } = queryOptions({\n *     queryKey: ['key'],\n *     queryFn: () => Promise.resolve(5),\n *     //  ^?  Promise<number>\n *   })\n *\n *   const queryClient = new QueryClient()\n *   const data = queryClient.getQueryData(queryKey)\n *   //    ^?  number | undefined\n * ```\n * @param options - The query options to tag with the type from `queryFn`.\n * @returns The tagged query options.\n */\nexport function queryOptions(options: unknown) {\n  return options\n}\n"],"names":[],"mappings":"AAwKO,SAAS,aAAa,SAAkB;AAC7C,SAAO;AACT;"}
+{"version":3,"file":"query-options.mjs","sources":["../src/query-options.ts"],"sourcesContent":["import type {\n  DefaultError,\n  InitialDataFunction,\n  NonUndefinedGuard,\n  OmitKeyof,\n  QueryFunction,\n  QueryKey,\n  QueryKeyWithDataTag,\n  SkipToken,\n} from '@tanstack/query-core'\nimport type { CreateQueryOptions } from './types'\n\n/**\n * The options accepted by the `queryOptions` overload selected when no `initialData` is set — `data` may be\n * `undefined` while the query is `pending`.\n *\n * @template TQueryFnData - The type your `queryFn` resolves to.\n * @template TError - The type of errors your `queryFn` may throw.\n * @template TData - The type `data` ends up as after `select` runs.\n * @template TQueryKey - The type of your `queryKey`.\n */\nexport type UndefinedInitialDataOptions<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n> = CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey> & {\n  /**\n   * If set, this value will be used as the initial data for the query cache (as long as the query hasn't been\n   * created or cached yet). If set to a function, the function will be called **once** during the shared/root\n   * query initialization, and be expected to synchronously return the initial data. Initial data is\n   * considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the\n   * cache.\n   */\n  initialData?:\n    | undefined\n    | InitialDataFunction<NonUndefinedGuard<TQueryFnData>>\n    | NonUndefinedGuard<TQueryFnData>\n}\n\n/**\n * The options accepted by the `queryOptions` overload selected when no `initialData` is set and `queryFn` is\n * not `skipToken` — same as {@link UndefinedInitialDataOptions}, but `queryFn` may not be `skipToken`.\n *\n * @template TQueryFnData - The type your `queryFn` resolves to.\n * @template TError - The type of errors your `queryFn` may throw.\n * @template TData - The type `data` ends up as after `select` runs.\n * @template TQueryKey - The type of your `queryKey`.\n */\nexport type UnusedSkipTokenOptions<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n> = OmitKeyof<\n  CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>,\n  'queryFn'\n> & {\n  /**\n   * `skipToken` is not allowed as a value here — this overload is selected when no `initialData` is set. If\n   * you don't intend to run the query yet, set `enabled: false` — omitting `queryFn` alone still triggers a\n   * fetch that fails with \"Missing queryFn\" unless `enabled` is `false` or a default query function has been\n   * defined. A default query function only supplies `queryFn`; it doesn't defer the fetch on its own.\n   */\n  queryFn?: Exclude<\n    CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>['queryFn'],\n    SkipToken | undefined\n  >\n}\n\n/**\n * The options accepted by the `queryOptions` overload selected when `initialData` is set — `data` is never\n * `undefined` (unless a `select` changes `TData` to include `undefined`).\n *\n * @template TQueryFnData - The type your `queryFn` resolves to.\n * @template TError - The type of errors your `queryFn` may throw.\n * @template TData - The type `data` ends up as after `select` runs.\n * @template TQueryKey - The type of your `queryKey`.\n */\nexport type DefinedInitialDataOptions<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n> = Omit<\n  CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>,\n  'queryFn'\n> & {\n  /**\n   * If set, this value will be used as the initial data for the query cache (as long as the query hasn't been\n   * created or cached yet). If set to a function, the function will be called **once** during the shared/root\n   * query initialization, and be expected to synchronously return the initial data. Initial data is\n   * considered stale by default unless a `staleTime` has been set. `initialData` **is persisted** to the\n   * cache.\n   */\n  initialData:\n    | NonUndefinedGuard<TQueryFnData>\n    | (() => NonUndefinedGuard<TQueryFnData>)\n  /**\n   * Optional here, but omitting it is only safe when no fetch will be attempted — for example with\n   * `enabled: false`, or when a default query function has been defined. Otherwise, an enabled query with no\n   * `queryFn` still tries to fetch and fails with a \"Missing queryFn\" error; `initialData` does not prevent this.\n   */\n  queryFn?: QueryFunction<TQueryFnData, TQueryKey>\n}\n\n/**\n * You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options\n * can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is\n * required and is the query key to generate options for.\n *\n * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined` (unless\n * a `select` changes `TData` to include `undefined`).\n *\n * @see {@link injectQuery} to run a query with these options.\n * @see [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.\n * @param options - The {@link DefinedInitialDataOptions} to use — everything you can pass to `injectQuery`,\n * with `initialData` set.\n * @returns The same options object, typed so that `queryKey` carries the inferred data type.\n *\n * @example\n * ```angular-ts\n * import { queryOptions, injectQuery } from '@tanstack/angular-query-experimental'\n *\n * export const postsOptions = queryOptions({\n *   queryKey: ['posts'],\n *   queryFn: fetchPosts,\n *   initialData: [],\n * })\n *\n * @Component({\n *   selector: 'posts',\n *   template: `\n *     <!-- `postsQuery.data()` is never `undefined`, thanks to `initialData` — even if a refetch\n *     fails, so the list stays visible alongside the error. -->\n *     @if (postsQuery.isError()) {\n *       <span>Error: {{ postsQuery.error()?.message }}</span>\n *     }\n *     <ul>\n *       @for (post of postsQuery.data(); track post.id) {\n *         <li>{{ post.title }}</li>\n *       }\n *     </ul>\n *   `,\n * })\n * export class Posts {\n *   readonly postsQuery = injectQuery(() => postsOptions)\n * }\n * ```\n */\nexport function queryOptions<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n>(\n  options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,\n): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> &\n  QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>\n\n/**\n * You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options\n * can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is\n * required and is the query key to generate options for.\n *\n * @see {@link injectQuery} to run a query with these options.\n * @see [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.\n * @param options - The {@link UnusedSkipTokenOptions} to use — everything you can pass to `injectQuery`.\n * @returns The same options object, typed so that `queryKey` carries the inferred data type.\n *\n * @example\n * A parameterized factory, so the same options object can be reused per `id`:\n * ```angular-ts\n * import { queryOptions, injectQuery } from '@tanstack/angular-query-experimental'\n *\n * export const postOptions = (id: string) =>\n *   queryOptions({\n *     queryKey: ['post', id],\n *     queryFn: () => fetchPost(id),\n *   })\n *\n * @Component({\n *   selector: 'post',\n *   template: `\n *     @if (postQuery.isPending()) {\n *       Loading...\n *     } @else if (postQuery.isError()) {\n *       <span>Error: {{ postQuery.error()?.message }}</span>\n *     } @else {\n *       <h1>{{ postQuery.data().title }}</h1>\n *     }\n *   `,\n * })\n * export class Post {\n *   readonly id = signal('1')\n *   readonly postQuery = injectQuery(() => postOptions(this.id()))\n * }\n * ```\n */\nexport function queryOptions<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n>(\n  options: UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey>,\n): UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey> &\n  QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>\n\n/**\n * You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options\n * can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is\n * required and is the query key to generate options for.\n *\n * @see {@link injectQuery} to run a query with these options.\n * @see [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.\n * @param options - The {@link UndefinedInitialDataOptions} to use — everything you can pass to `injectQuery`.\n * @returns The same options object, typed so that `queryKey` carries the inferred data type.\n * @remarks This is the only overload that accepts `queryFn: skipToken`, shown below.\n *\n * @example\n * A parameterized factory, so the same options object can be reused per `id`:\n * ```angular-ts\n * import { queryOptions, injectQuery } from '@tanstack/angular-query-experimental'\n *\n * export const postOptions = (id: string) =>\n *   queryOptions({\n *     queryKey: ['post', id],\n *     queryFn: () => fetchPost(id),\n *   })\n *\n * @Component({\n *   selector: 'post',\n *   template: `\n *     @if (postQuery.isPending()) {\n *       Loading...\n *     } @else if (postQuery.isError()) {\n *       <span>Error: {{ postQuery.error()?.message }}</span>\n *     } @else {\n *       <h1>{{ postQuery.data().title }}</h1>\n *     }\n *   `,\n * })\n * export class Post {\n *   readonly id = signal('1')\n *   readonly postQuery = injectQuery(() => postOptions(this.id()))\n * }\n * ```\n *\n * @example\n * A factory that disables the query, type safe, until `postId` is set:\n * ```angular-ts\n * import { queryOptions, skipToken, injectQuery } from '@tanstack/angular-query-experimental'\n *\n * export const postOptions = (postId: number | undefined) =>\n *   queryOptions({\n *     queryKey: ['post', postId],\n *     queryFn: postId != null ? () => fetchPost(postId) : skipToken,\n *   })\n *\n * @Component({\n *   selector: 'post',\n *   template: `\n *     @if (postId() == null) {\n *       Select a post\n *     } @else if (postQuery.isPending()) {\n *       Loading...\n *     } @else if (postQuery.isError()) {\n *       <span>Error: {{ postQuery.error()?.message }}</span>\n *     } @else {\n *       <h1>{{ postQuery.data().title }}</h1>\n *     }\n *   `,\n * })\n * export class Post {\n *   readonly postId = signal<number | undefined>(undefined)\n *   readonly postQuery = injectQuery(() => postOptions(this.postId()))\n * }\n * ```\n */\nexport function queryOptions<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n>(\n  options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,\n): UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> &\n  QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>\n\nexport function queryOptions(options: unknown) {\n  return options\n}\n"],"names":[],"mappings":"AAkSO,SAAS,aAAa,SAAkB;AAC7C,SAAO;AACT;"}

package/types.d.ts

@@ -1,43 +1,199 @@
 import { DefaultError, DefinedInfiniteQueryObserverResult, DefinedQueryObserverResult, InfiniteQueryObserverOptions, InfiniteQueryObserverResult, MutateFunction, MutationObserverOptions, MutationObserverResult, OmitKeyof, Override, QueryKey, QueryObserverOptions, QueryObserverResult } from '@tanstack/query-core';
 import { Signal } from '@angular/core';
 import { MapToSignals } from './signal-proxy.js';
+/**
+ * The options shared across `angular-query-experimental`'s query functions. Extends
+ * {@link QueryObserverOptions} from `@tanstack/query-core` as-is — unlike `react-query`,
+ * `angular-query-experimental` has no extra framework-specific option here.
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
+ * `select` is used.
+ * @template TQueryData - The type of the data actually held in the query cache — the input to `select` and
+ * `placeholderData`. Defaults to, and is usually the same as, `TQueryFnData`.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export interface CreateBaseQueryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> extends QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey> {
 }
+/**
+ * The options accepted by `injectQuery`. Same as {@link CreateBaseQueryOptions}, minus `suspense` — which
+ * `angular-query-experimental` doesn't support, unlike `react-query`.
+ *
+ * @template TQueryFnData - The type your `queryFn` resolves to.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` when no
+ * `select` is used.
+ * @template TQueryKey - The type of your `queryKey`.
+ */
 export interface CreateQueryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> extends OmitKeyof<CreateBaseQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>, 'suspense'> {
 }
 type CreateStatusBasedQueryResult<TStatus extends QueryObserverResult['status'], TData = unknown, TError = DefaultError> = Extract<QueryObserverResult<TData, TError>, {
     status: TStatus;
 }>;
+/**
+ * The `isSuccess`/`isError`/`isPending` methods on a query result. Unlike `react-query`'s derived booleans,
+ * these are type-guard methods you call — `if (query.isSuccess())` — so that `query.data` narrows away
+ * `undefined` inside the branch, the same way `status` narrowing works on the plain object `react-query`
+ * returns.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export interface BaseQueryNarrowing<TData = unknown, TError = DefaultError> {
     isSuccess: (this: CreateBaseQueryResult<TData, TError>) => this is CreateBaseQueryResult<TData, TError, CreateStatusBasedQueryResult<'success', TData, TError>>;
     isError: (this: CreateBaseQueryResult<TData, TError>) => this is CreateBaseQueryResult<TData, TError, CreateStatusBasedQueryResult<'error', TData, TError>>;
     isPending: (this: CreateBaseQueryResult<TData, TError>) => this is CreateBaseQueryResult<TData, TError, CreateStatusBasedQueryResult<'pending', TData, TError>>;
 }
+/**
+ * The options accepted by `injectInfiniteQuery`. Same as {@link CreateBaseQueryOptions}, minus `suspense` —
+ * which `angular-query-experimental` doesn't support, unlike `react-query` — extends
+ * {@link InfiniteQueryObserverOptions} from `@tanstack/query-core` for the infinite-query-specific options
+ * (`getNextPageParam`, `initialPageParam`, etc.).
+ *
+ * @template TQueryFnData - The type of a single page, as your `queryFn` resolves it.
+ * @template TError - The type of errors your `queryFn` may throw.
+ * @template TData - The type `data` ends up as after `select` runs. Defaults to `TQueryFnData` here, though
+ * `injectInfiniteQuery` itself defaults it to `InfiniteData<TQueryFnData>` — the shape `data` actually has
+ * when no `select` is used.
+ * @template TQueryKey - The type of your `queryKey`.
+ * @template TPageParam - The type of the parameter passed to `queryFn` to fetch a given page.
+ */
 export interface CreateInfiniteQueryOptions<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TPageParam = unknown> extends OmitKeyof<InfiniteQueryObserverOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, 'suspense'> {
 }
+/**
+ * The result of `injectQuery` when `initialData` isn't set — `data` may be `undefined` while the query is
+ * `pending`. Same shape as {@link QueryObserverResult} from `@tanstack/query-core`, but value fields (like
+ * `data`, `error`, `status`) are exposed as a `Signal` — read them with `query.data()`, not `query.data` —
+ * while function fields (like `refetch`) are called directly, unchanged. `isSuccess`/`isError`/`isPending`
+ * are {@link BaseQueryNarrowing} type-guard methods rather than plain booleans.
+ * `injectInfiniteQuery` returns {@link CreateInfiniteQueryResult} instead.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type CreateBaseQueryResult<TData = unknown, TError = DefaultError, TState = QueryObserverResult<TData, TError>> = BaseQueryNarrowing<TData, TError> & MapToSignals<OmitKeyof<TState, keyof BaseQueryNarrowing, 'safely'>>;
+/**
+ * The result of `injectQuery`. Same as {@link CreateBaseQueryResult}.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type CreateQueryResult<TData = unknown, TError = DefaultError> = CreateBaseQueryResult<TData, TError>;
+/**
+ * The result of `injectQuery` when `initialData` is set — `data` is never `undefined`. Same shape as
+ * {@link DefinedQueryObserverResult} from `@tanstack/query-core`, but value fields are exposed as a
+ * `Signal` while function fields are called directly, unchanged.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type DefinedCreateQueryResult<TData = unknown, TError = DefaultError, TState = DefinedQueryObserverResult<TData, TError>> = BaseQueryNarrowing<TData, TError> & MapToSignals<OmitKeyof<TState, keyof BaseQueryNarrowing, 'safely'>>;
+/**
+ * The result of `injectInfiniteQuery` when `initialData` isn't set — `data` may be `undefined` while the
+ * query is `pending`. Same shape as {@link InfiniteQueryObserverResult} from `@tanstack/query-core`, but
+ * value fields are exposed as a `Signal` while function fields (like `fetchNextPage`) are called directly,
+ * unchanged.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type CreateInfiniteQueryResult<TData = unknown, TError = DefaultError> = BaseQueryNarrowing<TData, TError> & MapToSignals<InfiniteQueryObserverResult<TData, TError>>;
+/**
+ * The result of `injectInfiniteQuery` when `initialData` is set — `data` is never `undefined`. Same shape as
+ * {@link DefinedInfiniteQueryObserverResult} from `@tanstack/query-core`, but value fields are exposed as a
+ * `Signal` while function fields are called directly, unchanged.
+ *
+ * @template TData - The type `data` ends up as after `select` runs.
+ * @template TError - The type of errors your `queryFn` may throw.
+ */
 export type DefinedCreateInfiniteQueryResult<TData = unknown, TError = DefaultError, TDefinedInfiniteQueryObserver = DefinedInfiniteQueryObserverResult<TData, TError>> = MapToSignals<TDefinedInfiniteQueryObserver>;
+/**
+ * The options accepted by `injectMutation`. Same as {@link MutationObserverOptions} from
+ * `@tanstack/query-core`, minus the internal `_defaulted` flag.
+ *
+ * @template TData - The type your mutation function resolves to.
+ * @template TError - The type of errors your mutation function may throw.
+ * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 export interface CreateMutationOptions<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> extends OmitKeyof<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>, '_defaulted'> {
 }
+/**
+ * The type of `mutate`, as returned by `injectMutation`. Forwards the variables (and an optional per-call
+ * `onSuccess`/`onError`/`onSettled`) to the underlying `mutate` call. Fire-and-forget — errors are surfaced
+ * through the mutation result, not thrown.
+ *
+ * @template TData - The type your mutation function resolves to.
+ * @template TError - The type of errors your mutation function may throw.
+ * @template TVariables - The type of the variable passed to `mutate`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 export type CreateMutateFunction<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> = (...args: Parameters<MutateFunction<TData, TError, TVariables, TOnMutateResult>>) => void;
+/**
+ * The type of `mutateAsync`, as returned by `injectMutation`. Similar to {@link CreateMutateFunction}, but
+ * returns a promise which can be awaited.
+ *
+ * @template TData - The type your mutation function resolves to.
+ * @template TError - The type of errors your mutation function may throw.
+ * @template TVariables - The type of the variable passed to `mutateAsync`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 export type CreateMutateAsyncFunction<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown> = MutateFunction<TData, TError, TVariables, TOnMutateResult>;
+/**
+ * The pre-`Signal` shape {@link CreateMutationResult} is built from — not what `injectMutation` actually
+ * returns. Same as {@link MutationObserverResult} from `@tanstack/query-core`, with `mutate` narrowed to the
+ * fire-and-forget {@link CreateMutateFunction} signature, plus the added `mutateAsync`.
+ *
+ * @template TData - The type your mutation function resolves to.
+ * @template TError - The type of errors your mutation function may throw.
+ * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 export type CreateBaseMutationResult<TData = unknown, TError = DefaultError, TVariables = unknown, TOnMutateResult = unknown> = Override<MutationObserverResult<TData, TError, TVariables, TOnMutateResult>, {
     mutate: CreateMutateFunction<TData, TError, TVariables, TOnMutateResult>;
 }> & {
+    /**
+     * Similar to `mutate`, but returns a promise which can be awaited.
+     */
     mutateAsync: CreateMutateAsyncFunction<TData, TError, TVariables, TOnMutateResult>;
 };
 type CreateStatusBasedMutationResult<TStatus extends CreateBaseMutationResult['status'], TData = unknown, TError = DefaultError, TVariables = unknown, TOnMutateResult = unknown> = Extract<CreateBaseMutationResult<TData, TError, TVariables, TOnMutateResult>, {
     status: TStatus;
 }>;
 type SignalFunction<T extends () => any> = T & Signal<ReturnType<T>>;
+/**
+ * The `isSuccess`/`isError`/`isPending`/`isIdle` methods on a mutation result. Each is both a `Signal`
+ * (its current boolean value is read reactively without calling it) and a type-guard function you can
+ * call — `if (mutation.isSuccess())` — so that `mutation.data` narrows away `undefined` inside the branch.
+ *
+ * @template TData - The type your mutation function resolves to.
+ * @template TError - The type of errors your mutation function may throw.
+ * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 export interface BaseMutationNarrowing<TData = unknown, TError = DefaultError, TVariables = unknown, TOnMutateResult = unknown> {
     isSuccess: SignalFunction<(this: CreateMutationResult<TData, TError, TVariables, TOnMutateResult>) => this is CreateMutationResult<TData, TError, TVariables, TOnMutateResult, CreateStatusBasedMutationResult<'success', TData, TError, TVariables, TOnMutateResult>>>;
     isError: SignalFunction<(this: CreateMutationResult<TData, TError, TVariables, TOnMutateResult>) => this is CreateMutationResult<TData, TError, TVariables, TOnMutateResult, CreateStatusBasedMutationResult<'error', TData, TError, TVariables, TOnMutateResult>>>;
     isPending: SignalFunction<(this: CreateMutationResult<TData, TError, TVariables, TOnMutateResult>) => this is CreateMutationResult<TData, TError, TVariables, TOnMutateResult, CreateStatusBasedMutationResult<'pending', TData, TError, TVariables, TOnMutateResult>>>;
     isIdle: SignalFunction<(this: CreateMutationResult<TData, TError, TVariables, TOnMutateResult>) => this is CreateMutationResult<TData, TError, TVariables, TOnMutateResult, CreateStatusBasedMutationResult<'idle', TData, TError, TVariables, TOnMutateResult>>>;
 }
+/**
+ * The result of `injectMutation`. Based on {@link CreateBaseMutationResult}, but value fields are exposed as
+ * a `Signal` — read them with `mutation.data()`, not `mutation.data` — while function fields (`mutate`,
+ * `mutateAsync`, `reset`) are called directly, unchanged. `isSuccess`/`isError`/`isPending`/`isIdle` are
+ * {@link BaseMutationNarrowing} type-guard methods rather than plain booleans.
+ *
+ * @template TData - The type your mutation function resolves to.
+ * @template TError - The type of errors your mutation function may throw.
+ * @template TVariables - The type of the variable passed to `mutate`/`mutateAsync`.
+ * @template TOnMutateResult - The type returned by `onMutate`, passed to `onSuccess`/`onError`/`onSettled` as
+ * their `onMutateResult` parameter — useful for optimistic-update rollback data.
+ */
 export type CreateMutationResult<TData = unknown, TError = DefaultError, TVariables = unknown, TOnMutateResult = unknown, TState = CreateStatusBasedMutationResult<CreateBaseMutationResult['status'], TData, TError, TVariables, TOnMutateResult>> = BaseMutationNarrowing<TData, TError, TVariables, TOnMutateResult> & MapToSignals<OmitKeyof<TState, keyof BaseMutationNarrowing, 'safely'>>;
 export {};