@doeixd/machine 0.0.17 → 0.0.19

package/src/index.ts

@@ -60,6 +60,21 @@ export type AsyncTransitionArgs<M extends AsyncMachine<any, any>, K extends keyo
   ? A extends [...infer Rest, TransitionOptions] ? Rest : A
   : never;
 
+/**
+ * A helper type to define a distinct state in a state machine (a "typestate").
+ * Allows defining the context and transitions in a single generic type.
+ * @template C - The context specific to this state.
+ * @template T - The transitions available in this state.
+ */
+export type TypeState<C extends object, T extends object = {}> = Machine<C, T>;
+
+/**
+ * A helper type to define a distinct async state in a state machine.
+ * @template C - The context specific to this state.
+ * @template T - The transitions available in this state.
+ */
+export type AsyncTypeState<C extends object, T extends object = {}> = AsyncMachine<C, T>;
+
 
 /**
  * Options passed to async transition functions, including cancellation support.
@@ -330,9 +345,9 @@ export type BindTransitions<T> = {
  * @param factory - A function that receives a `transition` helper and returns the transitions object.
  * @returns A new machine instance.
  */
-export function createMachine<C extends object, T extends Record<string, (this: C, ...args: any[]) => any>>(
+export function createMachine<C extends object, T extends Record<string, (this: C, ...args: any[]) => any> = Record<string, (this: C, ...args: any[]) => any>>(
   context: C,
-  factory: (transition: (newContext: C) => Machine<C, T>) => T
+  factory: (transition: (newContext: C) => Machine<C, any>) => T
 ): Machine<C, BindTransitions<T>>;
 
 /**
@@ -569,6 +584,41 @@ export function setContext<M extends Machine<any>>(
   return createMachine(newContext, transitions as any) as M;
 }
 
+/**
+ * Creates a minimal machine-like object with just a context property.
+ * Useful for creating test fixtures and working with pattern matching utilities.
+ *
+ * @template C - The context type
+ * @param context - The context object
+ * @returns An object with a readonly context property
+ *
+ * @example
+ * ```typescript
+ * // For testing with discriminated unions
+ * type FetchContext =
+ *   | { status: 'idle' }
+ *   | { status: 'success'; data: string };
+ *
+ * const idleMachine = createContext<FetchContext>({ status: 'idle' });
+ * const successMachine = createContext<FetchContext>({ status: 'success', data: 'result' });
+ *
+ * // Works with pattern matching
+ * const match = createMatcher(
+ *   discriminantCase('idle', 'status', 'idle'),
+ *   discriminantCase('success', 'status', 'success')
+ * );
+ *
+ * if (match.is.success(successMachine)) {
+ *   console.log(successMachine.context.data); // TypeScript knows data exists
+ * }
+ * ```
+ */
+export function createContext<C extends object>(
+  context: C
+): { readonly context: C } {
+  return { context };
+}
+
 /**
  * Creates a new machine by overriding or adding transition functions to an existing machine.
  * Ideal for mocking in tests or decorating functionality. The original machine is unchanged.
@@ -749,7 +799,8 @@ export function matchMachine<
 
 /**
  * Type-safe helper to assert that a machine's context has a specific discriminant value.
- * This narrows the type of the context based on the discriminant.
+ * This narrows the type of the context based on the discriminant, properly handling
+ * discriminated unions.
  *
  * @template M - The machine type.
  * @template K - The discriminant key.
@@ -760,8 +811,12 @@ export function matchMachine<
  * @returns True if the discriminant matches, with type narrowing.
  *
  * @example
- * if (hasState(machine, 'status', 'loading')) {
- *   // machine.context.status is narrowed to 'loading'
+ * type Context = { status: 'idle' } | { status: 'loading' } | { status: 'success'; data: string };
+ * const machine = createMachine<Context>({ status: 'success', data: 'test' }, {});
+ *
+ * if (hasState(machine, 'status', 'success')) {
+ *   // machine.context is narrowed to { status: 'success'; data: string }
+ *   console.log(machine.context.data); // ✓ TypeScript knows about 'data'
  * }
  */
 export function hasState<
@@ -772,7 +827,7 @@ export function hasState<
   machine: M,
   key: K,
   value: V
-): machine is M & { context: Context<M> & { [P in K]: V } } {
+): machine is M & { context: Extract<Context<M>, { [P in K]: V }> } {
   return machine.context[key] === value;
 }
 
@@ -1028,16 +1083,19 @@ export {
 
 export type {
   MachineConfig,
-  ExtractionConfig
+  ExtractionConfig,
+  ParallelRegionConfig,
+  ChildStatesConfig
 } from './extract';
 
+// Note: Extraction functions (extractMachine, extractMachines, generateChart) are NOT exported
+// to keep them out of the runtime bundle. Use the CLI tool or import directly from the source
+// file for build-time statechart generation.
 
 export * from './multi'
 
 export * from './higher-order'
 
-export * from './extract'
-
 // =============================================================================
 // SECTION: MIDDLEWARE & INTERCEPTION
 // =============================================================================
@@ -1069,4 +1127,25 @@ export {
   createTransitionExtender,
   createFunctionalMachine,
   state
-} from './functional-combinators';
+} from './functional-combinators';
+
+// =============================================================================
+// SECTION: PATTERN MATCHING
+// =============================================================================
+
+export {
+  createMatcher,
+  classCase,
+  discriminantCase,
+  customCase,
+  forContext,
+  type MatcherCase,
+  type CasesToMapping,
+  type MatcherUnion,
+  type CaseNames,
+  type CaseHandler,
+  type ExhaustivenessMarker,
+  type IsExhaustive,
+  type WhenBuilder,
+  type Matcher
+} from './matcher';

package/src/matcher.ts

@@ -0,0 +1,544 @@
+/**
+ * @file Advanced Pattern Matching for State Machines
+ * @description
+ * Provides type-safe pattern matching utilities for discriminating between machine types.
+ * Supports three complementary APIs: type guards, exhaustive pattern matching, and simple matching.
+ *
+ * @example
+ * ```typescript
+ * // Define a matcher for class-based machines
+ * const match = createMatcher(
+ *   classCase('idle', IdleMachine),
+ *   classCase('loading', LoadingMachine),
+ *   classCase('success', SuccessMachine)
+ * );
+ *
+ * // API 1: Type Guards
+ * if (match.is.loading(machine)) {
+ *   // machine is narrowed to LoadingMachine
+ * }
+ *
+ * // API 2: Exhaustive Pattern Matching
+ * const result = match.when(machine).is<string>(
+ *   match.case.idle(() => 'idle'),
+ *   match.case.loading(() => 'loading'),
+ *   match.case.success(m => m.context.data),
+ *   match.exhaustive
+ * );
+ *
+ * // API 3: Simple Match
+ * const name = match(machine); // 'idle' | 'loading' | 'success' | null
+ * ```
+ */
+
+import type { Machine, Context } from './index';
+import { hasState } from './index';
+
+// =============================================================================
+// SECTION: CORE TYPES
+// =============================================================================
+
+/**
+ * A matcher case tuple that defines a state pattern.
+ *
+ * @template Name - The unique name for this case (used for type guards and pattern matching)
+ * @template M - The machine type this case matches
+ * @template Pred - The predicate function that determines if a machine matches this case
+ */
+export type MatcherCase<
+  Name extends string,
+  M,
+  Pred extends (m: any) => m is M
+> = readonly [
+  name: Name,
+  machineType: M,
+  predicate: Pred
+];
+
+/**
+ * Extracts the machine type from a MatcherCase.
+ */
+type CaseToMachine<C> = C extends MatcherCase<any, infer M, any> ? M : never;
+
+/**
+ * Extracts the case name from a MatcherCase.
+ */
+type CaseToName<C> = C extends MatcherCase<infer Name, any, any> ? Name : never;
+
+/**
+ * Builds a mapping from case names to their machine types.
+ */
+export type CasesToMapping<Cases extends readonly MatcherCase<any, any, any>[]> = {
+  [C in Cases[number] as CaseToName<C>]: CaseToMachine<C>;
+};
+
+/**
+ * Creates a union of all possible machine types from the cases.
+ */
+export type MatcherUnion<Cases extends readonly MatcherCase<any, any, any>[]> =
+  Cases[number] extends MatcherCase<any, infer M, any> ? M : never;
+
+/**
+ * Extracts the union of all case names.
+ */
+export type CaseNames<Cases extends readonly MatcherCase<any, any, any>[]> =
+  CaseToName<Cases[number]>;
+
+/**
+ * A branded type representing a case handler in pattern matching.
+ * This is used internally to track which cases have been handled.
+ */
+export type CaseHandler<Name extends string, M, R> = {
+  readonly __brand: 'CaseHandler';
+  readonly __name: Name;
+  readonly __machine: M;
+  readonly __return: R;
+  readonly handler: (machine: M) => R;
+};
+
+/**
+ * Exhaustiveness marker - signals that all cases must be handled.
+ */
+export type ExhaustivenessMarker = {
+  readonly __exhaustive: true;
+};
+
+/**
+ * Extracts machine types from an array of case handlers.
+ */
+type HandledMachines<Handlers extends readonly any[]> =
+  Handlers extends readonly [infer H, ...infer Rest]
+    ? (H extends CaseHandler<any, infer M, any> ? M : never) | HandledMachines<Rest>
+    : never;
+
+/**
+ * Checks if all machine types in Union have been handled.
+ * Returns true if exhaustive, otherwise returns an error type with missing cases.
+ */
+export type IsExhaustive<Union, Handled> =
+  Exclude<Union, Handled> extends never
+    ? true
+    : {
+        readonly __error: 'Non-exhaustive match - missing cases';
+        readonly __missing: Exclude<Union, Handled>;
+      };
+
+/**
+ * Pattern matching builder returned by matcher.when().
+ */
+export interface WhenBuilder<
+  _Cases extends readonly MatcherCase<any, any, any>[],
+  M
+> {
+  /**
+   * Execute pattern matching with exhaustiveness checking.
+   *
+   * @template R - The return type of all handlers
+   * @param handlers - Array of case handlers followed by exhaustiveness marker
+   * @returns The result of the matched handler, or compile error if not exhaustive
+   *
+   * @example
+   * ```typescript
+   * match.when(machine).is<string>(
+   *   match.case.idle(() => 'idle'),
+   *   match.case.loading(() => 'loading'),
+   *   match.exhaustive
+   * );
+   * ```
+   */
+  is<R>(
+    ...handlers: [...any[], ExhaustivenessMarker]
+  ): IsExhaustive<M, HandledMachines<typeof handlers>> extends true
+    ? R
+    : IsExhaustive<M, HandledMachines<typeof handlers>>;
+}
+
+/**
+ * The main Matcher interface with three APIs.
+ */
+export interface Matcher<Cases extends readonly MatcherCase<any, any, any>[]> {
+  /**
+   * API 1: Type guard access via dynamic properties.
+   *
+   * @example
+   * ```typescript
+   * if (match.is.loading(machine)) {
+   *   // machine is narrowed to LoadingMachine
+   * }
+   * ```
+   */
+  readonly is: {
+    [Name in CaseNames<Cases>]: <M>(
+      machine: M
+    ) => machine is Extract<M, CasesToMapping<Cases>[Name]>;
+  };
+
+  /**
+   * API 2a: Pattern matching builder.
+   *
+   * @example
+   * ```typescript
+   * match.when(machine).is<string>(
+   *   match.case.idle(() => 'idle'),
+   *   match.case.loading(() => 'loading'),
+   *   match.exhaustive
+   * );
+   * ```
+   */
+  when: <M>(
+    machine: M
+  ) => WhenBuilder<Cases, M>;
+
+  /**
+   * API 2b: Case handler creator for pattern matching.
+   *
+   * @example
+   * ```typescript
+   * match.case.loading((m) => `Loading: ${m.context.startTime}`)
+   * ```
+   */
+  readonly case: {
+    [Name in CaseNames<Cases>]: <R>(
+      handler: (machine: CasesToMapping<Cases>[Name]) => R
+    ) => CaseHandler<Name, CasesToMapping<Cases>[Name], R>;
+  };
+
+  /**
+   * API 2c: Exhaustiveness marker for pattern matching.
+   */
+  readonly exhaustive: ExhaustivenessMarker;
+
+  /**
+   * API 3: Simple match - returns the name of the matched case or null.
+   *
+   * @example
+   * ```typescript
+   * const name = match(machine); // 'idle' | 'loading' | 'success' | null
+   * ```
+   */
+  <M>(machine: M): M extends MatcherUnion<Cases>
+    ? CaseNames<Cases> | null
+    : null;
+}
+
+// =============================================================================
+// SECTION: MATCHER CREATION
+// =============================================================================
+
+/**
+ * Creates a type-safe matcher for discriminating between machine types.
+ *
+ * @template Cases - Tuple of [name, MachineType, predicate] configurations
+ * @param cases - Array of matcher case definitions
+ * @returns A matcher object with three APIs: is (type guards), when (pattern matching), and direct call (simple match)
+ *
+ * @example
+ * ```typescript
+ * // Class-based matching
+ * const match = createMatcher(
+ *   ['idle', IdleMachine, (m): m is IdleMachine => m instanceof IdleMachine],
+ *   ['loading', LoadingMachine, (m): m is LoadingMachine => m instanceof LoadingMachine]
+ * );
+ *
+ * // Or use helper functions
+ * const match = createMatcher(
+ *   classCase('idle', IdleMachine),
+ *   classCase('loading', LoadingMachine)
+ * );
+ * ```
+ */
+export function createMatcher<
+  const Cases extends readonly MatcherCase<string, any, (m: any) => m is any>[]
+>(
+  ...cases: Cases
+): Matcher<Cases> {
+  // Build lookup map for O(1) case access
+  const nameToCase = new Map<string, { predicate: (m: any) => boolean }>();
+
+  for (const [name, _, predicate] of cases) {
+    if (nameToCase.has(name)) {
+      throw new Error(`Duplicate matcher case name: "${name}"`);
+    }
+    nameToCase.set(name, { predicate });
+  }
+
+  // API 1: Type Guards (using Proxy for dynamic property access)
+  const isProxy = new Proxy({} as any, {
+    get(_target, prop: string) {
+      return function isGuard<M>(machine: M): machine is any {
+        const caseConfig = nameToCase.get(prop);
+        if (!caseConfig) {
+          const available = Array.from(nameToCase.keys()).join(', ');
+          throw new Error(
+            `Unknown matcher case: "${prop}". Available cases: ${available}`
+          );
+        }
+        return caseConfig.predicate(machine);
+      };
+    }
+  });
+
+  // API 2b: Case Handlers (using Proxy for dynamic property access)
+  const caseProxy = new Proxy({} as any, {
+    get(_target, prop: string) {
+      return function createCaseHandler<R>(
+        handler: (machine: any) => R
+      ): CaseHandler<any, any, R> {
+        // Validate case name exists
+        if (!nameToCase.has(prop)) {
+          const available = Array.from(nameToCase.keys()).join(', ');
+          throw new Error(
+            `Unknown matcher case: "${prop}". Available cases: ${available}`
+          );
+        }
+
+        return {
+          __brand: 'CaseHandler' as const,
+          __name: prop,
+          __machine: undefined as any,
+          __return: undefined as any,
+          handler
+        };
+      };
+    }
+  });
+
+  // API 2c: Exhaustiveness marker
+  const exhaustive: ExhaustivenessMarker = { __exhaustive: true };
+
+  // API 2a: Pattern Matching Builder
+  function when<M>(machine: M): WhenBuilder<Cases, M> {
+    return {
+      is<R>(...handlers: any[]): R {
+        // Validate we have at least exhaustiveness marker
+        if (handlers.length === 0) {
+          throw new Error('Pattern match requires at least one handler and exhaustiveness marker');
+        }
+
+        // Last element should be exhaustiveness marker
+        const lastHandler = handlers[handlers.length - 1];
+        if (!lastHandler || typeof lastHandler !== 'object' || !('__exhaustive' in lastHandler)) {
+          throw new Error(
+            'Pattern match must end with match.exhaustive for compile-time exhaustiveness checking'
+          );
+        }
+
+        // Remove exhaustiveness marker
+        const actualHandlers = handlers.slice(0, -1) as CaseHandler<any, any, R>[];
+
+        // Try each handler in order (first-match-wins)
+        for (const caseHandler of actualHandlers) {
+          const caseName = caseHandler.__name;
+          const caseConfig = nameToCase.get(caseName);
+
+          if (!caseConfig) {
+            throw new Error(`Internal error: Unknown matcher case in handler: ${caseName}`);
+          }
+
+          if (caseConfig.predicate(machine)) {
+            return caseHandler.handler(machine);
+          }
+        }
+
+        // No handler matched - this means pattern match wasn't actually exhaustive at runtime
+        const handledCases = actualHandlers.map(h => h.__name).join(', ');
+        const allCases = Array.from(nameToCase.keys()).join(', ');
+        throw new Error(
+          `Non-exhaustive pattern match at runtime: no handler matched the machine.\n` +
+          `Handled cases: [${handledCases}]\n` +
+          `All cases: [${allCases}]\n` +
+          `This may occur if predicates don't cover all runtime possibilities.`
+        );
+      }
+    };
+  }
+
+  // API 3: Simple Match (callable function)
+  function simpleMatcher<M>(machine: M): string | null {
+    for (const [name, _, predicate] of cases) {
+      if (predicate(machine)) {
+        return name;
+      }
+    }
+    return null;
+  }
+
+  // Combine all APIs into a single object
+  return Object.assign(simpleMatcher, {
+    is: isProxy,
+    when,
+    case: caseProxy,
+    exhaustive
+  }) as any;
+}
+
+// =============================================================================
+// SECTION: HELPER FUNCTIONS
+// =============================================================================
+
+/**
+ * Creates a class-based matcher case using instanceof checking.
+ * This is the most common pattern for Type-State machines.
+ *
+ * @template Name - The unique name for this case
+ * @template T - The class constructor
+ * @param name - The name to use for this case
+ * @param machineClass - The class to check with instanceof
+ * @returns A matcher case tuple
+ *
+ * @example
+ * ```typescript
+ * const match = createMatcher(
+ *   classCase('idle', IdleMachine),
+ *   classCase('loading', LoadingMachine),
+ *   classCase('success', SuccessMachine)
+ * );
+ * ```
+ */
+export function classCase<
+  Name extends string,
+  T extends abstract new (...args: any[]) => any
+>(
+  name: Name,
+  machineClass: T
+): MatcherCase<Name, InstanceType<T>, (m: any) => m is InstanceType<T>> {
+  return [
+    name,
+    undefined as any, // Type-only, not used at runtime
+    (m): m is InstanceType<T> => m instanceof machineClass
+  ] as const;
+}
+
+/**
+ * Creates a discriminated union matcher case based on a context property.
+ * This integrates with the existing hasState utility for context-based discrimination.
+ *
+ * @template Name - The unique name for this case
+ * @template M - The machine type (use Machine<YourContextUnion> for proper narrowing)
+ * @template K - The context key to check
+ * @template V - The value to match
+ * @param name - The name to use for this case
+ * @param key - The context property to check
+ * @param value - The value the property should equal
+ * @returns A matcher case tuple
+ *
+ * @example
+ * ```typescript
+ * type FetchContext =
+ *   | { status: 'idle' }
+ *   | { status: 'loading' }
+ *   | { status: 'success'; data: string };
+ *
+ * const match = createMatcher(
+ *   discriminantCase<'idle', Machine<FetchContext>, 'status', 'idle'>('idle', 'status', 'idle'),
+ *   discriminantCase<'loading', Machine<FetchContext>, 'status', 'loading'>('loading', 'status', 'loading'),
+ *   discriminantCase<'success', Machine<FetchContext>, 'status', 'success'>('success', 'status', 'success')
+ * );
+ * ```
+ */
+export function discriminantCase<
+  Name extends string,
+  M extends Machine<any> = Machine<any>,
+  K extends keyof Context<M> = any,
+  V extends Context<M>[K] = any
+>(
+  name: Name,
+  key: K,
+  value: V
+): MatcherCase<
+  Name,
+  M & { context: Extract<Context<M>, { [P in K]: V }> },
+  (m: M) => m is M & { context: Extract<Context<M>, { [P in K]: V }> }
+> {
+  return [
+    name,
+    undefined as any, // Type-only, not used at runtime
+    (m): m is any => hasState(m, key as any, value as any)
+  ] as const;
+}
+
+/**
+ * Creates a custom matcher case with a user-defined predicate.
+ * For advanced matching logic beyond instanceof or discriminants.
+ *
+ * @template Name - The unique name for this case
+ * @template M - The machine type this case matches (inferred from predicate)
+ * @param name - The name to use for this case
+ * @param predicate - A type guard function that determines if a machine matches
+ * @returns A matcher case tuple
+ *
+ * @example
+ * ```typescript
+ * const match = createMatcher(
+ *   customCase('complex', (m): m is ComplexMachine => {
+ *     return m.context.value > 10 && m.context.status === 'active';
+ *   })
+ * );
+ * ```
+ */
+export function customCase<
+  const Name extends string,
+  M
+>(
+  name: Name,
+  predicate: (m: any) => m is M
+): MatcherCase<Name, M, (m: any) => m is M> {
+  return [name, undefined as any, predicate] as const;
+}
+
+/**
+ * Creates a discriminated matcher builder for a specific context union type.
+ * Provides better type inference by capturing the context type upfront.
+ *
+ * @template C - The discriminated union context type
+ * @returns A builder object with a `case` method for defining cases with less boilerplate
+ *
+ * @example
+ * ```typescript
+ * type FetchContext =
+ *   | { status: 'idle' }
+ *   | { status: 'loading'; startTime: number }
+ *   | { status: 'success'; data: string };
+ *
+ * const builder = forContext<FetchContext>();
+ *
+ * const match = createMatcher(
+ *   builder.case('idle', 'status', 'idle'),
+ *   builder.case('loading', 'status', 'loading'),
+ *   builder.case('success', 'status', 'success')
+ * );
+ *
+ * // Full type inference and narrowing works!
+ * if (match.is.success(machine)) {
+ *   console.log(machine.context.data); // ✓ TypeScript knows data exists
+ * }
+ * ```
+ */
+export function forContext<C extends object>() {
+  type MachineWithContext = { readonly context: C };
+
+  return {
+    /**
+     * Creates a discriminated union case with full type inference.
+     */
+    case<
+      Name extends string,
+      K extends keyof C,
+      V extends C[K]
+    >(
+      name: Name,
+      key: K,
+      value: V
+    ): MatcherCase<
+      Name,
+      MachineWithContext & { context: Extract<C, { [P in K]: V }> },
+      (m: MachineWithContext) => m is MachineWithContext & { context: Extract<C, { [P in K]: V }> }
+    > {
+      return [
+        name,
+        undefined as any,
+        (m): m is any => hasState(m, key as any, value as any)
+      ] as const;
+    }
+  };
+}