@doeixd/machine 0.0.7 → 0.0.9

package/dist/esm/development/index.js

@@ -104,9 +104,9 @@ function describe(_text, transition) {
   });
   return transition;
 }
-function guarded(guard, transition) {
+function guarded(guard2, transition) {
   attachRuntimeMeta(transition, {
-    guards: [guard]
+    guards: [guard2]
   });
   return transition;
 }
@@ -127,6 +127,118 @@ function action(action2, transition) {
   });
   return transition;
 }
+function guard(condition, transition, options = {}) {
+  const { onFail = "throw", errorMessage, description } = options;
+  const fullOptions = { ...options, onFail, errorMessage, description };
+  const guardedTransition = function(...args) {
+    const isMachine = typeof this === "object" && "context" in this;
+    const ctx = isMachine ? this.context : this;
+    const conditionResult = condition(ctx, ...args);
+    if (conditionResult) {
+      const contextForTransition = isMachine ? this.context : this;
+      return transition.apply(contextForTransition, args);
+    } else {
+      if (onFail === "throw") {
+        const message = errorMessage || "Guard condition failed";
+        throw new Error(message);
+      } else if (onFail === "ignore") {
+        if (isMachine) {
+          return this;
+        } else {
+          throw new Error('Cannot use "ignore" mode with context-only binding. Use full machine binding or provide fallback.');
+        }
+      } else if (typeof onFail === "function") {
+        if (isMachine) {
+          return onFail.apply(this, args);
+        } else {
+          throw new Error("Cannot use function fallback with context-only binding. Use full machine binding.");
+        }
+      } else {
+        return onFail;
+      }
+    }
+  };
+  Object.defineProperty(guardedTransition, "__guard", { value: true, enumerable: false });
+  Object.defineProperty(guardedTransition, "condition", { value: condition, enumerable: false });
+  Object.defineProperty(guardedTransition, "transition", { value: transition, enumerable: false });
+  Object.defineProperty(guardedTransition, "options", { value: fullOptions, enumerable: false });
+  attachRuntimeMeta(guardedTransition, {
+    description: description || "Synchronous guarded transition",
+    guards: [{ name: "runtime_guard", description: description || "Synchronous condition check" }]
+  });
+  return guardedTransition;
+}
+function guardAsync(condition, transition, options = {}) {
+  const { onFail = "throw", errorMessage, description } = options;
+  const fullOptions = { ...options, onFail, errorMessage, description };
+  const guardedTransition = async function(...args) {
+    const isMachine = typeof this === "object" && "context" in this;
+    const ctx = isMachine ? this.context : this;
+    const conditionResult = await Promise.resolve(condition(ctx, ...args));
+    if (conditionResult) {
+      const contextForTransition = isMachine ? this.context : this;
+      return transition.apply(contextForTransition, args);
+    } else {
+      if (onFail === "throw") {
+        const message = errorMessage || "Guard condition failed";
+        throw new Error(message);
+      } else if (onFail === "ignore") {
+        if (isMachine) {
+          return this;
+        } else {
+          throw new Error('Cannot use "ignore" mode with context-only binding. Use full machine binding or provide fallback.');
+        }
+      } else if (typeof onFail === "function") {
+        if (isMachine) {
+          return onFail.apply(this, args);
+        } else {
+          throw new Error("Cannot use function fallback with context-only binding. Use full machine binding.");
+        }
+      } else {
+        return onFail;
+      }
+    }
+  };
+  Object.defineProperty(guardedTransition, "__guard", { value: true, enumerable: false });
+  Object.defineProperty(guardedTransition, "condition", { value: condition, enumerable: false });
+  Object.defineProperty(guardedTransition, "transition", { value: transition, enumerable: false });
+  Object.defineProperty(guardedTransition, "options", { value: fullOptions, enumerable: false });
+  attachRuntimeMeta(guardedTransition, {
+    description: description || "Runtime guarded transition",
+    guards: [{ name: "runtime_guard", description: description || "Runtime condition check" }]
+  });
+  return guardedTransition;
+}
+function whenGuard(condition) {
+  return {
+    /**
+     * Define the transition to execute when the condition passes.
+     * Returns a guarded transition that can optionally have an else clause.
+     */
+    do(transition) {
+      const guarded2 = guard(condition, transition);
+      guarded2.else = function(fallback) {
+        return guard(condition, transition, { onFail: fallback });
+      };
+      return guarded2;
+    }
+  };
+}
+function whenGuardAsync(condition) {
+  return {
+    /**
+     * Define the transition to execute when the condition passes.
+     * Returns a guarded transition that can optionally have an else clause.
+     */
+    do(transition) {
+      const guarded2 = guardAsync(condition, transition);
+      guarded2.else = function(fallback) {
+        return guardAsync(condition, transition, { onFail: fallback });
+      };
+      return guarded2;
+    }
+  };
+}
 function metadata(_meta, value) {
   return value;
 }
@@ -226,9 +338,9 @@ function extractFromCallExpression(call2, verbose = false) {
       break;
     case "guarded":
       if (args[0]) {
-        const guard = parseObjectLiteral(args[0]);
-        if (Object.keys(guard).length > 0) {
-          metadata2.guards = [guard];
+        const guard2 = parseObjectLiteral(args[0]);
+        if (Object.keys(guard2).length > 0) {
+          metadata2.guards = [guard2];
         }
       }
       if (args[1] && Node.isCallExpression(args[1])) {
@@ -260,6 +372,36 @@ function extractFromCallExpression(call2, verbose = false) {
         }
       }
       break;
+    case "guard":
+      if (args[2]) {
+        const options = parseObjectLiteral(args[2]);
+        if (options.description) {
+          metadata2.description = options.description;
+        }
+      }
+      metadata2.guards = [{ name: "runtime_guard", description: metadata2.description || "Synchronous condition check" }];
+      if (args[1] && Node.isCallExpression(args[1])) {
+        const nested = extractFromCallExpression(args[1], verbose);
+        if (nested) {
+          Object.assign(metadata2, nested);
+        }
+      }
+      break;
+    case "guardAsync":
+      if (args[2]) {
+        const options = parseObjectLiteral(args[2]);
+        if (options.description) {
+          metadata2.description = options.description;
+        }
+      }
+      metadata2.guards = [{ name: "runtime_guard_async", description: metadata2.description || "Asynchronous condition check" }];
+      if (args[1] && Node.isCallExpression(args[1])) {
+        const nested = extractFromCallExpression(args[1], verbose);
+        if (nested) {
+          Object.assign(metadata2, nested);
+        }
+      }
+      break;
     default:
       return null;
   }
@@ -501,6 +643,37 @@ function generateChart() {
     process.exit(1);
   }
 }
+var ADVANCED_CONFIG_EXAMPLES = {
+  hierarchical: {
+    input: "examples/dashboardMachine.ts",
+    id: "dashboard",
+    classes: ["DashboardMachine", "LoggedOutMachine"],
+    initialState: "DashboardMachine",
+    children: {
+      contextProperty: "child",
+      initialState: "ViewingChildMachine",
+      classes: ["ViewingChildMachine", "EditingChildMachine"]
+    }
+  },
+  parallel: {
+    input: "examples/editorMachine.ts",
+    id: "editor",
+    parallel: {
+      regions: [
+        {
+          name: "fontWeight",
+          initialState: "NormalWeight",
+          classes: ["NormalWeight", "BoldWeight"]
+        },
+        {
+          name: "textDecoration",
+          initialState: "NoDecoration",
+          classes: ["NoDecoration", "UnderlineState"]
+        }
+      ]
+    }
+  }
+};
 if (__require.main === module) {
   generateChart();
 }
@@ -545,6 +718,16 @@ function extractStateNode(stateInstance) {
         transition.actions = meta.actions.map((a) => a.name);
       }
       stateNode.on[key] = transition;
+    } else if (meta.guards && meta.guards.length > 0) {
+      const transition = {
+        target: "GuardedTransition",
+        // Placeholder - actual target determined at runtime
+        cond: meta.guards.map((g) => g.name).join(" && ")
+      };
+      if (meta.description) {
+        transition.description = meta.description;
+      }
+      stateNode.on[key] = transition;
     }
   }
   if (invoke2.length > 0) {
@@ -920,6 +1103,859 @@ function createParallelMachine(m1, m2) {
   };
 }
 
+// src/middleware.ts
+var CANCEL = Symbol("CANCEL");
+function createMiddleware(machine, hooks, options = {}) {
+  const { mode = "auto", exclude = ["context"] } = options;
+  const wrapped = {};
+  for (const prop in machine) {
+    if (!Object.prototype.hasOwnProperty.call(machine, prop)) continue;
+    const value = machine[prop];
+    if (prop === "context") {
+      wrapped.context = value;
+      continue;
+    }
+    if (exclude.includes(prop)) {
+      wrapped[prop] = value;
+      continue;
+    }
+    if (typeof value !== "function" || prop.startsWith("_")) {
+      wrapped[prop] = value;
+      continue;
+    }
+    wrapped[prop] = createTransitionWrapper(
+      prop,
+      value,
+      machine,
+      hooks,
+      mode
+    );
+  }
+  return wrapped;
+}
+function createTransitionWrapper(transitionName, originalFn, machine, hooks, mode) {
+  return function wrappedTransition(...args) {
+    const context = machine.context;
+    const middlewareCtx = {
+      transitionName,
+      context,
+      args
+    };
+    const executeSyncTransition = () => {
+      try {
+        if (hooks.before) {
+          const beforeResult = hooks.before(middlewareCtx);
+          if (beforeResult === CANCEL) {
+            return machine;
+          }
+          if (beforeResult instanceof Promise) {
+            throw new Error(
+              `Middleware mode is 'sync' but before hook returned Promise for transition: ${transitionName}`
+            );
+          }
+        }
+        const result = originalFn.call(this, ...args);
+        if (result instanceof Promise) {
+          return handleAsyncResult(result, context);
+        }
+        if (hooks.after) {
+          const middlewareResult = {
+            transitionName,
+            prevContext: context,
+            nextContext: result.context,
+            args
+          };
+          const afterResult = hooks.after(middlewareResult);
+          if (afterResult instanceof Promise) {
+            throw new Error(
+              `Middleware mode is 'sync' but after hook returned Promise for transition: ${transitionName}`
+            );
+          }
+        }
+        return result;
+      } catch (err) {
+        if (hooks.error) {
+          const middlewareError = {
+            transitionName,
+            context,
+            args,
+            error: err
+          };
+          const errorResult = hooks.error(middlewareError);
+          if (errorResult instanceof Promise) {
+            errorResult.catch(() => {
+            });
+            throw err;
+          }
+          if (errorResult && typeof errorResult === "object" && "context" in errorResult) {
+            return errorResult;
+          }
+        }
+        throw err;
+      }
+    };
+    const handleAsyncResult = async (resultPromise, ctx) => {
+      try {
+        const result = await resultPromise;
+        if (hooks.after) {
+          const middlewareResult = {
+            transitionName,
+            prevContext: ctx,
+            nextContext: result.context,
+            args
+          };
+          await hooks.after(middlewareResult);
+        }
+        return result;
+      } catch (err) {
+        if (hooks.error) {
+          const middlewareError = {
+            transitionName,
+            context: ctx,
+            args,
+            error: err
+          };
+          const errorResult = await hooks.error(middlewareError);
+          if (errorResult && typeof errorResult === "object" && "context" in errorResult) {
+            return errorResult;
+          }
+        }
+        throw err;
+      }
+    };
+    const executeAsyncTransition = async () => {
+      try {
+        if (hooks.before) {
+          const beforeResult = await hooks.before(middlewareCtx);
+          if (beforeResult === CANCEL) {
+            return machine;
+          }
+        }
+        const result = await originalFn.call(this, ...args);
+        if (hooks.after) {
+          const middlewareResult = {
+            transitionName,
+            prevContext: context,
+            nextContext: result.context,
+            args
+          };
+          await hooks.after(middlewareResult);
+        }
+        return result;
+      } catch (err) {
+        if (hooks.error) {
+          const middlewareError = {
+            transitionName,
+            context,
+            args,
+            error: err
+          };
+          const errorResult = await hooks.error(middlewareError);
+          if (errorResult && typeof errorResult === "object" && "context" in errorResult) {
+            return errorResult;
+          }
+        }
+        throw err;
+      }
+    };
+    if (mode === "async") {
+      return executeAsyncTransition();
+    } else if (mode === "sync") {
+      return executeSyncTransition();
+    } else {
+      return executeSyncTransition();
+    }
+  };
+}
+function withLogging(machine, options = {}) {
+  const {
+    logger = console.log,
+    includeContext = true,
+    includeArgs = true
+  } = options;
+  return createMiddleware(machine, {
+    before: ({ transitionName, args }) => {
+      const argsStr = includeArgs && args.length > 0 ? ` ${JSON.stringify(args)}` : "";
+      logger(`→ ${transitionName}${argsStr}`);
+    },
+    after: ({ transitionName, nextContext }) => {
+      const contextStr = includeContext ? ` ${JSON.stringify(nextContext)}` : "";
+      logger(`✓ ${transitionName}${contextStr}`);
+    }
+  });
+}
+function withAnalytics(machine, track, options = {}) {
+  const {
+    eventPrefix = "state_transition",
+    includePrevContext = false,
+    includeArgs = true
+  } = options;
+  return createMiddleware(machine, {
+    after: async ({ transitionName, prevContext, nextContext, args }) => {
+      const properties = {
+        transition: transitionName,
+        to: nextContext
+      };
+      if (includePrevContext) {
+        properties.from = prevContext;
+      }
+      if (includeArgs && args.length > 0) {
+        properties.args = args;
+      }
+      await track(`${eventPrefix}.${transitionName}`, properties);
+    }
+  }, { mode: "async" });
+}
+function withValidation(machine, validate, options) {
+  return createMiddleware(machine, {
+    before: (ctx) => {
+      const result = validate(ctx);
+      if (result instanceof Promise) {
+        return result.then((r) => {
+          if (r === false) {
+            throw new Error(`Validation failed for transition: ${ctx.transitionName}`);
+          }
+          return void 0;
+        });
+      }
+      if (result === false) {
+        throw new Error(`Validation failed for transition: ${ctx.transitionName}`);
+      }
+      return void 0;
+    }
+  }, { mode: "auto", ...options });
+}
+function withPermissions(machine, canPerform, options) {
+  return createMiddleware(machine, {
+    before: (ctx) => {
+      const result = canPerform(ctx);
+      if (result instanceof Promise) {
+        return result.then((allowed) => {
+          if (!allowed) {
+            throw new Error(`Unauthorized transition: ${ctx.transitionName}`);
+          }
+          return void 0;
+        });
+      }
+      if (!result) {
+        throw new Error(`Unauthorized transition: ${ctx.transitionName}`);
+      }
+      return void 0;
+    }
+  }, { mode: "auto", ...options });
+}
+function withErrorReporting(machine, captureError, options = {}) {
+  const { includeContext = true, includeArgs = true, mode } = options;
+  return createMiddleware(machine, {
+    error: async ({ transitionName, context, args, error }) => {
+      const errorContext = {
+        transition: transitionName
+      };
+      if (includeContext) {
+        errorContext.context = context;
+      }
+      if (includeArgs && args.length > 0) {
+        errorContext.args = args;
+      }
+      await Promise.resolve(captureError(error, errorContext));
+    }
+  }, { mode });
+}
+function withPerformanceMonitoring(machine, onMetric) {
+  const timings = /* @__PURE__ */ new Map();
+  return createMiddleware(machine, {
+    before: ({ transitionName }) => {
+      timings.set(transitionName, performance.now());
+      return void 0;
+    },
+    after: ({ transitionName, nextContext }) => {
+      const startTime = timings.get(transitionName);
+      if (startTime) {
+        const duration = performance.now() - startTime;
+        timings.delete(transitionName);
+        const result = onMetric({ transitionName, duration, context: nextContext });
+        if (result instanceof Promise) {
+          return result;
+        }
+      }
+      return void 0;
+    }
+  }, { mode: "auto" });
+}
+function withRetry(machine, options = {}) {
+  const {
+    maxRetries = 3,
+    delay = 1e3,
+    backoffMultiplier = 1,
+    shouldRetry = () => true,
+    onRetry
+  } = options;
+  const wrapped = {};
+  for (const prop in machine) {
+    if (!Object.prototype.hasOwnProperty.call(machine, prop)) continue;
+    const value = machine[prop];
+    if (prop === "context" || typeof value !== "function") {
+      wrapped[prop] = value;
+      continue;
+    }
+    wrapped[prop] = async function retriableTransition(...args) {
+      let lastError;
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+          return await value.call(this, ...args);
+        } catch (error) {
+          lastError = error;
+          if (attempt === maxRetries) {
+            break;
+          }
+          if (!shouldRetry(lastError)) {
+            break;
+          }
+          onRetry == null ? void 0 : onRetry(attempt + 1, lastError);
+          const currentDelay = delay * Math.pow(backoffMultiplier, attempt);
+          await new Promise((resolve) => setTimeout(resolve, currentDelay));
+        }
+      }
+      throw lastError;
+    };
+  }
+  return wrapped;
+}
+function withHistory(machine, options = {}) {
+  const {
+    maxSize,
+    serializer,
+    filter,
+    onEntry,
+    _isRewrap = false
+  } = options;
+  const history = [];
+  let entryId = 0;
+  const instrumentedMachine = createMiddleware(machine, {
+    before: ({ transitionName, args }) => {
+      if (filter && !filter(transitionName, args)) {
+        return;
+      }
+      const entry = {
+        id: `entry-${entryId++}`,
+        transitionName,
+        args: [...args],
+        // Shallow clone args (fast, works with any type)
+        timestamp: Date.now()
+      };
+      if (serializer) {
+        try {
+          entry.serializedArgs = serializer.serialize(args);
+        } catch (err) {
+          console.error("Failed to serialize history args:", err);
+        }
+      }
+      history.push(entry);
+      if (maxSize && history.length > maxSize) {
+        history.shift();
+      }
+      onEntry == null ? void 0 : onEntry(entry);
+    }
+  }, { exclude: ["context", "history", "clearHistory"] });
+  if (!_isRewrap) {
+    for (const prop in instrumentedMachine) {
+      if (!Object.prototype.hasOwnProperty.call(instrumentedMachine, prop)) continue;
+      const value = instrumentedMachine[prop];
+      if (typeof value === "function" && !prop.startsWith("_") && prop !== "context" && !["history", "clearHistory"].includes(prop)) {
+        const originalFn = value;
+        instrumentedMachine[prop] = function(...args) {
+          const result = originalFn.apply(this, args);
+          if (result && typeof result === "object" && "context" in result && !("history" in result)) {
+            const rewrappedResult = createMiddleware(result, {
+              before: ({ transitionName, args: transArgs }) => {
+                if (filter && !filter(transitionName, transArgs)) {
+                  return;
+                }
+                const entry = {
+                  id: `entry-${entryId++}`,
+                  transitionName,
+                  args: [...transArgs],
+                  timestamp: Date.now()
+                };
+                if (serializer) {
+                  try {
+                    entry.serializedArgs = serializer.serialize(transArgs);
+                  } catch (err) {
+                    console.error("Failed to serialize history args:", err);
+                  }
+                }
+                history.push(entry);
+                if (maxSize && history.length > maxSize) {
+                  history.shift();
+                }
+                onEntry == null ? void 0 : onEntry(entry);
+              }
+            }, { exclude: ["context", "history", "clearHistory"] });
+            return Object.assign(rewrappedResult, {
+              history,
+              clearHistory: () => {
+                history.length = 0;
+                entryId = 0;
+              }
+            });
+          }
+          return result;
+        };
+      }
+    }
+  }
+  return Object.assign(instrumentedMachine, {
+    history,
+    clearHistory: () => {
+      history.length = 0;
+      entryId = 0;
+    }
+  });
+}
+function withSnapshot(machine, options = {}) {
+  const {
+    maxSize,
+    serializer,
+    captureSnapshot,
+    onlyIfChanged = false,
+    filter,
+    onSnapshot,
+    _extraExclusions = [],
+    _isRewrap = false
+  } = options;
+  const snapshots = [];
+  let snapshotId = 0;
+  const instrumentedMachine = createMiddleware(machine, {
+    after: ({ transitionName, prevContext, nextContext }) => {
+      if (filter && !filter(transitionName)) {
+        return;
+      }
+      if (onlyIfChanged) {
+        const changed = JSON.stringify(prevContext) !== JSON.stringify(nextContext);
+        if (!changed) {
+          return;
+        }
+      }
+      const snapshot = {
+        id: `snapshot-${snapshotId++}`,
+        transitionName,
+        before: { ...prevContext },
+        // Clone
+        after: { ...nextContext },
+        // Clone
+        timestamp: Date.now()
+      };
+      if (serializer) {
+        try {
+          snapshot.serializedBefore = serializer.serialize(prevContext);
+          snapshot.serializedAfter = serializer.serialize(nextContext);
+        } catch (err) {
+          console.error("Failed to serialize snapshot:", err);
+        }
+      }
+      if (captureSnapshot) {
+        try {
+          snapshot.diff = captureSnapshot(prevContext, nextContext);
+        } catch (err) {
+          console.error("Failed to capture snapshot:", err);
+        }
+      }
+      snapshots.push(snapshot);
+      if (maxSize && snapshots.length > maxSize) {
+        snapshots.shift();
+      }
+      onSnapshot == null ? void 0 : onSnapshot(snapshot);
+    }
+  }, { exclude: ["context", "snapshots", "clearSnapshots", "restoreSnapshot", ..._extraExclusions] });
+  const restoreSnapshot = (context) => {
+    const { context: _, ...transitions } = machine;
+    return { context, ...transitions };
+  };
+  if (!_isRewrap) {
+    for (const prop in instrumentedMachine) {
+      if (!Object.prototype.hasOwnProperty.call(instrumentedMachine, prop)) continue;
+      const value = instrumentedMachine[prop];
+      if (typeof value === "function" && !prop.startsWith("_") && prop !== "context" && !["snapshots", "clearSnapshots", "restoreSnapshot", "history", "clearHistory"].includes(prop)) {
+        const originalWrappedFn = value;
+        instrumentedMachine[prop] = function(...args) {
+          const result = originalWrappedFn.apply(this, args);
+          if (result && typeof result === "object" && "context" in result && !("snapshots" in result)) {
+            for (const transProp in result) {
+              if (!Object.prototype.hasOwnProperty.call(result, transProp)) continue;
+              const transValue = result[transProp];
+              if (typeof transValue === "function" && !transProp.startsWith("_") && transProp !== "context" && !["snapshots", "clearSnapshots", "restoreSnapshot", "history", "clearHistory"].includes(transProp)) {
+                const origTransFn = transValue;
+                result[transProp] = function(...transArgs) {
+                  const prevCtx = result.context;
+                  const transResult = origTransFn.apply(this, transArgs);
+                  if (transResult && typeof transResult === "object" && "context" in transResult) {
+                    const nextCtx = transResult.context;
+                    if (!(filter && !filter(transProp))) {
+                      let shouldRecord = true;
+                      if (onlyIfChanged) {
+                        const changed = JSON.stringify(prevCtx) !== JSON.stringify(nextCtx);
+                        shouldRecord = changed;
+                      }
+                      if (shouldRecord) {
+                        const snapshot = {
+                          id: `snapshot-${snapshotId++}`,
+                          transitionName: transProp,
+                          before: { ...prevCtx },
+                          after: { ...nextCtx },
+                          timestamp: Date.now()
+                        };
+                        if (serializer) {
+                          try {
+                            snapshot.serializedBefore = serializer.serialize(prevCtx);
+                            snapshot.serializedAfter = serializer.serialize(nextCtx);
+                          } catch (err) {
+                            console.error("Failed to serialize snapshot:", err);
+                          }
+                        }
+                        if (captureSnapshot) {
+                          try {
+                            snapshot.diff = captureSnapshot(prevCtx, nextCtx);
+                          } catch (err) {
+                            console.error("Failed to capture snapshot:", err);
+                          }
+                        }
+                        snapshots.push(snapshot);
+                        if (maxSize && snapshots.length > maxSize) {
+                          snapshots.shift();
+                        }
+                        onSnapshot == null ? void 0 : onSnapshot(snapshot);
+                      }
+                    }
+                  }
+                  return transResult;
+                };
+              }
+            }
+            const resultWithTracking = Object.assign(result, {
+              snapshots,
+              clearSnapshots: () => {
+                snapshots.length = 0;
+                snapshotId = 0;
+              },
+              restoreSnapshot
+            });
+            if (machine.history) {
+              resultWithTracking.history = machine.history;
+              resultWithTracking.clearHistory = machine.clearHistory;
+            }
+            return resultWithTracking;
+          }
+          return result;
+        };
+      }
+    }
+  }
+  return Object.assign(instrumentedMachine, {
+    snapshots,
+    clearSnapshots: () => {
+      snapshots.length = 0;
+      snapshotId = 0;
+    },
+    restoreSnapshot
+  });
+}
+function withTimeTravel(machine, options = {}) {
+  const { maxSize, serializer, onRecord } = options;
+  const history = [];
+  const snapshots = [];
+  let entryId = 0;
+  let snapshotId = 0;
+  const recordHistory = (transitionName, args) => {
+    const entry = {
+      id: `entry-${entryId++}`,
+      transitionName,
+      args: [...args],
+      timestamp: Date.now()
+    };
+    if (serializer) {
+      try {
+        entry.serializedArgs = serializer.serialize(args);
+      } catch (err) {
+        console.error("Failed to serialize history args:", err);
+      }
+    }
+    history.push(entry);
+    if (maxSize && history.length > maxSize) {
+      history.shift();
+    }
+    onRecord == null ? void 0 : onRecord("history", entry);
+  };
+  const recordSnapshot = (transitionName, prevContext, nextContext) => {
+    const snapshot = {
+      id: `snapshot-${snapshotId++}`,
+      transitionName,
+      before: { ...prevContext },
+      after: { ...nextContext },
+      timestamp: Date.now()
+    };
+    if (serializer) {
+      try {
+        snapshot.serializedBefore = serializer.serialize(prevContext);
+        snapshot.serializedAfter = serializer.serialize(nextContext);
+      } catch (err) {
+        console.error("Failed to serialize snapshot:", err);
+      }
+    }
+    snapshots.push(snapshot);
+    if (maxSize && snapshots.length > maxSize) {
+      snapshots.shift();
+    }
+    onRecord == null ? void 0 : onRecord("snapshot", snapshot);
+  };
+  const restoreSnapshot = (context) => {
+    const { context: _, ...transitions } = machine;
+    return Object.assign({ context }, context, transitions);
+  };
+  const replayFrom = (snapshotIndex = 0) => {
+    if (snapshotIndex < 0 || snapshotIndex >= snapshots.length) {
+      throw new Error(`Invalid snapshot index: ${snapshotIndex}`);
+    }
+    let current = restoreSnapshot(snapshots[snapshotIndex].before);
+    const snapshot = snapshots[snapshotIndex];
+    const historyStartIndex = history.findIndex(
+      (entry) => entry.transitionName === snapshot.transitionName && entry.timestamp === snapshot.timestamp
+    );
+    if (historyStartIndex === -1) {
+      throw new Error("Could not find matching history entry for snapshot");
+    }
+    for (let i = historyStartIndex; i < history.length; i++) {
+      const entry = history[i];
+      const transition = current[entry.transitionName];
+      if (typeof transition === "function") {
+        try {
+          current = transition.apply(current.context, entry.args);
+        } catch (err) {
+          console.error(`Replay failed at step ${i}:`, err);
+          throw err;
+        }
+      }
+    }
+    return current;
+  };
+  const wrapMachine = (machine2) => {
+    const wrapped = { ...machine2 };
+    for (const prop in machine2) {
+      if (!Object.prototype.hasOwnProperty.call(machine2, prop)) continue;
+      const value = machine2[prop];
+      if (typeof value === "function" && !prop.startsWith("_") && prop !== "context" && !["history", "snapshots", "clearHistory", "clearSnapshots", "clearTimeTravel", "restoreSnapshot", "replayFrom"].includes(prop)) {
+        wrapped[prop] = function(...args) {
+          recordHistory(prop, args);
+          const prevContext = wrapped.context;
+          const result = value.apply(this, args);
+          if (result && typeof result === "object" && "context" in result) {
+            recordSnapshot(prop, prevContext, result.context);
+          }
+          if (result && typeof result === "object" && "context" in result) {
+            return wrapMachine(result);
+          }
+          return result;
+        };
+      }
+    }
+    return Object.assign(wrapped, {
+      history,
+      snapshots,
+      clearHistory: () => {
+        history.length = 0;
+        entryId = 0;
+      },
+      clearSnapshots: () => {
+        snapshots.length = 0;
+        snapshotId = 0;
+      },
+      clearTimeTravel: () => {
+        history.length = 0;
+        snapshots.length = 0;
+        entryId = 0;
+        snapshotId = 0;
+      },
+      restoreSnapshot,
+      replayFrom
+    });
+  };
+  return wrapMachine(machine);
+}
+function compose(machine, ...middlewares) {
+  return middlewares.reduce((acc, middleware) => middleware(acc), machine);
+}
+function createCustomMiddleware(hooks, options) {
+  return (machine) => createMiddleware(machine, hooks, options);
+}
+function composeTyped(machine, ...middlewares) {
+  return middlewares.reduce((acc, middleware) => middleware(acc), machine);
+}
+function chain(machine) {
+  return new MiddlewareChainBuilder(machine);
+}
+var MiddlewareChainBuilder = class _MiddlewareChainBuilder {
+  constructor(machine) {
+    this.machine = machine;
+  }
+  /**
+   * Add a middleware to the composition chain.
+   * @param middleware - The middleware function to add
+   * @returns A new composer with the middleware applied
+   */
+  with(middleware) {
+    const result = middleware(this.machine);
+    return new _MiddlewareChainBuilder(result);
+  }
+  /**
+   * Build the final machine with all middlewares applied.
+   */
+  build() {
+    return this.machine;
+  }
+};
+function withDebugging(machine) {
+  return withTimeTravel(withSnapshot(withHistory(machine)));
+}
+function createPipeline(config = {}) {
+  const {
+    continueOnError = false,
+    logErrors = true,
+    onError
+  } = config;
+  return (machine, ...middlewares) => {
+    let currentMachine = machine;
+    const errors = [];
+    for (let i = 0; i < middlewares.length; i++) {
+      const middleware = middlewares[i];
+      try {
+        if ("middleware" in middleware && "when" in middleware) {
+          if (!middleware.when(currentMachine)) {
+            continue;
+          }
+          currentMachine = middleware.middleware(currentMachine);
+        } else {
+          currentMachine = middleware(currentMachine);
+        }
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        errors.push({ error: err, middlewareIndex: i });
+        if (logErrors) {
+          console.error(`Middleware pipeline error at index ${i}:`, err);
+        }
+        onError == null ? void 0 : onError(err, `middleware-${i}`);
+        if (!continueOnError) {
+          break;
+        }
+      }
+    }
+    return {
+      machine: currentMachine,
+      errors,
+      success: errors.length === 0
+    };
+  };
+}
+function createMiddlewareRegistry() {
+  const registry = /* @__PURE__ */ new Map();
+  return {
+    /**
+     * Register a middleware with a name and optional metadata.
+     */
+    register(name, middleware, description, priority) {
+      if (registry.has(name)) {
+        throw new Error(`Middleware '${name}' is already registered`);
+      }
+      registry.set(name, { name, middleware, description, priority });
+      return this;
+    },
+    /**
+     * Unregister a middleware by name.
+     */
+    unregister(name) {
+      return registry.delete(name);
+    },
+    /**
+     * Check if a middleware is registered.
+     */
+    has(name) {
+      return registry.has(name);
+    },
+    /**
+     * Get a registered middleware by name.
+     */
+    get(name) {
+      return registry.get(name);
+    },
+    /**
+     * List all registered middlewares.
+     */
+    list() {
+      return Array.from(registry.values()).sort((a, b) => {
+        var _a, _b;
+        return ((_a = a.priority) != null ? _a : 0) - ((_b = b.priority) != null ? _b : 0);
+      });
+    },
+    /**
+     * Apply a selection of registered middlewares to a machine.
+     * Middlewares are applied in priority order (lowest to highest).
+     */
+    apply(machine, middlewareNames) {
+      const middlewares = middlewareNames.map((name) => {
+        const entry = registry.get(name);
+        if (!entry) {
+          throw new Error(`Middleware '${name}' is not registered`);
+        }
+        return entry;
+      }).sort((a, b) => {
+        var _a, _b;
+        return ((_a = a.priority) != null ? _a : 0) - ((_b = b.priority) != null ? _b : 0);
+      });
+      return composeTyped(machine, ...middlewares.map((m) => m.middleware));
+    },
+    /**
+     * Apply all registered middlewares to a machine in priority order.
+     */
+    applyAll(machine) {
+      const middlewares = this.list();
+      return composeTyped(machine, ...middlewares.map((m) => m.middleware));
+    }
+  };
+}
+function when(middleware, predicate) {
+  const conditional = function(machine) {
+    return predicate(machine) ? middleware(machine) : machine;
+  };
+  conditional.middleware = middleware;
+  conditional.when = predicate;
+  return conditional;
+}
+function inDevelopment(middleware) {
+  return when(middleware, () => {
+    return typeof process !== "undefined" ? true : typeof window !== "undefined" ? !window.location.hostname.includes("production") : false;
+  });
+}
+function whenContext(key, value, middleware) {
+  return when(middleware, (machine) => machine.context[key] === value);
+}
+function combine(...middlewares) {
+  return (machine) => composeTyped(machine, ...middlewares);
+}
+function branch(branches, fallback) {
+  return (machine) => {
+    for (const [predicate, middleware] of branches) {
+      if (predicate(machine)) {
+        return middleware(machine);
+      }
+    }
+    return fallback ? fallback(machine) : machine;
+  };
+}
+function isMiddlewareFn(value) {
+  return typeof value === "function" && value.length === 1;
+}
+function isConditionalMiddleware(value) {
+  return value !== null && "middleware" in value && "when" in value && isMiddlewareFn(value.middleware) && typeof value.when === "function";
+}
+
 // src/utils.ts
 function isState(machine, machineClass) {
   return machine instanceof machineClass;
@@ -970,9 +2006,12 @@ var BoundMachine = class _BoundMachine {
     this.wrappedMachine = machine;
     return new Proxy(this, {
       get: (target, prop) => {
-        if (prop === "wrappedMachine" || prop === "context") {
+        if (prop === "wrappedMachine") {
           return Reflect.get(target, prop);
         }
+        if (prop === "context") {
+          return this.wrappedMachine.context;
+        }
         const value = this.wrappedMachine[prop];
         if (typeof value === "function") {
           return (...args) => {
@@ -987,17 +2026,15 @@ var BoundMachine = class _BoundMachine {
       }
     });
   }
-  /**
-   * 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);
+  const transitions = "context" in fns ? Object.fromEntries(
+    Object.entries(fns).filter(([key]) => key !== "context")
+  ) : fns;
+  const machine = Object.assign({ context }, transitions);
+  return machine;
 }
 function createAsyncMachine(context, fns) {
   return Object.assign({ context }, fns);
@@ -1033,6 +2070,17 @@ function extendTransitions(machine, newTransitions) {
   const combinedTransitions = { ...originalTransitions, ...newTransitions };
   return createMachine(context, combinedTransitions);
 }
+function combineFactories(factory1, factory2) {
+  return (...args) => {
+    const machine1 = factory1(...args);
+    const machine2 = factory2();
+    const combinedContext = { ...machine1.context, ...machine2.context };
+    const { context: _, ...transitions1 } = machine1;
+    const { context: __, ...transitions2 } = machine2;
+    const combinedTransitions = { ...transitions1, ...transitions2 };
+    return createMachine(combinedContext, combinedTransitions);
+  };
+}
 function createMachineBuilder(templateMachine) {
   const { context, ...transitions } = templateMachine;
   return (newContext) => {
@@ -1052,15 +2100,32 @@ function hasState(machine, key, value) {
 }
 function runMachine(initial, onChange) {
   let current = initial;
+  let activeController = null;
   async function dispatch(event) {
+    if (activeController) {
+      activeController.abort();
+      activeController = null;
+    }
     const fn = current[event.type];
     if (typeof fn !== "function") {
       throw new Error(`[Machine] Unknown event type '${String(event.type)}' on current state.`);
     }
-    const nextState = await fn.apply(current.context, event.args);
-    current = nextState;
-    onChange == null ? void 0 : onChange(current);
-    return current;
+    const controller = new AbortController();
+    activeController = controller;
+    try {
+      const nextStatePromise = fn.apply(current.context, [...event.args, { signal: controller.signal }]);
+      const nextState = await nextStatePromise;
+      if (controller.signal.aborted) {
+        return current;
+      }
+      current = nextState;
+      onChange == null ? void 0 : onChange(current);
+      return current;
+    } finally {
+      if (activeController === controller) {
+        activeController = null;
+      }
+    }
   }
   return {
     /** Gets the context of the current state of the machine. */
@@ -1068,7 +2133,14 @@ function runMachine(initial, onChange) {
       return current.context;
     },
     /** Dispatches a type-safe event to the machine, triggering a transition. */
-    dispatch
+    dispatch,
+    /** Stops any pending async operation and cleans up resources. */
+    stop: () => {
+      if (activeController) {
+        activeController.abort();
+        activeController = null;
+      }
+    }
   };
 }
 var MachineBase = class {
@@ -1085,6 +2157,7 @@ function next(m, update) {
   return createMachine(update(context), transitions);
 }
 export {
+  ADVANCED_CONFIG_EXAMPLES,
   BoundMachine,
   META_KEY,
   MachineBase,
@@ -1092,8 +2165,15 @@ export {
   RUNTIME_META,
   action,
   bindTransitions,
+  branch,
   call,
+  chain,
+  combine,
+  combineFactories,
+  compose,
+  composeTyped,
   createAsyncMachine,
+  createCustomMiddleware,
   createEnsemble,
   createEvent,
   createFetchMachine,
@@ -1101,9 +2181,12 @@ export {
   createMachine,
   createMachineBuilder,
   createMachineFactory,
+  createMiddleware,
+  createMiddlewareRegistry,
   createMultiMachine,
   createMutableMachine,
   createParallelMachine,
+  createPipeline,
   createRunner,
   delegateToChild,
   describe,
@@ -1115,9 +2198,14 @@ export {
   extractStateNode,
   generateChart,
   generateStatechart,
+  guard,
+  guardAsync,
   guarded,
   hasState,
+  inDevelopment,
   invoke,
+  isConditionalMiddleware,
+  isMiddlewareFn,
   isState,
   logState,
   matchMachine,
@@ -1138,6 +2226,21 @@ export {
   stepAsync,
   toggle,
   transitionTo,
+  when,
+  whenContext,
+  whenGuard,
+  whenGuardAsync,
+  withAnalytics,
+  withDebugging,
+  withErrorReporting,
+  withHistory,
+  withLogging,
+  withPerformanceMonitoring,
+  withPermissions,
+  withRetry,
+  withSnapshot,
+  withTimeTravel,
+  withValidation,
   yieldMachine
 };
 //# sourceMappingURL=index.js.map