controlled-machine 0.1.0

package/dist/react.d.cts

@@ -0,0 +1,100 @@
+declare type Actions<T extends MachineTypes> = T['actions'] extends string ? T['actions'] : string;
+
+declare type Cleanup = () => void;
+
+declare type Computed<T extends MachineTypes> = T['computed'] extends ComputedConfig ? T['computed'] : Record<string, never>;
+
+declare type ComputedConfig = Record<string, unknown>;
+
+declare type Context<T extends MachineTypes> = Input<T> & Computed<T>;
+
+declare type Effect<TContext, TEvents extends EventsConfig, TWatched = unknown> = {
+    watch: (context: TContext) => TWatched;
+    enter?: (context: TContext, helpers: EffectHelpers<TEvents>) => void | Cleanup | Promise<void>;
+    exit?: (context: TContext, helpers: EffectHelpers<TEvents>) => void | Cleanup;
+    change?: (context: TContext, prev: TWatched | undefined, curr: TWatched, helpers: EffectHelpers<TEvents>) => void | Cleanup;
+};
+
+declare type EffectHelpers<TEvents extends EventsConfig> = {
+    send: Send<TEvents>;
+};
+
+declare type Events<T extends MachineTypes> = T['events'] extends EventsConfig ? T['events'] : Record<string, undefined>;
+
+declare type EventsConfig = Record<string, unknown>;
+
+declare type Handler<TContext, TPayload = undefined, TActions extends string = string> = TActions | TActions[] | Rule<TContext, TPayload, TActions>[];
+
+declare type Input<T extends MachineTypes> = T['input'];
+
+declare type Machine<T extends MachineTypes> = {
+    computed?: {
+        [K in keyof Computed<T>]: (input: Input<T>) => Computed<T>[K];
+    };
+    on?: {
+        [K in keyof Events<T>]?: Handler<Context<T>, Events<T>[K], Actions<T>>;
+    };
+    states?: StatesConfig<State<T>, Context<T>, Events<T>, Actions<T>>;
+    always?: Rule<Context<T>, undefined, Actions<T>>[];
+    effects?: Effect<Context<T>, Events<T>, any>[];
+    actions?: {
+        [K in Actions<T>]: (context: Context<T>, payload?: any) => void;
+    };
+};
+
+/**
+ * Object-based generic types - specify only needed types in any order
+ *
+ * @example
+ * createMachine<{
+ *   input: MyInput
+ *   events: MyEvents
+ *   actions: 'foo' | 'bar'
+ * }>({...})
+ */
+declare type MachineTypes = {
+    input?: unknown;
+    events?: EventsConfig;
+    computed?: ComputedConfig;
+    actions?: string;
+    state?: string;
+};
+
+/**
+ * Controlled Machine
+ *
+ * A controlled state machine where state lives outside the machine.
+ *
+ * - input: External data passed in
+ * - computed: Derived values from input
+ * - context: input + computed (full context available in handlers)
+ * - on: Event → conditional actions
+ * - effects: Watch-based side effects
+ * - always: Auto-evaluated rules on context change
+ */
+declare type Rule<TContext, TPayload = undefined, TActions extends string = string> = {
+    when?: (context: TContext, payload: TPayload) => boolean;
+    do: TActions | TActions[];
+};
+
+export declare type Send<TEvents extends EventsConfig> = <K extends keyof TEvents>(event: K, ...args: TEvents[K] extends undefined ? [] : [payload: TEvents[K]]) => void;
+
+declare type State<T extends MachineTypes> = T['state'] extends string ? T['state'] : string;
+
+declare type StateConfig<TContext, TEvents extends EventsConfig, TActions extends string = string> = {
+    on?: {
+        [K in keyof TEvents]?: Handler<TContext, TEvents[K], TActions>;
+    };
+};
+
+declare type StatesConfig<TState extends string, TContext, TEvents extends EventsConfig, TActions extends string = string> = {
+    [K in TState]?: StateConfig<TContext, TEvents, TActions>;
+};
+
+export declare function useMachine<T extends MachineTypes>(machine: Machine<T>, input: T['input']): {
+    send: Send<Events<T>>;
+    computed: Computed<T>;
+    state: State<T>;
+};
+
+export { }

package/dist/react.d.ts

@@ -0,0 +1,100 @@
+declare type Actions<T extends MachineTypes> = T['actions'] extends string ? T['actions'] : string;
+
+declare type Cleanup = () => void;
+
+declare type Computed<T extends MachineTypes> = T['computed'] extends ComputedConfig ? T['computed'] : Record<string, never>;
+
+declare type ComputedConfig = Record<string, unknown>;
+
+declare type Context<T extends MachineTypes> = Input<T> & Computed<T>;
+
+declare type Effect<TContext, TEvents extends EventsConfig, TWatched = unknown> = {
+    watch: (context: TContext) => TWatched;
+    enter?: (context: TContext, helpers: EffectHelpers<TEvents>) => void | Cleanup | Promise<void>;
+    exit?: (context: TContext, helpers: EffectHelpers<TEvents>) => void | Cleanup;
+    change?: (context: TContext, prev: TWatched | undefined, curr: TWatched, helpers: EffectHelpers<TEvents>) => void | Cleanup;
+};
+
+declare type EffectHelpers<TEvents extends EventsConfig> = {
+    send: Send<TEvents>;
+};
+
+declare type Events<T extends MachineTypes> = T['events'] extends EventsConfig ? T['events'] : Record<string, undefined>;
+
+declare type EventsConfig = Record<string, unknown>;
+
+declare type Handler<TContext, TPayload = undefined, TActions extends string = string> = TActions | TActions[] | Rule<TContext, TPayload, TActions>[];
+
+declare type Input<T extends MachineTypes> = T['input'];
+
+declare type Machine<T extends MachineTypes> = {
+    computed?: {
+        [K in keyof Computed<T>]: (input: Input<T>) => Computed<T>[K];
+    };
+    on?: {
+        [K in keyof Events<T>]?: Handler<Context<T>, Events<T>[K], Actions<T>>;
+    };
+    states?: StatesConfig<State<T>, Context<T>, Events<T>, Actions<T>>;
+    always?: Rule<Context<T>, undefined, Actions<T>>[];
+    effects?: Effect<Context<T>, Events<T>, any>[];
+    actions?: {
+        [K in Actions<T>]: (context: Context<T>, payload?: any) => void;
+    };
+};
+
+/**
+ * Object-based generic types - specify only needed types in any order
+ *
+ * @example
+ * createMachine<{
+ *   input: MyInput
+ *   events: MyEvents
+ *   actions: 'foo' | 'bar'
+ * }>({...})
+ */
+declare type MachineTypes = {
+    input?: unknown;
+    events?: EventsConfig;
+    computed?: ComputedConfig;
+    actions?: string;
+    state?: string;
+};
+
+/**
+ * Controlled Machine
+ *
+ * A controlled state machine where state lives outside the machine.
+ *
+ * - input: External data passed in
+ * - computed: Derived values from input
+ * - context: input + computed (full context available in handlers)
+ * - on: Event → conditional actions
+ * - effects: Watch-based side effects
+ * - always: Auto-evaluated rules on context change
+ */
+declare type Rule<TContext, TPayload = undefined, TActions extends string = string> = {
+    when?: (context: TContext, payload: TPayload) => boolean;
+    do: TActions | TActions[];
+};
+
+export declare type Send<TEvents extends EventsConfig> = <K extends keyof TEvents>(event: K, ...args: TEvents[K] extends undefined ? [] : [payload: TEvents[K]]) => void;
+
+declare type State<T extends MachineTypes> = T['state'] extends string ? T['state'] : string;
+
+declare type StateConfig<TContext, TEvents extends EventsConfig, TActions extends string = string> = {
+    on?: {
+        [K in keyof TEvents]?: Handler<TContext, TEvents[K], TActions>;
+    };
+};
+
+declare type StatesConfig<TState extends string, TContext, TEvents extends EventsConfig, TActions extends string = string> = {
+    [K in TState]?: StateConfig<TContext, TEvents, TActions>;
+};
+
+export declare function useMachine<T extends MachineTypes>(machine: Machine<T>, input: T['input']): {
+    send: Send<Events<T>>;
+    computed: Computed<T>;
+    state: State<T>;
+};
+
+export { }

package/dist/react.js

@@ -0,0 +1,103 @@
+import { useRef, useMemo, useCallback, useEffect } from "react";
+import { computeValues, executeActions, executeHandler, processEffects, clearEffectStore } from "./index.js";
+function useMachine(machine, input) {
+  const inputRef = useRef(input);
+  const machineRef = useRef(machine);
+  const isMountedRef = useRef(true);
+  inputRef.current = input;
+  machineRef.current = machine;
+  const { computed: computedDef } = machine;
+  const context = useMemo(
+    () => computeValues(input, computedDef),
+    [input, computedDef]
+  );
+  const computed = useMemo(() => {
+    if (!computedDef) return {};
+    const result = {};
+    for (const key in computedDef) {
+      result[key] = context[key];
+    }
+    return result;
+  }, [context, computedDef]);
+  const contextRef = useRef(context);
+  contextRef.current = context;
+  const prevContextRef = useRef(context);
+  const effectStoreRef = useRef({
+    watchedValues: /* @__PURE__ */ new Map(),
+    enterCleanups: /* @__PURE__ */ new Map(),
+    changeCleanups: /* @__PURE__ */ new Map(),
+    exitCleanups: /* @__PURE__ */ new Map()
+  });
+  const { always, actions } = machine;
+  if (prevContextRef.current !== context && always && actions) {
+    const actionsMap = actions;
+    for (const rule of always) {
+      if (!rule.when || rule.when(context, void 0)) {
+        executeActions(rule.do, actionsMap, context, void 0);
+        break;
+      }
+    }
+  }
+  prevContextRef.current = context;
+  const send = useCallback(
+    (event, ...args) => {
+      const currentMachine = machineRef.current;
+      const currentInput = inputRef.current;
+      const currentContext = computeValues(
+        currentInput,
+        currentMachine.computed
+      );
+      const payload = args[0];
+      const state2 = currentContext.state;
+      if (state2 && currentMachine.states?.[state2]?.on?.[event]) {
+        const stateHandler = currentMachine.states[state2].on[event];
+        executeHandler(
+          stateHandler,
+          currentMachine.actions ?? {},
+          currentContext,
+          payload
+        );
+      }
+      const globalHandler = currentMachine.on?.[event];
+      if (globalHandler) {
+        executeHandler(
+          globalHandler,
+          currentMachine.actions ?? {},
+          currentContext,
+          payload
+        );
+      }
+    },
+    []
+    // no dependencies - uses refs
+  );
+  const safeSend = useCallback(
+    (event, ...args) => {
+      if (!isMountedRef.current) return;
+      send(event, ...args);
+    },
+    [send]
+  );
+  const effectHelpers = useMemo(
+    () => ({ send: safeSend }),
+    [safeSend]
+  );
+  const { effects } = machine;
+  useEffect(() => {
+    processEffects(effects, context, effectHelpers, effectStoreRef.current);
+  }, [context, effects, effectHelpers]);
+  useEffect(() => {
+    isMountedRef.current = true;
+    const store = effectStoreRef.current;
+    return () => {
+      isMountedRef.current = false;
+      clearEffectStore(store);
+    };
+  }, []);
+  const state = context.state ?? "";
+  return { send, computed, state };
+}
+export {
+  useMachine
+};
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sources":["../src/react.ts"],"sourcesContent":["/**\n * Controlled Machine - React Integration\n *\n * React hook for using controlled-machine in React components.\n */\n\nimport { useCallback, useRef, useEffect, useMemo } from 'react'\nimport {\n  type MachineTypes,\n  type Machine,\n  type Events,\n  type Computed,\n  type State,\n  type Send,\n  type EffectHelpers,\n  type EffectStore,\n  type Context,\n  computeValues,\n  executeActions,\n  executeHandler,\n  processEffects,\n  clearEffectStore,\n} from './index'\n\n// ============================================\n// React Hook\n// ============================================\n\nexport function useMachine<T extends MachineTypes>(\n  machine: Machine<T>,\n  input: T['input'],\n): { send: Send<Events<T>>; computed: Computed<T>; state: State<T> } {\n  // refs for stable callbacks\n  const inputRef = useRef(input)\n  const machineRef = useRef(machine)\n  const isMountedRef = useRef(true)\n\n  inputRef.current = input\n  machineRef.current = machine\n\n  // compute values\n  const { computed: computedDef } = machine\n  const context = useMemo(\n    () => computeValues(input, computedDef),\n    [input, computedDef],\n  )\n\n  // extract computed only\n  const computed = useMemo(() => {\n    if (!computedDef) return {} as Computed<T>\n    const result = {} as Computed<T>\n    for (const key in computedDef) {\n      result[key] = context[key]\n    }\n    return result\n  }, [context, computedDef])\n\n  const contextRef = useRef(context)\n  contextRef.current = context\n\n  const prevContextRef = useRef<Context<T>>(context)\n  const effectStoreRef = useRef<EffectStore>({\n    watchedValues: new Map(),\n    enterCleanups: new Map(),\n    changeCleanups: new Map(),\n    exitCleanups: new Map(),\n  })\n\n  // always: auto-evaluate when context changes (synchronous, during render)\n  const { always, actions } = machine\n  if (prevContextRef.current !== context && always && actions) {\n    const actionsMap = actions as Record<string, (context: Context<T>) => void>\n    for (const rule of always) {\n      if (!rule.when || rule.when(context, undefined)) {\n        executeActions(rule.do, actionsMap, context, undefined)\n        break\n      }\n    }\n  }\n  prevContextRef.current = context\n\n  // send: stable function (no deps, uses refs)\n  const send: Send<Events<T>> = useCallback(\n    <K extends keyof Events<T>>(\n      event: K,\n      ...args: Events<T>[K] extends undefined ? [] : [payload: Events<T>[K]]\n    ) => {\n      const currentMachine = machineRef.current\n      const currentInput = inputRef.current\n      const currentContext = computeValues(\n        currentInput,\n        currentMachine.computed,\n      )\n      const payload = args[0] as Events<T>[K]\n\n      // 1. State-specific handler first\n      const state = (currentContext as { state?: State<T> }).state\n      if (state && currentMachine.states?.[state]?.on?.[event]) {\n        const stateHandler = currentMachine.states[state].on![event]!\n        executeHandler(\n          stateHandler,\n          currentMachine.actions ?? {},\n          currentContext,\n          payload,\n        )\n      }\n\n      // 2. Global handler\n      const globalHandler = currentMachine.on?.[event]\n      if (globalHandler) {\n        executeHandler(\n          globalHandler,\n          currentMachine.actions ?? {},\n          currentContext,\n          payload,\n        )\n      }\n    },\n    [], // no dependencies - uses refs\n  )\n\n  // safeSend: won't be called after unmount\n  const safeSend: Send<Events<T>> = useCallback(\n    <K extends keyof Events<T>>(\n      event: K,\n      ...args: Events<T>[K] extends undefined ? [] : [payload: Events<T>[K]]\n    ) => {\n      if (!isMountedRef.current) return\n      send(event, ...args)\n    },\n    [send],\n  )\n\n  // effect helpers\n  const effectHelpers: EffectHelpers<Events<T>> = useMemo(\n    () => ({ send: safeSend }),\n    [safeSend],\n  )\n\n  // effects: detect watch value changes\n  const { effects } = machine\n  useEffect(() => {\n    processEffects(effects, context, effectHelpers, effectStoreRef.current)\n  }, [context, effects, effectHelpers])\n\n  // mount/unmount management\n  useEffect(() => {\n    isMountedRef.current = true\n    const store = effectStoreRef.current\n    return () => {\n      isMountedRef.current = false\n      clearEffectStore(store)\n    }\n  }, [])\n\n  // state from context (default to empty string if not provided)\n  const state = (context as { state?: State<T> }).state ?? ('' as State<T>)\n\n  return { send, computed, state }\n}\n\n// Re-export types for convenience\nexport type { Send } from './index'\n"],"names":["state"],"mappings":";;AA4BO,SAAS,WACd,SACA,OACmE;AAEnE,QAAM,WAAW,OAAO,KAAK;AAC7B,QAAM,aAAa,OAAO,OAAO;AACjC,QAAM,eAAe,OAAO,IAAI;AAEhC,WAAS,UAAU;AACnB,aAAW,UAAU;AAGrB,QAAM,EAAE,UAAU,YAAA,IAAgB;AAClC,QAAM,UAAU;AAAA,IACd,MAAM,cAAc,OAAO,WAAW;AAAA,IACtC,CAAC,OAAO,WAAW;AAAA,EAAA;AAIrB,QAAM,WAAW,QAAQ,MAAM;AAC7B,QAAI,CAAC,YAAa,QAAO,CAAA;AACzB,UAAM,SAAS,CAAA;AACf,eAAW,OAAO,aAAa;AAC7B,aAAO,GAAG,IAAI,QAAQ,GAAG;AAAA,IAC3B;AACA,WAAO;AAAA,EACT,GAAG,CAAC,SAAS,WAAW,CAAC;AAEzB,QAAM,aAAa,OAAO,OAAO;AACjC,aAAW,UAAU;AAErB,QAAM,iBAAiB,OAAmB,OAAO;AACjD,QAAM,iBAAiB,OAAoB;AAAA,IACzC,mCAAmB,IAAA;AAAA,IACnB,mCAAmB,IAAA;AAAA,IACnB,oCAAoB,IAAA;AAAA,IACpB,kCAAkB,IAAA;AAAA,EAAI,CACvB;AAGD,QAAM,EAAE,QAAQ,QAAA,IAAY;AAC5B,MAAI,eAAe,YAAY,WAAW,UAAU,SAAS;AAC3D,UAAM,aAAa;AACnB,eAAW,QAAQ,QAAQ;AACzB,UAAI,CAAC,KAAK,QAAQ,KAAK,KAAK,SAAS,MAAS,GAAG;AAC/C,uBAAe,KAAK,IAAI,YAAY,SAAS,MAAS;AACtD;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACA,iBAAe,UAAU;AAGzB,QAAM,OAAwB;AAAA,IAC5B,CACE,UACG,SACA;AACH,YAAM,iBAAiB,WAAW;AAClC,YAAM,eAAe,SAAS;AAC9B,YAAM,iBAAiB;AAAA,QACrB;AAAA,QACA,eAAe;AAAA,MAAA;AAEjB,YAAM,UAAU,KAAK,CAAC;AAGtB,YAAMA,SAAS,eAAwC;AACvD,UAAIA,UAAS,eAAe,SAASA,MAAK,GAAG,KAAK,KAAK,GAAG;AACxD,cAAM,eAAe,eAAe,OAAOA,MAAK,EAAE,GAAI,KAAK;AAC3D;AAAA,UACE;AAAA,UACA,eAAe,WAAW,CAAA;AAAA,UAC1B;AAAA,UACA;AAAA,QAAA;AAAA,MAEJ;AAGA,YAAM,gBAAgB,eAAe,KAAK,KAAK;AAC/C,UAAI,eAAe;AACjB;AAAA,UACE;AAAA,UACA,eAAe,WAAW,CAAA;AAAA,UAC1B;AAAA,UACA;AAAA,QAAA;AAAA,MAEJ;AAAA,IACF;AAAA,IACA,CAAA;AAAA;AAAA,EAAC;AAIH,QAAM,WAA4B;AAAA,IAChC,CACE,UACG,SACA;AACH,UAAI,CAAC,aAAa,QAAS;AAC3B,WAAK,OAAO,GAAG,IAAI;AAAA,IACrB;AAAA,IACA,CAAC,IAAI;AAAA,EAAA;AAIP,QAAM,gBAA0C;AAAA,IAC9C,OAAO,EAAE,MAAM;IACf,CAAC,QAAQ;AAAA,EAAA;AAIX,QAAM,EAAE,YAAY;AACpB,YAAU,MAAM;AACd,mBAAe,SAAS,SAAS,eAAe,eAAe,OAAO;AAAA,EACxE,GAAG,CAAC,SAAS,SAAS,aAAa,CAAC;AAGpC,YAAU,MAAM;AACd,iBAAa,UAAU;AACvB,UAAM,QAAQ,eAAe;AAC7B,WAAO,MAAM;AACX,mBAAa,UAAU;AACvB,uBAAiB,KAAK;AAAA,IACxB;AAAA,EACF,GAAG,CAAA,CAAE;AAGL,QAAM,QAAS,QAAiC,SAAU;AAE1D,SAAO,EAAE,MAAM,UAAU,MAAA;AAC3B;"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "controlled-machine",
+  "version": "0.1.0",
+  "description": "A controlled state machine where state lives outside the machine",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./react": {
+      "import": {
+        "types": "./dist/react.d.ts",
+        "default": "./dist/react.js"
+      },
+      "require": {
+        "types": "./dist/react.d.cts",
+        "default": "./dist/react.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "state-machine",
+    "controlled",
+    "event-driven",
+    "declarative",
+    "typescript"
+  ],
+  "author": "Hobin Jang",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dev-hobin/controlled-machine.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dev-hobin/controlled-machine/issues"
+  },
+  "homepage": "https://github.com/dev-hobin/controlled-machine#readme",
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.1",
+    "@types/react": "^19.2.8",
+    "jsdom": "^27.4.0",
+    "react": "^19.2.3",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.16"
+  }
+}