@pyreon/machine 0.5.0 → 0.7.0

package/lib/index.js

@@ -0,0 +1,104 @@
+import { signal } from "@pyreon/reactivity";
+
+//#region src/machine.ts
+/**
+* Create a reactive state machine — a constrained signal with type-safe transitions.
+*
+* The returned instance is callable (reads like a signal) and exposes
+* `send()`, `matches()`, `can()`, and listeners for state changes.
+*
+* @param config - Machine definition with initial state and state configs
+* @returns A reactive machine instance
+*
+* @example
+* ```tsx
+* const machine = createMachine({
+*   initial: 'idle',
+*   states: {
+*     idle: { on: { FETCH: 'loading' } },
+*     loading: { on: { SUCCESS: 'done', ERROR: 'error' } },
+*     done: {},
+*     error: { on: { RETRY: 'loading' } },
+*   },
+* })
+*
+* machine()              // 'idle'
+* machine.send('FETCH')
+* machine()              // 'loading'
+*
+* // Reactive in JSX
+* {() => machine.matches('loading') && <Spinner />}
+* ```
+*/
+function createMachine(config) {
+	const { initial, states } = config;
+	if (!(initial in states)) throw new Error(`[@pyreon/machine] Initial state '${initial}' is not defined in states`);
+	const current = signal(initial);
+	const enterListeners = /* @__PURE__ */ new Map();
+	const transitionListeners = /* @__PURE__ */ new Set();
+	function resolveTransition(event, payload) {
+		const stateConfig = states[current.peek()];
+		if (!stateConfig?.on) return null;
+		const transition = stateConfig.on[event];
+		if (!transition) return null;
+		if (typeof transition === "string") return transition;
+		if (transition.guard && !transition.guard(payload)) return null;
+		return transition.target;
+	}
+	function machine() {
+		return current();
+	}
+	machine.send = (event, payload) => {
+		const target = resolveTransition(event, payload);
+		if (target === null) return;
+		const from = current.peek();
+		const machineEvent = {
+			type: event,
+			payload
+		};
+		current.set(target);
+		for (const cb of transitionListeners) cb(from, target, machineEvent);
+		const listeners = enterListeners.get(target);
+		if (listeners) for (const cb of listeners) cb(machineEvent);
+	};
+	machine.matches = (...matchStates) => {
+		const state = current();
+		return matchStates.includes(state);
+	};
+	machine.can = (event) => {
+		const stateConfig = states[current()];
+		if (!stateConfig?.on) return false;
+		if (!stateConfig.on[event]) return false;
+		return true;
+	};
+	machine.nextEvents = () => {
+		const stateConfig = states[current()];
+		if (!stateConfig?.on) return [];
+		return Object.keys(stateConfig.on);
+	};
+	machine.reset = () => {
+		current.set(initial);
+	};
+	machine.onEnter = (state, callback) => {
+		if (!enterListeners.has(state)) enterListeners.set(state, /* @__PURE__ */ new Set());
+		enterListeners.get(state).add(callback);
+		return () => {
+			enterListeners.get(state)?.delete(callback);
+		};
+	};
+	machine.onTransition = (callback) => {
+		transitionListeners.add(callback);
+		return () => {
+			transitionListeners.delete(callback);
+		};
+	};
+	machine.dispose = () => {
+		enterListeners.clear();
+		transitionListeners.clear();
+	};
+	return machine;
+}
+
+//#endregion
+export { createMachine };
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/machine.ts"],"sourcesContent":["import { signal } from '@pyreon/reactivity'\nimport type {\n  EnterCallback,\n  InferEvents,\n  InferStates,\n  Machine,\n  MachineConfig,\n  MachineEvent,\n  TransitionCallback,\n  TransitionConfig,\n} from './types'\n\n/**\n * Create a reactive state machine — a constrained signal with type-safe transitions.\n *\n * The returned instance is callable (reads like a signal) and exposes\n * `send()`, `matches()`, `can()`, and listeners for state changes.\n *\n * @param config - Machine definition with initial state and state configs\n * @returns A reactive machine instance\n *\n * @example\n * ```tsx\n * const machine = createMachine({\n *   initial: 'idle',\n *   states: {\n *     idle: { on: { FETCH: 'loading' } },\n *     loading: { on: { SUCCESS: 'done', ERROR: 'error' } },\n *     done: {},\n *     error: { on: { RETRY: 'loading' } },\n *   },\n * })\n *\n * machine()              // 'idle'\n * machine.send('FETCH')\n * machine()              // 'loading'\n *\n * // Reactive in JSX\n * {() => machine.matches('loading') && <Spinner />}\n * ```\n */\nexport function createMachine<\n  const TConfig extends MachineConfig<string, string>,\n>(config: TConfig): Machine<InferStates<TConfig>, InferEvents<TConfig>> {\n  type TState = InferStates<TConfig>\n  type TEvent = InferEvents<TConfig>\n\n  const { initial, states } = config as unknown as MachineConfig<TState, TEvent>\n\n  // Validate initial state\n  if (!(initial in states)) {\n    throw new Error(\n      `[@pyreon/machine] Initial state '${initial}' is not defined in states`,\n    )\n  }\n\n  const current = signal<TState>(initial)\n  const enterListeners = new Map<TState, Set<EnterCallback<TEvent>>>()\n  const transitionListeners = new Set<TransitionCallback<TState, TEvent>>()\n\n  function resolveTransition(event: TEvent, payload?: unknown): TState | null {\n    const stateConfig = states[current.peek()]\n    if (!stateConfig?.on) return null\n\n    const transition = stateConfig.on[event] as\n      | TransitionConfig<TState>\n      | undefined\n    if (!transition) return null\n\n    if (typeof transition === 'string') {\n      return transition\n    }\n\n    // Guarded transition\n    if (transition.guard && !transition.guard(payload)) {\n      return null\n    }\n\n    return transition.target\n  }\n\n  // The machine instance — callable like a signal\n  function machine(): TState {\n    return current()\n  }\n\n  machine.send = (event: TEvent, payload?: unknown): void => {\n    const target = resolveTransition(event, payload)\n    if (target === null) return\n\n    const from = current.peek()\n    const machineEvent: MachineEvent<TEvent> = { type: event, payload }\n\n    current.set(target)\n\n    // Fire transition listeners\n    for (const cb of transitionListeners) {\n      cb(from, target, machineEvent)\n    }\n\n    // Fire enter listeners for the target state\n    const listeners = enterListeners.get(target)\n    if (listeners) {\n      for (const cb of listeners) {\n        cb(machineEvent)\n      }\n    }\n  }\n\n  machine.matches = (...matchStates: TState[]): boolean => {\n    const state = current()\n    return matchStates.includes(state)\n  }\n\n  machine.can = (event: TEvent): boolean => {\n    const stateConfig = states[current()]\n    if (!stateConfig?.on) return false\n\n    const transition = stateConfig.on[event]\n    if (!transition) return false\n\n    // For guarded transitions, we can't know without payload\n    // Return true if the event exists (guard may still reject)\n    return true\n  }\n\n  machine.nextEvents = (): TEvent[] => {\n    const stateConfig = states[current()]\n    if (!stateConfig?.on) return []\n    return Object.keys(stateConfig.on) as TEvent[]\n  }\n\n  machine.reset = (): void => {\n    current.set(initial)\n  }\n\n  machine.onEnter = (\n    state: TState,\n    callback: EnterCallback<TEvent>,\n  ): (() => void) => {\n    if (!enterListeners.has(state)) {\n      enterListeners.set(state, new Set())\n    }\n    enterListeners.get(state)!.add(callback)\n\n    return () => {\n      enterListeners.get(state)?.delete(callback)\n    }\n  }\n\n  machine.onTransition = (\n    callback: TransitionCallback<TState, TEvent>,\n  ): (() => void) => {\n    transitionListeners.add(callback)\n    return () => {\n      transitionListeners.delete(callback)\n    }\n  }\n\n  machine.dispose = (): void => {\n    enterListeners.clear()\n    transitionListeners.clear()\n  }\n\n  return machine as Machine<TState, TEvent>\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,cAEd,QAAsE;CAItE,MAAM,EAAE,SAAS,WAAW;AAG5B,KAAI,EAAE,WAAW,QACf,OAAM,IAAI,MACR,oCAAoC,QAAQ,4BAC7C;CAGH,MAAM,UAAU,OAAe,QAAQ;CACvC,MAAM,iCAAiB,IAAI,KAAyC;CACpE,MAAM,sCAAsB,IAAI,KAAyC;CAEzE,SAAS,kBAAkB,OAAe,SAAkC;EAC1E,MAAM,cAAc,OAAO,QAAQ,MAAM;AACzC,MAAI,CAAC,aAAa,GAAI,QAAO;EAE7B,MAAM,aAAa,YAAY,GAAG;AAGlC,MAAI,CAAC,WAAY,QAAO;AAExB,MAAI,OAAO,eAAe,SACxB,QAAO;AAIT,MAAI,WAAW,SAAS,CAAC,WAAW,MAAM,QAAQ,CAChD,QAAO;AAGT,SAAO,WAAW;;CAIpB,SAAS,UAAkB;AACzB,SAAO,SAAS;;AAGlB,SAAQ,QAAQ,OAAe,YAA4B;EACzD,MAAM,SAAS,kBAAkB,OAAO,QAAQ;AAChD,MAAI,WAAW,KAAM;EAErB,MAAM,OAAO,QAAQ,MAAM;EAC3B,MAAM,eAAqC;GAAE,MAAM;GAAO;GAAS;AAEnE,UAAQ,IAAI,OAAO;AAGnB,OAAK,MAAM,MAAM,oBACf,IAAG,MAAM,QAAQ,aAAa;EAIhC,MAAM,YAAY,eAAe,IAAI,OAAO;AAC5C,MAAI,UACF,MAAK,MAAM,MAAM,UACf,IAAG,aAAa;;AAKtB,SAAQ,WAAW,GAAG,gBAAmC;EACvD,MAAM,QAAQ,SAAS;AACvB,SAAO,YAAY,SAAS,MAAM;;AAGpC,SAAQ,OAAO,UAA2B;EACxC,MAAM,cAAc,OAAO,SAAS;AACpC,MAAI,CAAC,aAAa,GAAI,QAAO;AAG7B,MAAI,CADe,YAAY,GAAG,OACjB,QAAO;AAIxB,SAAO;;AAGT,SAAQ,mBAA6B;EACnC,MAAM,cAAc,OAAO,SAAS;AACpC,MAAI,CAAC,aAAa,GAAI,QAAO,EAAE;AAC/B,SAAO,OAAO,KAAK,YAAY,GAAG;;AAGpC,SAAQ,cAAoB;AAC1B,UAAQ,IAAI,QAAQ;;AAGtB,SAAQ,WACN,OACA,aACiB;AACjB,MAAI,CAAC,eAAe,IAAI,MAAM,CAC5B,gBAAe,IAAI,uBAAO,IAAI,KAAK,CAAC;AAEtC,iBAAe,IAAI,MAAM,CAAE,IAAI,SAAS;AAExC,eAAa;AACX,kBAAe,IAAI,MAAM,EAAE,OAAO,SAAS;;;AAI/C,SAAQ,gBACN,aACiB;AACjB,sBAAoB,IAAI,SAAS;AACjC,eAAa;AACX,uBAAoB,OAAO,SAAS;;;AAIxC,SAAQ,gBAAsB;AAC5B,iBAAe,OAAO;AACtB,sBAAoB,OAAO;;AAG7B,QAAO"}

package/lib/types/index.d.ts

@@ -0,0 +1,104 @@
+//#region src/types.d.ts
+/**
+ * A transition target — either a state name or an object with target and guard.
+ */
+type TransitionConfig<TState extends string> = TState | {
+  target: TState;
+  guard: (payload?: unknown) => boolean;
+};
+/**
+ * State definition — maps event names to transition configs.
+ */
+interface StateConfig<TState extends string, TEvent extends string> {
+  on?: Partial<Record<TEvent, TransitionConfig<TState>>>;
+}
+/**
+ * Machine definition — initial state and state configs.
+ */
+interface MachineConfig<TState extends string, TEvent extends string> {
+  initial: TState;
+  states: Record<TState, StateConfig<TState, TEvent>>;
+}
+/**
+ * Event object passed to listeners.
+ */
+interface MachineEvent<TEvent extends string = string> {
+  type: TEvent;
+  payload?: unknown;
+}
+/**
+ * Callback for onEnter — receives the event that caused the transition.
+ */
+type EnterCallback<TEvent extends string = string> = (event: MachineEvent<TEvent>) => void;
+/**
+ * Callback for onTransition — receives from state, to state, and the event.
+ */
+type TransitionCallback<TState extends string = string, TEvent extends string = string> = (from: TState, to: TState, event: MachineEvent<TEvent>) => void;
+/**
+ * The machine instance returned by `createMachine()`.
+ */
+interface Machine<TState extends string, TEvent extends string> {
+  /** Read current state — reactive in effects/computeds/JSX */
+  (): TState;
+  /** Send an event to trigger a transition */
+  send: (event: TEvent, payload?: unknown) => void;
+  /** Check if the machine is in one of the given states — reactive */
+  matches: (...states: TState[]) => boolean;
+  /** Check if an event would trigger a valid transition from current state */
+  can: (event: TEvent) => boolean;
+  /** Get all valid events from the current state — reactive */
+  nextEvents: () => TEvent[];
+  /** Reset to initial state */
+  reset: () => void;
+  /** Register a callback for when the machine enters a specific state */
+  onEnter: (state: TState, callback: EnterCallback<TEvent>) => () => void;
+  /** Register a callback for any state transition */
+  onTransition: (callback: TransitionCallback<TState, TEvent>) => () => void;
+  /** Remove all listeners and clean up */
+  dispose: () => void;
+}
+/** Extract state names from a machine config */
+type InferStates<T> = T extends {
+  states: Record<infer S, unknown>;
+} ? S & string : never;
+/** Extract event names from a machine config */
+type InferEvents<T> = T extends {
+  states: Record<string, {
+    on?: Partial<Record<infer E, unknown>>;
+  }>;
+} ? E & string : never;
+//#endregion
+//#region src/machine.d.ts
+/**
+ * Create a reactive state machine — a constrained signal with type-safe transitions.
+ *
+ * The returned instance is callable (reads like a signal) and exposes
+ * `send()`, `matches()`, `can()`, and listeners for state changes.
+ *
+ * @param config - Machine definition with initial state and state configs
+ * @returns A reactive machine instance
+ *
+ * @example
+ * ```tsx
+ * const machine = createMachine({
+ *   initial: 'idle',
+ *   states: {
+ *     idle: { on: { FETCH: 'loading' } },
+ *     loading: { on: { SUCCESS: 'done', ERROR: 'error' } },
+ *     done: {},
+ *     error: { on: { RETRY: 'loading' } },
+ *   },
+ * })
+ *
+ * machine()              // 'idle'
+ * machine.send('FETCH')
+ * machine()              // 'loading'
+ *
+ * // Reactive in JSX
+ * {() => machine.matches('loading') && <Spinner />}
+ * ```
+ */
+declare function createMachine<const TConfig extends MachineConfig<string, string>>(config: TConfig): Machine<InferStates<TConfig>, InferEvents<TConfig>>;
+//#endregion
+export { type EnterCallback, type InferEvents, type InferStates, type Machine, type MachineConfig, type MachineEvent, type StateConfig, type TransitionCallback, type TransitionConfig, createMachine };
+//# sourceMappingURL=index2.d.ts.map

package/lib/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index2.d.ts","names":[],"sources":["../../../src/types.ts","../../../src/machine.ts"],"mappings":";;AAGA;;KAAY,gBAAA,0BACR,MAAA;EACE,MAAA,EAAQ,MAAA;EAAQ,KAAA,GAAQ,OAAA;AAAA;;;;UAKb,WAAA;EACf,EAAA,GAAK,OAAA,CAAQ,MAAA,CAAO,MAAA,EAAQ,gBAAA,CAAiB,MAAA;AAAA;AAD/C;;;AAAA,UAOiB,aAAA;EACf,OAAA,EAAS,MAAA;EACT,MAAA,EAAQ,MAAA,CAAO,MAAA,EAAQ,WAAA,CAAY,MAAA,EAAQ,MAAA;AAAA;;;;UAM5B,YAAA;EACf,IAAA,EAAM,MAAA;EACN,OAAA;AAAA;;;;KAMU,aAAA,oCACV,KAAA,EAAO,YAAA,CAAa,MAAA;;;AAjBtB;KAuBY,kBAAA,oEAGP,IAAA,EAAM,MAAA,EAAQ,EAAA,EAAI,MAAA,EAAQ,KAAA,EAAO,YAAA,CAAa,MAAA;;;;UAKlC,OAAA;EA7B4B;EAAA,IA+BvC,MAAA;EA/BI;EAkCR,IAAA,GAAO,KAAA,EAAO,MAAA,EAAQ,OAAA;EAlCR;EAqCd,OAAA,MAAa,MAAA,EAAQ,MAAA;EAvC+B;EA0CpD,GAAA,GAAM,KAAA,EAAO,MAAA;EAzCJ;EA4CT,UAAA,QAAkB,MAAA;EA3CV;EA8CR,KAAA;EA9CuB;EAiDvB,OAAA,GAAU,KAAA,EAAO,MAAA,EAAQ,QAAA,EAAU,aAAA,CAAc,MAAA;EAjDN;EAoD3C,YAAA,GAAe,QAAA,EAAU,kBAAA,CAAmB,MAAA,EAAQ,MAAA;EApDH;EAuDjD,OAAA;AAAA;;KAMU,WAAA,MAAiB,CAAA;EAAY,MAAA,EAAQ,MAAA;AAAA,IAC7C,CAAA;;KAIQ,WAAA,MAAiB,CAAA;EAC3B,MAAA,EAAQ,MAAA;IAAiB,EAAA,GAAK,OAAA,CAAQ,MAAA;EAAA;AAAA,IAEpC,CAAA;;;AArFJ;;;;;;;;;;;;AAOA;;;;;;;;;;;;;;;;;AAPA,iBCsCgB,aAAA,uBACQ,aAAA,iBAAA,CACtB,MAAA,EAAQ,OAAA,GAAU,OAAA,CAAQ,WAAA,CAAY,OAAA,GAAU,WAAA,CAAY,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/machine",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Reactive state machines for Pyreon — constrained signals with type-safe transitions",
   "license": "MIT",
   "repository": {
@@ -41,10 +41,5 @@
   },
   "peerDependencies": {
     "@pyreon/reactivity": ">=0.5.0 <1.0.0"
-  },
-  "devDependencies": {
-    "@happy-dom/global-registrator": "^20.8.3",
-    "@pyreon/reactivity": ">=0.5.0 <1.0.0",
-    "@vitus-labs/tools-lint": "^1.11.0"
   }
 }