@hm-soft/status-history

상태 전이 머신 — 허용된 전이만 강제하고 변경 이력을 남깁니다. 주문·결재 같은 상태 흐름을 안전하게. 의존성 0, 상태는 직렬화 가능(DB 저장).

설치

npm install @hm-soft/status-history

사용

import { StatusMachine } from "@hm-soft/status-history";

const order = new StatusMachine({
  initial: "PENDING",
  transitions: {
    PENDING: ["PAID", "CANCELLED"],
    PAID:    ["SHIPPED", "REFUNDED"],
    SHIPPED: ["DELIVERED"],
  },
});

let state = order.initial();            // { current: "PENDING", history: [] }

order.can(state, "PAID");               // true
order.can(state, "SHIPPED");            // false
order.allowedNext(state);               // ["PAID", "CANCELLED"]

state = order.transition(state, "PAID", { by: "admin", reason: "결제완료" });
// state.current = "PAID"
// state.history = [{ from:"PENDING", to:"PAID", at:..., by:"admin", reason:"결제완료" }]

order.transition(state, "DELIVERED");   // throws: 'PAID' → 'DELIVERED' 전이는 허용되지 않습니다
order.isFinal("DELIVERED");             // true (나갈 전이 없음)

API

| 멤버 | 설명 | |------|------| | new StatusMachine({ initial, transitions }) | from→[to] 전이 정의 | | initial() | 초기 상태 | | can(state, to) | 전이 가능 여부 | | allowedNext(state) | 다음 가능 상태들 | | transition(state, to, {by?, reason?}, now?) | 전이 실행(불가 시 throw), 이력 추가 | | isFinal(state) | 종료 상태 여부 | | states() | 정의된 모든 상태 |

state/to 인자는 StatusState 또는 상태 문자열 모두 허용. now 주입으로 결정적 테스트 가능.

License

Apache-2.0