@doeixd/machine 0.0.6 → 0.0.7

package/README.md

@@ -499,6 +499,68 @@ import { next } from "@doeixd/machine";
 const updated = next(counter, (ctx) => ({ count: ctx.count + 1 }));
 ```
 
+### Transition Binding Helpers
+
+These utilities eliminate the need for `.call(m.context, ...)` boilerplate when invoking transitions.
+
+#### `call<C, F>(fn, context, ...args)`
+
+Explicitly binds a transition function to a context and invokes it. Useful when you need to call a transition with proper `this` binding.
+
+```typescript
+import { call } from "@doeixd/machine";
+
+type MyContext = { count: number };
+const increment = function(this: MyContext) { 
+  return { count: this.count + 1 }; 
+};
+
+const result = call(increment, { count: 5 }); // Returns { count: 6 }
+
+// Particularly useful with generator-based flows:
+const result = run(function* (m) {
+  m = yield* step(call(m.increment, m.context));
+  m = yield* step(call(m.add, m.context, 5));
+  return m;
+}, counter);
+```
+
+#### `bindTransitions<M>(machine)`
+
+Returns a Proxy that automatically binds all transition methods to the machine's context. Eliminates `.call(m.context, ...)` boilerplate entirely.
+
+```typescript
+import { bindTransitions } from "@doeixd/machine";
+
+const counter = bindTransitions(createMachine(
+  { count: 0 },
+  {
+    increment(this: { count: number }) {
+      return createMachine({ count: this.count + 1 }, this);
+    },
+    add(this: { count: number }, n: number) {
+      return createMachine({ count: this.count + n }, this);
+    }
+  }
+));
+
+// All methods are automatically bound - no need for .call()!
+const next = counter.increment(); // Works!
+const result = counter.add(5);    // Works!
+
+// Great for generator-based flows:
+const result = run(function* (m) {
+  m = yield* step(m.increment());     // Clean syntax!
+  m = yield* step(m.add(5));          // No .call() needed
+  return m;
+}, counter);
+```
+
+**How it works:**
+The Proxy intercepts all property access on the machine. When a property is a function (transition method), it wraps it to automatically call `.apply(machine.context, args)` before invoking. Non-callable properties are returned as-is.
+
+**Note:** The Proxy preserves type safety while providing ergonomic syntax. Use this when writing generator-based flows or any code that frequently calls transitions.
+
 #### `matchMachine<M, K, R>(machine, key, handlers)`
 
 Type-safe pattern matching on discriminated unions in context.
@@ -1673,6 +1735,98 @@ const charts = extractMachines({
 });
 ```
 
+### Advanced Patterns: Hierarchical and Parallel Machines
+
+**NEW**: The extractor now supports advanced state machine patterns for complex systems.
+
+#### Hierarchical (Nested States)
+
+Model parent states containing child states:
+
+```typescript
+const config: MachineConfig = {
+  input: 'src/dashboard.ts',
+  classes: ['Dashboard', 'ErrorState'],
+  id: 'dashboard',
+  initialState: 'Dashboard',
+  children: {
+    contextProperty: 'child',
+    initialState: 'ViewingMachine',
+    classes: ['ViewingMachine', 'EditingMachine']
+  }
+};
+```
+
+Generates:
+
+```json
+{
+  "id": "dashboard",
+  "initial": "Dashboard",
+  "states": {
+    "Dashboard": {
+      "initial": "ViewingMachine",
+      "states": {
+        "ViewingMachine": { "on": { /* ... */ } },
+        "EditingMachine": { "on": { /* ... */ } }
+      }
+    }
+  }
+}
+```
+
+#### Parallel (Orthogonal Regions)
+
+Model independent regions that evolve simultaneously:
+
+```typescript
+const config: MachineConfig = {
+  input: 'src/editor.ts',
+  id: 'editor',
+  parallel: {
+    regions: [
+      {
+        name: 'fontWeight',
+        initialState: 'Normal',
+        classes: ['Normal', 'Bold']
+      },
+      {
+        name: 'textDecoration',
+        initialState: 'None',
+        classes: ['None', 'Underline']
+      }
+    ]
+  }
+};
+```
+
+Generates:
+
+```json
+{
+  "id": "editor",
+  "type": "parallel",
+  "states": {
+    "fontWeight": {
+      "initial": "Normal",
+      "states": {
+        "Normal": { "on": { /* ... */ } },
+        "Bold": { "on": { /* ... */ } }
+      }
+    },
+    "textDecoration": {
+      "initial": "None",
+      "states": {
+        "None": { "on": { /* ... */ } },
+        "Underline": { "on": { /* ... */ } }
+      }
+    }
+  }
+}
+```
+
+**See [docs/ADVANCED_EXTRACTION.md](./docs/ADVANCED_EXTRACTION.md) for complete guide.**
+
 ### Runtime Extraction API
 
 Extract statecharts from **running machine instances** without requiring source code access:
@@ -1884,6 +2038,10 @@ overrideTransitions<M, T>(machine: M, overrides: T): M & T
 extendTransitions<M, T>(machine: M, newTransitions: T): M & T
 createMachineBuilder<M>(template: M): (context) => M
 
+// Transition Binding
+call<C, F>(fn: F, context: C, ...args): ReturnType<F>
+bindTransitions<M extends Machine<any>>(machine: M): M
+
 // Pattern Matching
 matchMachine<M, K, R>(machine: M, key: K, handlers): R
 hasState<M, K, V>(machine: M, key: K, value: V): boolean

package/dist/cjs/development/index.js

@@ -20,20 +20,27 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  BoundMachine: () => BoundMachine,
   META_KEY: () => META_KEY,
   MachineBase: () => MachineBase,
   MultiMachineBase: () => MultiMachineBase,
   RUNTIME_META: () => RUNTIME_META,
   action: () => action,
+  bindTransitions: () => bindTransitions,
+  call: () => call,
   createAsyncMachine: () => createAsyncMachine,
   createEnsemble: () => createEnsemble,
+  createEvent: () => createEvent,
+  createFetchMachine: () => createFetchMachine,
   createFlow: () => createFlow,
   createMachine: () => createMachine,
   createMachineBuilder: () => createMachineBuilder,
   createMachineFactory: () => createMachineFactory,
   createMultiMachine: () => createMultiMachine,
   createMutableMachine: () => createMutableMachine,
+  createParallelMachine: () => createParallelMachine,
   createRunner: () => createRunner,
+  delegateToChild: () => delegateToChild,
   describe: () => describe,
   extendTransitions: () => extendTransitions,
   extractFromInstance: () => extractFromInstance,
@@ -46,10 +53,14 @@ __export(src_exports, {
   guarded: () => guarded,
   hasState: () => hasState,
   invoke: () => invoke,
+  isState: () => isState,
+  logState: () => logState,
   matchMachine: () => matchMachine,
+  mergeContext: () => mergeContext,
   metadata: () => metadata,
   next: () => next,
   overrideTransitions: () => overrideTransitions,
+  pipeTransitions: () => pipeTransitions,
   run: () => run,
   runAsync: () => runAsync,
   runMachine: () => runMachine,
@@ -60,6 +71,7 @@ __export(src_exports, {
   setContext: () => setContext,
   step: () => step,
   stepAsync: () => stepAsync,
+  toggle: () => toggle,
   transitionTo: () => transitionTo,
   yieldMachine: () => yieldMachine
 });
@@ -256,17 +268,17 @@ function parseInvokeService(obj) {
   }
   return service;
 }
-function extractFromCallExpression(call, verbose = false) {
-  if (!import_ts_morph.Node.isCallExpression(call)) {
+function extractFromCallExpression(call2, verbose = false) {
+  if (!import_ts_morph.Node.isCallExpression(call2)) {
     return null;
   }
-  const expression = call.getExpression();
+  const expression = call2.getExpression();
   const fnName = import_ts_morph.Node.isIdentifier(expression) ? expression.getText() : null;
   if (!fnName) {
     return null;
   }
   const metadata2 = {};
-  const args = call.getArguments();
+  const args = call2.getArguments();
   switch (fnName) {
     case "transitionTo":
       if (args[0]) {
@@ -406,6 +418,26 @@ function analyzeStateNode(classSymbol, verbose = false) {
   }
   return chartNode;
 }
+function analyzeStateNodeWithNesting(className, classSymbol, sourceFile, childConfig, verbose = false) {
+  const stateNode = analyzeStateNode(classSymbol, verbose);
+  if (childConfig) {
+    if (verbose) {
+      console.error(`  👪 Analyzing children for state: ${className}`);
+    }
+    stateNode.initial = childConfig.initialState;
+    stateNode.states = {};
+    for (const childClassName of childConfig.classes) {
+      const childClassDeclaration = sourceFile.getClass(childClassName);
+      if (childClassDeclaration) {
+        const childSymbol = childClassDeclaration.getSymbolOrThrow();
+        stateNode.states[childClassName] = analyzeStateNode(childSymbol, verbose);
+      } else {
+        console.warn(`⚠️ Warning: Child class '${childClassName}' not found.`);
+      }
+    }
+  }
+  return stateNode;
+}
 function extractMachine(config, project, verbose = false) {
   if (verbose) {
     console.error(`
@@ -416,6 +448,45 @@ function extractMachine(config, project, verbose = false) {
   if (!sourceFile) {
     throw new Error(`Source file not found: ${config.input}`);
   }
+  if (config.parallel) {
+    if (verbose) {
+      console.error(`  ⏹️ Parallel machine detected. Analyzing regions.`);
+    }
+    const parallelChart = {
+      id: config.id,
+      type: "parallel",
+      states: {}
+    };
+    if (config.description) {
+      parallelChart.description = config.description;
+    }
+    for (const region of config.parallel.regions) {
+      if (verbose) {
+        console.error(`    📍 Analyzing region: ${region.name}`);
+      }
+      const regionStates = {};
+      for (const className of region.classes) {
+        const classDeclaration = sourceFile.getClass(className);
+        if (classDeclaration) {
+          const classSymbol = classDeclaration.getSymbolOrThrow();
+          regionStates[className] = analyzeStateNode(classSymbol, verbose);
+        } else {
+          console.warn(`⚠️ Warning: Class '${className}' not found for region '${region.name}'.`);
+        }
+      }
+      parallelChart.states[region.name] = {
+        initial: region.initialState,
+        states: regionStates
+      };
+    }
+    if (verbose) {
+      console.error(`  ✅ Extracted ${config.parallel.regions.length} parallel regions`);
+    }
+    return parallelChart;
+  }
+  if (!config.initialState || !config.classes) {
+    throw new Error(`Machine config for '${config.id}' must have either 'parallel' or 'initialState'/'classes'.`);
+  }
   const fullChart = {
     id: config.id,
     initial: config.initialState,
@@ -431,7 +502,14 @@ function extractMachine(config, project, verbose = false) {
       continue;
     }
     const classSymbol = classDeclaration.getSymbolOrThrow();
-    const stateNode = analyzeStateNode(classSymbol, verbose);
+    const hasChildren = className === config.initialState && config.children;
+    const stateNode = analyzeStateNodeWithNesting(
+      className,
+      classSymbol,
+      sourceFile,
+      hasChildren ? config.children : void 0,
+      verbose
+    );
     fullChart.states[className] = stateNode;
   }
   if (verbose) {
@@ -797,6 +875,198 @@ function createMutableMachine(sharedContext, factories, getDiscriminant) {
   });
 }
 
+// src/higher-order.ts
+function delegateToChild(actionName) {
+  return function(...args) {
+    const child = this.context.child;
+    if (typeof child[actionName] === "function") {
+      const newChildState = child[actionName](...args);
+      return setContext(this, { ...this.context, child: newChildState });
+    }
+    return this;
+  };
+}
+function toggle(prop) {
+  return function() {
+    if (typeof this.context[prop] !== "boolean") {
+      console.warn(`[toggle primitive] Property '${String(prop)}' is not a boolean. Toggling may have unexpected results.`);
+    }
+    return setContext(this, {
+      ...this.context,
+      [prop]: !this.context[prop]
+    });
+  };
+}
+var IdleMachine = class extends MachineBase {
+  constructor(config) {
+    super({ status: "idle" });
+    this.config = config;
+    this.fetch = (params) => new LoadingMachine(this.config, params != null ? params : this.config.initialParams, 1);
+  }
+};
+var LoadingMachine = class extends MachineBase {
+  constructor(config, params, attempts) {
+    super({ status: "loading", abortController: new AbortController(), attempts });
+    this.config = config;
+    this.params = params;
+    this.succeed = (data) => {
+      var _a, _b;
+      (_b = (_a = this.config).onSuccess) == null ? void 0 : _b.call(_a, data);
+      return new SuccessMachine(this.config, { status: "success", data });
+    };
+    this.fail = (error) => {
+      var _a, _b, _c;
+      const maxRetries = (_a = this.config.maxRetries) != null ? _a : 3;
+      if (this.context.attempts < maxRetries) {
+        return new RetryingMachine(this.config, this.params, error, this.context.attempts);
+      }
+      (_c = (_b = this.config).onError) == null ? void 0 : _c.call(_b, error);
+      return new ErrorMachine(this.config, { status: "error", error });
+    };
+    this.cancel = () => {
+      this.context.abortController.abort();
+      return new CanceledMachine(this.config);
+    };
+    this.execute();
+  }
+  async execute() {
+  }
+};
+var RetryingMachine = class extends MachineBase {
+  constructor(config, params, error, attempts) {
+    super({ status: "retrying", error, attempts });
+    this.config = config;
+    this.params = params;
+    // This would be called after a delay.
+    this.retry = (params) => new LoadingMachine(this.config, params != null ? params : this.params, this.context.attempts + 1);
+  }
+};
+var SuccessMachine = class extends MachineBase {
+  constructor(config, context) {
+    super(context);
+    this.config = config;
+    this.refetch = (params) => new LoadingMachine(this.config, params != null ? params : this.config.initialParams, 1);
+  }
+};
+var ErrorMachine = class extends MachineBase {
+  constructor(config, context) {
+    super(context);
+    this.config = config;
+    this.retry = (params) => new LoadingMachine(this.config, params != null ? params : this.config.initialParams, 1);
+  }
+};
+var CanceledMachine = class extends MachineBase {
+  constructor(config) {
+    super({ status: "canceled" });
+    this.config = config;
+    this.refetch = (params) => new LoadingMachine(this.config, params != null ? params : this.config.initialParams, 1);
+  }
+};
+function createFetchMachine(config) {
+  return new IdleMachine(config);
+}
+function createParallelMachine(m1, m2) {
+  const combinedContext = { ...m1.context, ...m2.context };
+  const transitions1 = { ...m1 };
+  const transitions2 = { ...m2 };
+  delete transitions1.context;
+  delete transitions2.context;
+  const combinedTransitions = {};
+  for (const key in transitions1) {
+    const transitionFn = transitions1[key];
+    combinedTransitions[key] = (...args) => {
+      const nextM1 = transitionFn.apply(m1.context, args);
+      return createParallelMachine(nextM1, m2);
+    };
+  }
+  for (const key in transitions2) {
+    const transitionFn = transitions2[key];
+    combinedTransitions[key] = (...args) => {
+      const nextM2 = transitionFn.apply(m2.context, args);
+      return createParallelMachine(m1, nextM2);
+    };
+  }
+  return {
+    context: combinedContext,
+    ...combinedTransitions
+  };
+}
+
+// src/utils.ts
+function isState(machine, machineClass) {
+  return machine instanceof machineClass;
+}
+function createEvent(type, ...args) {
+  return { type, args };
+}
+function mergeContext(machine, partialContext) {
+  return setContext(machine, (ctx) => ({ ...ctx, ...partialContext }));
+}
+async function pipeTransitions(initialMachine, ...transitions) {
+  let current = initialMachine;
+  for (const transitionFn of transitions) {
+    current = await transitionFn(current);
+  }
+  return current;
+}
+function logState(machine, label) {
+  if (label) {
+    console.log(label, machine.context);
+  } else {
+    console.log(machine.context);
+  }
+  return machine;
+}
+function call(fn, context, ...args) {
+  return fn.apply(context, args);
+}
+function bindTransitions(machine) {
+  return new Proxy(machine, {
+    get(target, prop) {
+      const value = target[prop];
+      if (typeof value === "function") {
+        return function(...args) {
+          const result = value.apply(target.context, args);
+          if (result && typeof result === "object" && "context" in result) {
+            return bindTransitions(result);
+          }
+          return result;
+        };
+      }
+      return value;
+    }
+  });
+}
+var BoundMachine = class _BoundMachine {
+  constructor(machine) {
+    this.wrappedMachine = machine;
+    return new Proxy(this, {
+      get: (target, prop) => {
+        if (prop === "wrappedMachine" || prop === "context") {
+          return Reflect.get(target, prop);
+        }
+        const value = this.wrappedMachine[prop];
+        if (typeof value === "function") {
+          return (...args) => {
+            const result = value.apply(this.wrappedMachine.context, args);
+            if (result && typeof result === "object" && "context" in result) {
+              return new _BoundMachine(result);
+            }
+            return result;
+          };
+        }
+        return value;
+      }
+    });
+  }
+  /**
+   * Access the underlying machine's context directly.
+   */
+  get context() {
+    return this.wrappedMachine.context;
+  }
+};
+
 // src/index.ts
 function createMachine(context, fns) {
   return Object.assign({ context }, fns);