Registry / web-framework / typescript-fsa-reducers

typescript-fsa-reducers

library1.2.2jsnpmunverified

TypeScript FSA Reducers provides a fluent, typesafe API for defining Redux reducers. It builds on `typescript-fsa` to streamline reducer creation by removing common boilerplate such as `if-else` chains for action type checking and manual extraction of payloads from actions. Instead, it offers a method-chaining approach with dedicated handlers for specific action creators. The current stable version is 1.2.2. While there isn't a strictly defined release cadence, the library has demonstrated consistent updates and a commitment to stability, notably reaching version 1.0.0. Its key differentiators include the fluent builder pattern (`.case()`, `.default()`, `.withHandling()`, `.build()`), strong type inference for state and payloads, and direct integration with `typescript-fsa`'s action creators, making reducer logic concise and highly maintainable in TypeScript Redux applications.

web-framework

npm install typescript-fsa-reducers

github ↗package ↗

INSTALL

IMPORT

SIG · TYPESCRIPT-FSA-RED

typescript-fsa-reducers

web-frameworkjavascriptv1.2.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

reducerWithInitialState

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

✗ const { reducerWithInitialState } = require('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

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

✗ 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

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

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

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

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)

Debug

Known issues

breakingIn `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`.

affects: >=1.0.0

breakingIn `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();`.

affects: >=0.4.0

gotchaStarting 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`.

affects: >=1.2.2

gotchaIn `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.

affects: >=0.4.5

gotchaWhen 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.

affects: >=0.4.0

Errors

Common errors & fixes

TypeError: reducer is not a function

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.

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'.

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`.

Upgrade

Version history

1.2.2latest on npm

Audit

Dependencies

typescript-fsarequiredCore dependency for creating typesafe actions that this library consumes. It became a peer dependency in v1.0.0.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/dphilipson/typescript-fsa-reducers ↗

packagehttps://www.npmjs.com/package/typescript-fsa-reducers ↗