exportable case reducers type, bugfix, documentation (#290)

* wip

* working state

* simplify types, remove ActionForReducer

* add documentation for types, remove obsolete `PayloadActions` type

* add release tags and type documentation

* specify all exports by hand

* add documentation and release tags

* add test "wrapping createSlice should be possible"

* don't use self-referencing generic restriction to support TS <3.4

* update comments

* CI please work

* Update src/createSlice.ts

Co-Authored-By: Mark Erikson <[email protected]>

* typos

* documentation

* prettier

* minor nitpick

* Update usage-with-typescript.md

* Update usage-with-typescript.md

Co-authored-by: Mark Erikson <[email protected]>

Author: phryneas

api-extractor.json

@@ -324,14 +324,9 @@
         "logLevel": "warning"
         // "addToApiReportFile": false
       },
-
-      "ae-missing-release-tag": {
-        "logLevel": "none",
-        "addToApiReportFile": true
-      },
       "ae-forgotten-export": {
         "logLevel": "none",
-        "addToApiReportFile": true
+        "addToApiReportFile": false
       }
       //
       // . . .

docs/usage/usage-with-typescript.md

@@ -195,6 +195,26 @@ createSlice({
 })
 ```
 
+### Defining the type of your `initialState`
+
+You might have noticed that it is not a good idea to pass your `SliceState` type as a generic to `createSlice`. This is due to the fact that in almost all cases, follow-up generic parameters to `createSlice` need to be inferred, and TypeScript cannot mix explicit declaration and inference of generic types within the same "generic block".
+
+Instead, you can use the construct `initialState: myInitialState as SliceState`.
+
+```ts
+type SliceState = { state: 'loading' } | { state: 'finished'; data: string }
+
+createSlice({
+  name: 'test',
+  initialState: { state: 'loading' } as SliceState,
+  reducers: {
+    // ...
+  }
+})
+```
+
+which will result in a `Slice<SliceState, ...>`.
+
 ### On the "type" property of slice action Reducers
 
 As TS cannot combine two string literals (`slice.name` and the key of `actionMap`) into a new literal, all actionCreators created by createSlice are of type 'string'. This is usually not a problem, as these types are only rarely used as literals.
@@ -222,3 +242,62 @@ If you actually _need_ that type, unfortunately there is no other way than manua
 ### Type safety with `extraReducers`
 
 Like in `createReducer`, the `extraReducers` map object is not easy to fully type. So, like with `createReducer`, you may also use the "builder callback" approach for defining the reducer object argument. See [the `createReducer` section above](#createreducer) for an example.
+
+### Wrapping `createSlice`
+
+If you need to reuse reducer logic, it is common to write ["higher-order reducers"](https://redux.js.org/recipes/structuring-reducers/reusing-reducer-logic#customizing-behavior-with-higher-order-reducers) that wrap a reducer function with additional common behavior. This can be done with `createSlice` as well, but due to the complexity of the types for `createSlice`, you have to use the `SliceCaseReducers` and `ValidateSliceCaseReducers` types in a very specific way.
+
+Here is an example of such a "generic" wrapped `createSlice` call:
+
+```ts
+interface GenericState<T> {
+  data?: T
+  status: 'loading' | 'finished' | 'error'
+}
+
+const createGenericSlice = <
+  T,
+  Reducers extends SliceCaseReducers<GenericState<T>>
+>({
+  name = '',
+  initialState,
+  reducers
+}: {
+  name: string
+  initialState: GenericState<T>
+  reducers: ValidateSliceCaseReducers<GenericState<T>, Reducers>
+}) => {
+  return createSlice({
+    name,
+    initialState,
+    reducers: {
+      start(state) {
+        state.status = 'loading'
+      },
+      /**
+       * If you want to write to values of the state that depend on the generic
+       * (in this case: `state.data`, which is T), you might need to specify the
+       * State type manually here, as it defaults to `Draft<GenericState<T>>`,
+       * which can sometimes be problematic with yet-unresolved generics.
+       * This is a general problem when working with immer's Draft type and generics.
+       */
+      success(state: GenericState<T>, action: PayloadAction<T>) {
+        state.data = action.payload
+        state.status = 'finished'
+      },
+      ...reducers
+    }
+  })
+}
+
+const wrappedSlice = createGenericSlice({
+  name: 'test',
+  initialState: { status: 'loading' } as GenericState<string>,
+  reducers: {
+    magic(state) {
+      state.status = 'finished'
+      state.data = 'hocus pocus'
+    }
+  }
+})
+```

etc/redux-toolkit.api.md

@@ -23,12 +23,19 @@ import { getDefaultMiddleware } from './getDefaultMiddleware'
 
 const IS_PRODUCTION = process.env.NODE_ENV === 'production'
 
+/**
+ * Callback function type, to be used in `ConfigureStoreOptions.enhancers`
+ *
+ * @public
+ */
 export type ConfigureEnhancersCallback = (
   defaultEnhancers: StoreEnhancer[]
 ) => StoreEnhancer[]
 
 /**
  * Options for `configureStore()`.
+ *
+ * @public
  */
 export interface ConfigureStoreOptions<S = any, A extends Action = AnyAction> {
   /**
@@ -78,9 +85,14 @@ export interface ConfigureStoreOptions<S = any, A extends Action = AnyAction> {
 /**
  * A Redux store returned by `configureStore()`. Supports dispatching
  * side-effectful _thunks_ in addition to plain actions.
+ *
+ * @public
  */
 export interface EnhancedStore<S = any, A extends Action = AnyAction>
   extends Store<S, A> {
+  /**
+   * @inheritdoc
+   */
   dispatch: ThunkDispatch<S, any, A>
 }
 
@@ -89,6 +101,8 @@ export interface EnhancedStore<S = any, A extends Action = AnyAction>
  *
  * @param config The store configuration.
  * @returns A configured Redux store.
+ *
+ * @public
  */
 export function configureStore<S = any, A extends Action = AnyAction>(
   options: ConfigureStoreOptions<S, A>

src/configureStore.ts

@@ -1,5 +1,10 @@
 import { Action } from 'redux'
-import { IsUnknownOrNonInferrable, IfMaybeUndefined, IfVoid } from './tsHelpers'
+import {
+  IsUnknownOrNonInferrable,
+  IfMaybeUndefined,
+  IfVoid,
+  IsAny
+} from './tsHelpers'
 
 /**
  * An action with a string type and an associated payload. This is the
@@ -9,6 +14,8 @@ import { IsUnknownOrNonInferrable, IfMaybeUndefined, IfVoid } from './tsHelpers'
  * @template T the type used for the action type.
  * @template M The type of the action's meta (optional)
  * @template E The type of the action's error (optional)
+ *
+ * @public
  */
 export type PayloadAction<
   P = void,
@@ -29,12 +36,24 @@ export type PayloadAction<
         error: E
       })
 
+/**
+ * A "prepare" method to be used as the second parameter of `createAction`.
+ * Takes any number of arguments and returns a Flux Standard Action without
+ * type (will be added later) that *must* contain a payload (might be undefined).
+ *
+ * @public
+ */
 export type PrepareAction<P> =
   | ((...args: any[]) => { payload: P })
   | ((...args: any[]) => { payload: P; meta: any })
   | ((...args: any[]) => { payload: P; error: any })
   | ((...args: any[]) => { payload: P; meta: any; error: any })
 
+/**
+ * Internal version of `ActionCreatorWithPreparedPayload`. Not to be used externally.
+ *
+ * @internal
+ */
 export type _ActionCreatorWithPreparedPayload<
   PA extends PrepareAction<any> | void,
   T extends string = string
@@ -56,46 +75,129 @@ export type _ActionCreatorWithPreparedPayload<
     >
   : void
 
+/**
+ * Basic type for all action creators.
+ *
+ * @inheritdoc {redux#ActionCreator}
+ */
 interface BaseActionCreator<P, T extends string, M = never, E = never> {
   type: T
   match(action: Action<unknown>): action is PayloadAction<P, T, M, E>
 }
 
+/**
+ * An action creator that takes multiple arguments that are passed
+ * to a `PrepareAction` method to create the final Action.
+ * @typeParam Args arguments for the action creator function
+ * @typeParam P `payload` type
+ * @typeParam T `type` name
+ * @typeParam E optional `error` type
+ * @typeParam M optional `meta` type
+ *
+ * @inheritdoc {redux#ActionCreator}
+ *
+ * @public
+ */
 export interface ActionCreatorWithPreparedPayload<
   Args extends unknown[],
   P,
   T extends string = string,
   E = never,
   M = never
 > extends BaseActionCreator<P, T, M, E> {
+  /**
+   * Calling this {@link redux#ActionCreator} with `Args` will return
+   * an Action with a payload of type `P` and (depending on the `PrepareAction`
+   * method used) a `meta`- and `error` property of types `M` and `E` respectively.
+   */
   (...args: Args): PayloadAction<P, T, M, E>
 }
 
+/**
+ * An action creator of type `T` that takes an optional payload of type `P`.
+ *
+ * @inheritdoc {redux#ActionCreator}
+ *
+ * @public
+ */
 export interface ActionCreatorWithOptionalPayload<P, T extends string = string>
   extends BaseActionCreator<P, T> {
+  /**
+   * Calling this {@link redux#ActionCreator} without arguments will
+   * return a {@link PayloadAction} of type `T` with a payload of `undefined`
+   */
   (payload?: undefined): PayloadAction<undefined, T>
+  /**
+   * Calling this {@link redux#ActionCreator} with an argument will
+   * return a {@link PayloadAction} of type `T` with a payload of `P`
+   */
   <PT extends Diff<P, undefined>>(payload?: PT): PayloadAction<PT, T>
 }
 
+/**
+ * An action creator of type `T` that takes no payload.
+ *
+ * @inheritdoc {redux#ActionCreator}
+ *
+ * @public
+ */
 export interface ActionCreatorWithoutPayload<T extends string = string>
   extends BaseActionCreator<undefined, T> {
+  /**
+   * Calling this {@link redux#ActionCreator} will
+   * return a {@link PayloadAction} of type `T` with a payload of `undefined`
+   */
   (): PayloadAction<undefined, T>
 }
 
+/**
+ * An action creator of type `T` that requires a payload of type P.
+ *
+ * @inheritdoc {redux#ActionCreator}
+ *
+ * @public
+ */
 export interface ActionCreatorWithPayload<P, T extends string = string>
   extends BaseActionCreator<P, T> {
+  /**
+   * Calling this {@link redux#ActionCreator} with an argument will
+   * return a {@link PayloadAction} of type `T` with a payload of `P`
+   * If possible, `P` will be narrowed down to the exact type of the payload argument.
+   */
   <PT extends P>(payload: PT): PayloadAction<PT, T>
+  /**
+   * Calling this {@link redux#ActionCreator} with an argument will
+   * return a {@link PayloadAction} of type `T` with a payload of `P`
+   */
   (payload: P): PayloadAction<P, T>
 }
 
+/**
+ * An action creator of type `T` whose `payload` type could not be inferred. Accepts everything as `payload`.
+ *
+ * @inheritdoc {redux#ActionCreator}
+ *
+ * @public
+ */
 export interface ActionCreatorWithNonInferrablePayload<
   T extends string = string
 > extends BaseActionCreator<unknown, T> {
+  /**
+   * Calling this {@link redux#ActionCreator} with an argument will
+   * return a {@link PayloadAction} of type `T` with a payload
+   * of exactly the type of the argument.
+   */
   <PT extends unknown>(payload: PT): PayloadAction<PT, T>
 }
 
 /**
  * An action creator that produces actions with a `payload` attribute.
+ *
+ * @typeParam P the `payload` type
+ * @typeParam T the `type` of the resulting action
+ * @typeParam PA if the resulting action is preprocessed by a `prepare` method, the signature of said method.
+ *
+ * @public
  */
 export type PayloadActionCreator<
   P = void,
@@ -105,19 +207,23 @@ export type PayloadActionCreator<
   PA,
   _ActionCreatorWithPreparedPayload<PA, T>,
   // else
-  IsUnknownOrNonInferrable<
+  IsAny<
     P,
-    ActionCreatorWithNonInferrablePayload<T>,
-    // else
-    IfVoid<
+    ActionCreatorWithPayload<any, T>,
+    IsUnknownOrNonInferrable<
       P,
-      ActionCreatorWithoutPayload<T>,
+      ActionCreatorWithNonInferrablePayload<T>,
       // else
-      IfMaybeUndefined<
+      IfVoid<
         P,
-        ActionCreatorWithOptionalPayload<P, T>,
+        ActionCreatorWithoutPayload<T>,
         // else
-        ActionCreatorWithPayload<P, T>
+        IfMaybeUndefined<
+          P,
+          ActionCreatorWithOptionalPayload<P, T>,
+          // else
+          ActionCreatorWithPayload<P, T>
+        >
       >
     >
   >
@@ -133,12 +239,26 @@ export type PayloadActionCreator<
  * @param type The action type to use for created actions.
  * @param prepare (optional) a method that takes any number of arguments and returns { payload } or { payload, meta }.
  *                If this is given, the resulting action creator will pass it's arguments to this method to calculate payload & meta.
+ *
+ * @public
  */
-
 export function createAction<P = void, T extends string = string>(
   type: T
 ): PayloadActionCreator<P, T>
 
+/**
+ * A utility function to create an action creator for the given action type
+ * string. The action creator accepts a single argument, which will be included
+ * in the action object as a field called payload. The action creator function
+ * will also have its toString() overriden so that it returns the action type,
+ * allowing it to be used in reducer logic that is looking for that action type.
+ *
+ * @param type The action type to use for created actions.
+ * @param prepare (optional) a method that takes any number of arguments and returns { payload } or { payload, meta }.
+ *                If this is given, the resulting action creator will pass it's arguments to this method to calculate payload & meta.
+ *
+ * @public
+ */
 export function createAction<
   PA extends PrepareAction<any>,
   T extends string = string
@@ -182,6 +302,8 @@ export function createAction(type: string, prepareAction?: Function): any {
  *
  * @param action The action creator whose action type to get.
  * @returns The action type used by the action creator.
+ *
+ * @public
  */
 export function getType<T extends string>(
   actionCreator: PayloadActionCreator<any, T>