adonisjs-state-machines

What problem does it solve?

Managing complex domain lifecycles in AdonisJS Lucid models is error-prone without a structured pattern. This Skill provides a zero-dependency, type-safe state machine approach that enforces valid state transitions, supports guards and side effects, and optionally logs transitions for auditing.

Core Features & Use Cases

• Static transition maps defined on the state machine class to eliminate per-instance closures and prevent memory leaks.
• Guards that throw on invalid transitions to ensure business rules are always enforced.
• After-transition hooks to perform side effects (emails, events) after a successful transition without retaining model references.
• Optional audit trail via a state_transitions table to track model_type, column, and state changes for traceability.
• Real-world pattern: model an Order lifecycle from Draft to Completed with terminal states and guards.

Quick Start

Define the enum, create a StateMachine subclass with transitions and guards, attach it to a model via HasStateMachine, then perform transitions using model.stateMachine('column').transitionTo(TargetState).