npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

typescript-fsa-reducers-vanuan

v1.3.0

Published

Fluent syntax for defining typesafe Redux reducers on top of typescript-fsa.

Downloads

5

Readme

TypeScript FSA Reducers

Fluent syntax for defining typesafe Redux reducers on top of typescript-fsa.

Build
Status

Introduction

This library will allow you to write typesafe reducers that look like this:

const reducer = reducerWithInitialState(INITIAL_STATE)
    .case(setName, setNameHandler)
    .case(addBalance, addBalanceHandler)
    .case(setIsFrozen, setIsFrozenHandler);

It removes the boilerplate normally associated with writing reducers, including if-else chains, the default case, and the need to pull the payload field off of the action.

Table of Contents

Usage

This library allows you to define reducers by chaining a series of handlers for different action types and optionally providing an initial value. It builds on top of and assumes familiarity with the excellent typescript-fsa.

Suppose we have used typescript-fsa to define our state and some actions:

import actionCreatorFactory from "typescript-fsa";
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");

Using vanilla typescript-fsa, we might define a reducer as follows:

import { Action } from "redux";
import { isType } from "typescript-fsa";

function reducer(state = INITIAL_STATE, action: Action): State {
    if (isType(action, setName)) {
        return { ...state, name: action.payload };
    } else if (isType(action, addBalance)) {
        return {
            ...state,
            balance: state.balance + action.payload,
        };
    } else if (isType(action, setIsFrozen)) {
        return { ...state, isFrozen: action.payload };
    } else {
        return state;
    }
}

Using this library, the above is exactly equivalent to the following code:

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

const reducer = reducerWithInitialState(INITIAL_STATE)
    .case(setName, (state, name) => ({ ...state, name }))
    .case(addBalance, (state, amount) => ({
        ...state,
        balance: state.balance + amount,
    }))
    .case(setIsFrozen, (state, isFrozen) => ({ ...state, isFrozen }));

Note that unlike the vanilla case, there is no need to pull the payload off of the action, as it is passed directly to the handler, nor is it necessary to specify a default case which returns state unmodified.

Everything is typesafe. If the types of the action payload and handler don't line up, then TypeScript will complain. If you find it easier to read, you can of course pull out the handlers into separate functions, as shown in the Introduction.

If the full action is needed rather than just the payload, .caseWithAction() may be used in place of .case(). This may be useful if you intend to pass the action unchanged to a different reducer, or if you need to read the meta field of the action. For example:

import { Action } from "typescript-fsa";

const setText = actionCreator<string>("SET_TEXT");

const reducer = reducerWithInitialState({
    text: "",
    lastEditBy: "",
}).caseWithAction(incrementCount, (state, { payload, meta }) => ({
    text: payload,
    lastEditBy: meta.author,
}));

// Returns { text: "hello", lastEditBy: "cbrontë" }.
reducer(undefined, setText("hello", { author: "cbrontë" }));

Further, a single handler may be assigned to multiple action types at once using .cases() or .casesWithAction():

const reducer = reducerWithInitialState(initialState).cases(
    [setName, addBalance],
    (state, payload) => {
        // Payload has type SetNamePayload | AddBalancePayload.
        // ...

        // Make sure to return the updated state, or TypeScript will give you a
        // rather unhelpful error message.
        return state;
    },
);

The reducer builder chains are mutable. Each call to .case() modifies the callee to respond to the specified action type. If this is undesirable, see the .build() method below.

Installation

For this library to be useful, you will also need typescript-fsa to define your actions.

With Yarn:

yarn add typescript-fsa-reducers typescript-fsa

Or with NPM:

npm install --save typescript-fsa-reducers typescript-fsa

API

Starting a reducer chain

reducerWithInitialState(initialState)

Starts a reducer builder-chain which uses the provided initial state if passed undefined as its state. For example usage, see the Usage section above.

reducerWithoutInitialState()

Starts a reducer builder-chain without special logic for an initial state. undefined will be treated like any other value for the state.

Redux seems to really want you to provide an initial state for your reducers. Its createStore API encourages it and combineReducers function enforces it. For the Redux author's reasoning behind this, see this thread. For this reason, reducerWithInitialState will likely be the more common choice, but the option to not provide an initial state is there in case you have some means of composing reducers for which initial state is unnecessary.

Note that since the type of the state cannot be inferred from the initial state, it must be provided as a type parameter:

const reducer = reducerWithoutInitialState<State>()
    .case(setName, setNameHandler)
    .case(addBalance, addBalanceHandler)
    .case(setIsFrozen, setIsFrozenHandler);

upcastingReducer()

Starts a builder-chain which produces a "reducer" whose return type is a supertype of the input state. This is most useful for handling a state which may be in one of several "modes", each of which responds differently to actions and can transition to the other modes. Many applications will not have a use for this.

Note that the function produced is technically not a reducer because the initial and updated states are different types.

Example usage:

type State = StoppedState | RunningState;

interface StoppedState {
    type: "STOPPED";
}

interface StartedState {
    type: "STARTED";
    count: number;
}

const INITIAL_STATE: State = { type: "STOPPED" };

const startWithCount = actionCreator<number>("START_WITH_COUNT");
const addToCount = actionCreator<number>("ADD_TO_COUNT");
const stop = actionCreator<void>("STOP");

function startWithCountHandler(state: StoppedState, count: number): State {
    return { type: "STARTED", count };
}

function addToCountHandler(state: StartedState, count: number): State {
    return { ...state, count: state.count + count };
}

function stopHandler(state: StartedState): State {
    return { type: "STOPPED" };
}

const stoppedReducer = upcastingReducer<StoppedState, State>()
    .case(startWithCount, startWithCountHandler);

const startedReducer = upcastingReducer<StartedState, State>()
    .case(addToCount, addToCountHandler)
    .case(stop, stopHandler);

function reducer(state = INITIAL_STATE, action: Redux.Action): State {
    if (state.type === "STOPPED") {
        return stoppedReducer(state, action);
    } else if (state.type === "STARTED") {
        return startedReducer(state, action);
    } else {
        throw new Error("Unknown state");
    }
}

Reducer chain methods

.case(actionCreator, handler(state, payload) => newState)

Mutates the reducer such that it applies handler when passed actions matching the type of actionCreator. For examples, see Usage.

.caseWithAction(actionCreator, handler(state, action) => newState)

Like .case(), except that handler receives the entire action as its second argument rather than just the payload. This is useful if you want to read other properties of the action, such as meta or error, or if you want to pass the entire action unmodified to some other function. For an example, see Usage.

.cases(actionCreators, handler(state, payload) => newState)

Like .case(), except that multiple action creators may be provided and the same handler is applied to all of them. That is,

reducerWithInitialState(initialState).cases(
    [setName, addBalance, setIsFrozen],
    handler,
);

is equivalent to

reducerWithInitialState(initialState)
    .case(setName, handler)
    .case(addBalance, handler)
    .case(setIsFrozen, handler);

Note that the payload passed to the handler may be of the type of any of the listed action types' payloads. In TypeScript terms, this means it has type P1 | P2 | ..., where P1, P2, ... are the payload types of the listed action creators.

The payload type is inferred automatically for up to four action types. After that, it must be supplied as a type annotation, for example:

reducerWithInitialState(initialState).cases <
    { documentId: number } >
    ([
        selectDocument,
        editDocument,
        deleteDocument,
        sendDocument,
        archiveDocument,
    ],
    handler);

.casesWithAction(actionCreators, handler(state, action) => newState)

Like .cases(), except that the handler receives the entire action as its second argument rather than just the payload.

.withHandling(updateBuilder(builder) => builder)

Convenience method which applies the provided function to the current builder and returns the result. Useful if you have a sequence of builder updates (calls to .case(), etc.) which you want to reuse across several reducers.

.default(handler(state, action) => newState)

Produces a reducer which applies handler when no previously added .case(), .caseWithAction(), etc. matched. The handler is similar to the one in .caseWithAction(). Note that .default() ends the chain and internally does the same as .build(), because it is not intended that the chain be mutated after calling .default().

This is useful if you have a "delegate" reducer that should be called on any action after handling a few specific actions in the parent.

const NESTED_STATE = {
    someProp: "hello",
};

const nestedReducer = reducerWithInitialState(NESTED_STATE)
    .case(...);

const INITIAL_STATE = {
    someOtherProp: "world"
    nested: NESTED_STATE
};

const reducer = reducerWithInitialState(INITIAL_STATE)
    .case(...)
    .default((state, action) => ({
        ...state,
        nested: nestedReducer(state.nested, action),
    }));

.build()

Returns a plain reducer function whose behavior matches the current state of the reducer chain. Further updates to the chain (through calls to .case()) will have no effect on this function.

There are two reasons you may want to do this:

  1. You want to ensure that the reducer is not modified further

    Calling .build() is an example of defensive coding. It prevents someone from causing confusing behavior by importing your reducer in an unrelated file and adding cases to it.

  2. You want your package to export a reducer, but not have its types depend on typescript-fsa-reducers

    If the code that defines a reducer and the code that uses it reside in separate NPM packages, you may run into type errors since the exported reducer has type ReducerBuilder, which the consuming package does not recognize unless it also depends on typescript-fsa-reducers. This is avoided by returning a plain function instead.

Example usage:

const reducer = reducerWithInitialState(INITIAL_STATE)
    .case(setName, setNameHandler)
    .case(addBalance, addBalanceHandler)
    .case(setIsFrozen, setIsFrozenHandler)
    .build();

Copyright © 2017 David Philipson