automata-reducer

a tiny (< 0.5kb gzip) finite-state-machine that switches reducers. no dependencies.

since version 3.0, an optional functional operator may be supplied to the factory. that operator is applied to the automata reducer only for known events, i.e. events for which a reducer or list of reducers is defined in the automata spec. unknown events trigger a default value reducer for proper initialization. this is useful for e.g. efficiently applying the automata reducer through a cursor (lense): for example, to apply an automata to a single todo instance in a list of todo instances for relevent events only.

example

see this example in this directory. run this example in your browser.

import createAutomataReducer, { AutomataSpec, StandardAction } from 'automata-reducer'
import { propCursor } from 'basic-cursors'
import actions from './actions'
import logger from './console'
const log = logger()

interface State {
  state: AutomataState
  value: number
}

type AutomataState = 'init' | 'idle'

const inValue = propCursor('value')

const automata: AutomataSpec<AutomataState,State> = {
  init: {
    IDLE: 'idle',
    INCREMENT: [inValue(increment), 'idle']
  },
  idle: {
    RESET: ['init', inValue(reset)],
    INCREMENT: inValue(increment)
  }
}

function increment (value: number = 0, { payload }: StandardAction<number>) {
  return value + +payload
}

function reset (): number {
  return 0
}

const reducer = createAutomataReducer(automata, 'init')

const idle = reducer(void 0, actions.IDLE())
log('IDLE(): %O', idle) // IDLE(): {"state":"idle"}
const fourtytwo = reducer(idle, actions.INCREMENT(42))
log('INCREMENT(42): %O', fourtytwo) // INCREMENT(42): {"state":"idle","value":42}
const init = reducer(fourtytwo, actions.RESET())
log('RESET(): %O', init) // RESET(): {"state":"init","value":0}

API v3.2

as demonstrated in the above example, for each automata state, the automata spec defines a single reducer or a list of reducers for each action (or event) relevant to that state.

• a string is replaced by a reducer of the automata's state that sets the latter to that string.
• reducers listed in an array are executed sequentially, from right to left (last to first).

when combined with a propCursor from the basic-cursors module which applies a reducer to a named property of the state object, and only updates the state if the reducer returns a different value, reducers can be minimized to very simple functions, resulting in a self-documenting the automata spec, such as in the above example.

export declare type AutomataSpec<
  X extends string | number,
  S = any,
  P = any,
  A = StandardAction<P>
> = { [state in X]: ReducerSpec<X, S, P, A> }

export interface ReducerSpec<
  X extends string | number,
  S = any,
  P = any,
  A = StandardAction<P>
> {
  [type: string]: (Reducer<S, P, A> | X)[] | Reducer<S, P, A> | X
}

export declare type Reducer<S, P = any, A = StandardAction<P>> = (
  state?: S,
  action?: A
) => S

export interface StandardAction<P = any> {
  type: string
  payload?: P
}

export interface AutomataReducerOptions<
  X extends string | number = string,
  K extends string | number = 'state',
  I extends { [key in K]: X } = { [key in K]: X },
  O = I,
  P = any
> {
  key: K
  toStandardAction: ActionStandardizer<P>
  operator: Operator<I, O>
}

export declare type ActionStandardizer<P = any> = <A>(
  action: A
) => StandardAction<P>

export declare type Operator<I = {}, O = I> = (
  fn: (i: I, ...args: any[]) => I
) => (o: O, ...args: any[]) => O

export default function createAutomataReducer<
  X extends string | number,
  K extends string | number = 'state',
  I extends { [key in K]: X } = { [key in K]: X },
  O = I,
  P = any,
  A = StandardAction<P>
> (
  automata: AutomataSpec<X, I, P, A>,
  init: X,
  opts?: Partial<AutomataReducerOptions<X, K, I, O, P>> | string
): Reducer<O, P, A>

for a detailed specification of this API, run the unit tests in your browser.

TypeScript

although this library is written in TypeScript, it may also be imported into plain JavaScript code: modern code editors will still benefit from the available type definition, e.g. for helpful code completion.

License

Copyright 2018 Stéphane M. Catala

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and Limitations under the License.