jmeinlschmidt / rxjs-fsm

Finite state machine using RxJS!

rxjs-fsm

This package provides a set of tools for utilizing complete deterministic finite automata (Finite state machine) in RxJS with a focus on functional programming. Allowing developers to efficiently manage complex state machines in context of reactive programming.

✅  Tree Shakeable (ES modules)
✅  Fully Typed
✅  Unit Tests
✅  Documentation

Installation

npm i @jkba/rxjs-fsm

Example Usage

Let's consider the following use-case as an example. It is discussed in detail in a dedicated blog post.

In the very first step, let's represent this automata:

export type Input = 'toggle' | 'hide';
export type State = 'hidden' | 'shown';

export const transitions: StateTransitions<State, Input> = {
  hidden: {
    toggle: 'shown',
    hide: 'hidden',
  },
  shown: {
    toggle: 'hidden',
    hide: 'hidden',
  },
};

Suppose we represent inputs as Observables and the initial state as a constant:

const toggle$ = new Subject<void>();
const hide$ = new Subject<void>();

const initialState: State = 'hidden';

It is necessary to create a single input Observable and mark individual values in order to retain proper types. For this purpose, let's use fsmHelpersFactory function.

const { markInput } = fsmHelpersFactory<State, Input>(transitions);

const input$ = merge(
  toggle$.pipe(markInput('toggle')),
  hide$.pipe(markInput('hide')),
);

Finally, we can create the machine object:

const machine = rxjsFsmFactory(transitions, input$, initialState);

Listen to the current state:

machine.selectState().subscribe(console.log);

// Emits only on `hidden` state
machine.selectState('hidden').subscribe(console.log);

Minimalistic

Another approach is to avoid the machine object and use this library in a pipe with an existing Observable:

const {
  fsm,
  markInput,
} = fsmHelpersFactory<State, Input>(transitions);

const state$ = input$.pipe(fsm(initialState));

state$.subscribe(console.log);

Build

Use npm link and then npm link @jkba/rxjs-fsm in your project.

Release

Use npm version, don't forget to push the tag and the CI will take care of the rest.

License

This project is licensed under MIT License. For the full text of the license, see the LICENSE file.

rxjs-fsm's Issues

Add Prettier

and don't forget the badge ;-) https://github.com/prettier/prettier

Consider state management libraries integration

Consider integrating this package to state management libraries such as ngrx/component-store or Elf.

Idea: Connect to store via custom method withFsm.

Reference

• https://github.com/ngneat/elf/blob/master/packages/entities/src/lib/entity.state.ts#L64
• https://ngneat.github.io/elf/docs/features/entities-management/entities

CI for release

Nondeterministic automata

Consider transition function accepting functions as new states:

const transitions: TransitionFn = {
  hidden: {
    toggle: 'shown',
    hide: 'hidden',
  },
  shown: {
    toggle: 'hidden',
    hide: () => hasPermissions ? 'hidden' : 'shown',
  },
};

Error handling

Since this package uses only complete automata, undefined (or error) state needs to be used in order to represent missing states.

Add Hooks

Allow function hooks (callbacks) for accessing state and leaving state.

ESLint