@stefanobalocco/jcfsm

jCFSM

A compact finite state machine for JavaScript and TypeScript, with async callback support and zero runtime dependencies.

Features

• Explicit transitions — only registered transitions succeed; all others return false
• Four callback hooks — OnBefore, OnLeave, OnAfter, OnEnter — sync or async
• Guard support — OnBefore callbacks abort a transition by returning false
• Re-entrant safe — StateSet calls nested inside a callback return false without side effects
• Zero dependencies — no runtime dependencies
• TypeScript — full type definitions included

Installation

npm / bundler:

npm install jcfsm

Browser (CDN):

<script type="module">
	import jCFSM from 'https://unpkg.com/jcfsm@2.0.0/jcfsm.min.js';

	const fsm = new jCFSM( 'idle' );
	fsm.StateAdd( 'running' );
	fsm.TransitionAdd( 'idle', 'running' );

	await fsm.StateSet( 'running' );
	console.log( fsm.state ); // 'running'
</script>

Quick Start

import jCFSM from 'jcfsm';

const fsm = new jCFSM( 'idle' );

fsm.StateAdd( 'running' );
fsm.StateAdd( 'stopped' );

fsm.TransitionAdd( 'idle', 'running' );
fsm.TransitionAdd( 'running', 'stopped' );

fsm.StateOnEnterAdd( 'running', ( current, prev ) => {
	console.log( `Entered ${current} from ${prev}` );
} );

fsm.TransitionOnBeforeAdd( 'running', 'stopped', async () => {
	const allowed = await checkIfStopIsAllowed();
	return allowed;
} );

await fsm.StateSet( 'running' ); // true
await fsm.StateSet( 'idle' );    // false — no transition defined
await fsm.StateSet( 'stopped' ); // true or false — depends on the guard

Callback Execution Order

When StateSet succeeds, callbacks fire in this order:

OnBefore → OnLeave → OnAfter → OnEnter

If any OnBefore callback returns false, the transition aborts immediately. OnLeave, OnAfter, and OnEnter do not fire.

API

Constructor

new jCFSM( initialState: string )

Creates a new FSM. The initial state is registered automatically.

---

State management

Method	Returns	Description
StateAdd( state )	boolean	Registers a new state. Returns false if the state already exists.
StateDel( state )	boolean	Removes a state and all its associated transitions. Returns false if the state does not exist.
state	string	Returns the current state.
StateSet( state )	Promise<boolean>	Triggers a transition to state. Returns false if the transition is not defined, if a guard aborts it, or if another transition is already in progress.

---

State callbacks

These callbacks fire whenever the machine enters or leaves a specific state, regardless of which transition triggered the change.

Signatures:

type FunctionOnEnter = ( currentState: string, prevState: string ) => void | Promise<void>;
type FunctionOnLeave = ( currentState: string, nextState: string ) => void | Promise<void>;

Method	Description
StateOnEnterAdd( state, func )	Registers a callback that fires after entering state. Returns false if the state does not exist or the callback is already registered.
StateOnEnterDel( state, func )	Removes an enter callback. Returns false if the callback is not found.
StateOnLeaveAdd( state, func )	Registers a callback that fires before leaving state. Returns false if the state does not exist or the callback is already registered.
StateOnLeaveDel( state, func )	Removes a leave callback. Returns false if the callback is not found.

---

Transition management

Transitions define which state changes are allowed. StateSet fails unless the corresponding transition is registered.

Method	Returns	Description
TransitionAdd( from, to )	boolean	Registers the transition from from to to. Returns false if either state does not exist or the transition already exists.
TransitionDel( from, to )	boolean	Removes the transition. Returns false if the transition does not exist.

---

Transition callbacks

These callbacks fire only for a specific from → to pair.

Signatures:

type FunctionOnTransitionBefore = () => boolean | Promise<boolean>;
type FunctionOnTransitionAfter  = () => void    | Promise<void>;

Method	Description
TransitionOnBeforeAdd( from, to, func )	Registers a guard that fires before the transition. Return false to abort. Returns false if the transition does not exist.
TransitionOnBeforeDel( from, to, func )	Removes a before callback. Returns false if the callback is not found.
TransitionOnAfterAdd( from, to, func )	Registers a callback that fires after the transition completes. Returns false if the transition does not exist.
TransitionOnAfterDel( from, to, func )	Removes an after callback. Returns false if the callback is not found.

---

License

See LICENSE.md.