UNPKG

7.91 kBTypeScriptView Raw
1import type { Api, Module, ModuleName } from './apiTypes';
2import type { BaseQueryArg, BaseQueryFn } from './baseQueryTypes';
3import type { SerializeQueryArgs } from './defaultSerializeQueryArgs';
4import type { EndpointBuilder, EndpointDefinitions } from './endpointDefinitions';
5export interface CreateApiOptions<BaseQuery extends BaseQueryFn, Definitions extends EndpointDefinitions, ReducerPath extends string = 'api', TagTypes extends string = never> {
6 /**
7 * The base query used by each endpoint if no `queryFn` option is specified. RTK Query exports a utility called [fetchBaseQuery](./fetchBaseQuery) as a lightweight wrapper around `fetch` for common use-cases. See [Customizing Queries](../../rtk-query/usage/customizing-queries) if `fetchBaseQuery` does not handle your requirements.
8 *
9 * @example
10 *
11 * ```ts
12 * import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query'
13 *
14 * const api = createApi({
15 * // highlight-start
16 * baseQuery: fetchBaseQuery({ baseUrl: '/' }),
17 * // highlight-end
18 * endpoints: (build) => ({
19 * // ...endpoints
20 * }),
21 * })
22 * ```
23 */
24 baseQuery: BaseQuery;
25 /**
26 * An array of string tag type names. Specifying tag types is optional, but you should define them so that they can be used for caching and invalidation. When defining an tag type, you will be able to [provide](../../rtk-query/usage/automated-refetching#providing-tags) them with `provides` and [invalidate](../../rtk-query/usage/automated-refetching#invalidating-tags) them with `invalidates` when configuring [endpoints](#endpoints).
27 *
28 * @example
29 *
30 * ```ts
31 * import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query'
32 *
33 * const api = createApi({
34 * baseQuery: fetchBaseQuery({ baseUrl: '/' }),
35 * // highlight-start
36 * tagTypes: ['Post', 'User'],
37 * // highlight-end
38 * endpoints: (build) => ({
39 * // ...endpoints
40 * }),
41 * })
42 * ```
43 */
44 tagTypes?: readonly TagTypes[];
45 /**
46 * The `reducerPath` is a _unique_ key that your service will be mounted to in your store. If you call `createApi` more than once in your application, you will need to provide a unique value each time. Defaults to `'api'`.
47 *
48 * @example
49 *
50 * ```ts
51 * // codeblock-meta title="apis.js"
52 * import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query';
53 *
54 * const apiOne = createApi({
55 * // highlight-start
56 * reducerPath: 'apiOne',
57 * // highlight-end
58 * baseQuery: fetchBaseQuery({ baseUrl: '/' }),
59 * endpoints: (builder) => ({
60 * // ...endpoints
61 * }),
62 * });
63 *
64 * const apiTwo = createApi({
65 * // highlight-start
66 * reducerPath: 'apiTwo',
67 * // highlight-end
68 * baseQuery: fetchBaseQuery({ baseUrl: '/' }),
69 * endpoints: (builder) => ({
70 * // ...endpoints
71 * }),
72 * });
73 * ```
74 */
75 reducerPath?: ReducerPath;
76 /**
77 * Accepts a custom function if you have a need to change the creation of cache keys for any reason.
78 */
79 serializeQueryArgs?: SerializeQueryArgs<BaseQueryArg<BaseQuery>>;
80 /**
81 * Endpoints are just a set of operations that you want to perform against your server. You define them as an object using the builder syntax. There are two basic endpoint types: [`query`](../../rtk-query/usage/queries) and [`mutation`](../../rtk-query/usage/mutations).
82 */
83 endpoints(build: EndpointBuilder<BaseQuery, TagTypes, ReducerPath>): Definitions;
84 /**
85 * Defaults to `60` _(this value is in seconds)_. This is how long RTK Query will keep your data cached for **after** the last component unsubscribes. For example, if you query an endpoint, then unmount the component, then mount another component that makes the same request within the given time frame, the most recent value will be served from the cache.
86 *
87 * ```ts
88 * // codeblock-meta title="keepUnusedDataFor example"
89 *
90 * import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
91 * interface Post {
92 * id: number
93 * name: string
94 * }
95 * type PostsResponse = Post[]
96 *
97 * const api = createApi({
98 * baseQuery: fetchBaseQuery({ baseUrl: '/' }),
99 * endpoints: (build) => ({
100 * getPosts: build.query<PostsResponse, void>({
101 * query: () => 'posts',
102 * // highlight-start
103 * keepUnusedDataFor: 5
104 * // highlight-end
105 * })
106 * })
107 * })
108 * ```
109 */
110 keepUnusedDataFor?: number;
111 /**
112 * Defaults to `false`. This setting allows you to control whether if a cached result is already available RTK Query will only serve a cached result, or if it should `refetch` when set to `true` or if an adequate amount of time has passed since the last successful query result.
113 * - `false` - Will not cause a query to be performed _unless_ it does not exist yet.
114 * - `true` - Will always refetch when a new subscriber to a query is added. Behaves the same as calling the `refetch` callback or passing `forceRefetch: true` in the action creator.
115 * - `number` - **Value is in seconds**. If a number is provided and there is an existing query in the cache, it will compare the current time vs the last fulfilled timestamp, and only refetch if enough time has elapsed.
116 *
117 * If you specify this option alongside `skip: true`, this **will not be evaluated** until `skip` is false.
118 */
119 refetchOnMountOrArgChange?: boolean | number;
120 /**
121 * Defaults to `false`. This setting allows you to control whether RTK Query will try to refetch all subscribed queries after the application window regains focus.
122 *
123 * If you specify this option alongside `skip: true`, this **will not be evaluated** until `skip` is false.
124 *
125 * Note: requires [`setupListeners`](./setupListeners) to have been called.
126 */
127 refetchOnFocus?: boolean;
128 /**
129 * Defaults to `false`. This setting allows you to control whether RTK Query will try to refetch all subscribed queries after regaining a network connection.
130 *
131 * If you specify this option alongside `skip: true`, this **will not be evaluated** until `skip` is false.
132 *
133 * Note: requires [`setupListeners`](./setupListeners) to have been called.
134 */
135 refetchOnReconnect?: boolean;
136}
137export declare type CreateApi<Modules extends ModuleName> = {
138 /**
139 * Creates a service to use in your application. Contains only the basic redux logic (the core module).
140 *
141 * @link https://rtk-query-docs.netlify.app/api/createApi
142 */
143 <BaseQuery extends BaseQueryFn, Definitions extends EndpointDefinitions, ReducerPath extends string = 'api', TagTypes extends string = never>(options: CreateApiOptions<BaseQuery, Definitions, ReducerPath, TagTypes>): Api<BaseQuery, Definitions, ReducerPath, TagTypes, Modules>;
144};
145/**
146 * Builds a `createApi` method based on the provided `modules`.
147 *
148 * @link https://rtk-query-docs.netlify.app/concepts/customizing-create-api
149 *
150 * @example
151 * ```ts
152 * const MyContext = React.createContext<ReactReduxContextValue>(null as any);
153 * const customCreateApi = buildCreateApi(
154 * coreModule(),
155 * reactHooksModule({ useDispatch: createDispatchHook(MyContext) })
156 * );
157 * ```
158 *
159 * @param modules - A variable number of modules that customize how the `createApi` method handles endpoints
160 * @returns A `createApi` method using the provided `modules`.
161 */
162export declare function buildCreateApi<Modules extends [Module<any>, ...Module<any>[]]>(...modules: Modules): CreateApi<Modules[number]['name']>;