add result, error, and meta schemas

EskiMojo14 · EskiMojo14 · commit 116db6ef8c49 · 2025-02-26T14:53:27.000Z
diff --git a/packages/toolkit/src/query/core/buildThunks.ts b/packages/toolkit/src/query/core/buildThunks.ts
@@ -488,10 +488,13 @@ export function buildThunks<
     },
   ) => {
     const endpointDefinition = endpointDefinitions[arg.endpointName]
+    const { metaSchema } = endpointDefinition
 
     try {
-      let transformResponse: TransformCallback =
-        getTransformCallbackForEndpoint(endpointDefinition, 'transformResponse')
+      let transformResponse = getTransformCallbackForEndpoint(
+        endpointDefinition,
+        'transformResponse',
+      )
 
       const baseQueryApi = {
         signal,
@@ -548,11 +551,10 @@ export function buildThunks<
         finalQueryArg: unknown,
       ): Promise<QueryReturnValue> {
         let result: QueryReturnValue
-        const { extraOptions, argSchema } = endpointDefinition
+        const { extraOptions, argSchema, rawResultSchema, resultSchema } =
+          endpointDefinition
 
-        if (argSchema) {
-          await parseWithSchema(argSchema, finalQueryArg)
-        }
+        if (argSchema) await parseWithSchema(argSchema, finalQueryArg)
 
         if (forceQueryFn) {
           // upsertQueryData relies on this to pass in the user-provided value
@@ -607,12 +609,25 @@ export function buildThunks<
 
         if (result.error) throw new HandledError(result.error, result.meta)
 
-        const transformedResponse = await transformResponse(
-          result.data,
+        let { data } = result
+
+        if (rawResultSchema) {
+          data = await parseWithSchema(rawResultSchema, result.data)
+        }
+
+        let transformedResponse = await transformResponse(
+          data,
           result.meta,
           finalQueryArg,
         )
 
+        if (resultSchema) {
+          transformedResponse = await parseWithSchema(
+            resultSchema,
+            transformedResponse,
+          )
+        }
+
         return {
           ...result,
           data: transformedResponse,
@@ -702,6 +717,13 @@ export function buildThunks<
         finalQueryReturnValue = await executeRequest(arg.originalArgs)
       }
 
+      if (metaSchema && finalQueryReturnValue.meta) {
+        finalQueryReturnValue.meta = await parseWithSchema(
+          metaSchema,
+          finalQueryReturnValue.meta,
+        )
+      }
+
       // console.log('Final result: ', transformedData)
       return fulfillWithValue(
         finalQueryReturnValue.data,
@@ -711,25 +733,43 @@ export function buildThunks<
         }),
       )
     } catch (error) {
-      let catchedError = error
-      if (catchedError instanceof HandledError) {
-        let transformErrorResponse: TransformCallback =
-          getTransformCallbackForEndpoint(
-            endpointDefinition,
-            'transformErrorResponse',
-          )
+      let caughtError = error
+      if (caughtError instanceof HandledError) {
+        let transformErrorResponse = getTransformCallbackForEndpoint(
+          endpointDefinition,
+          'transformErrorResponse',
+        )
+        const { rawErrorSchema, errorSchema } = endpointDefinition
+
+        let { value, meta } = caughtError
+
+        if (rawErrorSchema) {
+          value = await parseWithSchema(rawErrorSchema, value)
+        }
+
+        if (metaSchema) {
+          meta = await parseWithSchema(metaSchema, meta)
+        }
 
         try {
+          let transformedErrorResponse = await transformErrorResponse(
+            value,
+            meta,
+            arg.originalArgs,
+          )
+          if (errorSchema) {
+            transformedErrorResponse = await parseWithSchema(
+              errorSchema,
+              transformedErrorResponse,
+            )
+          }
+
           return rejectWithValue(
-            await transformErrorResponse(
-              catchedError.value,
-              catchedError.meta,
-              arg.originalArgs,
-            ),
-            addShouldAutoBatch({ baseQueryMeta: catchedError.meta }),
+            transformedErrorResponse,
+            addShouldAutoBatch({ baseQueryMeta: meta }),
           )
         } catch (e) {
-          catchedError = e
+          caughtError = e
         }
       }
       if (
@@ -739,12 +779,12 @@ export function buildThunks<
         console.error(
           `An unhandled error occurred processing a request for the endpoint "${arg.endpointName}".
 In the case of an unhandled error, no tags will be "provided" or "invalidated".`,
-          catchedError,
+          caughtError,
         )
       } else {
-        console.error(catchedError)
+        console.error(caughtError)
       }
-      throw catchedError
+      throw caughtError
     }
   }
 
diff --git a/packages/toolkit/src/query/endpointDefinitions.ts b/packages/toolkit/src/query/endpointDefinitions.ts
@@ -119,6 +119,9 @@ type EndpointDefinitionWithQuery<
 
   /** A schema for the result *before* it's passed to `transformResponse` */
   rawResultSchema?: StandardSchemaV1<BaseQueryResult<BaseQuery>>
+
+  /** A schema for the error object returned by the `query` or `queryFn`, *before* it's passed to `transformErrorResponse` */
+  rawErrorSchema?: StandardSchemaV1<BaseQueryError<BaseQuery>>
 }
 
 type EndpointDefinitionWithQueryFn<
@@ -180,6 +183,7 @@ type EndpointDefinitionWithQueryFn<
   transformResponse?: never
   transformErrorResponse?: never
   rawResultSchema?: never
+  rawErrorSchema?: never
   /**
    * Defaults to `true`.
    *
@@ -217,9 +221,12 @@ export type BaseEndpointDefinition<
   /** A schema for the result (including `transformResponse` if provided) */
   resultSchema?: StandardSchemaV1<ResultType>
 
-  /** A schema for the error object returned by the `query` or `queryFn` */
+  /** A schema for the error object returned by the `query` or `queryFn` (including `transformErrorResponse` if provided) */
   errorSchema?: StandardSchemaV1<BaseQueryError<BaseQuery>>
 
+  /** A schema for the `meta` property returned by the `query` or `queryFn` */
+  metaSchema?: StandardSchemaV1<BaseQueryMeta<BaseQuery>>
+
   /* phantom type */
   [resultType]?: ResultType
   /* phantom type */
diff --git a/packages/toolkit/src/query/tests/createApi.test.ts b/packages/toolkit/src/query/tests/createApi.test.ts
@@ -8,6 +8,7 @@ import type { SerializedError } from '@reduxjs/toolkit'
 import { configureStore, createAction, createReducer } from '@reduxjs/toolkit'
 import type {
   DefinitionsFromApi,
+  FetchBaseQueryError,
   FetchBaseQueryMeta,
   OverrideResultType,
   SerializeQueryArgs,
@@ -28,6 +29,7 @@ const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(noop)
 
 afterEach(() => {
   vi.clearAllMocks()
+  server.resetHandlers()
 })
 
 afterAll(() => {
@@ -1188,15 +1190,11 @@ describe('timeout behavior', () => {
 
 describe('endpoint schemas', () => {
   test("can be used to validate the endpoint's arguments", async () => {
-    server.use(
-      http.get('https://example.com/success/1', () => HttpResponse.json({})),
-    )
-
     const api = createApi({
       baseQuery: fetchBaseQuery({ baseUrl: 'https://example.com' }),
       endpoints: (build) => ({
         query: build.query<unknown, { id: number }>({
-          query: ({ id }) => `/success/${id}`,
+          query: ({ id }) => `/post/${id}`,
           argSchema: v.object({ id: v.number() }),
         }),
       }),
@@ -1223,4 +1221,126 @@ describe('endpoint schemas', () => {
       stack: expect.any(String),
     })
   })
+  test("can be used to validate the endpoint's raw result", async () => {
+    const api = createApi({
+      baseQuery: fetchBaseQuery({ baseUrl: 'https://example.com' }),
+      endpoints: (build) => ({
+        query: build.query<{ success: boolean }, void>({
+          query: () => '/success',
+          rawResultSchema: v.object({ value: v.literal('success!') }),
+        }),
+      }),
+    })
+    const storeRef = setupApiStore(api, undefined, {
+      withoutTestLifecycles: true,
+    })
+    const result = await storeRef.store.dispatch(api.endpoints.query.initiate())
+    expect(result?.error).toEqual<SerializedError>({
+      name: 'SchemaError',
+      message: expect.any(String),
+      stack: expect.any(String),
+    })
+  })
+  test("can be used to validate the endpoint's final result", async () => {
+    server.use(
+      http.get('https://example.com/success/', () =>
+        HttpResponse.json({ success: true }),
+      ),
+    )
+    const api = createApi({
+      baseQuery: fetchBaseQuery({ baseUrl: 'https://example.com' }),
+      endpoints: (build) => ({
+        query: build.query<{ success: boolean }, void>({
+          query: () => '/success',
+          transformResponse: () => ({ success: false }),
+          resultSchema: v.object({ success: v.literal(true) }),
+        }),
+      }),
+    })
+    const storeRef = setupApiStore(api, undefined, {
+      withoutTestLifecycles: true,
+    })
+    const result = await storeRef.store.dispatch(api.endpoints.query.initiate())
+    expect(result?.error).toEqual<SerializedError>({
+      name: 'SchemaError',
+      message: expect.any(String),
+      stack: expect.any(String),
+    })
+  })
+  test("can be used to validate the endpoint's raw error result", async () => {
+    const api = createApi({
+      baseQuery: fetchBaseQuery({ baseUrl: 'https://example.com' }),
+      endpoints: (build) => ({
+        query: build.query<{ success: boolean }, void>({
+          query: () => '/error',
+          rawErrorSchema: v.object({
+            status: v.pipe(v.number(), v.minValue(400), v.maxValue(499)),
+            data: v.unknown(),
+          }),
+        }),
+      }),
+    })
+    const storeRef = setupApiStore(api, undefined, {
+      withoutTestLifecycles: true,
+    })
+    const result = await storeRef.store.dispatch(api.endpoints.query.initiate())
+    expect(result?.error).toEqual<SerializedError>({
+      name: 'SchemaError',
+      message: expect.any(String),
+      stack: expect.any(String),
+    })
+  })
+  test("can be used to validate the endpoint's final error result", async () => {
+    const api = createApi({
+      baseQuery: fetchBaseQuery({ baseUrl: 'https://example.com' }),
+      endpoints: (build) => ({
+        query: build.query<{ success: boolean }, void>({
+          query: () => '/error',
+          transformErrorResponse: (error): FetchBaseQueryError => ({
+            status: 'CUSTOM_ERROR',
+            data: error,
+            error: 'whoops',
+          }),
+          errorSchema: v.object({
+            status: v.literal('CUSTOM_ERROR'),
+            error: v.literal('oh no'),
+            data: v.unknown(),
+          }),
+        }),
+      }),
+    })
+    const storeRef = setupApiStore(api, undefined, {
+      withoutTestLifecycles: true,
+    })
+    const result = await storeRef.store.dispatch(api.endpoints.query.initiate())
+    expect(result?.error).toEqual<SerializedError>({
+      name: 'SchemaError',
+      message: expect.any(String),
+      stack: expect.any(String),
+    })
+  })
+  test("can be used to validate the endpoint's meta result", async () => {
+    const api = createApi({
+      baseQuery: fetchBaseQuery({ baseUrl: 'https://example.com' }),
+      endpoints: (build) => ({
+        query: build.query<{ success: boolean }, void>({
+          query: () => '/success',
+          metaSchema: v.object({
+            request: v.instance(Request),
+            response: v.instance(Response),
+            timestamp: v.number(),
+          }),
+        }),
+      }),
+    })
+    const storeRef = setupApiStore(api, undefined, {
+      withoutTestLifecycles: true,
+    })
+    const result = await storeRef.store.dispatch(api.endpoints.query.initiate())
+    expect(result?.error).toEqual<SerializedError>({
+      name: 'SchemaError',
+      message: expect.any(String),
+      stack: expect.any(String),
+    })
+  })
 })
