TypeScript FSA Reducers

Common errors

• TypeError: reducer is not a function

  cause Prior to v0.4.0, reducer builder chains were immutable and could be used directly as Redux reducers. After v0.4.0, they became mutable builders, and the final reducer function must be explicitly extracted.
  fix Always call `.build()` at the end of your reducer chain to get the actual reducer function: `const myReducer = reducerWithInitialState(...).case(...).build();`

• Cannot find module 'typescript-fsa' or its corresponding type declarations.

  cause From v1.0.0, `typescript-fsa` is a peer dependency and must be installed separately by the consumer project. If it's missing, TypeScript will report that the module cannot be found.
  fix Install `typescript-fsa` explicitly: `npm install typescript-fsa` or `yarn add typescript-fsa`.

• Argument of type 'undefined' is not assignable to parameter of type 'State'.

  cause This error can occur when trying to use a reducer created by `reducerWithoutInitialState()` and passing `undefined` as the state, particularly with `v1.2.2`'s stricter type definitions. `reducerWithoutInitialState` treats `undefined` as a regular state value, not a trigger for initial state.
  fix If you intend for `undefined` to trigger an initial state, use `reducerWithInitialState(INITIAL_STATE)`. If you truly want to handle `undefined` as a valid state, ensure your `State` type explicitly includes `| undefined`.

Warnings

• breaking In `v1.0.0`, `typescript-fsa` transitioned from a hard dependency to a peer dependency. If your project relied on `typescript-fsa-reducers` to implicitly install `typescript-fsa`, you must now install `typescript-fsa` explicitly.
  Fix: Ensure `typescript-fsa` is explicitly listed and installed in your project's `dependencies` or `devDependencies`: `npm install typescript-fsa` or `yarn add typescript-fsa`.
• breaking In `v0.4.0`, reducer chains became mutable. Previously, methods like `.case()` returned a new reducer builder instance, but now they modify the existing instance. To obtain an immutable reducer function (which is the standard for Redux), you *must* call the new `.build()` method at the end of your chain.
  Fix: Always terminate your reducer chain with `.build()`. For example, `const reducer = reducerWithInitialState(...).case(...).build();`.
• gotcha Starting with `v1.2.2`, TypeScript types were updated for `reducerWithoutInitialState`. Passing `undefined` as the *first* argument (representing the state) to reducers created by `reducerWithoutInitialState` will now correctly result in a type error unless `undefined` is explicitly a subtype of your state. This corrects a previous typing oversight.
  Fix: When using `reducerWithoutInitialState`, ensure that the first argument passed to the generated reducer is a valid state value or explicitly type your state to include `undefined` if that is intended (though `reducerWithInitialState` is typically preferred for explicit initial states). The library expects `undefined` to trigger initial state logic only for `reducerWithInitialState`.
• gotcha In `v0.4.5`, the type definition of reducers created by builders was updated to explicitly accept `undefined` as its first argument (the state), which causes the initial state to be used (when using `reducerWithInitialState`). While this functionality always existed, the type definitions previously 'hid' it. This change aligns with Redux type definitions.
  Fix: Be aware that reducers correctly handle `undefined` as a state argument (especially for `reducerWithInitialState`) to trigger initial state usage. Ensure your code accounts for this and doesn't rely on previous type errors for `undefined` state handling.
• gotcha When combining reducers that might have differing or upcasted state types, you may encounter TypeScript errors. The `.build()` method helps to normalize the output type, but complex scenarios might still require careful type management or use of `upcastingReducer`.
  Fix: For complex type interactions, ensure explicit type annotations for state, use `upcastingReducer()` as needed, or review the `typescript-fsa` and Redux documentation on reducer composition and type inference for best practices.

Install

• npm install typescript-fsa-reducers npm
• yarn add typescript-fsa-reducers yarn
• pnpm add typescript-fsa-reducers pnpm

Imports

• reducerWithInitialState
  wrong:

  const { reducerWithInitialState } = require('typescript-fsa-reducers');

  correct:

  import { reducerWithInitialState } from 'typescript-fsa-reducers';

  This is the primary way to start a reducer chain when an initial state is always provided. The library is primarily designed for modern ES Modules and TypeScript.
• reducerWithoutInitialState
  wrong:

  import reducerWithoutInitialState from 'typescript-fsa-reducers';

  correct:

  import { reducerWithoutInitialState } from 'typescript-fsa-reducers';

  Used to create a reducer builder without an initial state, treating `undefined` as a regular state value. It's a named export, not a default.
• upcastingReducer
  wrong:

  const upcastingReducer = require('typescript-fsa-reducers').upcastingReducer;

  correct:

  import { upcastingReducer } from 'typescript-fsa-reducers';

  Used for more advanced reducer composition scenarios involving state type upcasting. Follows standard named import conventions.

Quickstart

Demonstrates defining a typesafe Redux reducer using `reducerWithInitialState`, handling different action types with `.case()`, adding a default handler, and calling `.build()` to finalize the reducer. It also shows basic reducer usage.

import actionCreatorFactory from 'typescript-fsa';
import { reducerWithInitialState } from 'typescript-fsa-reducers';

const actionCreator = actionCreatorFactory();

interface State {
    name: string;
    balance: number;
    isFrozen: boolean;
}

const INITIAL_STATE: State = {
    name: 'Untitled',
    balance: 0,
    isFrozen: false,
};

const setName = actionCreator<string>('SET_NAME');
const addBalance = actionCreator<number>('ADD_BALANCE');
const setIsFrozen = actionCreator<boolean>('SET_IS_FROZEN');

const myReducer = reducerWithInitialState(INITIAL_STATE)
    .case(setName, (state, name) => ({ ...state, name }))
    .case(addBalance, (state, amount) => ({
        ...state,
        balance: state.balance + amount,
    }))
    .case(setIsFrozen, (state, isFrozen) => ({ ...state, isFrozen }))
    .default((state, action) => {
        // Handle any unhandled actions or simply return the state.
        console.log(`Unhandled action: ${action.type}`);
        return state;
    })
    .build(); // Don't forget to call .build() to get the final reducer function

// Example usage (typically with Redux store)
let currentState = myReducer(undefined, { type: '@@INIT' }); // Initial state
console.log('Initial state:', currentState); // { name: 'Untitled', balance: 0, isFrozen: false }

currentState = myReducer(currentState, setName('Alice'));
console.log('After setName:', currentState); // { name: 'Alice', balance: 0, isFrozen: false }

currentState = myReducer(currentState, addBalance(100));
console.log('After addBalance:', currentState); // { name: 'Alice', balance: 100, isFrozen: false }

currentState = myReducer(currentState, { type: 'UNKNOWN_ACTION' });
console.log('After UNKNOWN_ACTION:', currentState); // { name: 'Alice', balance: 100, isFrozen: false } (and console log for unhandled action)