@doeixd/machine 0.0.7 → 0.0.8

package/src/adapters.ts

@@ -0,0 +1,407 @@
+// src/adapters.ts
+
+/**
+ * @file Event-Driven Adapters for @doeixd/machine
+ * @description Provides primitives to adapt a machine's method-call-based API
+ * to standard event-driven interfaces like the browser's `EventTarget` and
+ * Node.js's `EventEmitter`. These adapters allow your type-safe machines to
+ * integrate seamlessly into decoupled, event-driven architectures.
+ */
+
+import { EventEmitter } from 'events';
+import {
+  Machine,
+  Runner,
+  createRunner,
+  Context,
+  TransitionNames,
+} from './index';
+
+// =============================================================================
+// SECTION 0: Observable Types (Minimal Implementation)
+// =============================================================================
+
+/**
+ * A minimal Observer interface for reactive streams.
+ * Compatible with RxJS and other Observable implementations.
+ */
+export interface Observer<T> {
+  next?: (value: T) => void;
+  error?: (error: any) => void;
+  complete?: () => void;
+}
+
+/**
+ * A minimal Observable interface for reactive streams.
+ * Compatible with RxJS and other Observable implementations.
+ */
+export interface Observable<T> {
+  subscribe(observer: Observer<T>): { unsubscribe: () => void };
+}
+
+// =============================================================================
+// SECTION 1: EventTarget Adapter (for Browser Environments)
+// =============================================================================
+
+// --- Helper Types for EventTarget ---
+
+/**
+ * A helper type that extracts the detail payload for a given machine event.
+ * If the transition has arguments, it's an array of those arguments.
+ * If it has no arguments, it's `undefined`.
+ *
+ * @template M The machine type.
+ * @template K The name of the transition.
+ */
+export type MachineEventDetail<
+  M extends Machine<any>,
+  K extends TransitionNames<M>
+> = M[K] extends (...args: infer A) => any ? (A extends [] ? undefined : A) : never;
+
+/**
+ * A mapped type that creates a DOM-standard event map for a machine.
+ * This is crucial for providing type safety when using `addEventListener`.
+ *
+ * It includes:
+ * - A `statechange` event with the new machine state in its detail.
+ * - An `error` event with an `Error` object in its detail.
+ * - An entry for every possible machine transition.
+ *
+ * @template M The machine type.
+ */
+export type MachineEventMap<M extends Machine<any>> = {
+  [K in TransitionNames<M>]: CustomEvent<MachineEventDetail<M, K>>;
+} & {
+  statechange: CustomEvent<{ state: M }>;
+  error: CustomEvent<{ error: Error }>;
+};
+
+
+/**
+ * A type-safe, augmented EventTarget that wraps a state machine.
+ *
+ * It provides two key functionalities:
+ * 1. Emits a `CustomEvent` named 'statechange' whenever the machine's state updates.
+ * 2. Listens for other `CustomEvent`s and translates them into type-safe machine transitions.
+ *
+ * @template M The machine type (can be a union of states).
+ */
+export class MachineEventTarget<M extends Machine<any>> extends EventTarget {
+  private readonly runner: Runner<M>;
+
+  /**
+   * The current, readonly state of the machine.
+   * Access this property to get the latest machine instance for UI rendering or inspection.
+   * @example
+   * console.log(machineTarget.state.context.count);
+   */
+  public get state(): M {
+    return this.runner.state;
+  }
+
+  /**
+   * A direct, readonly accessor to the machine's current context.
+   * A convenience property equivalent to `machineTarget.state.context`.
+   */
+  public get context(): Context<M> {
+    return this.runner.state.context;
+  }
+
+  constructor(initialMachine: M) {
+    super();
+
+    this.runner = createRunner(initialMachine, (newState) => {
+      this.dispatchEvent(new CustomEvent('statechange', { detail: { state: newState } }));
+    });
+
+    const handleEvent = (event: Event) => {
+      const { type, detail } = event as CustomEvent;
+      if (type === 'statechange' || type === 'error') return;
+
+      const action = (this.runner.actions as any)[type];
+      if (typeof action === 'function') {
+        const args = Array.isArray(detail) ? detail : [];
+        action(...args);
+      } else {
+        const error = new Error(`Invalid event type "${type}" for current state "${(this.state.context as any).status || 'unknown'}".`);
+        this.dispatchEvent(new CustomEvent('error', { detail: { error } }));
+      }
+    };
+
+    // Override dispatchEvent to intercept all events and route them.
+    const originalDispatchEvent = this.dispatchEvent.bind(this);
+    this.dispatchEvent = (event: Event): boolean => {
+      // The event is first handled by our logic, then passed to the native dispatcher.
+      handleEvent(event);
+      return originalDispatchEvent(event);
+    };
+  }
+  
+  // Type-safe event listener methods for machine events
+  public addMachineEventListener<K extends keyof MachineEventMap<M>>(
+    type: K,
+    listener: (event: MachineEventMap<M>[K]) => void,
+    options?: boolean | AddEventListenerOptions
+  ): void {
+    super.addEventListener(type, listener as EventListener, options);
+  }
+
+  public removeMachineEventListener<K extends keyof MachineEventMap<M>>(
+    type: K,
+    listener: (event: MachineEventMap<M>[K]) => void,
+    options?: boolean | EventListenerOptions
+  ): void {
+    super.removeEventListener(type, listener as EventListener, options);
+  }
+
+
+
+  /**
+   * A type-safe method for dispatching transition events.
+   * This is the recommended way to interact with the machine from your application code.
+   *
+   * @param type The name of the transition to trigger (e.g., 'add').
+   * @param detail The arguments for that transition, matching the method signature.
+   *
+   * @example
+   * // For a transition `add(n: number)`
+   * machineTarget.dispatch('add', [5]);
+   *
+   * // For a transition `increment()`
+   * machineTarget.dispatch('increment');
+   */
+  public dispatch<K extends TransitionNames<M>>(
+    type: K,
+    detail?: MachineEventDetail<M, K>
+  ): void {
+    super.dispatchEvent(new CustomEvent(type, { detail }));
+  }
+}
+
+/**
+ * Creates a browser-native EventTarget from a machine.
+ *
+ * This powerful adapter makes your machine behave like a standard DOM element,
+ * perfect for decoupling components or integrating with event-driven browser APIs.
+ *
+ * @param initialMachine The machine instance to wrap.
+ * @returns A `MachineEventTarget` instance.
+ */
+export function asEventTarget<M extends Machine<any>>(initialMachine: M): MachineEventTarget<M> {
+  return new MachineEventTarget(initialMachine);
+}
+
+/**
+ * A utility function to ergonomically add and clean up a listener on a MachineEventTarget.
+ * It returns an `unsubscribe` function, which is ideal for use in `useEffect` hooks.
+ *
+ * @param target The `MachineEventTarget` to listen to.
+ * @param type The name of the event to listen for.
+ * @param listener The callback function to execute.
+ * @returns A cleanup function that removes the event listener.
+ *
+ * @example
+ * useEffect(() => {
+ *   // The listener is automatically typed based on the event name.
+ *   const unsubscribe = listen(counterTarget, 'statechange', (event) => {
+ *     setCount(event.detail.state.context.count);
+ *   });
+ *
+ *   // The returned function is perfect for a useEffect cleanup.
+ *   return unsubscribe;
+ * }, []);
+ */
+export function listen<M extends Machine<any>, K extends keyof MachineEventMap<M>>(
+  target: MachineEventTarget<M>,
+  type: K,
+  listener: (event: MachineEventMap<M>[K]) => void
+): () => void {
+  target.addMachineEventListener(type, listener);
+  return () => {
+    target.removeMachineEventListener(type, listener);
+  };
+}
+
+
+// =============================================================================
+// SECTION 2: EventEmitter Adapter (for Node.js & Event-Driven Architectures)
+// =============================================================================
+
+/**
+ * Defines the events and their payloads that our MachineEventEmitter can emit,
+ * providing strict type safety for listeners.
+ */
+interface MachineEmitterEvents<M extends Machine<any>> {
+  statechange: (newState: M) => void;
+  error: (error: Error) => void;
+}
+
+/**
+ * A type-safe, augmented EventEmitter that wraps a state machine.
+ *
+ * It provides two key functionalities:
+ * 1. Emits a `'statechange'` event whenever the machine's state updates.
+ * 2. Exposes a type-safe `dispatch` method to trigger machine transitions.
+ *
+ * @template M The machine type (can be a union of states).
+ */
+export class MachineEventEmitter<M extends Machine<any>> extends EventEmitter {
+  private readonly runner: Runner<M>;
+
+  // Augment EventEmitter's methods to be fully type-safe with our event map.
+  public on<E extends keyof MachineEmitterEvents<M>>(event: E, listener: MachineEmitterEvents<M>[E]): this {
+    return super.on(event, listener);
+  }
+  public emit<E extends keyof MachineEmitterEvents<M>>(event: E, ...args: Parameters<MachineEmitterEvents<M>[E]>): boolean {
+    return super.emit(event, ...args);
+  }
+
+  public get state(): M {
+    return this.runner.state;
+  }
+  public get context(): Context<M> {
+    return this.runner.state.context;
+  }
+
+  constructor(initialMachine: M) {
+    super();
+    this.runner = createRunner(initialMachine, (newState) => {
+      this.emit('statechange', newState);
+    });
+  }
+
+  /**
+   * A type-safe method for dispatching transitions to the machine.
+   * This is the primary input for the machine in an event-driven system.
+   *
+   * @param eventName The name of the transition to trigger.
+   * @param args The arguments for that transition, matching the method signature.
+   *
+   * @example
+   * sessionEmitter.dispatch('login', 'username', 'password');
+   */
+  public dispatch<K extends TransitionNames<M>>(
+    eventName: K,
+    ...args: M[K] extends (...args: infer A) => any ? A : never
+  ): void {
+    const action = (this.runner.actions as any)[eventName];
+
+    if (typeof action === 'function') {
+      action(...args);
+    } else {
+      this.emit('error', new Error(`Invalid event "${String(eventName)}" for current state.`));
+    }
+  }
+}
+
+/**
+ * Creates a Node.js-style EventEmitter from a machine.
+ *
+ * This adapter is perfect for backend services, scripts, or any architecture that
+ * uses the classic EventEmitter pattern for decoupling system components.
+ *
+ * @param initialMachine The machine instance to wrap.
+ * @returns A `MachineEventEmitter` instance.
+ */
+export function asEventEmitter<M extends Machine<any>>(initialMachine: M): MachineEventEmitter<M> {
+  return new MachineEventEmitter(initialMachine);
+}
+
+
+// =============================================================================
+// SECTION 3: Observable Adapter (for Stream-Based Architectures)
+// =============================================================================
+
+/**
+ * A type-safe Observable that wraps a state machine, emitting the new state
+ * on every transition.
+ *
+ * This class conforms to the standard Observable interface, making it compatible
+ * with libraries like RxJS and frameworks that use Observables (e.g., Angular).
+ *
+ * @template M The machine type (can be a union of states).
+ */
+export class MachineObservable<M extends Machine<any>> implements Observable<M> {
+  private readonly runner: Runner<M>;
+  private observers: Set<Observer<M>> = new Set();
+
+  public get state(): M {
+    return this.runner.state;
+  }
+  public get context(): Context<M> {
+    return this.runner.state.context;
+  }
+
+  constructor(initialMachine: M) {
+    this.runner = createRunner(initialMachine, (newState) => {
+      // When the runner's state changes, push the new state to all subscribers.
+      this.observers.forEach(observer => observer.next?.(newState));
+    });
+
+    // We can also forward errors from the runner if we enhance it to do so.
+  }
+
+  /**
+   * Subscribes to the stream of machine states.
+   *
+   * @param observer An object with `next`, `error`, and `complete` methods.
+   * @returns A subscription object with an `unsubscribe` method.
+   */
+  public subscribe(observer: Observer<M>): { unsubscribe: () => void } {
+    // Immediately provide the current state to the new subscriber.
+    observer.next?.(this.runner.state);
+
+    this.observers.add(observer);
+    
+    return {
+      unsubscribe: () => {
+        this.observers.delete(observer);
+        // Optional: If this is the last observer, we could tear down the machine.
+        // For now, we keep it simple and the machine lives forever.
+      },
+    };
+  }
+
+  /**
+   * A type-safe method for dispatching transitions to the machine.
+   *
+   * @param eventName The name of the transition to trigger.
+   * @param args The arguments for that transition.
+   */
+  public dispatch<K extends TransitionNames<M>>(
+    eventName: K,
+    ...args: M[K] extends (...args: infer A) => any ? A : never
+  ): void {
+    const action = (this.runner.actions as any)[eventName];
+    if (typeof action === 'function') {
+      action(...args);
+    } else {
+      // Emit an error to all observers.
+      const error = new Error(`Invalid event "${String(eventName)}" for current state.`);
+      this.observers.forEach(o => o.error?.(error));
+    }
+  }
+  
+  /**
+   * Signals to all observers that the stream is complete.
+   * This is useful when the machine reaches a final state.
+   */
+  public complete(): void {
+    this.observers.forEach(o => o.complete?.());
+    this.observers.clear();
+  }
+}
+
+/**
+ * Creates an Observable from a machine.
+ *
+ * This adapter is perfect for integrating your machine into architectures that
+ * rely on Observables and reactive streams (e.g., RxJS, Angular). It emits the
+ * new machine state on every transition.
+ *
+ * @param initialMachine The machine instance to wrap.
+ * @returns A `MachineObservable` instance.
+ */
+export function asObservable<M extends Machine<any>>(initialMachine: M): MachineObservable<M> {
+  return new MachineObservable(initialMachine);
+}

package/src/extract.ts

@@ -106,7 +106,7 @@ export interface ExtractionConfig {
  * @returns A JSON-compatible value (string, number, object, array).
  * @internal
  */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
+// @ts-expect-error - verbose parameter is used but TypeScript doesn't detect it
 function _typeToJson(type: Type, verbose = false): any {
   // --- Terminal Types ---
   const symbol = type.getSymbol();

package/src/index.ts

@@ -25,13 +25,33 @@ export type Machine<C extends object> = {
 
 /**
  * The shape of an asynchronous machine, where transitions can return Promises.
- * @template C - The context (state) object type.
+ * Async transitions receive an AbortSignal as the last parameter for cancellation support.
+ * @template C - The context object type.
  */
 export type AsyncMachine<C extends object> = {
   /** The readonly state of the machine. */
   readonly context: C;
 } & Record<string, (...args: any[]) => MaybePromise<AsyncMachine<any>>>;
 
+/**
+ * Utility type to extract the parameters of an async transition function,
+ * which includes TransitionOptions as the last parameter.
+ */
+export type AsyncTransitionArgs<M extends AsyncMachine<any>, K extends keyof M & string> =
+  M[K] extends (...args: infer A) => any
+    ? A extends [...infer Rest, TransitionOptions]
+      ? Rest
+      : A
+    : never;
+
+/**
+ * Options passed to async transition functions, including cancellation support.
+ */
+export interface TransitionOptions {
+  /** AbortSignal for cancelling long-running async operations. */
+  signal: AbortSignal;
+}
+
 
 // =============================================================================
 // SECTION: TYPE UTILITIES & INTROSPECTION
@@ -130,7 +150,12 @@ export function createMachine<C extends object, T extends Record<string, (this:
   context: C,
   fns: T
 ): { context: C } & T {
-  return Object.assign({ context }, fns);
+  // If fns is a machine (has context property), extract just the transition functions
+  const transitions = 'context' in fns ? Object.fromEntries(
+    Object.entries(fns).filter(([key]) => key !== 'context')
+  ) : fns;
+  const machine = Object.assign({ context }, transitions);
+  return machine as { context: C } & T;
 }
 
 /**
@@ -263,6 +288,79 @@ export function extendTransitions<
   return createMachine(context, combinedTransitions) as M & T;
 }
 
+/**
+ * Combines two machine factories into a single factory that creates machines with merged context and transitions.
+ * This allows you to compose independent state machines that operate on different parts of the same context.
+ *
+ * The resulting factory takes the parameters of the first factory, while the second factory is called with no arguments.
+ * Context properties are merged (second factory's context takes precedence on conflicts).
+ * Transition names must not conflict between the two machines.
+ *
+ * @template F1 - The first factory function type.
+ * @template F2 - The second factory function type.
+ * @param factory1 - The first machine factory (provides parameters and primary context).
+ * @param factory2 - The second machine factory (provides additional context and transitions).
+ * @returns A new factory function that creates combined machines.
+ *
+ * @example
+ * ```typescript
+ * // Define two independent machines
+ * const createCounter = (initial: number) =>
+ *   createMachine({ count: initial }, {
+ *     increment: function() { return createMachine({ count: this.count + 1 }, this); },
+ *     decrement: function() { return createMachine({ count: this.count - 1 }, this); }
+ *   });
+ *
+ * const createLogger = () =>
+ *   createMachine({ logs: [] as string[] }, {
+ *     log: function(message: string) {
+ *       return createMachine({ logs: [...this.logs, message] }, this);
+ *     },
+ *     clear: function() {
+ *       return createMachine({ logs: [] }, this);
+ *     }
+ *   });
+ *
+ * // Combine them
+ * const createCounterWithLogging = combineFactories(createCounter, createLogger);
+ *
+ * // Use the combined factory
+ * const machine = createCounterWithLogging(5); // { count: 5, logs: [] }
+ * const incremented = machine.increment(); // { count: 6, logs: [] }
+ * const logged = incremented.log("Count incremented"); // { count: 6, logs: ["Count incremented"] }
+ * ```
+ */
+export function combineFactories<
+  F1 extends (...args: any[]) => Machine<any>,
+  F2 extends () => Machine<any>
+>(
+  factory1: F1,
+  factory2: F2
+): (
+  ...args: Parameters<F1>
+) => Machine<Context<ReturnType<F1>> & Context<ReturnType<F2>>> &
+     Omit<ReturnType<F1>, 'context'> &
+     Omit<ReturnType<F2>, 'context'> {
+  return (...args: Parameters<F1>) => {
+    // Create instances from both factories
+    const machine1 = factory1(...args);
+    const machine2 = factory2();
+
+    // Merge contexts (machine2 takes precedence on conflicts)
+    const combinedContext = { ...machine1.context, ...machine2.context };
+
+    // Extract transitions from both machines
+    const { context: _, ...transitions1 } = machine1;
+    const { context: __, ...transitions2 } = machine2;
+
+    // Combine transitions (TypeScript will catch conflicts at compile time)
+    const combinedTransitions = { ...transitions1, ...transitions2 };
+
+    // Create the combined machine
+    return createMachine(combinedContext, combinedTransitions) as any;
+  };
+}
+
 /**
  * Creates a builder function from a "template" machine instance.
  * This captures the behavior of a machine and returns a factory that can stamp out
@@ -361,27 +459,61 @@ export function hasState<
 /**
  * Runs an asynchronous state machine with a managed lifecycle and event dispatch capability.
  * This is the "interpreter" for async machines, handling state updates and side effects.
+ * Provides automatic AbortController management to prevent async race conditions.
  *
  * @template M - The initial machine type.
  * @param initial - The initial machine state.
  * @param onChange - Optional callback invoked with the new machine state after every transition.
- * @returns An object with a `state` getter for the current context and an async `dispatch` function.
+ * @returns An object with a `state` getter for the current context, an async `dispatch` function, and a `stop` method.
  */
 export function runMachine<M extends AsyncMachine<any>>(
   initial: M,
   onChange?: (m: M) => void
 ) {
   let current = initial;
+  // Keep track of the controller for the currently-running async transition.
+  let activeController: AbortController | null = null;
 
   async function dispatch<E extends Event<typeof current>>(event: E): Promise<M> {
+    // 1. If an async transition is already in progress, cancel it.
+    if (activeController) {
+      activeController.abort();
+      activeController = null;
+    }
+
     const fn = (current as any)[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?.(current);
-    return current;
+
+    // 2. Create a new AbortController for this new transition.
+    const controller = new AbortController();
+    activeController = controller;
+
+    try {
+      // 3. Pass the signal to the transition function.
+      const nextStatePromise = fn.apply(current.context, [...event.args, { signal: controller.signal }]);
+
+      const nextState = await nextStatePromise;
+
+      // 4. If this promise resolved but has since been aborted, do not update state.
+      // This prevents the race condition.
+      if (controller.signal.aborted) {
+        // Return the *current* state, as if the transition never completed.
+        return current;
+      }
+
+      current = nextState;
+      onChange?.(current);
+      return current;
+
+    } finally {
+      // 5. Clean up the controller once the transition is complete (resolved or rejected).
+      // Only clear it if it's still the active one.
+      if (activeController === controller) {
+        activeController = null;
+      }
+    }
   }
 
   return {
@@ -391,6 +523,13 @@ export function runMachine<M extends AsyncMachine<any>>(
     },
     /** Dispatches a type-safe event to the machine, triggering a transition. */
     dispatch,
+    /** Stops any pending async operation and cleans up resources. */
+    stop: () => {
+      if (activeController) {
+        activeController.abort();
+        activeController = null;
+      }
+    },
   };
 }
 
@@ -535,6 +674,8 @@ export {
   transitionTo,
   describe,
   guarded,
+  guard,
+  whenGuard,
   invoke,
   action,
   metadata,
@@ -544,7 +685,10 @@ export {
   type InvokeMeta,
   type ActionMeta,
   type ClassConstructor,
-  type WithMeta
+  type WithMeta,
+  type GuardOptions,
+  type GuardFallback,
+  type GuardedTransition
 } from './primitives';
 
 // =============================================================================
@@ -578,6 +722,51 @@ export * from './multi'
 
 export * from './higher-order'
 
+// =============================================================================
+// SECTION: MIDDLEWARE & INTERCEPTION
+// =============================================================================
+
+export {
+  createMiddleware,
+  withLogging,
+  withAnalytics,
+  withValidation,
+  withPermissions,
+  withErrorReporting,
+  withPerformanceMonitoring,
+  withRetry,
+  withHistory,
+  withSnapshot,
+  withTimeTravel,
+  compose,
+  composeTyped,
+  createPipeline,
+  createMiddlewareRegistry,
+  when,
+  inDevelopment,
+  whenContext,
+  combine,
+  branch,
+  isMiddlewareFn,
+  isConditionalMiddleware,
+  createCustomMiddleware,
+  type MiddlewareHooks,
+  type MiddlewareOptions,
+  type MiddlewareContext,
+  type MiddlewareResult,
+  type MiddlewareError,
+  type HistoryEntry,
+  type ContextSnapshot,
+  type Serializer,
+  type MiddlewareFn,
+  type ConditionalMiddleware,
+  type NamedMiddleware,
+  type PipelineConfig,
+  type PipelineResult,
+  chain,
+  withDebugging
+} from './middleware';
+
 // =============================================================================
 // SECTION: UTILITIES & HELPERS
 // =============================================================================