@doeixd/machine 0.0.18 → 0.0.20

package/dist/types/matcher.d.ts

@@ -0,0 +1,325 @@
+/**
+ * @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';
+/**
+ * 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 ExtractHandledMachines<H extends readonly any[]> = H extends readonly [infer First, ...infer Rest] ? (First extends CaseHandler<any, infer M, any> ? M : never) | ExtractHandledMachines<Rest> : never;
+/**
+ * Extracts return types from an array of case handlers.
+ */
+type ExtractHandlerReturn<H extends readonly any[]> = H extends readonly CaseHandler<any, any, infer R>[] ? R : 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
+     * );
+     * ```
+     */
+    /**
+     * Overload 1: Infer return type from handlers (Enables exhaustiveness checking).
+     */
+    is<H extends readonly CaseHandler<CaseNames<_Cases>, any, any>[]>(...handlers: [...H, ExhaustivenessMarker]): IsExhaustive<M, ExtractHandledMachines<H>> extends true ? ExtractHandlerReturn<H> : IsExhaustive<M, ExtractHandledMachines<H>>;
+    /**
+     * Overload 2: Explicit return type (No exhaustiveness checking).
+     */
+    is<R>(...handlers: [...CaseHandler<CaseNames<_Cases>, any, R>[], ExhaustivenessMarker]): R;
+}
+/**
+ * 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>]: (machine: any) => machine is 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;
+}
+/**
+ * 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 declare function createMatcher<const Cases extends readonly MatcherCase<string, any, (m: any) => m is any>[]>(...cases: Cases): Matcher<Cases>;
+/**
+ * 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 declare 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>>;
+/**
+ * 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 declare 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;
+    }>;
+}>;
+/**
+ * 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 declare function customCase<const Name extends string, M>(name: Name, predicate: (m: any) => m is M): MatcherCase<Name, M, (m: any) => m is M>;
+/**
+ * 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 declare function forContext<C extends object>(): {
+    /**
+     * 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, {
+        readonly context: Extract<C, { [P in K]: V; }>;
+    }, (m: {
+        readonly context: C;
+    }) => m is {
+        readonly context: Extract<C, { [P in K]: V; }>;
+    }>;
+};
+export {};
+//# sourceMappingURL=matcher.d.ts.map

package/dist/types/matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matcher.d.ts","sourceRoot":"","sources":["../../src/matcher.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doeixd/machine",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "files": [
     "dist",
     "src"
@@ -115,12 +115,24 @@
       },
       "require": "./dist/cjs/production/core.js",
       "import": "./dist/esm/production/core.js"
+    },
+    "./extract": {
+      "types": "./dist/types/extract.d.ts",
+      "development": {
+        "require": "./dist/cjs/development/extract.js",
+        "import": "./dist/esm/development/extract.js"
+      },
+      "require": "./dist/cjs/production/extract.js",
+      "import": "./dist/esm/production/extract.js"
     }
   },
   "typesVersions": {
     "*": {
       "core": [
         "./dist/types/core.d.ts"
+      ],
+      "extract": [
+        "./dist/types/extract.d.ts"
       ]
     }
   },

package/src/index.ts

@@ -345,7 +345,7 @@ 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, any>) => T
 ): Machine<C, BindTransitions<T>>;
@@ -584,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.
@@ -764,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.
@@ -775,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<
@@ -787,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;
 }
 
@@ -1043,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
 // =============================================================================
@@ -1084,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';