From f1cc324ea81031447f5594fd78c75748738cc1f9 Mon Sep 17 00:00:00 2001 From: Arnoud de Vries <6420061+arnoud-dv@users.noreply.github.com> Date: Fri, 15 Nov 2024 18:26:28 +0100 Subject: [PATCH] docs(angular-query): add TypeScript documentation --- docs/config.json | 4 + docs/framework/angular/quick-start.md | 1 + docs/framework/angular/typescript.md | 174 ++++++++++++++++++++++++++ docs/framework/react/typescript.md | 2 +- 4 files changed, 180 insertions(+), 1 deletion(-) create mode 100644 docs/framework/angular/typescript.md diff --git a/docs/config.json b/docs/config.json index ffe9ec23a4..943e3cbfa1 100644 --- a/docs/config.json +++ b/docs/config.json @@ -145,6 +145,10 @@ "label": "Devtools", "to": "framework/angular/devtools" }, + { + "label": "TypeScript", + "to": "framework/angular/typescript" + }, { "label": "Zoneless", "to": "framework/angular/zoneless" diff --git a/docs/framework/angular/quick-start.md b/docs/framework/angular/quick-start.md index b593a8798f..d2fd9a9ad4 100644 --- a/docs/framework/angular/quick-start.md +++ b/docs/framework/angular/quick-start.md @@ -51,6 +51,7 @@ import { lastValueFrom } from 'rxjs' import { injectMutation, injectQuery, + QueryClient } from '@tanstack/angular-query-experimental' @Component({ diff --git a/docs/framework/angular/typescript.md b/docs/framework/angular/typescript.md new file mode 100644 index 0000000000..e0e1396c1e --- /dev/null +++ b/docs/framework/angular/typescript.md @@ -0,0 +1,174 @@ +--- +id: typescript +title: TypeScript +ref: docs/framework/react/typescript.md +replace: + { + 'useQuery': 'injectQuery', + 'useMutation': 'injectMutation', + 'react-query': 'angular-query-experimental', + 'public API of React Query': 'public API of TanStack Query and - after the experimental phase, the angular-query package', + 'still follows': 'still follow', + 'React Query': 'TanStack Query', + '`success`': '`isSuccess()`', + 'function:': 'function.', + 'separate function': 'separate function or a service', + } +--- + +[//]: # 'TypeInference1' + +```angular-ts +@Component({ + // ... + template: `@let data = query.data();`, + // ^? data: number | undefined +}) +class MyComponent { + query = injectQuery(() => ({ + queryKey: ['test'], + queryFn: () => Promise.resolve(5), + })) +} +``` + +[//]: # 'TypeInference1' +[//]: # 'TypeInference2' + +```angular-ts +@Component({ + // ... + template: `@let data = query.data();`, + // ^? data: string | undefined +}) +class MyComponent { + query = injectQuery(() => ({ + queryKey: ['test'], + queryFn: () => Promise.resolve(5), + select: (data) => data.toString(), + })) +} +``` + +[//]: # 'TypeInference2' +[//]: # 'TypeInference3' + +In this example we pass Group[] to the type parameter of HttpClient's `get` method. + +```angular-ts +@Component({ + template: `@let data = query.data();`, + // ^? data: Group[] | undefined +}) +class MyComponent { + http = inject(HttpClient) + + query = injectQuery(() => ({ + queryKey: ['groups'], + queryFn: () => lastValueFrom(this.http.get('/groups')), + })) +} +``` + +[//]: # 'TypeInference3' +[//]: # 'TypeInference4' + +```angular-ts +@Component({ + // ... + template: ` + @if (query.isSuccess()) { + @let data = query.data(); + // ^? data: number + } + `, +}) +class MyComponent { + query = injectQuery(() => ({ + queryKey: ['test'], + queryFn: () => Promise.resolve(5), + })) +} +``` + +> TypeScript currently does not support discriminated unions on object methods. Narrowing on signal fields on objects such as query results only works on signals returning a boolean. Prefer using `isSuccess()` and similar boolean status signals over `status() === 'success'`. + +[//]: # 'TypeInference4' +[//]: # 'TypingError' + +```angular-ts +@Component({ + // ... + template: `@let error = query.error();`, + // ^? error: Error | null +}) +class MyComponent { + query = injectQuery(() => ({ + queryKey: ['groups'], + queryFn: fetchGroups + })) +} +``` + +[//]: # 'TypingError' +[//]: # 'TypingError2' + +```angular-ts +@Component({ + // ... + template: `@let error = query.error();`, + // ^? error: string | null +}) +class MyComponent { + query = injectQuery(() => ({ + queryKey: ['groups'], + queryFn: fetchGroups, + })) +} +``` + +[//]: # 'TypingError2' +[//]: # 'TypingError3' + +```ts +import axios from 'axios' + +query = injectQuery(() => ({ queryKey: ['groups'], queryFn: fetchGroups })) + +computed(() => { + const error = query.error() + // ^? error: Error | null + + if (axios.isAxiosError(error)) { + error + // ^? const error: AxiosError + } +}) +``` + +[//]: # 'TypingError3' +[//]: # 'RegisterErrorType' + +```ts +import '@tanstack/angular-query-experimental' + +declare module '@tanstack/angular-query-experimental' { + interface Register { + defaultError: AxiosError + } +} + +const query = injectQuery(() => ({ + queryKey: ['groups'], + queryFn: fetchGroups, +})) + +computed(() => { + const error = query.error() + // ^? error: AxiosError | null +}) +``` + +[//]: # 'RegisterErrorType' +[//]: # 'Materials' +[//]: # 'Materials' diff --git a/docs/framework/react/typescript.md b/docs/framework/react/typescript.md index 6832db00cd..cc2249dae0 100644 --- a/docs/framework/react/typescript.md +++ b/docs/framework/react/typescript.md @@ -176,7 +176,7 @@ declare module '@tanstack/react-query' { ## Typing Query Options -If you inline query options into `useQuery`, you'll get automatic type inference. However, you might want to extract the query options into a separate function to share them between `useQuery` and e.g. `prefetchQuery`. In that case, you'd lose type inference. To get it back, you can use `queryOptions` helper: +If you inline query options into `useQuery`, you'll get automatic type inference. However, you might want to extract the query options into a separate function to share them between `useQuery` and e.g. `prefetchQuery`. In that case, you'd lose type inference. To get it back, you can use the `queryOptions` helper: ```ts import { queryOptions } from '@tanstack/react-query'