createAsyncThunk: support for meta (reduxjs#1083)

* createAsyncThunk: support for `meta`
* adjust matcher type to work around variance problems
* also allow to `throw rejectedWithValue`, cleanup
* add test for `mapBuilders` with the extended `createAsyncThunk`
* add docs

Author: phryneas

docs/api/createAsyncThunk.mdx

@@ -81,17 +81,20 @@ The `payloadCreator` function will be called with two arguments:
   - `extra`: the "extra argument" given to the thunk middleware on setup, if available
   - `requestId`: a unique string ID value that was automatically generated to identify this request sequence
   - `signal`: an [`AbortController.signal` object](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/signal) that may be used to see if another part of the app logic has marked this request as needing cancelation.
-  - `rejectWithValue`: rejectWithValue is a utility function that you can `return` in your action creator to return a rejected response with a defined payload. It will pass whatever value you give it and return it in the payload of the rejected action.
+  - `rejectWithValue(value, [meta])`: rejectWithValue is a utility function that you can `return` (or `throw`) in your action creator to return a rejected response with a defined payload and meta. It will pass whatever value you give it and return it in the payload of the rejected action. If you also pass in a `meta`, it will be merged with the existing `rejectedAction.meta`.
+  - `fulfillWithValue(value, meta)`: fulfillWithValue is a utility function that you can `return` in your action creator to `fulfill` with a value while having the ability of adding to `fulfilledAction.meta`.
 
 The logic in the `payloadCreator` function may use any of these values as needed to calculate the result.
 
 ### Options
 
 An object with the following optional fields:
 
-- `condition`: a callback that can be used to skip execution of the payload creator and all action dispatches, if desired. See [Canceling Before Execution](#canceling-before-execution) for a complete description.
+- `condition(arg, { getState, extra } ): boolean`: a callback that can be used to skip execution of the payload creator and all action dispatches, if desired. See [Canceling Before Execution](#canceling-before-execution) for a complete description.
 - `dispatchConditionRejection`: if `condition()` returns `false`, the default behavior is that no actions will be dispatched at all. If you still want a "rejected" action to be dispatched when the thunk was canceled, set this flag to `true`.
-- `idGenerator`: a function to use when generating the `requestId` for the request sequence. Defaults to use [nanoid](./otherExports.mdx/#nanoid).
+- `idGenerator(): string`: a function to use when generating the `requestId` for the request sequence. Defaults to use [nanoid](./otherExports.mdx/#nanoid).
+- `serializeError(error: unknown) => any` to replace the internal `miniSerializeError` method with your own serialization logic.
+- `getPendingMeta({ arg, requestId }, { getState, extra }): any`: a function to create an object that will be merged into the `pendingAction.meta` field.
 
 ## Return Value
 

docs/usage/usage-with-typescript.md

@@ -497,7 +497,28 @@ const lastReturnedAction = await store.dispatch(fetchUserById(3))
 
 The second argument to the `payloadCreator`, known as `thunkApi`, is an object containing references to the `dispatch`, `getState`, and `extra` arguments from the thunk middleware as well as a utility function called `rejectWithValue`. If you want to use these from within the `payloadCreator`, you will need to define some generic arguments, as the types for these arguments cannot be inferred. Also, as TS cannot mix explicit and inferred generic parameters, from this point on you'll have to define the `Returned` and `ThunkArg` generic parameter as well.
 
-To define the types for these arguments, pass an object as the third generic argument, with type declarations for some or all of these fields: `{dispatch?, state?, extra?, rejectValue?}`.
+To define the types for these arguments, pass an object as the third generic argument, with type declarations for some or all of these fields:
+
+```ts
+type AsyncThunkConfig = {
+  /** return type for `thunkApi.getState` */
+  state?: unknown
+  /** type for `thunkApi.dispatch` */
+  dispatch?: Dispatch
+  /** type of the `extra` argument for the thunk middleware, which will be passed in as `thunkApi.extra` */
+  extra?: unknown
+  /** type to be passed into `rejectWithValue`'s first argument that will end up on `rejectedAction.payload` */
+  rejectValue?: unknown
+  /** return type of the `serializeError` option callback */
+  serializedErrorType?: unknown
+  /** type to be returned from the `getPendingMeta` option callback & merged into `pendingAction.meta` */
+  pendingMeta?: unknown
+  /** type to be passed into the second argument of `fulfillWithValue` to finally be merged into `fulfilledAction.meta` */
+  fulfilledMeta?: unknown
+  /** type to be passed into the second argument of `rejectWithValue` to finally be merged into `rejectedAction.meta` */
+  rejectedMeta?: unknown
+}
+```
 
 ```ts
 const fetchUserById = createAsyncThunk<