@classytic/primitives 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,43 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0]
+
+### Added
+
+- **`/state-machine` subpath** — `defineStateMachine<TStatus>({ name, transitions, errorFactory? })`
+  declarative state-transition primitive. Replaces hand-rolled
+  `if (status === 'X') throw` blocks across kernels:
+
+  ```typescript
+  import { defineStateMachine } from '@classytic/primitives/state-machine';
+
+  const ORDER_MACHINE = defineStateMachine<OrderStatus>({
+    name: 'Order',
+    transitions: {
+      draft: ['approved', 'cancelled'],
+      approved: ['shipped', 'cancelled'],
+      shipped: [],
+      cancelled: [],
+    },
+  });
+
+  ORDER_MACHINE.assertTransition('order-1', 'draft', 'approved'); // OK
+  ORDER_MACHINE.assertTransition('order-1', 'shipped', 'draft');  // throws
+  ORDER_MACHINE.canTransition('draft', 'shipped');                // false
+  ORDER_MACHINE.isTerminal('shipped');                            // true
+  ```
+
+  Generic over the status string-union — `Record<TStatus, readonly TStatus[]>`
+  on `transitions` enforces exhaustiveness at the call site. Kernels with their
+  own typed transition error class (e.g. flow's `InvalidTransitionError`) wire
+  it via `errorFactory` so the thrown type stays domain-consistent. Standalone
+  callers get the bundled `IllegalTransitionError` (carries `entityType` /
+  `entityId` / `from` / `to` + `code: 'illegal_transition'` + `status: 422`).
+
+  First consumer: `@classytic/flow` `PROCUREMENT_MACHINE` (procurement-order
+  approve / cancel transitions).
+
 ## [0.1.1]
 
 ### Added

package/dist/state-machine.d.mts

@@ -0,0 +1,103 @@
+//#region src/state-machine.d.ts
+/**
+ * Declarative state-machine primitive.
+ *
+ * Replaces hand-rolled `if (status === 'X') throw` blocks scattered
+ * across domain services. Each aggregate declares one transition table;
+ * the helper provides `canTransition` / `assertTransition` / `isTerminal`
+ * accessors that the services share.
+ *
+ * Generic over the status string-union so calls stay type-safe:
+ *   `defineStateMachine<ProcurementStatus>({ name: 'ProcurementOrder', transitions: { … } })`
+ * The TS compiler enforces exhaustiveness — every status string in the
+ * union MUST have an entry in `transitions` (terminal statuses map to `[]`).
+ *
+ * @example
+ * import { defineStateMachine } from '@classytic/primitives/state-machine';
+ *
+ * type OrderStatus = 'draft' | 'approved' | 'shipped' | 'cancelled';
+ * const ORDER_MACHINE = defineStateMachine<OrderStatus>({
+ *   name: 'Order',
+ *   transitions: {
+ *     draft: ['approved', 'cancelled'],
+ *     approved: ['shipped', 'cancelled'],
+ *     shipped: [],
+ *     cancelled: [],
+ *   },
+ * });
+ *
+ * ORDER_MACHINE.assertTransition('order-1', 'draft', 'approved'); // OK
+ * ORDER_MACHINE.assertTransition('order-1', 'shipped', 'draft');  // throws
+ * ORDER_MACHINE.canTransition('draft', 'shipped');                // false
+ * ORDER_MACHINE.isTerminal('shipped');                            // true
+ *
+ * Hosts that already have their own typed transition error can swap it
+ * in via `errorFactory`:
+ *
+ * @example
+ * import { InvalidTransitionError } from './errors.js';
+ * const FLOW_MACHINE = defineStateMachine<MoveStatus>({
+ *   name: 'StockMove',
+ *   transitions: { … },
+ *   errorFactory: ({ entityType, entityId, from, to }) =>
+ *     new InvalidTransitionError(entityType, entityId, from, to),
+ * });
+ */
+/**
+ * Default error thrown by `assertTransition` when no `errorFactory` is
+ * supplied. Carries the structured fields (`entityType`, `entityId`,
+ * `from`, `to`) plus a stable `code` so hosts can pattern-match on
+ * either `instanceof` or `error.code === 'illegal_transition'`.
+ */
+declare class IllegalTransitionError extends Error {
+  readonly code: "illegal_transition";
+  readonly status = 422;
+  readonly entityType: string;
+  readonly entityId: string;
+  readonly from: string;
+  readonly to: string;
+  constructor(entityType: string, entityId: string, from: string, to: string);
+}
+interface TransitionErrorContext {
+  readonly entityType: string;
+  readonly entityId: string;
+  readonly from: string;
+  readonly to: string;
+}
+interface StateMachineDefinition<TStatus extends string> {
+  /** Aggregate name surfaced in the thrown error's `entityType`. */
+  name: string;
+  /**
+   * Adjacency list — for each status, the set of statuses you can
+   * legally transition TO. Terminal statuses map to an empty array.
+   * `Record<TStatus, …>` enforces exhaustiveness at the call site.
+   */
+  transitions: Record<TStatus, readonly TStatus[]>;
+  /**
+   * Optional custom error factory. When omitted, `assertTransition`
+   * throws `IllegalTransitionError`. Hosts that own a domain error
+   * (e.g. flow's `InvalidTransitionError`) wire their own here so the
+   * thrown type stays consistent with the rest of the package.
+   */
+  errorFactory?: (ctx: TransitionErrorContext) => Error;
+}
+interface StateMachine<TStatus extends string> {
+  /** The aggregate name (`StockMove`, `ProcurementOrder`, etc.). */
+  readonly name: string;
+  /** All terminal statuses (no outgoing transitions). */
+  readonly terminal: ReadonlySet<TStatus>;
+  /** True when `from → to` is in the transition table. */
+  canTransition(from: TStatus, to: TStatus): boolean;
+  /** True when `status` is terminal. */
+  isTerminal(status: TStatus): boolean;
+  /**
+   * Throw a transition error when `from → to` isn't allowed.
+   * `entityId` is included in the error for traceability.
+   */
+  assertTransition(entityId: string, from: TStatus, to: TStatus): void;
+  /** The raw transition table — exposed read-only for advanced callers. */
+  readonly transitions: Readonly<Record<TStatus, readonly TStatus[]>>;
+}
+declare function defineStateMachine<TStatus extends string>(definition: StateMachineDefinition<TStatus>): StateMachine<TStatus>;
+//#endregion
+export { IllegalTransitionError, StateMachine, StateMachineDefinition, TransitionErrorContext, defineStateMachine };

package/dist/state-machine.mjs

@@ -0,0 +1,94 @@
+//#region src/state-machine.ts
+/**
+* Declarative state-machine primitive.
+*
+* Replaces hand-rolled `if (status === 'X') throw` blocks scattered
+* across domain services. Each aggregate declares one transition table;
+* the helper provides `canTransition` / `assertTransition` / `isTerminal`
+* accessors that the services share.
+*
+* Generic over the status string-union so calls stay type-safe:
+*   `defineStateMachine<ProcurementStatus>({ name: 'ProcurementOrder', transitions: { … } })`
+* The TS compiler enforces exhaustiveness — every status string in the
+* union MUST have an entry in `transitions` (terminal statuses map to `[]`).
+*
+* @example
+* import { defineStateMachine } from '@classytic/primitives/state-machine';
+*
+* type OrderStatus = 'draft' | 'approved' | 'shipped' | 'cancelled';
+* const ORDER_MACHINE = defineStateMachine<OrderStatus>({
+*   name: 'Order',
+*   transitions: {
+*     draft: ['approved', 'cancelled'],
+*     approved: ['shipped', 'cancelled'],
+*     shipped: [],
+*     cancelled: [],
+*   },
+* });
+*
+* ORDER_MACHINE.assertTransition('order-1', 'draft', 'approved'); // OK
+* ORDER_MACHINE.assertTransition('order-1', 'shipped', 'draft');  // throws
+* ORDER_MACHINE.canTransition('draft', 'shipped');                // false
+* ORDER_MACHINE.isTerminal('shipped');                            // true
+*
+* Hosts that already have their own typed transition error can swap it
+* in via `errorFactory`:
+*
+* @example
+* import { InvalidTransitionError } from './errors.js';
+* const FLOW_MACHINE = defineStateMachine<MoveStatus>({
+*   name: 'StockMove',
+*   transitions: { … },
+*   errorFactory: ({ entityType, entityId, from, to }) =>
+*     new InvalidTransitionError(entityType, entityId, from, to),
+* });
+*/
+/**
+* Default error thrown by `assertTransition` when no `errorFactory` is
+* supplied. Carries the structured fields (`entityType`, `entityId`,
+* `from`, `to`) plus a stable `code` so hosts can pattern-match on
+* either `instanceof` or `error.code === 'illegal_transition'`.
+*/
+var IllegalTransitionError = class extends Error {
+	code = "illegal_transition";
+	status = 422;
+	entityType;
+	entityId;
+	from;
+	to;
+	constructor(entityType, entityId, from, to) {
+		super(`Invalid transition for ${entityType} ${entityId}: ${from} → ${to}`);
+		this.name = "IllegalTransitionError";
+		this.entityType = entityType;
+		this.entityId = entityId;
+		this.from = from;
+		this.to = to;
+	}
+};
+function defineStateMachine(definition) {
+	const { name, transitions, errorFactory } = definition;
+	const terminal = /* @__PURE__ */ new Set();
+	for (const [status, allowed] of Object.entries(transitions)) if (allowed.length === 0) terminal.add(status);
+	const buildError = errorFactory ? errorFactory : (ctx) => new IllegalTransitionError(ctx.entityType, ctx.entityId, ctx.from, ctx.to);
+	return {
+		name,
+		terminal,
+		transitions,
+		canTransition(from, to) {
+			return transitions[from]?.includes(to) ?? false;
+		},
+		isTerminal(status) {
+			return terminal.has(status);
+		},
+		assertTransition(entityId, from, to) {
+			if (!transitions[from]?.includes(to)) throw buildError({
+				entityType: name,
+				entityId,
+				from,
+				to
+			});
+		}
+	};
+}
+//#endregion
+export { IllegalTransitionError, defineStateMachine };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -97,6 +97,10 @@
       "types": "./dist/person.d.mts",
       "default": "./dist/person.mjs"
     },
+    "./state-machine": {
+      "types": "./dist/state-machine.d.mts",
+      "default": "./dist/state-machine.mjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [