Skip to content

Commit f7ed362

Browse files
committed
add onSchemaFailure and skipSchemaValidation docs
1 parent 4e7616f commit f7ed362

File tree

3 files changed

+131
-11
lines changed

3 files changed

+131
-11
lines changed

docs/rtk-query/api/createApi.mdx

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -483,6 +483,26 @@ You can set this globally in `createApi`, but you can also override the default
483483
If you specify `track: false` when manually dispatching queries, RTK Query will not be able to automatically refetch for you.
484484
:::
485485

486+
### `onSchemaFailure`
487+
488+
[summary](docblock://query/createApi.ts?token=CreateApiOptions.onSchemaFailure)
489+
490+
[examples](docblock://query/createApi.ts?token=CreateApiOptions.onSchemaFailure)
491+
492+
:::note
493+
You can set this globally in `createApi`, but you can also override the default value and have more granular control by passing `onSchemaFailure` to each individual endpoint definition.
494+
:::
495+
496+
### `skipSchemaValidation`
497+
498+
[summary](docblock://query/createApi.ts?token=CreateApiOptions.skipSchemaValidation)
499+
500+
[examples](docblock://query/createApi.ts?token=CreateApiOptions.skipSchemaValidation)
501+
502+
:::note
503+
You can set this globally in `createApi`, but you can also override the default value and have more granular control by passing `skipSchemaValidation` to each individual endpoint definition.
504+
:::
505+
486506
## Endpoint Definition Parameters
487507

488508
### `query`

packages/toolkit/src/query/createApi.ts

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -214,7 +214,59 @@ export interface CreateApiOptions<
214214
NoInfer<ReducerPath>
215215
>
216216

217+
/**
218+
* A function that is called when a schema validation fails.
219+
*
220+
* Gets called with a `NamedSchemaError` and an object containing the endpoint name, the type of the endpoint, the argument passed to the endpoint, and the query cache key (if applicable).
221+
*
222+
* `NamedSchemaError` has the following properties:
223+
* - `issues`: an array of issues that caused the validation to fail
224+
* - `value`: the value that was passed to the schema
225+
* - `schemaName`: the name of the schema that was used to validate the value (e.g. `argSchema`)
226+
*
227+
* @example
228+
* ```ts
229+
* // codeblock-meta no-transpile
230+
* import { createApi } from '@reduxjs/toolkit/query/react'
231+
* import * as v from "valibot"
232+
*
233+
* const api = createApi({
234+
* baseQuery: fetchBaseQuery({ baseUrl: '/' }),
235+
* endpoints: (build) => ({
236+
* getPost: build.query<Post, { id: number }>({
237+
* query: ({ id }) => `/post/${id}`,
238+
* }),
239+
* }),
240+
* onSchemaFailure: (error, info) => {
241+
* console.error(error, info)
242+
* },
243+
* })
244+
* ```
245+
*/
217246
onSchemaFailure?: SchemaFailureHandler
247+
/**
248+
* Defaults to `false`.
249+
*
250+
* If set to `true`, will skip schema validation for all endpoints, unless overridden by the endpoint.
251+
*
252+
* @example
253+
* ```ts
254+
* // codeblock-meta no-transpile
255+
* import { createApi } from '@reduxjs/toolkit/query/react'
256+
* import * as v from "valibot"
257+
*
258+
* const api = createApi({
259+
* baseQuery: fetchBaseQuery({ baseUrl: '/' }),
260+
* skipSchemaValidation: process.env.NODE_ENV === "test", // skip schema validation in tests, since we'll be mocking the response
261+
* endpoints: (build) => ({
262+
* getPost: build.query<Post, { id: number }>({
263+
* query: ({ id }) => `/post/${id}`,
264+
* responseSchema: v.object({ id: v.number(), name: v.string() }),
265+
* }),
266+
* })
267+
* })
268+
* ```
269+
*/
218270
skipSchemaValidation?: boolean
219271
}
220272

packages/toolkit/src/query/endpointDefinitions.ts

Lines changed: 59 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -120,12 +120,11 @@ type EndpointDefinitionWithQuery<
120120
): unknown
121121

122122
/**
123-
* A schema for the result *before* it's passed to `transformResponse`
123+
* A schema for the result *before* it's passed to `transformResponse`.
124124
*
125125
* @example
126126
* ```ts
127127
* // codeblock-meta no-transpile
128-
*
129128
* import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
130129
* import * as v from "valibot"
131130
*
@@ -147,12 +146,11 @@ type EndpointDefinitionWithQuery<
147146
rawResponseSchema?: StandardSchemaV1<RawResultType>
148147

149148
/**
150-
* A schema for the error object returned by the `query` or `queryFn`, *before* it's passed to `transformErrorResponse`
149+
* A schema for the error object returned by the `query` or `queryFn`, *before* it's passed to `transformErrorResponse`.
151150
*
152151
* @example
153152
* ```ts
154153
* // codeblock-meta no-transpile
155-
*
156154
* import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
157155
* import * as v from "valibot"
158156
* import {customBaseQuery, baseQueryErrorSchema} from "./customBaseQuery"
@@ -251,7 +249,6 @@ interface CommonEndpointDefinition<
251249
* @example
252250
* ```ts
253251
* // codeblock-meta no-transpile
254-
*
255252
* import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
256253
* import * as v from "valibot"
257254
*
@@ -269,12 +266,11 @@ interface CommonEndpointDefinition<
269266
argSchema?: StandardSchemaV1<QueryArg>
270267

271268
/**
272-
* A schema for the result (including `transformResponse` if provided)
269+
* A schema for the result (including `transformResponse` if provided).
273270
*
274271
* @example
275272
* ```ts
276273
* // codeblock-meta no-transpile
277-
*
278274
* import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
279275
* import * as v from "valibot"
280276
*
@@ -295,12 +291,11 @@ interface CommonEndpointDefinition<
295291
responseSchema?: StandardSchemaV1<ResultType>
296292

297293
/**
298-
* A schema for the error object returned by the `query` or `queryFn` (including `transformErrorResponse` if provided)
294+
* A schema for the error object returned by the `query` or `queryFn` (including `transformErrorResponse` if provided).
299295
*
300296
* @example
301297
* ```ts
302298
* // codeblock-meta no-transpile
303-
*
304299
* import { createApi } from '@reduxjs/toolkit/query/react'
305300
* import * as v from "valibot"
306301
* import { customBaseQuery, baseQueryErrorSchema } from "./customBaseQuery"
@@ -319,12 +314,11 @@ interface CommonEndpointDefinition<
319314
errorResponseSchema?: StandardSchemaV1<BaseQueryError<BaseQuery>>
320315

321316
/**
322-
* A schema for the `meta` property returned by the `query` or `queryFn`
317+
* A schema for the `meta` property returned by the `query` or `queryFn`.
323318
*
324319
* @example
325320
* ```ts
326321
* // codeblock-meta no-transpile
327-
*
328322
* import { createApi } from '@reduxjs/toolkit/query/react'
329323
* import * as v from "valibot"
330324
* import { customBaseQuery, baseQueryMetaSchema } from "./customBaseQuery"
@@ -356,7 +350,61 @@ interface CommonEndpointDefinition<
356350
*/
357351
structuralSharing?: boolean
358352

353+
/**
354+
* A function that is called when a schema validation fails.
355+
*
356+
* Gets called with a `NamedSchemaError` and an object containing the endpoint name, the type of the endpoint, the argument passed to the endpoint, and the query cache key (if applicable).
357+
*
358+
* `NamedSchemaError` has the following properties:
359+
* - `issues`: an array of issues that caused the validation to fail
360+
* - `value`: the value that was passed to the schema
361+
* - `schemaName`: the name of the schema that was used to validate the value (e.g. `argSchema`)
362+
*
363+
* @example
364+
* ```ts
365+
* // codeblock-meta no-transpile
366+
* import { createApi } from '@reduxjs/toolkit/query/react'
367+
* import * as v from "valibot"
368+
*
369+
* const api = createApi({
370+
* baseQuery: fetchBaseQuery({ baseUrl: '/' }),
371+
* endpoints: (build) => ({
372+
* getPost: build.query<Post, { id: number }>({
373+
* query: ({ id }) => `/post/${id}`,
374+
* onSchemaFailure: (error, info) => {
375+
* console.error(error, info)
376+
* },
377+
* }),
378+
* })
379+
* })
380+
* ```
381+
*/
359382
onSchemaFailure?: SchemaFailureHandler
383+
384+
/**
385+
* Defaults to `false`.
386+
*
387+
* If set to `true`, will skip schema validation for this endpoint.
388+
* Overrides the global setting.
389+
*
390+
* @example
391+
* ```ts
392+
* // codeblock-meta no-transpile
393+
* import { createApi } from '@reduxjs/toolkit/query/react'
394+
* import * as v from "valibot"
395+
*
396+
* const api = createApi({
397+
* baseQuery: fetchBaseQuery({ baseUrl: '/' }),
398+
* endpoints: (build) => ({
399+
* getPost: build.query<Post, { id: number }>({
400+
* query: ({ id }) => `/post/${id}`,
401+
* responseSchema: v.object({ id: v.number(), name: v.string() }),
402+
* skipSchemaValidation: process.env.NODE_ENV === "test", // skip schema validation in tests, since we'll be mocking the response
403+
* }),
404+
* })
405+
* })
406+
* ```
407+
*/
360408
skipSchemaValidation?: boolean
361409
}
362410

0 commit comments

Comments
 (0)