Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lexkrstn/fsm
A strongly typed finite state machine for TypeScript/JavaScript with zero dependencies.
https://github.com/lexkrstn/fsm
finite-state-machine fsm javascript typescript
Last synced: 10 days ago
JSON representation
A strongly typed finite state machine for TypeScript/JavaScript with zero dependencies.
- Host: GitHub
- URL: https://github.com/lexkrstn/fsm
- Owner: lexkrstn
- License: mit
- Created: 2022-10-07T14:13:49.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2022-10-07T23:26:22.000Z (over 2 years ago)
- Last Synced: 2025-01-09T00:54:12.061Z (about 1 month ago)
- Topics: finite-state-machine, fsm, javascript, typescript
- Language: TypeScript
- Homepage:
- Size: 407 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://badge.fury.io/js/@lexkrstn%2Ffsm)
# Finite State Machine
Finite state machines are useful for modeling complicated flows and keeping
track of state. The package provides a strongly typed FSM implementation for
TypeScript and JavaScript.
## Motivation
Theoretically, the FSM must comprise only 2 key elements:
- states
- transitions between them
In practice, though, implementations typically have at least one of the
following flaws:
1. **Mixing up multiple patterns**, such as inheriting States from Strategies.
There is nothing wrong with this approach if you're not planning to reuse
FSM anywhere else. But it's a bad idea for a library, because not every
problem requires this mix. In the example below I'm demonstrating how to
make use of the both patterns together separating the concerns.
2. **States with onEnter/onExit handlers only**. This approach assumes that
these two handlers can independently compose a transition function, which
is not the case if the transition depends on both the previous and the
next state.
3. **Making the client to extend a state class**. First, it doesn't make sense
to incapsulate each state in a separate class, unless you're mixing it
with the Strategy pattern. Secondly, it's not unusual to find youself
having to repeat the same blocks of code again and again, especially if the
State implementation has the onEnter/onExit handlers for transitions.
All these reasons prompted me to write this library.
## Features:
- SRP-compliant
- Type-safe
- Only 1 KB (minified)
- Zero dependencies
- Asynchronous transitions
- Simple state and transition definition
## Installation:
```bash
npm i -S @lexkrstn/fsm
```
## Example:
In the following example, I'm modeling a Player class for a game.
Notice how multiple patterns can be used together without mixing conserns.
```typescript
// Declare states and events.
type PlayerStates = 'staying' | 'running' | 'dead';
type PlayerEvents = Event<'stop'> | Event<'run', [number, number]> | Event<'die'>;
// Define player strategies
interface PlayerStrategy {
onUpdate(dt: number): void;
}
class RunStrategy implements PlayerStrategy {
public onUpdate(dt: number) {
console.log('running');
}
}
class StayStrategy implements PlayerStrategy {
public onUpdate(dt: number) {
console.log('staying');
}
}
class DeadStrategy implements PlayerStrategy {
public onUpdate(dt: number) {
console.log('dead');
}
}
function playerStrategyFactory(state: PlayerStates): PlayerStrategy {
switch (state) {
case 'staying': return new StayStrategy();
case 'running': return new RunStrategy();
case 'dead': return new DeadStrategy();
default:
throw new Error(`Unknown state: ${state}`);
}
}
class Player implements PlayerStrategy {
private fsm: FSM;
private strategy: PlayerStrategy = new StayStrategy();
public constructor(initialState: PlayerStates = 'staying') {
this.strategy = playerStrategyFactory(initialState);
this.fsm = new FSM(
initialState,
[
['running', 'stop', 'staying', this.transitionToStaying],
['staying', 'run', 'running', this.transitionToRunning],
['*', 'die', 'dead', this.transitionToDead],
],
);
}
public stop() { return this.fsm.dispatch('stop'); }
public die() { return this.fsm.dispatch('die'); }
public run(x: number, y: number) { return this.fsm.dispatch('run', x, y); }
public isRunning() { return this.fsm.getState() === 'running'; }
public isStaying() { return this.fsm.getState() === 'staying'; }
public isDead() { return this.fsm.getState() === 'dead'; }
public isControllable() { return !this.fsm.isFinal(); }
public can(action: EventType) { return this.fsm.can(action); }
public onUpdate(dt: number) {
this.strategy.onUpdate(dt);
}
private transitionToStaying = async () => {
this.strategy = new StayStrategy();
await timeout(); // Emulate some async work
};
private transitionToRunning = async (x: number, y: number) => {
this.strategy = new RunStrategy();
await timeout(); // Emulate some async work
};
private transitionToDead = () => {
this.strategy = new DeadStrategy();
};
}
(async () => {
const player = new Player();
// Dispatch the 'run' event with 2 parameters (position x, y) and wait
// for the transition to complete.
await player.run(0, 0);
player.isRunning(); // => true
// Check if the player can stop (i.e. the FSM can dispatch this event)
player.can('stop'); // => true
// Kill the player, but don't wait.
await player.die();
// Did we reach the final state?
player.isControllable(); // => false
})();
```