@stravigor/machine 0.4.6

package/README.md

@@ -0,0 +1,98 @@
+# @stravigor/machine
+
+State machine for the [Strav](https://www.npmjs.com/package/@stravigor/core) framework. Declarative state definitions with transitions, guards, side effects, and event emission.
+
+## Install
+
+```bash
+bun add @stravigor/machine
+```
+
+Requires `@stravigor/core` as a peer dependency.
+
+## Usage
+
+### Define a Machine
+
+```ts
+import { defineMachine } from '@stravigor/machine'
+
+const orderMachine = defineMachine({
+  field: 'status',
+  initial: 'pending',
+  states: ['pending', 'processing', 'shipped', 'delivered', 'canceled'],
+  transitions: {
+    process: { from: 'pending', to: 'processing' },
+    ship:    { from: 'processing', to: 'shipped' },
+    deliver: { from: 'shipped', to: 'delivered' },
+    cancel:  { from: ['pending', 'processing'], to: 'canceled' },
+  },
+  guards: {
+    cancel: (order) => !order.locked,
+  },
+  effects: {
+    ship: async (order) => {
+      await sendShippingNotification(order)
+    },
+  },
+  events: {
+    ship:    'order:shipped',
+    deliver: 'order:delivered',
+    cancel:  'order:canceled',
+  },
+})
+```
+
+### Standalone (Any Object)
+
+```ts
+const order = { status: 'pending', id: 1, locked: false }
+
+orderMachine.state(order)                 // 'pending'
+orderMachine.is(order, 'pending')         // true
+orderMachine.can(order, 'process')        // true
+orderMachine.can(order, 'ship')           // false
+orderMachine.availableTransitions(order)  // ['process', 'cancel']
+
+await orderMachine.apply(order, 'process')
+// order.status === 'processing'
+```
+
+### ORM Mixin
+
+```ts
+import { BaseModel } from '@stravigor/core/orm'
+import { stateful } from '@stravigor/machine'
+
+class Order extends stateful(BaseModel, orderMachine) {
+  declare id: number
+  declare status: string
+}
+
+const order = await Order.find(1)
+order.is('pending')               // true
+order.can('ship')                 // false
+order.availableTransitions()      // ['process', 'cancel']
+
+await order.transition('process')
+// validates → mutates → saves → emits event
+
+// Query helpers
+const shipped = await Order.inState('shipped').get()
+const active = await Order.inState(['processing', 'shipped']).get()
+```
+
+## Features
+
+- **Guards** — sync or async functions that must return `true` for a transition to proceed
+- **Effects** — side effects that run after the state is mutated (before persistence in the mixin)
+- **Events** — automatic `Emitter.emit()` after transitions complete
+- **Composable** — works with `compose()` alongside other mixins like `searchable()`
+
+## Documentation
+
+See the full [Machine guide](../../guides/machine.md).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@stravigor/machine",
+  "version": "0.4.6",
+  "type": "module",
+  "description": "State machine for the Strav framework",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "tsconfig.json"
+  ],
+  "peerDependencies": {
+    "@stravigor/core": "0.4.5"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,25 @@
+import { StravError } from '@stravigor/core/exceptions'
+
+/** Thrown when a transition is not valid from the entity's current state. */
+export class TransitionError extends StravError {
+  constructor(
+    public readonly transition: string,
+    public readonly currentState: string,
+    public readonly allowedFrom: string[]
+  ) {
+    super(
+      `Cannot apply transition "${transition}" from state "${currentState}". ` +
+        `Allowed from: [${allowedFrom.join(', ')}]`
+    )
+  }
+}
+
+/** Thrown when a transition's guard rejects the transition. */
+export class GuardError extends StravError {
+  constructor(
+    public readonly transition: string,
+    public readonly currentState: string
+  ) {
+    super(`Guard rejected transition "${transition}" from state "${currentState}".`)
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { defineMachine } from './machine.ts'
+export { stateful } from './stateful.ts'
+export { TransitionError, GuardError } from './errors.ts'
+export type { MachineDefinition, TransitionDefinition, TransitionMeta, Machine } from './types.ts'

package/src/machine.ts

@@ -0,0 +1,134 @@
+import Emitter from '@stravigor/core/events/emitter'
+import type { MachineDefinition, Machine, TransitionMeta } from './types.ts'
+import { TransitionError, GuardError } from './errors.ts'
+
+/**
+ * Define a state machine.
+ *
+ * Returns a `Machine` object that can validate and apply transitions to any entity.
+ * The machine operates on a single field of the entity object.
+ *
+ * @example
+ * const orderMachine = defineMachine({
+ *   field: 'status',
+ *   initial: 'pending',
+ *   states: ['pending', 'processing', 'shipped', 'delivered', 'canceled'],
+ *   transitions: {
+ *     process: { from: 'pending', to: 'processing' },
+ *     ship:    { from: 'processing', to: 'shipped' },
+ *     deliver: { from: 'shipped', to: 'delivered' },
+ *     cancel:  { from: ['pending', 'processing'], to: 'canceled' },
+ *   },
+ *   guards: {
+ *     cancel: (order) => !order.locked,
+ *   },
+ *   effects: {
+ *     ship: async (order) => await sendShippingNotification(order),
+ *   },
+ *   events: {
+ *     ship:    'order:shipped',
+ *     deliver: 'order:delivered',
+ *   },
+ * })
+ */
+export function defineMachine<TState extends string, TTransition extends string>(
+  definition: MachineDefinition<TState, TTransition>
+): Machine<TState, TTransition> {
+  // Pre-compute normalized from-arrays for each transition
+  const fromMap = new Map<TTransition, TState[]>()
+  for (const [name, def] of Object.entries(definition.transitions) as [
+    TTransition,
+    { from: TState | TState[]; to: TState },
+  ][]) {
+    fromMap.set(name, Array.isArray(def.from) ? def.from : [def.from])
+  }
+
+  return {
+    definition,
+
+    state(entity: any): TState {
+      return entity[definition.field] as TState
+    },
+
+    is(entity: any, state: TState): boolean {
+      return entity[definition.field] === state
+    },
+
+    can(entity: any, transition: TTransition): boolean | Promise<boolean> {
+      const currentState = entity[definition.field] as TState
+      const allowed = fromMap.get(transition)
+      if (!allowed || !allowed.includes(currentState)) return false
+
+      const guard = definition.guards?.[transition]
+      if (!guard) return true
+
+      const result = guard(entity)
+      // Support both sync and async guards
+      if (typeof (result as any)?.then === 'function') {
+        return (result as Promise<boolean>).catch(() => false)
+      }
+      return result as boolean
+    },
+
+    availableTransitions(entity: any): TTransition[] {
+      const currentState = entity[definition.field] as TState
+      const available: TTransition[] = []
+
+      for (const [name, fromStates] of fromMap) {
+        if (fromStates.includes(currentState)) {
+          available.push(name)
+        }
+      }
+
+      return available
+    },
+
+    async apply(
+      entity: any,
+      transition: TTransition
+    ): Promise<TransitionMeta<TState, TTransition>> {
+      const currentState = entity[definition.field] as TState
+      const transitionDef = definition.transitions[transition]
+      if (!transitionDef) {
+        throw new TransitionError(transition, currentState, [])
+      }
+
+      const allowed = fromMap.get(transition)!
+      if (!allowed.includes(currentState)) {
+        throw new TransitionError(transition, currentState, allowed)
+      }
+
+      // Run guard
+      const guard = definition.guards?.[transition]
+      if (guard) {
+        const passed = await guard(entity)
+        if (!passed) {
+          throw new GuardError(transition, currentState)
+        }
+      }
+
+      const meta: TransitionMeta<TState, TTransition> = {
+        from: currentState,
+        to: transitionDef.to,
+        transition,
+      }
+
+      // Mutate field
+      entity[definition.field] = transitionDef.to
+
+      // Run effect
+      const effect = definition.effects?.[transition]
+      if (effect) {
+        await effect(entity, meta)
+      }
+
+      // Emit event
+      const eventName = definition.events?.[transition]
+      if (eventName && Emitter.listenerCount(eventName) > 0) {
+        Emitter.emit(eventName, { entity, ...meta }).catch(() => {})
+      }
+
+      return meta
+    },
+  }
+}

package/src/stateful.ts

@@ -0,0 +1,73 @@
+import type BaseModel from '@stravigor/core/orm/base_model'
+import type { NormalizeConstructor } from '@stravigor/core/helpers'
+import type { Machine, TransitionMeta } from './types.ts'
+
+/**
+ * Mixin that adds state machine methods to a BaseModel subclass.
+ *
+ * @example
+ * import { BaseModel } from '@stravigor/core/orm'
+ * import { defineMachine, stateful } from '@stravigor/machine'
+ *
+ * const orderMachine = defineMachine({
+ *   field: 'status',
+ *   initial: 'pending',
+ *   states: ['pending', 'processing', 'shipped'],
+ *   transitions: {
+ *     process: { from: 'pending', to: 'processing' },
+ *     ship:    { from: 'processing', to: 'shipped' },
+ *   },
+ * })
+ *
+ * class Order extends stateful(BaseModel, orderMachine) {
+ *   declare id: number
+ *   declare status: string
+ * }
+ *
+ * const order = await Order.find(1)
+ * order.is('pending')            // true
+ * order.can('process')           // true
+ * await order.transition('process')  // validates, mutates, saves, emits
+ *
+ * // Composable with other mixins:
+ * import { compose } from '@stravigor/core/helpers'
+ * class Order extends compose(BaseModel, searchable, m => stateful(m, orderMachine)) { }
+ */
+export function stateful<T extends NormalizeConstructor<typeof BaseModel>>(
+  Base: T,
+  machine: Machine
+) {
+  return class Stateful extends Base {
+    /** Check if this model instance is in the given state. */
+    is(state: string): boolean {
+      return machine.is(this, state)
+    }
+
+    /** Check if a transition can be applied to this model instance. */
+    can(transition: string): boolean | Promise<boolean> {
+      return machine.can(this, transition)
+    }
+
+    /** List all transitions available from this model's current state. */
+    availableTransitions(): string[] {
+      return machine.availableTransitions(this)
+    }
+
+    /**
+     * Apply a transition: validate, mutate, save, and emit event.
+     * Throws `TransitionError` if the transition is invalid from the current state.
+     * Throws `GuardError` if the guard rejects the transition.
+     */
+    async transition(name: string): Promise<TransitionMeta> {
+      const meta = await machine.apply(this, name)
+      await this.save()
+      return meta
+    }
+
+    /** Query scope: filter records in the given state(s). */
+    static inState(state: string | string[]) {
+      const states = Array.isArray(state) ? state : [state]
+      return (this as unknown as typeof BaseModel).query().whereIn(machine.definition.field, states)
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,68 @@
+// ── Machine Definition ──────────────────────────────────────────────────────
+
+export interface TransitionDefinition<TState extends string = string> {
+  from: TState | TState[]
+  to: TState
+}
+
+export interface MachineDefinition<
+  TState extends string = string,
+  TTransition extends string = string,
+> {
+  /** The field on the entity that holds the state value. */
+  field: string
+  /** The initial state for new entities. */
+  initial: TState
+  /** All valid states. */
+  states: TState[]
+  /** Named transitions with from/to state definitions. */
+  transitions: Record<TTransition, TransitionDefinition<TState>>
+  /** Guard functions that must return true for a transition to proceed. */
+  guards?: Partial<Record<TTransition, (entity: any) => boolean | Promise<boolean>>>
+  /** Side effects to run after a transition (before persistence). */
+  effects?: Partial<
+    Record<
+      TTransition,
+      (entity: any, meta: TransitionMeta<TState, TTransition>) => void | Promise<void>
+    >
+  >
+  /** Event names to emit via Emitter after a transition completes. */
+  events?: Partial<Record<TTransition, string>>
+}
+
+// ── Transition Meta ─────────────────────────────────────────────────────────
+
+export interface TransitionMeta<
+  TState extends string = string,
+  TTransition extends string = string,
+> {
+  from: TState
+  to: TState
+  transition: TTransition
+}
+
+// ── Machine Interface ───────────────────────────────────────────────────────
+
+export interface Machine<TState extends string = string, TTransition extends string = string> {
+  /** The machine definition. */
+  readonly definition: MachineDefinition<TState, TTransition>
+
+  /** Get the current state of an entity. */
+  state(entity: any): TState
+
+  /** Check if an entity is in a specific state. */
+  is(entity: any, state: TState): boolean
+
+  /** Check if a transition can be applied (valid from-state + guard passes). */
+  can(entity: any, transition: TTransition): boolean | Promise<boolean>
+
+  /** List all transitions available from the entity's current state. */
+  availableTransitions(entity: any): TTransition[]
+
+  /**
+   * Apply a transition to an entity.
+   * Validates the from-state, runs the guard, mutates the field, runs the effect, and emits the event.
+   * Does NOT persist — caller is responsible for saving.
+   */
+  apply(entity: any, transition: TTransition): Promise<TransitionMeta<TState, TTransition>>
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts"]
+}