Stategate

A flexible, type-safe state machine library for JavaScript/TypeScript projects. Easily manage entity state transitions, enforce business rules, and hook into lifecycle events.

Features

• Type-safe state transitions
• Abortable transitions with custom handlers
• Global hooks for before/after/error/invalid transitions
• Extensible event system
• Designed for use in Node.js and browser environments

Installation

npm install @dixxanta08/stategate

Usage

import { StateMachine } from "@dixxanta08/stategate";

const config = {
  initialState: "pending",
  transitions: {
    pending: {
      approved: {
        isAbortable: true,
        onBefore: async (entity) => {
          // Custom logic before transition
        },
        onAfter: async (entity) => {
          // Custom logic after transition
        },
        onAbort: (payload) => {
          console.log("Transition aborted", payload);
        },
        details: {
          label: "Approve",
          description: "Approve the entity",
          allowedActors: "admin",
        },
      },
    },
    approved: {
      archived: {
        onBefore: async (entity) => {
          // Custom logic
        },
      },
    },
  },
  globalHooks: {
    beforeTransition: [
      async (payload) => {
        console.log("Before transition", payload);
      },
    ],
    afterTransition: [
      async (payload) => {
        console.log("After transition", payload);
      },
    ],
    onInvalidTransition: (payload) => {
      console.error("Invalid transition", payload);
    },
    onError: (error, payload) => {
      console.error("Transition error", error, payload);
    },
  },
};

const entity = { status: "pending" };
const machine = new StateMachine(config);

machine.transition(entity, "approved", { actor: "admin" });

API

StateMachine

• constructor(config: MachineConfig) — Initialize with a machine config
• transition(entity, nextState, context?) — Perform a state transition
• on(event, callback) — Register event handler
• emit(event) — Trigger event handlers

Types

• MachineConfig — State machine configuration
• TransitionConfig — Per-transition settings
• TransitionPayload — Transition event payload
• AbortTransition, InvalidTransition — Custom error classes

Upcoming Updates

• Visualizer for state machines
• Built-in validation for transitions and configs
• Metrics/telemetry hooks
• Pre-built common workflows (orders, tasks, etc.)
• Enhanced error handling and cancellation chaining

Stay tuned for more features!

License

MIT