docs(angular-query): add jsdoc (#7379)

arnoud-dv · web-flow · commit 32d1e8226228 · 2024-05-04T22:11:36.000+02:00
* fix: remove unused export
diff --git a/examples/angular/basic/src/app/app.config.ts b/examples/angular/basic/src/app/app.config.ts
@@ -1,9 +1,9 @@
 import { provideHttpClient, withFetch } from '@angular/common/http'
-import { ApplicationConfig } from '@angular/core'
 import {
   QueryClient,
   provideAngularQuery,
 } from '@tanstack/angular-query-experimental'
+import type { ApplicationConfig } from '@angular/core'
 
 export const appConfig: ApplicationConfig = {
   providers: [
diff --git a/packages/angular-query-devtools-experimental/src/angular-query-devtools.component.ts b/packages/angular-query-devtools-experimental/src/angular-query-devtools.component.ts
@@ -39,7 +39,9 @@ export class AngularQueryDevtools
   /*
    * It is intentional that there are no default values on inputs.
    * Core devtools will set defaults when values are undefined.
-   * */
+   *
+   * Signal inputs are not used to remain compatible with previous Angular versions.
+   */
 
   /**
    * Add this attribute if you want the dev tools to default to being open
diff --git a/packages/angular-query-experimental/src/__tests__/inject-mutation-state.test.ts b/packages/angular-query-experimental/src/__tests__/inject-mutation-state.test.ts
@@ -3,7 +3,6 @@ import { QueryClient } from '@tanstack/query-core'
 import { TestBed } from '@angular/core/testing'
 import { describe, expect, test, vi } from 'vitest'
 import { By } from '@angular/platform-browser'
-import { JsonPipe } from '@angular/common'
 import { injectMutation } from '../inject-mutation'
 import { injectMutationState } from '../inject-mutation-state'
 import { provideAngularQuery } from '../providers'
@@ -139,7 +138,6 @@ describe('injectMutationState', () => {
           }
         `,
         standalone: true,
-        imports: [JsonPipe],
       })
       class FakeComponent {
         name = input.required<string>()
diff --git a/packages/angular-query-experimental/src/create-base-query.ts b/packages/angular-query-experimental/src/create-base-query.ts
@@ -31,7 +31,7 @@ export function createBaseQuery<
   TQueryData,
   TQueryKey extends QueryKey,
 >(
-  options: (
+  optionsFn: (
     client: QueryClient,
   ) => CreateBaseQueryOptions<
     TQueryFnData,
@@ -57,7 +57,7 @@ export function createBaseQuery<
        */
       const defaultedOptionsSignal = computed(() => {
         const defaultedOptions = queryClient.defaultQueryOptions(
-          options(queryClient),
+          optionsFn(queryClient),
         )
         defaultedOptions._optimisticResults = 'optimistic'
         return defaultedOptions
diff --git a/packages/angular-query-experimental/src/index.ts b/packages/angular-query-experimental/src/index.ts
@@ -20,9 +20,5 @@ export * from './inject-mutation'
 export * from './inject-mutation-state'
 export * from './inject-queries'
 export * from './inject-query'
-export {
-  injectQueryClient,
-  provideQueryClient,
-  QUERY_CLIENT,
-} from './inject-query-client'
+export { injectQueryClient, provideQueryClient } from './inject-query-client'
 export { provideAngularQuery } from './providers'
diff --git a/packages/angular-query-experimental/src/infinite-query-options.ts b/packages/angular-query-experimental/src/infinite-query-options.ts
@@ -41,6 +41,14 @@ export type DefinedInitialDataInfiniteOptions<
     | (() => NonUndefinedGuard<InfiniteData<TQueryFnData, TPageParam>>)
 }
 
+/**
+ * Allows to share and re-use infinite query options in a type-safe way.
+ *
+ * The `queryKey` will be tagged with the type from `queryFn`.
+ * @param options - The infinite query options to tag with the type from `queryFn`.
+ * @returns The tagged infinite query options.
+ * @public
+ */
 export function infiniteQueryOptions<
   TQueryFnData,
   TError = DefaultError,
@@ -65,6 +73,14 @@ export function infiniteQueryOptions<
   queryKey: DataTag<TQueryKey, InfiniteData<TQueryFnData>>
 }
 
+/**
+ * Allows to share and re-use infinite query options in a type-safe way.
+ *
+ * The `queryKey` will be tagged with the type from `queryFn`.
+ * @param options - The infinite query options to tag with the type from `queryFn`.
+ * @returns The tagged infinite query options.
+ * @public
+ */
 export function infiniteQueryOptions<
   TQueryFnData,
   TError = DefaultError,
@@ -89,6 +105,14 @@ export function infiniteQueryOptions<
   queryKey: DataTag<TQueryKey, InfiniteData<TQueryFnData>>
 }
 
+/**
+ * Allows to share and re-use infinite query options in a type-safe way.
+ *
+ * The `queryKey` will be tagged with the type from `queryFn`.
+ * @param options - The infinite query options to tag with the type from `queryFn`.
+ * @returns The tagged infinite query options.
+ * @public
+ */
 export function infiniteQueryOptions(options: unknown) {
   return options
 }
diff --git a/packages/angular-query-experimental/src/inject-infinite-query.ts b/packages/angular-query-experimental/src/inject-infinite-query.ts
@@ -20,14 +20,22 @@ import type {
   UndefinedInitialDataInfiniteOptions,
 } from './infinite-query-options'
 
+/**
+ * Injects an infinite query: a declarative dependency on an asynchronous source of data that is tied to a unique key.
+ * Infinite queries can additively "load more" data onto an existing set of data or "infinite scroll"
+ * @param optionsFn - A function that returns infinite query options.
+ * @param injector - The Angular injector to use.
+ * @returns The infinite query result.
+ * @public
+ */
 export function injectInfiniteQuery<
   TQueryFnData,
   TError = DefaultError,
   TData = InfiniteData<TQueryFnData>,
   TQueryKey extends QueryKey = QueryKey,
   TPageParam = unknown,
 >(
-  options: (
+  optionsFn: (
     client: QueryClient,
   ) => UndefinedInitialDataInfiniteOptions<
     TQueryFnData,
@@ -39,14 +47,22 @@ export function injectInfiniteQuery<
   injector?: Injector,
 ): CreateInfiniteQueryResult<TData, TError>
 
+/**
+ * Injects an infinite query: a declarative dependency on an asynchronous source of data that is tied to a unique key.
+ * Infinite queries can additively "load more" data onto an existing set of data or "infinite scroll"
+ * @param optionsFn - A function that returns infinite query options.
+ * @param injector - The Angular injector to use.
+ * @returns The infinite query result.
+ * @public
+ */
 export function injectInfiniteQuery<
   TQueryFnData,
   TError = DefaultError,
   TData = InfiniteData<TQueryFnData>,
   TQueryKey extends QueryKey = QueryKey,
   TPageParam = unknown,
 >(
-  options: (
+  optionsFn: (
     client: QueryClient,
   ) => DefinedInitialDataInfiniteOptions<
     TQueryFnData,
@@ -58,14 +74,22 @@ export function injectInfiniteQuery<
   injector?: Injector,
 ): DefinedCreateInfiniteQueryResult<TData, TError>
 
+/**
+ * Injects an infinite query: a declarative dependency on an asynchronous source of data that is tied to a unique key.
+ * Infinite queries can additively "load more" data onto an existing set of data or "infinite scroll"
+ * @param optionsFn - A function that returns infinite query options.
+ * @param injector - The Angular injector to use.
+ * @returns The infinite query result.
+ * @public
+ */
 export function injectInfiniteQuery<
   TQueryFnData,
   TError = DefaultError,
   TData = InfiniteData<TQueryFnData>,
   TQueryKey extends QueryKey = QueryKey,
   TPageParam = unknown,
 >(
-  options: (
+  optionsFn: (
     client: QueryClient,
   ) => CreateInfiniteQueryOptions<
     TQueryFnData,
@@ -78,14 +102,22 @@ export function injectInfiniteQuery<
   injector?: Injector,
 ): CreateInfiniteQueryResult<TData, TError>
 
+/**
+ * Injects an infinite query: a declarative dependency on an asynchronous source of data that is tied to a unique key.
+ * Infinite queries can additively "load more" data onto an existing set of data or "infinite scroll"
+ * @param optionsFn - A function that returns infinite query options.
+ * @param injector - The Angular injector to use.
+ * @returns The infinite query result.
+ * @public
+ */
 export function injectInfiniteQuery(
-  options: (client: QueryClient) => CreateInfiniteQueryOptions,
+  optionsFn: (client: QueryClient) => CreateInfiniteQueryOptions,
   injector?: Injector,
 ) {
   return assertInjector(injectInfiniteQuery, injector, () => {
     const queryClient = injectQueryClient()
     return createBaseQuery(
-      options,
+      optionsFn,
       InfiniteQueryObserver as typeof QueryObserver,
       queryClient,
     )
diff --git a/packages/angular-query-experimental/src/inject-is-fetching.ts b/packages/angular-query-experimental/src/inject-is-fetching.ts
@@ -4,6 +4,16 @@ import { assertInjector } from './util/assert-injector/assert-injector'
 import { injectQueryClient } from './inject-query-client'
 import type { Injector, Signal } from '@angular/core'
 
+/**
+ * Injects a signal that tracks the number of queries that your application is loading or
+ * fetching in the background.
+ *
+ * Can be used for app-wide loading indicators
+ * @param filters - The filters to apply to the query.
+ * @param injector - The Angular injector to use.
+ * @returns signal with number of loading or fetching queries.
+ * @public
+ */
 export function injectIsFetching(
   filters?: QueryFilters,
   injector?: Injector,
diff --git a/packages/angular-query-experimental/src/inject-is-mutating.ts b/packages/angular-query-experimental/src/inject-is-mutating.ts
@@ -4,6 +4,15 @@ import { assertInjector } from './util/assert-injector/assert-injector'
 import { injectQueryClient } from './inject-query-client'
 import type { Injector, Signal } from '@angular/core'
 
+/**
+ * Injects a signal that tracks the number of mutations that your application is fetching.
+ *
+ * Can be used for app-wide loading indicators
+ * @param filters - The filters to apply to the query.
+ * @param injector - The Angular injector to use.
+ * @returns signal with number of fetching mutations.
+ * @public
+ */
 export function injectIsMutating(
   filters?: MutationFilters,
   injector?: Injector,
diff --git a/packages/angular-query-experimental/src/inject-mutation-state.ts b/packages/angular-query-experimental/src/inject-mutation-state.ts
@@ -43,10 +43,20 @@ function getResult<TResult = MutationState>(
     )
 }
 
+/**
+ * @public
+ */
 export interface InjectMutationStateOptions {
   injector?: Injector
 }
 
+/**
+ * Injects a signal that tracks the state of all mutations.
+ * @param mutationStateOptionsFn - A function that returns mutation state options.
+ * @param options - The Angular injector to use.
+ * @returns The signal that tracks the state of all mutations.
+ * @public
+ */
 export function injectMutationState<TResult = MutationState>(
   mutationStateOptionsFn: () => MutationStateOptions<TResult> = () => ({}),
   options?: InjectMutationStateOptions,
diff --git a/packages/angular-query-experimental/src/inject-mutation.ts b/packages/angular-query-experimental/src/inject-mutation.ts
@@ -26,13 +26,22 @@ import type {
   CreateMutationResult,
 } from './types'
 
+/**
+ * Injects a mutation: an imperative function that can be invoked which typically performs server side effects.
+ *
+ * Unlike queries, mutations are not run automatically.
+ * @param optionsFn - A function that returns mutation options.
+ * @param injector - The Angular injector to use.
+ * @returns The mutation.
+ * @public
+ */
 export function injectMutation<
   TData = unknown,
   TError = DefaultError,
   TVariables = void,
   TContext = unknown,
 >(
-  options: (
+  optionsFn: (
     client: QueryClient,
   ) => CreateMutationOptions<TData, TError, TVariables, TContext>,
   injector?: Injector,
@@ -50,7 +59,7 @@ export function injectMutation<
           TError,
           TVariables,
           TContext
-        >(queryClient, options(queryClient))
+        >(queryClient, optionsFn(queryClient))
         const mutate: CreateMutateFunction<
           TData,
           TError,
@@ -61,7 +70,7 @@ export function injectMutation<
         }
 
         effect(() => {
-          observer.setOptions(options(queryClient))
+          observer.setOptions(optionsFn(queryClient))
         })
 
         const result = signal(observer.getCurrentResult())
diff --git a/packages/angular-query-experimental/src/inject-queries.ts b/packages/angular-query-experimental/src/inject-queries.ts
@@ -119,6 +119,7 @@ type GetResults<T> =
 
 /**
  * QueriesOptions reducer recursively unwraps function arguments to infer/enforce type param
+ * @public
  */
 export type QueriesOptions<
   T extends Array<any>,
@@ -161,6 +162,7 @@ export type QueriesOptions<
 
 /**
  * QueriesResults reducer recursively maps type param to results
+ * @public
  */
 export type QueriesResults<
   T extends Array<any>,
@@ -196,6 +198,9 @@ export type QueriesResults<
           : // Fallback
             Array<QueryObserverResult>
 
+/**
+ * @public
+ */
 export function injectQueries<
   T extends Array<any>,
   TCombinedResult = QueriesResults<T>,
diff --git a/packages/angular-query-experimental/src/inject-query-client.ts b/packages/angular-query-experimental/src/inject-query-client.ts
@@ -1,7 +1,25 @@
 import { createNoopInjectionToken } from './util/create-injection-token/create-injection-token'
 import type { QueryClient } from '@tanstack/query-core'
 
-const [injectQueryClient, provideQueryClient, QUERY_CLIENT] =
-  createNoopInjectionToken<QueryClient>('QueryClientToken')
+const tokens = createNoopInjectionToken<QueryClient>('QueryClientToken')
 
-export { injectQueryClient, provideQueryClient, QUERY_CLIENT }
+/**
+ * Injects the `QueryClient` instance into the component or service.
+ *
+ * **Example**
+ * ```ts
+ * const queryClient = injectQueryClient();
+ * ```
+ * @returns The `QueryClient` instance.
+ * @public
+ */
+export const injectQueryClient = tokens[0]
+
+/**
+ * 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 const provideQueryClient = tokens[1]
diff --git a/packages/angular-query-experimental/src/inject-query.ts b/packages/angular-query-experimental/src/inject-query.ts
diff --git a/packages/angular-query-experimental/src/providers.ts b/packages/angular-query-experimental/src/providers.ts
diff --git a/packages/angular-query-experimental/src/query-options.ts b/packages/angular-query-experimental/src/query-options.ts
diff --git a/packages/angular-query-experimental/src/signal-proxy.ts b/packages/angular-query-experimental/src/signal-proxy.ts
diff --git a/packages/angular-query-experimental/src/types.ts b/packages/angular-query-experimental/src/types.ts

Original file line number	Diff line number	Diff line change
`@@ -43,10 +43,20 @@ function getResult<TResult = MutationState>(`
`43`	`43`	`)`
`44`	`44`	`}`
`45`	`45`
	`46`	`+/**`
	`47`	`+ * @public`
	`48`	`+ */`
`46`	`49`	`export interface InjectMutationStateOptions {`
`47`	`50`	`injector?: Injector`
`48`	`51`	`}`
`49`	`52`
	`53`	`+/**`
	`54`	`+ * Injects a signal that tracks the state of all mutations.`
	`55`	`+ * @param mutationStateOptionsFn - A function that returns mutation state options.`
	`56`	`+ * @param options - The Angular injector to use.`
	`57`	`+ * @returns The signal that tracks the state of all mutations.`
	`58`	`+ * @public`
	`59`	`+ */`
`50`	`60`	`export function injectMutationState<TResult = MutationState>(`
`51`	`61`	`mutationStateOptionsFn: () => MutationStateOptions<TResult> = () => ({}),`
`52`	`62`	`options?: InjectMutationStateOptions,`