Getting Started

Installation

Install the package using your preferred package manager:

npm install statecharts.sh

pnpm add statecharts.sh

bun add statecharts.sh

Your First Statechart

Create a simple toggle statechart:

import { chart } from "statecharts.sh";

const toggle = chart({
  context: {},
  initial: "inactive",
  states: {
    inactive: {
      on: { TOGGLE: "active" },
    },
    active: {
      on: { TOGGLE: "inactive" },
    },
  },
});

Starting an Instance

A chart is a blueprint. To run it, create an instance:

const instance = toggle.start();

console.log(instance.state.value); // "inactive"

instance.send("TOGGLE");
console.log(instance.state.value); // "active"

Subscribing to State Changes

React to state transitions:

instance.subscribe((state) => {
  console.log("Current state:", state.value);
});

instance.send("TOGGLE"); // logs: "Current state: inactive"

Using Context

Store data alongside state:

const counter = chart({
  context: { count: 0 },
  initial: "idle",
  states: {
    idle: {
      on: {
        INCREMENT: {
          actions: (ctx) => ({ count: ctx.count + 1 }),
        },
        DECREMENT: {
          actions: (ctx) => ({ count: ctx.count - 1 }),
        },
      },
    },
  },
});

const instance = counter.start();
instance.send("INCREMENT");
console.log(instance.state.context.count); // 1

Next Steps

• Learn how to use statecharts with React
• Explore the API Reference for full documentation
• See Examples for real-world patterns