Merge branch 'master' into create-slice-creators

Author: EskiMojo14

.github/workflows/tests.yml

@@ -48,7 +48,7 @@ jobs:
 
       # Read existing version, reuse that, add a Git short hash
       - name: Set build version to Git commit
-        run: node scripts/writeGitVersion.mjs $(git rev-parse --short HEAD)
+        run: yarn tsx scripts/writeGitVersion.mts $(git rev-parse --short HEAD)
 
       - name: Check updated version
         run: jq .version package.json
@@ -111,7 +111,7 @@ jobs:
       fail-fast: false
       matrix:
         node: ['20.x']
-        ts: ['4.7', '4.8', '4.9', '5.0', '5.1', '5.2', '5.3', '5.4', '5.5']
+        ts: ['5.0', '5.1', '5.2', '5.3', '5.4', '5.5']
     steps:
       - name: Checkout repo
         uses: actions/checkout@v4

docs/rtk-query/api/createApi.mdx

@@ -16,6 +16,11 @@ description: 'RTK Query > API: createApi reference'
 
 Typically, you should only have one API slice per base URL that your application needs to communicate with. For example, if your site fetches data from both `/api/posts` and `/api/users`, you would have a single API slice with `/api/` as the base URL, and separate endpoint definitions for `posts` and `users`. This allows you to effectively take advantage of [automated re-fetching](../usage/automated-refetching.mdx) by defining [tag](../usage/automated-refetching.mdx#tags) relationships across endpoints.
 
+This is because:
+
+- Automatic tag invalidation only works within a single API slice. If you have multiple API slices, the automatic invalidation won't work across them.
+- Every `createApi` call generates its own middleware, and each middleware added to the store will run checks against every dispatched action. That has a perf cost that adds up. So, if you called `createApi` 10 times and added 10 separate API middleware to the store, that will be noticeably slower perf-wise.
+
 For maintainability purposes, you may wish to split up endpoint definitions across multiple files, while still maintaining a single API slice which includes all of these endpoints. See [code splitting](../usage/code-splitting.mdx) for how you can use the `injectEndpoints` property to inject API endpoints from other files into a single API slice definition.
 
 :::
@@ -91,6 +96,7 @@ export const { useGetPokemonByNameQuery } = pokemonApi
   - `endpoint` - The name of the endpoint.
   - `type` - Type of request (`query` or `mutation`).
   - `forced` - Indicates if a query has been forced.
+  - `queryCacheKey`- The computed query cache key.
 - `extraOptions` - The value of the optional `extraOptions` property provided for a given endpoint
 
 #### baseQuery function signature

docs/rtk-query/api/created-api/api-slice-utils.mdx

@@ -335,7 +335,7 @@ type UseMutationResult<T> = {
   data?: T // Returned result if present
   error?: unknown // Error result if present
   endpointName?: string // The name of the given endpoint for the mutation
-  fulfilledTimestamp?: number // Timestamp for when the mutation was completed
+  fulfilledTimeStamp?: number // Timestamp for when the mutation was completed
 
   // Derived request status booleans
   isUninitialized: boolean // Mutation has not been fired yet

docs/rtk-query/api/created-api/hooks.mdx

@@ -19,6 +19,11 @@ This section documents the contents of that API structure, with the different fi
 
 Typically, you should only have one API slice per base URL that your application needs to communicate with. For example, if your site fetches data from both `/api/posts` and `/api/users`, you would have a single API slice with `/api/` as the base URL, and separate endpoint definitions for `posts` and `users`. This allows you to effectively take advantage of [automated re-fetching](../../usage/automated-refetching.mdx) by defining [tag](../../usage/automated-refetching.mdx#tags) relationships across endpoints.
 
+This is because:
+
+- Automatic tag invalidation only works within a single API slice. If you have multiple API slices, the automatic invalidation won't work across them.
+- Every `createApi` call generates its own middleware, and each middleware added to the store will run checks against every dispatched action. That has a perf cost that adds up. So, if you called `createApi` 10 times and added 10 separate API middleware to the store, that will be noticeably slower perf-wise.
+
 For maintainability purposes, you may wish to split up endpoint definitions across multiple files, while still maintaining a single API slice which includes all of these endpoints. See [code splitting](../../usage/code-splitting.mdx) for how you can use the `injectEndpoints` property to inject API endpoints from other files into a single API slice definition.
 
 :::

docs/rtk-query/api/created-api/overview.mdx

@@ -64,7 +64,7 @@ type FetchBaseQueryArgs = {
     api: Pick<
       BaseQueryApi,
       'getState' | 'extra' | 'endpoint' | 'type' | 'forced'
-    >,
+    > & { arg: string | FetchArgs },
   ) => MaybePromise<Headers | void>
   fetchFn?: (
     input: RequestInfo,
@@ -83,14 +83,60 @@ type FetchBaseQueryResult = Promise<
       meta?: { request: Request; response: Response }
     }
   | {
-      error: {
-        status: number
-        data: any
-      }
+      error: FetchBaseQueryError
       data?: undefined
       meta?: { request: Request; response: Response }
     }
 >
+
+type FetchBaseQueryError =
+  | {
+      /**
+       * * `number`:
+       *   HTTP status code
+       */
+      status: number
+      data: unknown
+    }
+  | {
+      /**
+       * * `"FETCH_ERROR"`:
+       *   An error that occurred during execution of `fetch` or the `fetchFn` callback option
+       **/
+      status: 'FETCH_ERROR'
+      data?: undefined
+      error: string
+    }
+  | {
+      /**
+       * * `"PARSING_ERROR"`:
+       *   An error happened during parsing.
+       *   Most likely a non-JSON-response was returned with the default `responseHandler` "JSON",
+       *   or an error occurred while executing a custom `responseHandler`.
+       **/
+      status: 'PARSING_ERROR'
+      originalStatus: number
+      data: string
+      error: string
+    }
+  | {
+      /**
+       * * `"TIMEOUT_ERROR"`:
+       *   Request timed out
+       **/
+      status: 'TIMEOUT_ERROR'
+      data?: undefined
+      error: string
+    }
+  | {
+      /**
+       * * `"CUSTOM_ERROR"`:
+       *   A custom error type that you can return from your `queryFn` where another error might not make sense.
+       **/
+      status: 'CUSTOM_ERROR'
+      data?: unknown
+      error: string
+    }
 ```
 
 ## Parameters
@@ -105,7 +151,7 @@ Typically a string like `https://api.your-really-great-app.com/v1/`. If you don'
 
 _(optional)_
 
-Allows you to inject headers on every request. You can specify headers at the endpoint level, but you'll typically want to set common headers like `authorization` here. As a convenience mechanism, the second argument allows you to use `getState` to access your redux store in the event you store information you'll need there such as an auth token. Additionally, it provides access to `extra`, `endpoint`, `type`, and `forced` to unlock more granular conditional behaviors.
+Allows you to inject headers on every request. You can specify headers at the endpoint level, but you'll typically want to set common headers like `authorization` here. As a convenience mechanism, the second argument allows you to use `getState` to access your redux store in the event you store information you'll need there such as an auth token. Additionally, it provides access to `arg`, `extra`, `endpoint`, `type`, and `forced` to unlock more granular conditional behaviors.
 
 You can mutate the `headers` argument directly, and returning it is optional.
 
@@ -114,6 +160,7 @@ type prepareHeaders = (
   headers: Headers,
   api: {
     getState: () => unknown
+    arg: string | FetchArgs
     extra: unknown
     endpoint: string
     type: 'query' | 'mutation'
@@ -297,6 +344,17 @@ export const customApi = createApi({
 If you make a `json` request to an API that only returns a `200` with an undefined body, `fetchBaseQuery` will pass that through as `undefined` and will not try to parse it as `json`. This can be common with some APIs, especially on `delete` requests.
 :::
 
+#### Default response handler
+
+The default response handler is `"json"`, which is equivalent to the following function:
+
+```ts title="Default responseHandler"
+const defaultResponseHandler = async (res: Response) => {
+  const text = await res.text()
+  return text.length ? JSON.parse(text) : null
+}
+```
+
 ### Handling non-standard Response status codes
 
 By default, `fetchBaseQuery` will `reject` any `Response` that does not have a status code of `2xx` and set it to `error`. This is the same behavior you've most likely experienced with `axios` and other popular libraries. In the event that you have a non-standard API you're dealing with, you can use the `validateStatus` option to customize this behavior.

docs/rtk-query/api/fetchBaseQuery.mdx

@@ -38,12 +38,12 @@ RTK-Query uses a very familiar redux-centric architecture. Where the `api` is a
 The slices built inside this "build" are:
 _Some of which have their own actions_
 
-- querySlice
-- mutationSlice
-- invalidationSlice
-- subscriptionSlice (used as a dummy slice to generate actions internally)
-- internalSubscriptionsSlice
-- configSlice (internal tracking of focus state, online state, hydration etc)
+- `querySlice`
+- `mutationSlice`
+- `invalidationSlice`
+- `subscriptionSlice` (used as a dummy slice to generate actions internally)
+- `internalSubscriptionsSlice`
+- `configSlice` (internal tracking of focus state, online state, hydration etc)
 
 buildSlice also exposes the core action `resetApiState` which is subsequently added to the `api.util`
 
@@ -53,21 +53,21 @@ RTK-Query has a series of custom middlewares established within its store to han
 
 Each middleware built during this step is referred to internally as a "Handler" and are as follows:
 
-- `buildDevCheckHandler
-- `buildCacheCollectionHandler
-- `buildInvalidationByTagsHandler
-- `buildPollingHandler
-- `buildCacheLifecycleHandler
-- `buildQueryLifecycleHandler
+- `buildDevCheckHandler`
+- `buildCacheCollectionHandler`
+- `buildInvalidationByTagsHandler`
+- `buildPollingHandler`
+- `buildCacheLifecycleHandler`
+- `buildQueryLifecycleHandler`
 
 ### buildSelectors
 
 build selectors is a crucial step that exposes to the `api` and utils:
 
-- `buildQuerySelector
-- `buildMutationSelector
-- `selectInvalidatedBy
-- `selectCachedArgsForQuery
+- `buildQuerySelector`
+- `buildMutationSelector`
+- `selectInvalidatedBy`
+- `selectCachedArgsForQuery`
 
 ### return
 

docs/rtk-query/internal/overview.mdx

@@ -636,7 +636,7 @@ const staggeredBaseQueryWithBailOut = retry(
     // bail out of re-tries immediately if unauthorized,
     // because we know successive re-retries would be redundant
     if (result.error?.status === 401) {
-      retry.fail(result.error)
+      retry.fail(result.error, result.meta)
     }
 
     return result

docs/rtk-query/usage/customizing-queries.mdx

@@ -150,7 +150,7 @@ Writing immutable update logic by hand _is_ hard, and **accidentally mutating st
 Immer provides a function called `produce`, which accepts two arguments: your original `state`, and a callback function. The callback function is given a "draft" version of that state, and inside the callback, it is safe to write code that mutates the draft value. Immer tracks all attempts to mutate the draft value and then replays those mutations using their immutable equivalents to create a safe, immutably updated result:
 
 ```js
-import produce from 'immer'
+import { produce } from 'immer'
 
 const baseState = [
   {

docs/usage/immer-reducers.md

@@ -9632,11 +9632,11 @@ __metadata:
 
 "typescript@patch:typescript@npm%3A^5.5.4#optional!builtin<compat/typescript>":
   version: 5.5.4
-  resolution: "typescript@patch:typescript@npm%3A5.5.4#optional!builtin<compat/typescript>::version=5.5.4&hash=d69c25"
+  resolution: "typescript@patch:typescript@npm%3A5.5.4#optional!builtin<compat/typescript>::version=5.5.4&hash=379a07"
   bin:
     tsc: bin/tsc
     tsserver: bin/tsserver
-  checksum: 10/2c065f0ef81855eac25c9b658a3c9da65ffc005260c12854c2286f40f3667e1b1ecf8bdbdd37b59aa0397920378ce7900bff8cb32e0f1c7af6fd86efc676718c
+  checksum: 10/746fdd0865c5ce4f15e494c57ede03a9e12ede59cfdb40da3a281807853fe63b00ef1c912d7222143499aa82f18b8b472baa1830df8804746d09b55f6cf5b1cc
   languageName: node
   linkType: hard