little-fsm

• What is little-fsm?
• Installation
• Quick Start

What is little-fsm?

A strongly-typed lightweight state machine.

Installation

npm

1npm install little-fsm --save

Check the npm repository of little-fsm for details.

Quick Start

Let's construct a state machine to model the state transitions in a vending machine.

• The vending machine starts in an idle state, waiting for user interaction.
• When a customer inserts money, the machine transitions to the ready-to-order state, signaling that it is prepared to accept a selection.
• Once the customer chooses a product, the machine enters the dispensing state, where it delivers the chosen item to the customer.
• After dispensing, the machine transitions to the refunding state, where it returns the excess amount.
• Once the refund (if any) is complete, the machine returns to the idle state, ready for the next customer interaction.

Fsm with empty context

1import { NoContext, retainContext, FsmBuilder } from "little-fsm"
2
3type VendingMachineManifest = {
4    states: {
5        'idle': NoContext, 
6        'ready-to-order': NoContext,
7        'dispensing-item': NoContext,
8        'refunding': NoContext
9    },
10    events: {
11        "money-inserted": {},
12        "item-selected" : {},
13        "item-dispensed": {}
14        "cancelled" : {},
15        "refunded" : {},
16    }
17}
18
19function buildFsm(): Fsm<VendingMachineManifest> {
20    let builder = new FsmBuilder<VendingMachineManifest>();
21
22    builder.simpleState('idle')
23        .transition('money-inserted', 'ready-to-order', retainContext);
24
25    builder.simpleState('ready-to-order')
26        .transition('item-selected', 'dispensing-item', retainContext)
27        .transition('cancelled', 'refunding', retainContext);
28
29    builder.simpleState('dispensing-item')
30        .transition('item-dispensed', 'refunding', retainContext);
31
32    builder.simpleState('refunding')
33        .transition('refunded', 'idle', retainContext);
34
35    return builder.build();
36}

The initial state in your vending machine's state machine can be set this way:

1let fsm = buildFsm();    
2fsm.init('idle', {});

When the customer inserts money, we trigger an event to the finite state machine (FSM).

1fsm.processEvent('money-inserted', {})

Fsm with the context in ready-to-order state

Here’s how to incorporate the concept of an amount balance in the context of the ready-to-order state:

1...
2type VendingMachineManifest = {
3    states: {
4        'idle': NoContext,
5        'ready-to-order': {
6            context: {
7                balanceAmount:number
8            }
9        },
10        'dispensing-item': NoContext,
11        'refunding': NoContext
12    },
13    events: {
14        "money-inserted": {insertedAmount:number},
15        "item-selected" : {},
16        "item-dispensed": {}
17        "cancelled" : {},
18        "refunded" : {},
19    }
20}
21...

When the customer inserts money, the system transitions to the ready-to-order state. At this point, the context is changed to NoContext to {amountBalance:number}.

Notice that the new state context is derived from the existing state context and the event data.

1...
2builder.simpleState('idle')
3    .transition('money-inserted', 'ready-to-order', 
4        (context, event) => {
5            return {amountBalance: event.insertedAmount}
6        });
7...

When inserting money while the system is already at ready-to-order state.

1builder.simpleState('ready-to-order')
2    .transition('item-selected', 'dispensing-item', retainContext)
3    .transition('cancelled', 'refunding', retainContext)
4    .transition('money-inserted', 'ready-to-order', (ctx, event) => {
5        return {
6            balanceAmount: ctx.balanceAmount + event.insertedAmount
7        }
8    });

When the customer inserts money, we trigger an event to the finite state machine (FSM).

1fsm.processEvent('money-inserted', {
2    insertedAmount: 5
3})

You can observe the state entry into ready-to-order state:

1fsm.setEntryEffect('ready-to-order', ctx => {
2    // display balance on screen
3    // or play sounds to notify user of ready to order stage
4    console.log("Current balance:", ctx.balanceAmount);
5})

Example implementation of observing the entry into the dispensing-item state:

1fsm.setEntryEffect('dispensing-item', ctx => {
2    // Simulating the duration of dispensing a product item.
3    // In reality, you may be listening to a hardware event.
4    setTimeout(() => {
5        fsm.processEvent('item-dispensed')
6    }, 5000); // 5 seconds
7})