Skip to content

task(docs): Updates docs to include result description meta param [#1904] #1934

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+18 −3
Open

task(docs): Updates docs to include result description meta param [#1904] #1934

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions docs/rtk-query/api/createApi.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,8 @@ export type QueryDefinition<
TagTypes,
ResultType,
QueryArg,
BaseQueryError<BaseQuery>
BaseQueryError<BaseQuery>,
BaseQueryMeta<BaseQuery>
>

keepUnusedDataFor?: number
Expand Down Expand Up @@ -228,7 +229,13 @@ export type MutationDefinition<

extraOptions?: BaseQueryExtraOptions<BaseQuery>

invalidatesTags?: ResultDescription<TagTypes, ResultType, QueryArg>
invalidatesTags?: ResultDescription<
TagTypes,
ResultType,
QueryArg,
BaseQueryError<BaseQuery>,
BaseQueryMeta<BaseQuery>
>

onQueryStarted?(
arg: QueryArg,
Expand Down
1 change: 1 addition & 0 deletions docs/rtk-query/usage-with-typescript.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -398,6 +398,7 @@ When using the function notation, both the `providesTags` and `invalidatesTags`
- result: `ResultType` | `undefined` - The result returned by a successful query. The type corresponds with `ResultType` as [supplied to the built endpoint](#typing-query-and-mutation-endpoints). In the error case for a query, this will be `undefined`.
- error: `ErrorType` | `undefined` - The error returned by an errored query. The type corresponds with `Error` as [supplied to the `baseQuery` for the api](#typing-a-basequery). In the success case for a query, this will be `undefined`.
- arg: `QueryArg` - The argument supplied to the `query` property when the query itself is called. The type corresponds with `QueryArg` as [supplied to the built endpoint](#typing-query-and-mutation-endpoints).
- meta: `MetaType` | `undefined` - The optional `meta` value returned by `baseQuery`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, this is tricky to communicate. When using fetchBaseQuery, this will actually be a combination of baseQueryMeta (the type FetchBaseQueryMeta) and a maybe user-defined SomeCustomInjectedMetaAUserProvides. This results in an object that looks like: { request: Request, response?: Response, ...someCustomInjectedMeta }. This will be present for any fulfilled or rejected request.

This might be fine for now, but we'll definitely want to revisit this as well as the Adding Meta information to queries section in customizing-queries.md

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I appreciate the clarification. Let me chew on this feedback and I can push another iteration.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

little confused by this comment - when is baseQueryMeta not determined by the baseQuery? (#4098 not withstanding, which i just discovered)


A recommended use-case with `providesTags` when a query returns a list of items is to provide a tag for each item in the list using the entity ID, as well as a 'LIST' ID tag (see [Advanced Invalidation with abstract tag IDs](./usage/automated-refetching.mdx#advanced-invalidation-with-abstract-tag-ids)).

Expand Down
9 changes: 8 additions & 1 deletion docs/rtk-query/usage/automated-refetching.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,14 @@ _see also: [invalidatesTags API reference](../api/createApi.mdx#invalidatestags)

A _mutation_ can _invalidate_ specific cached data based on the tags. Doing so determines which cached data will be either refetched or removed from the cache.

The `invalidatesTags` argument can either be an array of `string` (such as `['Post']`), `{type: string, id?: string|number}` (such as `[{type: 'Post', id: 1}]`), or a callback that returns such an array. That function will be passed the result as the first argument, the response error as the second argument, and the argument originally passed into the `query` method as the third argument. Note that either the result or error arguments may be undefined based on whether the mutation was successful or not.
The `invalidatesTags` argument can either be an array of `string` (such as `['Post']`), `{type: string, id?: string|number}` (such as `[{type: 'Post', id: 1}]`), or a callback that returns such an array. That function will be passed:

1. the result as the first argument,
1. the response error as the second argument,
1. the argument originally passed into the `query` method as the third argument,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is generally difficult to read.

Was it (passed into the query method) and is now the third argument to invalidatesTags?
or
Was it (passed into the query method as the third argument)?

1. and any optional `meta` property resolved by `baseQuery`.

Note that either the result or error arguments may be undefined based on whether the mutation was successful or not.

## Cache tags

Expand Down