diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt index 137234a3a..e01246ae5 100644 --- a/.github/actions/spelling/expect.txt +++ b/.github/actions/spelling/expect.txt @@ -75,7 +75,7 @@ radist reate redocly refetched -Refetches +refetches remarkjs remarkrc reqid @@ -102,6 +102,7 @@ TMeta TMutation TOperation TPage +TParameters TParams TQuery TRequest diff --git a/website/docs/hooks/useInfiniteQuery.mdx b/website/docs/hooks/useInfiniteQuery.mdx index 04908ed30..beb2c4696 100644 --- a/website/docs/hooks/useInfiniteQuery.mdx +++ b/website/docs/hooks/useInfiniteQuery.mdx @@ -20,13 +20,15 @@ const query = api...useInfiniteQuery( ### Arguments -1. `parameters: { path, query, header } | QueryKey | undefined` +1. `parameters: { path, query, header, body } | InfiniteQueryKey | undefined` - **Required only if OpenAPI specification defines required parameters** - If the operation has no required parameters according to OpenAPI, you can omit this argument - - `parameters` will be used to generate the `QueryKey` - - Instead of an object with `{path, query, header}`, you can pass a `QueryKey` as an array + - `parameters` will be used to generate the _Infinite Query Key_ + - For operations generated with `--queryable-write-operations`, query parameters may also include `body` + - In that mode, `body` is part of the infinite query key and cache identity + - Mutation calls keep `body` as a separate top-level argument + - Instead of an object with `{ path, query, header, body }`, you can pass a typed `InfiniteQueryKey` from `getInfiniteQueryKey(...)` which is also strictly-typed ✨ - - If operation does not require parameters, you must pass an empty object `{}` for strictness 2. `infiniteQueryOptions?: UseInfiniteQueryOptions` - **Optional**, represents the options of the [_useInfiniteQuery(...) 🌴_](https://tanstack.com/query/latest/docs/framework/react/reference/useInfiniteQuery) Hook diff --git a/website/docs/hooks/useIsFetching.mdx b/website/docs/hooks/useIsFetching.mdx index 2832e2bf1..27a0a0ac8 100644 --- a/website/docs/hooks/useIsFetching.mdx +++ b/website/docs/hooks/useIsFetching.mdx @@ -20,7 +20,8 @@ const queriesNumber = api...useIsFetching( 1. `filters?: QueryFiltersByParameters | QueryFiltersByQueryKey` - **Optional**, represents the [_Query Filters 🌴_](https://tanstack.com/query/latest/docs/framework/react/guides/filters#query-filters) to be used. If not provided, _all_ normal and _Infinite_ queries will be used to filter. - - `filters.parameters: { path, query, header }` will be used for filtering queries by parameters + - `filters.parameters: { path, query, header, body }` filters queries by operation parameters. + - For operations generated with `--queryable-write-operations`, `body` can be included in `filters.parameters` and participates in query cache identity. - `filters.infinite: boolean` will be used to filter infinite or normal queries - `filters.queryKey: QueryKey` will be used for filtering queries by _QueryKey_ instead of parameters - `filters.queryKey` and `filters.parameters` are mutually exclusive diff --git a/website/docs/hooks/useQueries.mdx b/website/docs/hooks/useQueries.mdx index 782d88bbe..49fe32b07 100644 --- a/website/docs/hooks/useQueries.mdx +++ b/website/docs/hooks/useQueries.mdx @@ -2,6 +2,9 @@ sidebar_label: useQueries() --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # useQueries(...) The Hook enables you to concurrently execute multiple asynchronous data fetching operations. @@ -20,7 +23,8 @@ const queries = api...useQueries( - **Required**, represents the options for queries, see [_useQueries(...) 🌴_](https://tanstack.com/query/latest/docs/framework/react/reference/useQueries) documentation - `options.queries: QueryOptions[]` - **Required** array of _Queries_ to be executed - - `parameters: { path, query, header }` will be used for the request + - `parameters: { path, query, header, body }` will be used for the request + - For operations generated with `--queryable-write-operations`, `body` is part of the query key and cache identity - `queryKey: QueryKey` will be used for the request instead of the `parameters` - `queryKey` and `parameters` are mutually exclusive - `options.combine?: (result: UseQueriesResults) => TCombinedResult` @@ -37,54 +41,77 @@ during code generation. ### Example -```tsx -import { createAPIClient } from './api'; // generated by OpenAPI Qraft - -import { requestFn } from '@openapi-qraft/react'; -import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; - -const queryClient = new QueryClient(); - -const api = createAPIClient({ - requestFn, - queryClient, - baseUrl: 'https://api.sandbox.monite.com/v1', -}); - -const useEntityQueries = () => { - /** - * Initiates two concurrent GET requests: - * ### - * GET /entities/3e3e-3e3e-3e3e - * x-monite-version: 2023-09-01 - * ### - * GET /entities/5c5c-5c5c-5c5c - * x-monite-version: 2023-09-01 - **/ - return api.entities.getEntities.useQueries({ - queries: [ - { - parameters: { - header: { - 'x-monite-version': '2023-09-01', + + + ```tsx + import { createAPIClient } from './api'; // generated by OpenAPI Qraft + + import { requestFn } from '@openapi-qraft/react'; + import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; + + const queryClient = new QueryClient(); + + const api = createAPIClient({ + requestFn, + queryClient, + baseUrl: 'https://api.sandbox.monite.com/v1', + }); + + const useEntityQueries = () => { + return api.entities.getEntities.useQueries({ + queries: [ + { + parameters: { + header: { 'x-monite-version': '2023-09-01' }, + path: { entity_id: '3e3e-3e3e-3e3e' }, + }, }, - path: { - entity_id: '3e3e-3e3e-3e3e', + { + parameters: { + header: { 'x-monite-version': '2023-09-01' }, + path: { entity_id: '5c5c-5c5c-5c5c' }, + }, }, - }, + ], + combine: (results) => results.map((result) => result.data), + }); + }; + ``` + + With body}> + ```tsx + const firstSearch = { + header: { 'x-monite-version': '1' }, + path: { approval_policy_id: '2' }, + body: { + name: 'New Name', + description: 'New Description', }, - { - parameters: { - header: { - 'x-monite-version': '2023-09-01', - }, - path: { - entity_id: '5c5c-5c5c-5c5c', - }, - }, + }; + + const secondSearchParameters = { + ...firstSearch, + body: { + name: 'Another Name', + description: 'Another Description', }, - ], - combine: (results) => results.map((result) => result.data), - }); -} -``` + }; + + const secondSearchQueryKey = + api.approvalPolicies.patchApprovalPoliciesId.getQueryKey( + secondSearchParameters + ); + + const results = api.approvalPolicies.patchApprovalPoliciesId.useQueries({ + queries: [ + { parameters: firstSearch }, + { queryKey: secondSearchQueryKey }, + ], + }); + + // Never pass `secondSearchParameters` as `queryKey` directly. + // `getQueryKey(...)` builds the tuple shape TanStack Query expects. + // `firstSearch.body` and `secondSearchParameters.body` produce different cache entries. + ``` + + diff --git a/website/docs/hooks/useQuery.mdx b/website/docs/hooks/useQuery.mdx index b3b840419..b5302b968 100644 --- a/website/docs/hooks/useQuery.mdx +++ b/website/docs/hooks/useQuery.mdx @@ -27,11 +27,13 @@ const query = api...useQuery( ### Arguments -1. `parameters: { path, query, header, body? } | QueryKey | void` +1. `parameters: { path, query, header, body } | QueryKey | void` - **Required only if OpenAPI specification defines required parameters** - If the operation has no required parameters according to OpenAPI, you can omit this argument - `parameters` will be used to generate the `QueryKey` - - For write operations (when using `--queryable-write-operations`), you can include a `body` parameter + - For operations generated with `--queryable-write-operations`, query parameters may also include `body` + - In that mode, `body` is part of the query key and cache identity for query hooks and query-client methods + - Mutation calls keep `body` as a separate top-level argument - Instead of an object with `{ path, query, header, body }`, you can pass a `QueryKey` as an array which is also strictly-typed diff --git a/website/docs/hooks/useSuspenseInfiniteQuery.mdx b/website/docs/hooks/useSuspenseInfiniteQuery.mdx index 5678c2588..d3e769cd3 100644 --- a/website/docs/hooks/useSuspenseInfiniteQuery.mdx +++ b/website/docs/hooks/useSuspenseInfiniteQuery.mdx @@ -18,13 +18,15 @@ const query = api...useSuspenseInfiniteQuery( ### Arguments -1. `parameters: { path, query, header } | QueryKey | undefined` +1. `parameters: { path, query, header, body } | InfiniteQueryKey | undefined` - **Required only if OpenAPI specification defines required parameters** - If the operation has no required parameters according to OpenAPI, you can omit this argument - - `parameters` will be used to generate the `QueryKey` - - Instead of an object with `{path, query, header}`, you can pass a `QueryKey` as an array + - `parameters` will be used to generate the _Infinite Query Key_ + - For operations generated with `--queryable-write-operations`, query parameters may also include `body` + - In that mode, `body` is part of the infinite query key and cache identity + - Mutation calls keep `body` as a separate top-level argument + - Instead of an object with `{ path, query, header, body }`, you can pass a typed `InfiniteQueryKey` from `getInfiniteQueryKey(...)` which is also strictly-typed ✨ - - If operation does not require parameters, you must pass an empty object `{}` for strictness 2. `suspenseInfiniteQueryOptions?: UseSuspenseInfiniteQueryOptions` - **Optional**, represents the options of the diff --git a/website/docs/hooks/useSuspenseQueries.mdx b/website/docs/hooks/useSuspenseQueries.mdx index 6aa2bcbf7..567018e8d 100644 --- a/website/docs/hooks/useSuspenseQueries.mdx +++ b/website/docs/hooks/useSuspenseQueries.mdx @@ -23,7 +23,8 @@ const result = api...useSuspenseQueries( - **Required**, represents the options for queries, see [_useSuspenseQueries(...) 🌴_](https://tanstack.com/query/latest/docs/framework/react/reference/useSuspenseQueries) documentation - `options.queries: QueryOptions[]` - **Required** array of _Queries_ to be executed - - `parameters: { path, query, header }` will be used for the request + - `parameters: { path, query, header, body }` will be used for the request + - For operations generated with `--queryable-write-operations`, `body` is part of the query key and cache identity - `queryKey: QueryKey` will be used for the request instead of the `parameters` - `queryKey` and `parameters` are mutually exclusive - `options.combine?: (result: UseQueriesResults) => TCombinedResult` @@ -109,3 +110,30 @@ export default function() { ) } ``` + +### Queryable Write Operations + +For operations generated with `--queryable-write-operations`, `useSuspenseQueries` accepts the same `parameters.body` +shape as `useQueries`. Each distinct body is part of the query key and creates a distinct cache entry. + +```tsx +const queryKey = + api.approvalPolicies.patchApprovalPoliciesId.getQueryKey({ + header: { 'x-monite-version': '1' }, + path: { approval_policy_id: '2' }, + body: { name: 'Another Name' }, + }); + +const results = api.approvalPolicies.patchApprovalPoliciesId.useSuspenseQueries({ + queries: [ + { + parameters: { + header: { 'x-monite-version': '1' }, + path: { approval_policy_id: '2' }, + body: { name: 'New Name' }, + }, + }, + { queryKey }, + ], +}); +``` diff --git a/website/docs/hooks/useSuspenseQuery.mdx b/website/docs/hooks/useSuspenseQuery.mdx index 2297e3afa..2955a581d 100644 --- a/website/docs/hooks/useSuspenseQuery.mdx +++ b/website/docs/hooks/useSuspenseQuery.mdx @@ -20,13 +20,15 @@ const result = api...useSuspenseQuery( ### Arguments -1. `parameters: { path, query, header } | QueryKey | void` +1. `parameters: { path, query, header, body } | QueryKey | void` - **Required only if OpenAPI specification defines required parameters** - If the operation has no required parameters according to OpenAPI, you can omit this argument - `parameters` will be used to generate the `QueryKey` - - Instead of an object with `{path, query, header}`, you can pass a `QueryKey` as an array + - For operations generated with `--queryable-write-operations`, query parameters may also include `body` + - In that mode, `body` is part of the query key and cache identity for query hooks and query-client methods + - Mutation calls keep `body` as a separate top-level argument + - Instead of an object with `{ path, query, header, body }`, you can pass a `QueryKey` as an array which is also strictly-typed ✨ - - If operation does not require parameters, you must pass an empty object `{}` for strictness 2. `queryOptions?: UseQueryOptions` - **Optional**, represents the options of the [_useSuspenseQuery(...) 🌴_](https://tanstack.com/query/latest/docs/framework/react/reference/useSuspenseQuery) Hook diff --git a/website/docs/query-client/cancelQueries.mdx b/website/docs/query-client/cancelQueries.mdx index 34fc0a79f..234f3cf12 100644 --- a/website/docs/query-client/cancelQueries.mdx +++ b/website/docs/query-client/cancelQueries.mdx @@ -25,7 +25,8 @@ guide for more information. 1. `filters: QueryFiltersByParameters | QueryFiltersByQueryKey` - **Required**, represents the [_Query Filters 🌴_](https://tanstack.com/query/latest/docs/framework/react/guides/filters#query-filters) to be used, strictly-typed ✨ - - `filters.parameters: { path, query, header }` will be used for filtering queries by parameters + - `filters.parameters: { path, query, header, body }` filters queries by operation parameters. + - For operations generated with `--queryable-write-operations`, `body` can be included in `filters.parameters` and participates in query cache identity. - `filters.infinite?: boolean` will be used to filter infinite or normal queries, **Required** if `predicate` is provided - `filters.queryKey?: QueryKey` will be used for filtering queries by _QueryKey_ instead of ~~`parameters`~~ - `filters.queryKey` and `filters.parameters` are mutually exclusive @@ -45,7 +46,8 @@ guide for more information. 1. `filters: QueryFiltersByParameters | QueryFiltersByQueryKey` - **Required**, represents the [_Query Filters 🌴_](https://tanstack.com/query/latest/docs/framework/react/guides/filters#query-filters) to be used, strictly-typed ✨ - - `filters.parameters: { path, query, header }` will be used for filtering queries by parameters + - `filters.parameters: { path, query, header, body }` filters queries by operation parameters. + - For operations generated with `--queryable-write-operations`, `body` can be included in `filters.parameters` and participates in query cache identity. - `filters.infinite?: boolean` will be used to filter infinite or normal queries, **Required** if `predicate` is provided - `filters.queryKey?: QueryKey` will be used for filtering queries by _QueryKey_ instead of ~~`parameters`~~ - `filters.queryKey` and `filters.parameters` are mutually exclusive diff --git a/website/docs/query-client/ensureInfiniteQueryData.mdx b/website/docs/query-client/ensureInfiniteQueryData.mdx index 8efd6df53..ffb651bf3 100644 --- a/website/docs/query-client/ensureInfiniteQueryData.mdx +++ b/website/docs/query-client/ensureInfiniteQueryData.mdx @@ -22,9 +22,12 @@ const result = api...ensureInfiniteQueryData({ ``` ### Arguments -1. - `parameters: { path, query, header } | QueryKey | void` +1. - `parameters: { path, query, header, body } | InfiniteQueryKey | void` - OpenAPI request parameters for the query, strictly-typed ✨ - - `parameters` will be used to generate the `QueryKey` + - `parameters` will be used to generate the _Infinite Query Key_ + - For operations generated with `--queryable-write-operations`, query parameters may also include `body` + - In that mode, `body` is part of the infinite query key and cache identity + - Mutation calls keep `body` as a separate top-level argument - `fetchInfiniteQueryOptions?: FetchInfiniteQueryOptions` - `requestFn?: RequestFn` - **Optional**, a function that will be used to execute the request diff --git a/website/docs/query-client/ensureQueryData.mdx b/website/docs/query-client/ensureQueryData.mdx index 4b2b5225e..ec72763ce 100644 --- a/website/docs/query-client/ensureQueryData.mdx +++ b/website/docs/query-client/ensureQueryData.mdx @@ -22,9 +22,12 @@ const result = api...ensureQueryData({ ### Arguments -1. - `parameters: { path, query, header } | QueryKey | void` +1. - `parameters: { path, query, header, body } | QueryKey | void` - **Required**, OpenAPI request parameters for the query, strictly-typed ✨ - `parameters` will be used to generate the `QueryKey` + - For operations generated with `--queryable-write-operations`, query parameters may also include `body` + - In that mode, `body` is part of the query key and cache identity for query-client methods + - Mutation calls keep `body` as a separate top-level argument - `requestFn?: RequestFn` - **Optional**, a function that will be used to execute the request - `revalidateIfStale?: boolean` diff --git a/website/docs/query-client/fetchInfiniteQuery.mdx b/website/docs/query-client/fetchInfiniteQuery.mdx index 28ae692f3..697a18e49 100644 --- a/website/docs/query-client/fetchInfiniteQuery.mdx +++ b/website/docs/query-client/fetchInfiniteQuery.mdx @@ -26,9 +26,12 @@ const result = api...fetchInfiniteQuery( ### Arguments -1. - `parameters: { path, query, header } | QueryKey | void` +1. - `parameters: { path, query, header, body } | InfiniteQueryKey | void` - OpenAPI request parameters for the query, strictly-typed ✨ - - `parameters` will be used to generate the `QueryKey` + - `parameters` will be used to generate the _Infinite Query Key_ + - For operations generated with `--queryable-write-operations`, query parameters may also include `body` + - In that mode, `body` is part of the infinite query key and cache identity + - Mutation calls keep `body` as a separate top-level argument - `fetchInfiniteQueryOptions?: FetchInfiniteQueryOptions` - `requestFn?: RequestFn` - **Optional**, a function that will be used to execute the request diff --git a/website/docs/query-client/fetchQuery.mdx b/website/docs/query-client/fetchQuery.mdx index 6ddd0636a..90c4d4205 100644 --- a/website/docs/query-client/fetchQuery.mdx +++ b/website/docs/query-client/fetchQuery.mdx @@ -29,9 +29,12 @@ const result = api...fetchQuery( ### Arguments -1. - `parameters: { path, query, header } | QueryKey | void` +1. - `parameters: { path, query, header, body } | QueryKey | void` - **Required**, OpenAPI request parameters for the query, strictly-typed ✨ - `parameters` will be used to generate the `QueryKey` + - For operations generated with `--queryable-write-operations`, query parameters may also include `body` + - In that mode, `body` is part of the query key and cache identity for query-client methods + - Mutation calls keep `body` as a separate top-level argument - `requestFn?: RequestFn` - **Optional**, a function that will be used to execute the request - `baseUrl?: string` @@ -70,6 +73,20 @@ const result = api...fetchQuery( ); ``` + With body}> + ```ts + const policy = await api.approvalPolicies.patchApprovalPoliciesId.fetchQuery({ + parameters: { + header: { 'x-monite-version': '1' }, + path: { approval_policy_id: '2' }, + body: { + name: 'New Name', + description: 'New Description', + }, + }, + }); + ``` + With queryFn}> ```ts import { createAPIClient } from './api'; // generated by OpenAPI Qraft CLI diff --git a/website/docs/query-client/getInfiniteQueryData.mdx b/website/docs/query-client/getInfiniteQueryData.mdx index 7ed585f10..0e18ddd02 100644 --- a/website/docs/query-client/getInfiniteQueryData.mdx +++ b/website/docs/query-client/getInfiniteQueryData.mdx @@ -13,10 +13,12 @@ const data = api...getInfiniteQueryData(parameters); ### Arguments -1. `parameters: { path, query, header } | QueryKey | void` - - **Required** parameters to retrieve the data from the cache. - - Instead of an object with `{ path, query, header }`, you can pass a `QueryKey` as an array - which is also strictly-typed ✨ +1. `parameters: { path, query, header, body } | InfiniteQueryKey | void` + - **Required only if OpenAPI specification defines required parameters** to retrieve the data from the cache. + - If the operation has no required parameters according to OpenAPI, you can omit this argument. + - For operations generated with `--queryable-write-operations`, query parameters may also include `body`. + In that mode, `body` is part of the infinite query key and cache identity. + - Instead of an object with `{ path, query, header, body }`, you can pass a typed infinite query key from `getInfiniteQueryKey(...)`. ### Returns diff --git a/website/docs/query-client/getInfiniteQueryKey.mdx b/website/docs/query-client/getInfiniteQueryKey.mdx index eb7514754..73ee95a1b 100644 --- a/website/docs/query-client/getInfiniteQueryKey.mdx +++ b/website/docs/query-client/getInfiniteQueryKey.mdx @@ -4,7 +4,7 @@ sidebar_label: getInfiniteQueryKey() # getInfiniteQueryKey(...) -The method provides a standardized way to generate `QueryKey` the _Infinite Queries_. +The method provides a standardized way to generate `InfiniteQueryKey` for _Infinite Queries_. See TanStack [_Query Keys 🌴_](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) guide for more information. @@ -14,13 +14,16 @@ const queryKey = api...getInfiniteQueryKey(parameters); ### Arguments -1. - `parameters: { path, query, header } | QueryKey | void` - - **Required**, OpenAPI request parameters for the query, strictly-typed ✨ - - `parameters` will be used to generate the `QueryKey` +1. - `parameters: { path, query, header, body } | void` + - **Required only if OpenAPI specification defines required parameters**, strictly-typed ✨ + - If the operation has no required parameters according to OpenAPI, you can omit this argument. + - For operations generated with `--queryable-write-operations`, query parameters may also include `body`. + In that mode, `body` is part of the infinite query key and cache identity. + - The returned `InfiniteQueryKey` can be passed to query-client methods that accept typed infinite query key arrays. ### Returns -`QueryKey` - a query key for the _Infinite Queries_ +`InfiniteQueryKey` - an infinite query key for the _Infinite Queries_ ### Example diff --git a/website/docs/query-client/getInfiniteQueryState.mdx b/website/docs/query-client/getInfiniteQueryState.mdx index 15da1c452..995d2307b 100644 --- a/website/docs/query-client/getInfiniteQueryState.mdx +++ b/website/docs/query-client/getInfiniteQueryState.mdx @@ -2,13 +2,76 @@ sidebar_label: getInfiniteQueryState() --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # getInfiniteQueryState(...) -The method is the same as the [`getQueryState`](getQueryState.mdx) method, but for infinite queries. -See the TanStack -[_queryClient.getQueryState(...) 🌴_](https://tanstack.com/query/latest/docs/reference/QueryClient#queryclientgetquerystate) -documentation. +The method enables direct access to the `QueryClient` cache state for a specific _Infinite Query_. +It is the infinite-query counterpart to [`getQueryState`](getQueryState.mdx): Qraft still calls TanStack +[_queryClient.getQueryState(...) 🌴_](https://tanstack.com/query/latest/docs/reference/QueryClient#queryclientgetquerystate), +but it builds an infinite query key and returns state for infinite cache data. + +```ts +const state = api...getInfiniteQueryState(parameters); +``` + +## Arguments + +1. `parameters: { path, query, header, body } | InfiniteQueryKey | void` + - Operation parameters used to build the _Infinite Query Key_, strictly-typed ✨ + - For operations generated with `--queryable-write-operations`, query parameters may also include `body`. + In that mode, `body` is part of the infinite query key and cache identity. + - Instead of an object with `{ path, query, header, body }`, you can pass a typed infinite query key from `getInfiniteQueryKey(...)`. + - For operations without required parameters, call the method without arguments. + +## Returns + +`QueryState, TError> | undefined` - The current cache state for the infinite query, or `undefined` if the infinite query is not in the cache. + +## Example + + + + ```tsx + const parameters = { + query: { status: 'available' }, + }; + + api.pet.findPetsByStatus.setInfiniteQueryData(parameters, { + pages: [ + [{ id: 1, name: 'Rex', status: 'available' }], + ], + pageParams: [parameters], + }); + + const state = api.pet.findPetsByStatus.getInfiniteQueryState(parameters); + + expect(state?.data).toEqual({ + pages: [ + [{ id: 1, name: 'Rex', status: 'available' }], + ], + pageParams: [parameters], + }); + ``` + + + ```tsx + const parameters = { + query: { status: 'available' }, + }; + const queryKey = api.pet.findPetsByStatus.getInfiniteQueryKey(parameters); + + api.pet.findPetsByStatus.setInfiniteQueryData(queryKey, { + pages: [ + [{ id: 1, name: 'Rex', status: 'available' }], + ], + pageParams: [parameters], + }); + + const state = api.pet.findPetsByStatus.getInfiniteQueryState(queryKey); -:::info -Documentation is actively being updated 🚧 -::: + expect(state?.status).toEqual('success'); + ``` + + diff --git a/website/docs/query-client/getQueryData.mdx b/website/docs/query-client/getQueryData.mdx index ad59b2f74..7b7989caf 100644 --- a/website/docs/query-client/getQueryData.mdx +++ b/website/docs/query-client/getQueryData.mdx @@ -18,10 +18,12 @@ const data = api...getQueryData( ## Arguments -1. `parameters: { path, query, header } | QueryKey | void` - - **Required** parameters to retrieve the data from the _Query Cache_. - - Instead of an object with `{ path, query, header }`, you can pass a `QueryKey` as an array - which is also strictly-typed ✨ +1. `parameters: { path, query, header, body } | QueryKey | void` + - **Required only if OpenAPI specification defines required parameters** to retrieve the data from the _Query Cache_. + - If the operation has no required parameters according to OpenAPI, you can omit this argument. + - For operations generated with `--queryable-write-operations`, query parameters may also include `body`. + In that mode, `body` is part of the query key and cache identity for query-client methods. + - Instead of an object with `{ path, query, header, body }`, you can pass a typed `QueryKey` array. ## Returns The data from the _Query Cache_ for the specific query, strictly-typed ✨ @@ -40,13 +42,11 @@ The data from the _Query Cache_ for the specific query, strictly-typed ✨ ```tsx - const pet = api.pet.getPetById.getQueryData( - [ - { method: 'get', url: '/pet/{petId}', infinite: false, }, - { petId: 123 }, - ], - {} - ); + const queryKey = api.pet.getPetById.getQueryKey({ + path: { petId: 123 }, + }); + + const pet = api.pet.getPetById.getQueryData(queryKey); expect(pet?.id).toEqual(123); ``` diff --git a/website/docs/query-client/getQueryKey.mdx b/website/docs/query-client/getQueryKey.mdx index b40755605..d087886b4 100644 --- a/website/docs/query-client/getQueryKey.mdx +++ b/website/docs/query-client/getQueryKey.mdx @@ -16,9 +16,12 @@ const queryKey = api...getQueryKey(parameters); ### Arguments -1. - `parameters: { path, query, header } | void` - - **Optional**, OpenAPI request parameters for the query, strictly-typed ✨ - - `parameters` will be used to generate the `QueryKey` +1. - `parameters: { path, query, header, body } | void` + - **Required only if OpenAPI specification defines required parameters**, strictly-typed ✨ + - If the operation has no required parameters according to OpenAPI, you can omit this argument. + - For operations generated with `--queryable-write-operations`, query parameters may also include `body`. + In that mode, `body` is part of the query key and cache identity for query-client methods. + - The returned `QueryKey` can be passed to query-client methods that accept typed query key arrays. ### Returns @@ -44,6 +47,28 @@ const queryKey = api...getQueryKey(parameters); ]); ``` + With body}> + ```tsx + const queryKey = + api.approvalPolicies.patchApprovalPoliciesId.getQueryKey({ + header: { 'x-monite-version': '1' }, + path: { approval_policy_id: '2' }, + body: { + name: 'New Name', + description: 'New Description', + }, + }); + + expect(queryKey[1]).toEqual({ + header: { 'x-monite-version': '1' }, + path: { approval_policy_id: '2' }, + body: { + name: 'New Name', + description: 'New Description', + }, + }); + ``` + Without parameters} default> In case all parameters are optional - you can pass nothing. diff --git a/website/docs/query-client/getQueryState.mdx b/website/docs/query-client/getQueryState.mdx index 82b4ea52c..cc2d34298 100644 --- a/website/docs/query-client/getQueryState.mdx +++ b/website/docs/query-client/getQueryState.mdx @@ -2,12 +2,66 @@ sidebar_label: getQueryState() --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # getQueryState(...) -See the TanStack -[_queryClient.getQueryState(...) 🌴_](https://tanstack.com/query/latest/docs/reference/QueryClient#queryclientgetquerystate) -documentation. +The method enables direct access to the `QueryClient` cache state for a specific _Query_. +It is a strictly-typed wrapper around TanStack +[_queryClient.getQueryState(...) 🌴_](https://tanstack.com/query/latest/docs/reference/QueryClient#queryclientgetquerystate). + +```ts +const state = api...getQueryState(parameters); +``` + +## Arguments + +1. `parameters: { path, query, header, body } | QueryKey | void` + - Operation parameters used to build the _Query Key_, strictly-typed ✨ + - For operations generated with `--queryable-write-operations`, query parameters may also include `body`. + In that mode, `body` is part of the query key and cache identity for query-client methods. + - Instead of an object with `{ path, query, header, body }`, you can pass a typed `QueryKey` array. + - For operations without required parameters, call the method without arguments. + +## Returns + +`QueryState | undefined` - The current cache state for the query, or `undefined` if the query is not in the cache. + +## Example + + + + ```tsx + const parameters = { path: { petId: 123 } }; + + await api.pet.getPetById.fetchQuery({ parameters }); + + const state = api.pet.getPetById.getQueryState(parameters); + + expect(state?.status).toEqual('success'); + expect(state?.data?.id).toEqual(123); + ``` + + + ```tsx + const parameters = { path: { petId: 123 } }; + const queryKey = api.pet.getPetById.getQueryKey(parameters); + + await api.pet.getPetById.fetchQuery({ parameters }); + + const state = api.pet.getPetById.getQueryState(queryKey); + + expect(state?.status).toEqual('success'); + ``` + + + ```tsx + await api.pet.findPets.fetchQuery(); + + const state = api.pet.findPets.getQueryState(); -:::info -Documentation is actively being updated 🚧 -::: + expect(state?.status).toEqual('success'); + ``` + + diff --git a/website/docs/query-client/invalidateQueries.mdx b/website/docs/query-client/invalidateQueries.mdx index 2c5b92db4..9e15a6a73 100644 --- a/website/docs/query-client/invalidateQueries.mdx +++ b/website/docs/query-client/invalidateQueries.mdx @@ -26,7 +26,8 @@ guide for more information. 1. `filters: QueryFiltersByParameters | QueryFiltersByQueryKey` - **Required**, represents the [_Query Filters 🌴_](https://tanstack.com/query/latest/docs/framework/react/guides/filters#query-filters) to be used, strictly-typed ✨ - - `filters.parameters: { path, query, header }` will be used for filtering queries by parameters + - `filters.parameters: { path, query, header, body }` filters queries by operation parameters. + - For operations generated with `--queryable-write-operations`, `body` can be included in `filters.parameters` and participates in query cache identity. - `filters.infinite: boolean` will be used to filter infinite or normal queries - `filters.queryKey: QueryKey` will be used for filtering queries by _QueryKey_ instead of parameters - `filters.queryKey` and `filters.parameters` are mutually exclusive diff --git a/website/docs/query-client/isFetching.mdx b/website/docs/query-client/isFetching.mdx index 8aad68109..5bb4496c6 100644 --- a/website/docs/query-client/isFetching.mdx +++ b/website/docs/query-client/isFetching.mdx @@ -26,7 +26,8 @@ guide for more information. 1. `filters: QueryFiltersByParameters | QueryFiltersByQueryKey` - **Required**, represents the [_Query Filters 🌴_](https://tanstack.com/query/latest/docs/framework/react/guides/filters#query-filters) to be used, strictly-typed ✨ - - `filters.parameters: { path, query, header }` will be used for filtering queries by parameters + - `filters.parameters: { path, query, header, body }` filters queries by operation parameters. + - For operations generated with `--queryable-write-operations`, `body` can be included in `filters.parameters` and participates in query cache identity. - `filters.infinite: boolean` will be used to filter infinite or normal queries - `filters.queryKey: QueryKey` will be used for filtering queries by _QueryKey_ instead of parameters - `filters.queryKey` and `filters.parameters` are mutually exclusive @@ -76,6 +77,20 @@ guide for more information. expect(numberOfFetchingEntities).toEqual(1); ``` + + For queryable write operations, `body` can be part of the filter parameters: + + ```ts + const matchingPolicySearches = + qraft.approvalPolicies.patchApprovalPoliciesId.isFetching({ + infinite: false, + parameters: { + header: { 'x-monite-version': '1' }, + path: { approval_policy_id: '2' }, + body: { name: 'New Name' }, + }, + }); + ``` filters}> To check _all normal queries for a particular endpoint_, you can call `isFetching(...)` without `parameters`: diff --git a/website/docs/query-client/refetchQueries.mdx b/website/docs/query-client/refetchQueries.mdx index e24f1da86..439db281d 100644 --- a/website/docs/query-client/refetchQueries.mdx +++ b/website/docs/query-client/refetchQueries.mdx @@ -24,7 +24,8 @@ See also the TanStack [_queryClient.refetchQueries(...) 🌴_](https://tanstack. 1. `filters: QueryFiltersByParameters | QueryFiltersByQueryKey` - **Required**, represents the [_Query Filters 🌴_](https://tanstack.com/query/latest/docs/framework/react/guides/filters#query-filters) to be used, strictly-typed ✨ - - `filters.parameters: { path, query, header }` will be used for filtering queries by parameters + - `filters.parameters: { path, query, header, body }` filters queries by operation parameters. + - For operations generated with `--queryable-write-operations`, `body` can be included in `filters.parameters` and participates in query cache identity. - `filters.infinite: boolean` will be used to filter infinite or normal queries - `filters.queryKey: QueryKey` will be used for filtering queries by _QueryKey_ instead of parameters - `filters.queryKey` and `filters.parameters` are mutually exclusive @@ -47,7 +48,8 @@ See also the TanStack [_queryClient.refetchQueries(...) 🌴_](https://tanstack. 1. `filters: QueryFiltersByParameters | QueryFiltersByQueryKey` - **Required**, represents the [_Query Filters 🌴_](https://tanstack.com/query/latest/docs/framework/react/guides/filters#query-filters) to be used, strictly-typed ✨ - - `filters.parameters: { path, query, header }` will be used for filtering queries by parameters + - `filters.parameters: { path, query, header, body }` filters queries by operation parameters. + - For operations generated with `--queryable-write-operations`, `body` can be included in `filters.parameters` and participates in query cache identity. - `filters.infinite: boolean` will be used to filter infinite or normal queries - `filters.queryKey: QueryKey` will be used for filtering queries by _QueryKey_ instead of parameters - `filters.queryKey` and `filters.parameters` are mutually exclusive diff --git a/website/docs/query-client/removeQueries.mdx b/website/docs/query-client/removeQueries.mdx index b1d1d0cb1..a5e5d7964 100644 --- a/website/docs/query-client/removeQueries.mdx +++ b/website/docs/query-client/removeQueries.mdx @@ -19,7 +19,8 @@ qraft...removeQueries(filters) 1. `filters: QueryFiltersByParameters | QueryFiltersByQueryKey` - **Required**, represents the [_Query Filters 🌴_](https://tanstack.com/query/latest/docs/framework/react/guides/filters#query-filters) to be used, strictly-typed ✨ - - `filters.parameters: { path, query, header }` will be used for filtering queries by parameters + - `filters.parameters: { path, query, header, body }` filters queries by operation parameters. + - For operations generated with `--queryable-write-operations`, `body` can be included in `filters.parameters` and participates in query cache identity. - `filters.infinite: boolean` will be used to filter infinite or normal queries - `filters.queryKey: QueryKey` will be used for filtering queries by _QueryKey_ instead of parameters - `filters.queryKey` and `filters.parameters` are mutually exclusive diff --git a/website/docs/query-client/resetQueries.mdx b/website/docs/query-client/resetQueries.mdx index 3f7612126..44f797a46 100644 --- a/website/docs/query-client/resetQueries.mdx +++ b/website/docs/query-client/resetQueries.mdx @@ -2,12 +2,86 @@ sidebar_label: resetQueries() --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # resetQueries(...) -The function is used to refetch a list of queries by their keys. -The API is the same as [_cancelQueries(...)_](cancelQueries.mdx) Hook. -See also the TanStack [_queryClient.resetQueries(...) 🌴_](https://tanstack.com/query/latest/docs/reference/QueryClient#queryclientresetqueries) documentation. +The method resets matching queries in the `QueryClient` cache and refetches active queries. +It is a strictly-typed wrapper around TanStack +[_queryClient.resetQueries(...) 🌴_](https://tanstack.com/query/latest/docs/reference/QueryClient#queryclientresetqueries). + +```ts +await api...resetQueries(filters, options); +``` + +## Arguments + +1. `filters?: QueryFiltersByParameters | QueryFiltersByQueryKey` + - Optional [_Query Filters 🌴_](https://tanstack.com/query/latest/docs/framework/react/guides/filters#query-filters), strictly-typed ✨ + - `filters.parameters: { path, query, header, body }` filters queries by operation parameters. + - For operations generated with `--queryable-write-operations`, `body` can be included in `filters.parameters` and participates in query cache identity. + - `filters.queryKey: QueryKey` filters queries by an explicit typed query key instead of parameters. + - `filters.parameters` and `filters.queryKey` are mutually exclusive. + - `filters.infinite: boolean` filters regular or infinite query cache entries. + - `filters.predicate?: (query: Query) => boolean` applies custom matching after the typed filter. +2. `options?: ResetOptions` + - Optional TanStack reset options. + - See the TanStack [_queryClient.resetQueries(...) 🌴_](https://tanstack.com/query/latest/docs/reference/QueryClient#queryclientresetqueries) documentation for more details. + +## Returns + +`Promise` - Resolves after matching active queries have been reset and refetched. + +## Example + + + + ```tsx + const parameters = { path: { petId: 123 } }; + + api.pet.getPetById.setQueryData(parameters, { + id: 123, + name: 'Rex', + }); + + await api.pet.getPetById.resetQueries({ + parameters, + infinite: false, + }); + ``` + + + ```tsx + const parameters = { path: { petId: 123 } }; + const queryKey = api.pet.getPetById.getQueryKey(parameters); -:::info -Documentation is actively being updated 🚧 -::: + await api.pet.getPetById.resetQueries({ + queryKey, + exact: true, + }); + ``` + + + ```tsx + await api.pet.getPetById.resetQueries({ + parameters: { path: { petId: 123 } }, + infinite: false, + predicate: (query) => query.state.status !== 'pending', + }); + ``` + + + ```tsx + await api.pet.getPetById.resetQueries( + { + parameters: { path: { petId: 123 } }, + infinite: false, + }, + { + cancelRefetch: false, + } + ); + ``` + + diff --git a/website/docs/query-client/setInfiniteQueryData.mdx b/website/docs/query-client/setInfiniteQueryData.mdx index 0d10d898a..08eb1add7 100644 --- a/website/docs/query-client/setInfiniteQueryData.mdx +++ b/website/docs/query-client/setInfiniteQueryData.mdx @@ -2,13 +2,114 @@ sidebar_label: setInfiniteQueryData() --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # setInfiniteQueryData(...) -The method enables direct access to the `QueryClient` cache to set the data for a specific _Infinite Query_. -The method API is the same as the [`setQueryData`](setQueryData.mdx) method, but it is specifically for _Infinite Queries_. +The method enables direct access to the `QueryClient` cache to set data for a specific _Infinite Query_. +It has the same role as [`setQueryData`](setQueryData.mdx), but writes infinite-query data with `pages` and `pageParams`. See the TanStack [_queryClient.setQueryData 🌴_](https://tanstack.com/query/latest/docs/reference/QueryClient#queryclientsetquerydata) documentation. -:::info -Documentation is actively being updated 🚧 -::: +```ts +const data = api...setInfiniteQueryData( + parameters, + updater, + options +); +``` + +## Arguments + +1. `parameters: { path, query, header, body } | InfiniteQueryKey` + - **Required** parameters to set the data in the _Infinite Query Cache_. + - For operations generated with `--queryable-write-operations`, query parameters may also include `body`. + In that mode, `body` is part of the infinite query key and cache identity. + - Instead of an object with `{ path, query, header, body }`, you can pass a typed infinite query key from `getInfiniteQueryKey(...)`. +2. `updater: InfiniteData | (oldData: InfiniteData | undefined) => InfiniteData | undefined` + - **Required** updater for the infinite-query cache data. + - If a non-function value is passed, the data will be updated to this value. + - If a function is passed, it receives the old infinite-query data and must return the next value. +3. `options?: SetQueryDataOptions` + - Optional options to set the data in the cache. + - See the TanStack [_queryClient.setQueryData 🌴_](https://tanstack.com/query/latest/docs/reference/QueryClient#queryclientsetquerydata) documentation for more details. + +## Returns + +`InfiniteData | undefined` - The data that was written to the cache, or `undefined` if the updater returns `undefined`. + +## Example + + + + ```tsx + const parameters = { + query: { status: 'available' }, + }; + + const pets = api.pet.findPetsByStatus.setInfiniteQueryData(parameters, { + pages: [ + [{ id: 1, name: 'Rex', status: 'available' }], + ], + pageParams: [parameters], + }); + + expect(pets).toEqual({ + pages: [ + [{ id: 1, name: 'Rex', status: 'available' }], + ], + pageParams: [parameters], + }); + ``` + + + ```tsx + const parameters = { + query: { status: 'available' }, + }; + + api.pet.findPetsByStatus.setInfiniteQueryData(parameters, { + pages: [[]], + pageParams: [parameters], + }); + + const pets = api.pet.findPetsByStatus.setInfiniteQueryData( + parameters, + (oldData) => ({ + pages: [ + ...(oldData?.pages ?? []), + [{ id: 2, name: 'Bella', status: 'available' }], + ], + pageParams: [ + ...(oldData?.pageParams ?? []), + { query: { status: 'available', page: 2 } }, + ], + }) + ); + + expect(pets?.pages.at(-1)).toEqual([ + { id: 2, name: 'Bella', status: 'available' }, + ]); + ``` + + + ```tsx + const parameters = { + query: { status: 'available' }, + }; + const queryKey = api.pet.findPetsByStatus.getInfiniteQueryKey(parameters); + + api.pet.findPetsByStatus.setInfiniteQueryData(queryKey, { + pages: [ + [{ id: 1, name: 'Rex', status: 'available' }], + ], + pageParams: [parameters], + }); + + expect( + api.pet.findPetsByStatus.getInfiniteQueryData(parameters)?.pages + ).toHaveLength(1); + ``` + + diff --git a/website/docs/query-client/setQueriesData.mdx b/website/docs/query-client/setQueriesData.mdx index 7715fb438..1706565c4 100644 --- a/website/docs/query-client/setQueriesData.mdx +++ b/website/docs/query-client/setQueriesData.mdx @@ -25,7 +25,8 @@ See the TanStack [_queryClient.setQueriesData 🌴_](https://tanstack.com/query/ 1. `filters: QueryFiltersByParameters | QueryFiltersByQueryKey` - **Required**, represents the [_Query Filters 🌴_](https://tanstack.com/query/latest/docs/framework/react/guides/filters#query-filters) to be used, strictly-typed ✨ - - `filters.parameters: { path, query, header }` will be used for filtering queries by parameters + - `filters.parameters: { path, query, header, body }` filters queries by operation parameters. + - For operations generated with `--queryable-write-operations`, `body` can be included in `filters.parameters` and participates in query cache identity. - `filters.infinite: boolean` will be used to filter infinite or normal queries - `filters.queryKey: QueryKey` will be used for filtering queries by _QueryKey_ instead of parameters - `filters.queryKey` and `filters.parameters` are mutually exclusive @@ -47,7 +48,8 @@ See the TanStack [_queryClient.setQueriesData 🌴_](https://tanstack.com/query/ 1. `filters: QueryFiltersByParameters | QueryFiltersByQueryKey` - **Required**, represents the [_Query Filters 🌴_](https://tanstack.com/query/latest/docs/framework/react/guides/filters#query-filters) to be used, strictly-typed ✨ - - `filters.parameters: { path, query, header }` will be used for filtering queries by parameters + - `filters.parameters: { path, query, header, body }` filters queries by operation parameters. + - For operations generated with `--queryable-write-operations`, `body` can be included in `filters.parameters` and participates in query cache identity. - `filters.infinite: boolean` will be used to filter infinite or normal queries - `filters.queryKey: QueryKey` will be used for filtering queries by _QueryKey_ instead of parameters - `filters.queryKey` and `filters.parameters` are mutually exclusive @@ -94,15 +96,14 @@ See the TanStack [_queryClient.setQueriesData 🌴_](https://tanstack.com/query/ ``` With QueryKey}> - It's also possible to use a `QueryKey` as an array instead of an object with `{path, query, header}`: + It's also possible to use a typed `QueryKey` from `getQueryKey(...)` instead of an object with `{ path, query, header, body }`: ```tsx const pets = qraft.pet.getPetById.setQueriesData( { - queryKey: [ - { method: 'get', url: '/pet/{petId}', infinite: false }, - { petId: 123 }, - ], + queryKey: qraft.pet.getPetById.getQueryKey({ + path: { petId: 123 }, + }), }, { id: 123, name: 'Rex' } ); diff --git a/website/docs/query-client/setQueryData.mdx b/website/docs/query-client/setQueryData.mdx index 3d0504474..00a114877 100644 --- a/website/docs/query-client/setQueryData.mdx +++ b/website/docs/query-client/setQueryData.mdx @@ -20,10 +20,11 @@ const data = qraft...setQueryData( ## Arguments -1. `parameters: { path, query, header } | QueryKey` +1. `parameters: { path, query, header, body } | QueryKey` - **Required** parameters to set the data in the _Query Cache_. - - Instead of an object with `{path, query, header}`, you can pass a `QueryKey` as an array - which is also strictly-typed ✨ + - For operations generated with `--queryable-write-operations`, query parameters may also include `body`. + In that mode, `body` is part of the query key and cache identity for query-client methods. + - Instead of an object with `{ path, query, header, body }`, you can pass a typed `QueryKey` array. 2. `updater: TData | (oldData: TData | undefined) => TData | undefined` - **Required** updater for the cache data - If a non-function value is passed, the data will be updated to this value @@ -57,15 +58,39 @@ The `TData` from the updater or `undefined` if it returns nothing }); ``` + With body}> + ```tsx + const parameters = { + header: { 'x-monite-version': '1' }, + path: { approval_policy_id: '2' }, + body: { + name: 'New Name', + description: 'New Description', + }, + }; + + qraft.approvalPolicies.patchApprovalPoliciesId.setQueryData(parameters, { + id: '2', + name: 'New Name', + description: 'New Description', + }); + + const policy = + qraft.approvalPolicies.patchApprovalPoliciesId.getQueryData(parameters); + + expect(policy?.name).toEqual('New Name'); + ``` + With QueryKey}> - It's also possible to use a `QueryKey` as an array instead of an object with `{path, query, header}`: + It's also possible to use a typed `QueryKey` array instead of an object with `{ path, query, header, body }`: ```tsx + const queryKey = qraft.pet.getPetById.getQueryKey({ + path: { petId: 123 }, + }); + const pet = qraft.pet.getPetById.setQueryData( - [ - { method: 'get', url: '/pet/{petId}', infinite: false }, - { petId: 123 }, - ], + queryKey, { id: 123, name: 'Rex' } ); ```