v2.7.0

[markerikson]

RTK has hit Stage 2.7! 🤣 This feature release adds support for Standard Schema validation in RTK Query endpoints, fixes several issues with infinite queries, improves perf when infinite queries provide tags, adds a dev-mode check for duplicate middleware, and improves reference stability in slice selectors and infinite query hooks.

Changelog

Standard Schema Validation for RTK Query

Apps often need to validate responses from the server, both to ensure the data is correct, and to help enforce that the data matches the expected TS types. This is typically done with schema libraries such as Zod, Valibot, and Arktype. Because of the similarities in usage APIs, those libraries and others now support a common API definition called Standard Schema, allowing you to plug your chosen validation library in anywhere Standard Schema is supported.

RTK Query now supports using Standard Schema to validate query args, responses, and errors. If schemas are provided, the validations will be run and errors thrown if the data is invalid. Additionally, providing a schema allows TS inference for that type as well, allowing you to omit generic types from the endpoint.

Schema usage is per-endpoint, and can look like this:

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
import * as v from 'valibot'

const postSchema = v.object({
  id: v.number(),
  name: v.string(),
})
type Post = v.InferOutput<typeof postSchema>

const api = createApi({
  baseQuery: fetchBaseQuery({ baseUrl: '/' }),
  endpoints: (build) => ({
    getPost: build.query({
      // infer arg from here
      query: ({ id }: { id: number }) => `/post/${id}`,
      // infer result from here
      responseSchema: postSchema,
    }),
    getTransformedPost: build.query({
      // infer arg from here
      query: ({ id }: { id: number }) => `/post/${id}`,
      // infer untransformed result from here
      rawResponseSchema: postSchema,
      // infer transformed result from here
      transformResponse: (response) => ({
        ...response,
        published_at: new Date(response.published_at),
      }),
    }),
  }),
})

If desired, you can also configure schema error handling with the catchSchemaFailure option. You can also disable actual runtime validation with skipSchemaValidation (primarily useful for cases when payloads may be large and expensive to validate, but you still want to benefit from the TS type inference).

See the "Schema Validation" docs section in the createApi reference and the usage guide sections on queries, infinite queries, and mutations, for more details.

Infinite Query Fixes

This release fixes several reported issue with infinite queries:

• The lifecycleApi.updateCachedData method is now correctly available
• The skip option now correctly works for infinite query hooks
• Infinite query fulfilled actions now include the meta field from the base query (such as {request, response}). For cases where multiple pages are being refetched, this will be the meta from the last page fetched.
• useInfiniteQuerySubscription now returns stable references for refetch and the fetchNext/PreviousPage methods

upsertQueryEntries, Tags Performance and API State Structure

We recently published a fix to actually process per-endpoint providedTags when using upsertQueryEntries. However, this exposed a performance issue - the internal tag handling logic was doing repeated O(n) iterations over all endpoint+tag entries in order to clear out existing references to that cache key. In cases where hundreds or thousands of cache entries were being inserted, this became extremely expensive.

We've restructured the state.api.provided data structure to handle reverse-mapping between tags and cache keys, which drastically improves performance in this case. However, it's worth noting that this is a change to that state structure. This shouldn't affect apps, because the RTKQ state is intended to be treated as a black box and not generally directly accessed by user app code. However, it's possible someone may have depended on that specific state structure when writing a custom selector, in which case this would break. An actual example of this is the Redux DevTools RTKQ panel, which iterates the tags data while displaying cache entries. That did break with this change. Prior to releasing RTK 2.7,we released Redux DevTools 3.2.10, which includes support for both the old and new state.api.provided definitions.

TS Support Matrix Updates

Following with the DefinitelyTyped support matrix, we've officially dropped support for TS 5.0, and currently support TS 5.1 - 5.8. (RTK likely still works with 5.0, but we no longer test against that in CI.)

Duplicate Middleware Dev Checks

configureStore now checks the final middleware array for duplicate middleware references. This will catch cases such as accidentally adding the same RTKQ API middleware twice (such as adding baseApi.middleware and injectedApi.middlweware - these are actually the same object and same middleware).

Unlike the other dev-mode checks, this is part of configureStore itself, not getDefaultMiddleware().

This can be configured via the new duplicateMiddlewareCheck option.

Other Changes

createEntityAdapter now correctly handles adding an item and then applying multiple updates to it.

The generated combineSlices selectors will now return the same placeholder initial state reference for a given slice, rather than returning a new initial state reference every time.

useQuery hooks should now correctly refetch after dispatching resetApiState.

What's Changed

• Process multiple update for the same new entity by @demyanm in Process multiple update for the same new entity #4890
• add infinite query support for updateCachedData by @alexmotoc in add infinite query support for updateCachedData #4905
• add infinite query skip support by @alexmotoc in add infinite query skip support #4906
• Cache initial state in injected scenarios by @EskiMojo14 in Cache initial state in injected scenarios #4908
• Rewrite providedTags handling for better perf by @markerikson in Rewrite providedTags handling for better perf #4910
• Allow standard schemas to validate endpoint values by @EskiMojo14 in Allow standard schemas to validate endpoint values #4864
• fix(rtk-query): useQuery hook does not refetch after resetApiState by @juniusfree in fix(rtk-query): useQuery hook does not refetch after resetApiState #4758
• Drop TS 5.0 from compat matrix by @markerikson in Drop TS 5.0 from compat matrix #4925
• Add duplicate middleware dev check to configureStore by @markerikson in Add duplicate middleware dev check to configureStore #4927
• Improve duplicate middleware error and save build output by @markerikson in Improve duplicate middleware error and save build output #4928
• Add meta handling for infinite queries by @markerikson in Add meta handling for infinite queries #4939
• improve stability of useInfiniteQuerySubscription's return value by @EskiMojo14 in improve stability of useInfiniteQuerySubscription's return value #4937
• Add catchSchemaFailure, and docs for RTKQ schema features by @EskiMojo14 in Add catchSchemaFailure, and docs for RTKQ schema features #4934

Full Changelog: v2.6.1...v2.7.0

---

This discussion was created from the release v2.7.0.

[User6531]

Thank you very much for this update — you did an awesome job! 🙌 This is a fantastic feature, and it allows me to replace a lot of custom response validation code with just a few lines. Really appreciate the effort put into it.

I do have a quick question regarding catchSchemaFailure and serializable errors. According to the docs, catchSchemaFailure should return a FetchBaseQueryError, and the example shows:

const api = createApi({
  baseQuery: fetchBaseQuery({ baseUrl: '/' }),
  catchSchemaFailure: (error, info) => ({
    status: 'CUSTOM_ERROR',
    error: error.schemaName + ' failed validation',
    data: error,
  }),
});

However, since the error passed here is of type NamedSchemaError, which includes non-serializable properties, passing it directly to data causes a warning in the console:

A non-serializable value was detected in an action, in the path: payload.data.

To avoid this, would it be better to pass only the serializable parts, like data: error.message instead?

Thanks again — loving the improvements!

[EskiMojo14]

yep, good catch - PR welcome :)