@doeixd/machine 0.0.4

package/dist/types/generators.d.ts

@@ -0,0 +1,314 @@
+/**
+ * @file Generator-based state machine composition utilities.
+ * @description
+ * This module provides a generator-based approach to composing state machine transitions.
+ * Instead of chaining method calls or using composition functions, you can write
+ * imperative-style code using generators that feels like sequential, synchronous code
+ * while maintaining the immutability and type safety of the state machine model.
+ *
+ * This pattern is particularly useful for:
+ * - Multi-step workflows where each step depends on the previous
+ * - Complex transition logic that would be unwieldy with chaining
+ * - When you want imperative control flow (if/else, loops) with immutable state
+ * - Testing scenarios where you want to control the flow step-by-step
+ *
+ * @example
+ * ```typescript
+ * const result = run(function* (machine) {
+ *   // Each yield passes control back and receives the next state
+ *   let m = yield* step(machine.increment());
+ *   m = yield* step(m.add(5));
+ *   if (m.context.count > 10) {
+ *     m = yield* step(m.reset());
+ *   }
+ *   return m.context.count;
+ * }, initialMachine);
+ * ```
+ */
+import { Machine } from './index';
+/**
+ * Runs a generator-based state machine flow to completion.
+ *
+ * This function executes a generator that yields machine states and returns a final value.
+ * Each yield passes the current machine state back to the generator, allowing you to
+ * write imperative-style code while maintaining immutability.
+ *
+ * **How it works:**
+ * 1. The generator function receives the initial machine
+ * 2. Each `yield` expression produces a new machine state
+ * 3. That state is sent back into the generator via `next()`
+ * 4. The generator can use the received state for the next operation
+ * 5. When the generator returns, that value is returned from `run()`
+ *
+ * **Key insight:** The generator doesn't mutate state—it yields new immutable states
+ * at each step, creating a clear audit trail of state transitions.
+ *
+ * @template C - The context object type for the machine.
+ * @template T - The return type of the generator (can be any type).
+ *
+ * @param flow - A generator function that receives a machine and yields machines,
+ *               eventually returning a value of type T.
+ * @param initial - The initial machine state to start the flow.
+ *
+ * @returns The final value returned by the generator.
+ *
+ * @example Basic usage with counter
+ * ```typescript
+ * const counter = createMachine({ count: 0 }, {
+ *   increment: function() {
+ *     return createMachine({ count: this.count + 1 }, this);
+ *   },
+ *   add: function(n: number) {
+ *     return createMachine({ count: this.count + n }, this);
+ *   }
+ * });
+ *
+ * const finalCount = run(function* (m) {
+ *   m = yield* step(m.increment());  // count: 1
+ *   m = yield* step(m.add(5));       // count: 6
+ *   m = yield* step(m.increment());  // count: 7
+ *   return m.context.count;
+ * }, counter);
+ *
+ * console.log(finalCount); // 7
+ * ```
+ *
+ * @example Conditional logic
+ * ```typescript
+ * const result = run(function* (m) {
+ *   m = yield* step(m.increment());
+ *
+ *   if (m.context.count > 5) {
+ *     m = yield* step(m.reset());
+ *   } else {
+ *     m = yield* step(m.add(10));
+ *   }
+ *
+ *   return m;
+ * }, counter);
+ * ```
+ *
+ * @example Loops and accumulation
+ * ```typescript
+ * const sum = run(function* (m) {
+ *   let total = 0;
+ *
+ *   for (let i = 0; i < 5; i++) {
+ *     m = yield* step(m.increment());
+ *     total += m.context.count;
+ *   }
+ *
+ *   return total;
+ * }, counter);
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * const result = run(function* (m) {
+ *   try {
+ *     m = yield* step(m.riskyOperation());
+ *     m = yield* step(m.processResult());
+ *   } catch (error) {
+ *     m = yield* step(m.handleError(error));
+ *   }
+ *   return m;
+ * }, machine);
+ * ```
+ */
+export declare function run<C extends object, T>(flow: (m: Machine<C>) => Generator<Machine<C>, T, Machine<C>>, initial: Machine<C>): T;
+/**
+ * A helper function to yield a machine state and receive the next state back.
+ *
+ * This function creates a mini-generator that yields the provided machine and
+ * returns whatever value the outer runner sends back. It's designed to be used
+ * with `yield*` (yield delegation) inside your main generator.
+ *
+ * **Why use this helper?**
+ * - Makes the intent clear: "step to this state"
+ * - Provides a consistent API for state transitions
+ * - Enables type inference for the received state
+ * - Works seamlessly with the `run()` function
+ *
+ * **What `yield*` does:**
+ * `yield*` delegates to another generator. When you write `yield* step(m)`,
+ * control passes to the `step` generator, which yields `m`, then returns the
+ * value sent back by the runner.
+ *
+ * @template C - The context object type for the machine.
+ *
+ * @param m - The machine state to yield.
+ *
+ * @returns A generator that yields the machine and returns the received state.
+ *
+ * @example Basic stepping
+ * ```typescript
+ * run(function* (machine) {
+ *   // Yield this state and receive the next one
+ *   const next = yield* step(machine.increment());
+ *   console.log(next.context.count);
+ *   return next;
+ * }, counter);
+ * ```
+ *
+ * @example Without step (more verbose)
+ * ```typescript
+ * run(function* (machine) {
+ *   // This is what step() does internally
+ *   const next = yield machine.increment();
+ *   return next;
+ * }, counter);
+ * ```
+ *
+ * @example Chaining with step
+ * ```typescript
+ * run(function* (m) {
+ *   m = yield* step(m.action1());
+ *   m = yield* step(m.action2());
+ *   m = yield* step(m.action3());
+ *   return m;
+ * }, machine);
+ * ```
+ */
+export declare function step<C extends object>(m: Machine<C>): Generator<Machine<C>, Machine<C>, Machine<C>>;
+/**
+ * Alternative to `step` that doesn't require `yield*`.
+ * This is semantically identical but uses direct yielding.
+ *
+ * Use this if you prefer the simpler syntax without delegation.
+ *
+ * @template C - The context object type.
+ * @param m - The machine to yield.
+ * @returns The same machine (passed through).
+ *
+ * @example
+ * ```typescript
+ * run(function* (m) {
+ *   m = yield m.increment(); // No yield* needed
+ *   m = yield m.add(5);
+ *   return m;
+ * }, counter);
+ * ```
+ */
+export declare function yieldMachine<C extends object>(m: Machine<C>): Machine<C>;
+/**
+ * Runs multiple generator flows in sequence, passing the result of each to the next.
+ *
+ * This is useful for composing multiple generator-based workflows into a pipeline.
+ *
+ * @template C - The context object type.
+ * @param initial - The initial machine state.
+ * @param flows - An array of generator functions to run in sequence.
+ * @returns The final machine state after all flows complete.
+ *
+ * @example
+ * ```typescript
+ * const flow1 = function* (m: Machine<{ count: number }>) {
+ *   m = yield* step(m.increment());
+ *   return m;
+ * };
+ *
+ * const flow2 = function* (m: Machine<{ count: number }>) {
+ *   m = yield* step(m.add(5));
+ *   return m;
+ * };
+ *
+ * const result = runSequence(counter, [flow1, flow2]);
+ * console.log(result.context.count); // 6
+ * ```
+ */
+export declare function runSequence<C extends object>(initial: Machine<C>, flows: Array<(m: Machine<C>) => Generator<Machine<C>, Machine<C>, Machine<C>>>): Machine<C>;
+/**
+ * Creates a reusable generator flow that can be composed into other flows.
+ *
+ * This allows you to define common state machine patterns as reusable building blocks.
+ *
+ * @template C - The context object type.
+ * @param flow - A generator function representing a reusable flow.
+ * @returns A function that can be used with `yield*` in other generators.
+ *
+ * @example
+ * ```typescript
+ * // Define a reusable flow
+ * const incrementThrice = createFlow(function* (m: Machine<{ count: number }>) {
+ *   m = yield* step(m.increment());
+ *   m = yield* step(m.increment());
+ *   m = yield* step(m.increment());
+ *   return m;
+ * });
+ *
+ * // Use it in another flow
+ * const result = run(function* (m) {
+ *   m = yield* incrementThrice(m);
+ *   m = yield* step(m.add(10));
+ *   return m;
+ * }, counter);
+ * ```
+ */
+export declare function createFlow<C extends object>(flow: (m: Machine<C>) => Generator<Machine<C>, Machine<C>, Machine<C>>): (m: Machine<C>) => Generator<Machine<C>, Machine<C>, Machine<C>>;
+/**
+ * Runs a generator flow with debugging output at each step.
+ *
+ * This is useful for understanding the state transitions in your flow.
+ *
+ * @template C - The context object type.
+ * @template T - The return type.
+ * @param flow - The generator function to run.
+ * @param initial - The initial machine state.
+ * @param logger - Optional custom logger function.
+ * @returns The final value from the generator.
+ *
+ * @example
+ * ```typescript
+ * const result = runWithDebug(function* (m) {
+ *   m = yield* step(m.increment());
+ *   m = yield* step(m.add(5));
+ *   return m.context.count;
+ * }, counter);
+ *
+ * // Output:
+ * // Step 0: { count: 0 }
+ * // Step 1: { count: 1 }
+ * // Step 2: { count: 6 }
+ * // Final: 6
+ * ```
+ */
+export declare function runWithDebug<C extends object, T>(flow: (m: Machine<C>) => Generator<Machine<C>, T, Machine<C>>, initial: Machine<C>, logger?: (step: number, machine: Machine<C>) => void): T;
+/**
+ * Async version of `run` for async state machines.
+ *
+ * This allows you to use async/await inside your generator flows while maintaining
+ * the same compositional benefits.
+ *
+ * @template C - The context object type.
+ * @template T - The return type.
+ * @param flow - An async generator function.
+ * @param initial - The initial machine state.
+ * @returns A promise that resolves to the final value.
+ *
+ * @example
+ * ```typescript
+ * const result = await runAsync(async function* (m) {
+ *   m = yield* stepAsync(await m.fetchData());
+ *   m = yield* stepAsync(await m.processData());
+ *   return m.context;
+ * }, asyncMachine);
+ * ```
+ */
+export declare function runAsync<C extends object, T>(flow: (m: Machine<C>) => AsyncGenerator<Machine<C>, T, Machine<C>>, initial: Machine<C>): Promise<T>;
+/**
+ * Async version of `step` for async generators.
+ *
+ * @template C - The context object type.
+ * @param m - The machine to yield.
+ * @returns An async generator.
+ *
+ * @example
+ * ```typescript
+ * await runAsync(async function* (m) {
+ *   m = yield* stepAsync(await m.asyncOperation());
+ *   return m;
+ * }, machine);
+ * ```
+ */
+export declare function stepAsync<C extends object>(m: Machine<C>): AsyncGenerator<Machine<C>, Machine<C>, Machine<C>>;
+//# sourceMappingURL=generators.d.ts.map

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

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

package/dist/types/index.d.ts

@@ -0,0 +1,339 @@
+/**
+ * @file A tiny, immutable, and type-safe state machine library for TypeScript.
+ * @author doeixd
+ * @version 1.0.0
+ */
+/**
+ * A utility type that represents either a value of type T or a Promise that resolves to T.
+ * @template T - The value type.
+ */
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * The fundamental shape of any machine: a `context` object for state, and methods for transitions.
+ * @template C - The context (state) object type.
+ */
+export type Machine<C extends object> = {
+    /** The readonly state of the machine. */
+    readonly context: C;
+} & Record<string, (...args: any[]) => Machine<any>>;
+/**
+ * The shape of an asynchronous machine, where transitions can return Promises.
+ * @template C - The context (state) object type.
+ */
+export type AsyncMachine<C extends object> = {
+    /** The readonly state of the machine. */
+    readonly context: C;
+} & Record<string, (...args: any[]) => MaybePromise<AsyncMachine<any>>>;
+/**
+ * Extracts the context type `C` from a machine type `M`.
+ * @template M - The machine type.
+ * @example type Ctx = Context<Machine<{ count: number }>> // { count: number }
+ */
+export type Context<M extends {
+    context: any;
+}> = M["context"];
+/**
+ * Extracts the transition function signatures from a machine, excluding the context property.
+ * @template M - The machine type.
+ */
+export type Transitions<M extends BaseMachine<any>> = Omit<M, "context">;
+/**
+ * Extracts the argument types for a specific transition function in a Machine.
+ * @template M - The machine type.
+ * @template K - The transition function name.
+ */
+export type TransitionArgs<M extends Machine<any>, K extends keyof M & string> = M[K] extends (...args: infer A) => any ? A : never;
+/**
+ * Extracts the names of all transitions as a string union type.
+ * @template M - The machine type.
+ * @example
+ * type Names = TransitionNames<Machine<{ count: number }> & { increment: () => any }>
+ * // Names = "increment"
+ */
+export type TransitionNames<M extends BaseMachine<any>> = keyof Omit<M, "context"> & string;
+/**
+ * Base machine type that both Machine and AsyncMachine extend from.
+ * @template C - The context object type.
+ */
+export type BaseMachine<C extends object> = {
+    /** The readonly state of the machine. */
+    readonly context: C;
+} & Record<string, (...args: any[]) => any>;
+/**
+ * Helper to make a type deeply readonly (freezes nested objects).
+ * Useful for ensuring immutability of context at the type level.
+ * @template T - The type to make readonly.
+ */
+export type DeepReadonly<T> = {
+    readonly [P in keyof T]: T[P] extends object ? T[P] extends (...args: any[]) => any ? T[P] : DeepReadonly<T[P]> : T[P];
+};
+/**
+ * Infers the machine type from a machine factory function.
+ * @template F - The factory function type.
+ * @example
+ * const factory = () => createMachine({ count: 0 }, { ... });
+ * type MyMachine = InferMachine<typeof factory>; // Extracts the return type
+ */
+export type InferMachine<F extends (...args: any[]) => any> = ReturnType<F>;
+/**
+ * A discriminated union type representing an event that can be dispatched to a machine.
+ * This is automatically generated from a machine's type signature, ensuring full type safety.
+ * @template M - The machine type.
+ * @example
+ * type CounterEvent = Event<Machine<{ count: number }>& { add: (n: number) => any }>
+ * // CounterEvent = { type: "add"; args: [number] }
+ */
+export type Event<M extends BaseMachine<any>> = {
+    [K in keyof Omit<M, "context"> & string]: M[K] extends (...args: infer A) => any ? {
+        type: K;
+        args: A;
+    } : never;
+}[keyof Omit<M, "context"> & string];
+/**
+ * Creates a synchronous state machine from a context and transition functions.
+ * This is the core factory for the functional approach.
+ *
+ * @template C - The context object type.
+ * @param context - The initial state context.
+ * @param fns - An object containing transition function definitions.
+ * @returns A new machine instance.
+ */
+export declare function createMachine<C extends object, T extends Record<string, (this: C, ...args: any[]) => any>>(context: C, fns: T): {
+    context: C;
+} & T;
+/**
+ * Creates an asynchronous state machine from a context and async transition functions.
+ *
+ * @template C - The context object type.
+ * @param context - The initial state context.
+ * @param fns - An object containing async transition function definitions.
+ * @returns A new async machine instance.
+ */
+export declare function createAsyncMachine<C extends object, T extends Record<string, (this: C, ...args: any[]) => any>>(context: C, fns: T): {
+    context: C;
+} & T;
+/**
+ * Creates a machine factory - a higher-order function that simplifies machine creation.
+ * Instead of writing transition logic that creates new machines, you just write
+ * pure context transformation functions.
+ *
+ * @template C - The context object type.
+ * @returns A factory configurator function.
+ *
+ * @example
+ * const counterFactory = createMachineFactory<{ count: number }>()({
+ *   increment: (ctx) => ({ count: ctx.count + 1 }),
+ *   add: (ctx, n: number) => ({ count: ctx.count + n })
+ * });
+ *
+ * const counter = counterFactory({ count: 0 });
+ * const next = counter.increment(); // Returns new machine with count: 1
+ */
+export declare function createMachineFactory<C extends object>(): <T extends Record<string, (ctx: C, ...args: any[]) => C>>(transformers: T) => (initialContext: C) => Machine<C> & { [K in keyof T]: (this: C, ...args: T[K] extends (ctx: C, ...args: infer A) => C ? A : never) => Machine<C>; };
+/**
+ * Creates a new machine instance with an updated context, preserving all original transitions.
+ * This is the primary, type-safe utility for applying state changes.
+ *
+ * @template M - The machine type.
+ * @param machine - The original machine instance.
+ * @param newContextOrFn - The new context object or an updater function.
+ * @returns A new machine instance of the same type with the updated context.
+ */
+export declare function setContext<M extends Machine<any>>(machine: M, newContextOrFn: Context<M> | ((ctx: Readonly<Context<M>>) => Context<M>)): M;
+/**
+ * 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.
+ *
+ * @template M - The original machine type.
+ * @template T - An object of new or overriding transition functions.
+ * @param machine - The base machine instance.
+ * @param overrides - An object containing the transitions to add or overwrite.
+ * @returns A new machine instance with the merged transitions.
+ */
+export declare function overrideTransitions<M extends Machine<any>, T extends Record<string, (this: Context<M>, ...args: any[]) => any>>(machine: M, overrides: T): Machine<Context<M>> & Omit<Transitions<M>, keyof T> & T;
+/**
+ * Creates a new machine by adding new transition functions.
+ * This utility will produce a compile-time error if you attempt to add a
+ * transition that already exists, preventing accidental overrides.
+ *
+ * @template M - The original machine type.
+ * @template T - An object of new transition functions, whose keys must not exist in M.
+ * @param machine - The base machine instance.
+ * @param newTransitions - An object containing the new transitions to add.
+ * @returns A new machine instance with the combined original and new transitions.
+ */
+export declare function extendTransitions<M extends Machine<any>, T extends Record<string, (this: Context<M>, ...args: any[]) => any> & {
+    [K in keyof T]: K extends keyof M ? never : T[K];
+}>(machine: M, newTransitions: T): M & T;
+/**
+ * Creates a builder function from a "template" machine instance.
+ * This captures the behavior of a machine and returns a factory that can stamp out
+ * new instances with different initial contexts. Excellent for class-based machines.
+ *
+ * @template M - The machine type.
+ * @param templateMachine - An instance of a machine to use as the template.
+ * @returns A function that builds new machines of type M.
+ */
+export declare function createMachineBuilder<M extends Machine<any>>(templateMachine: M): (context: Context<M>) => M;
+/**
+ * Pattern match on a machine's state based on a discriminant property in the context.
+ * This provides type-safe exhaustive matching for state machines.
+ *
+ * @template M - The machine type.
+ * @template K - The discriminant key in the context.
+ * @template R - The return type.
+ * @param machine - The machine to match against.
+ * @param discriminantKey - The key in the context to use for matching (e.g., "status").
+ * @param handlers - An object mapping each possible value to a handler function.
+ * @returns The result of the matched handler.
+ *
+ * @example
+ * const result = matchMachine(
+ *   machine,
+ *   'status',
+ *   {
+ *     idle: (ctx) => "Machine is idle",
+ *     loading: (ctx) => "Loading...",
+ *     success: (ctx) => `Success: ${ctx.data}`,
+ *     error: (ctx) => `Error: ${ctx.error}`
+ *   }
+ * );
+ */
+export declare function matchMachine<M extends Machine<any>, K extends keyof Context<M> & string, R>(machine: M, discriminantKey: K, handlers: {
+    [V in Context<M>[K] & string]: (ctx: Context<M>) => R;
+}): R;
+/**
+ * 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.
+ *
+ * @template M - The machine type.
+ * @template K - The discriminant key.
+ * @template V - The discriminant value.
+ * @param machine - The machine to check.
+ * @param key - The discriminant key to check.
+ * @param value - The expected value.
+ * @returns True if the discriminant matches, with type narrowing.
+ *
+ * @example
+ * if (hasState(machine, 'status', 'loading')) {
+ *   // machine.context.status is narrowed to 'loading'
+ * }
+ */
+export declare function hasState<M extends Machine<any>, K extends keyof Context<M>, V extends Context<M>[K]>(machine: M, key: K, value: V): machine is M & {
+    context: Context<M> & {
+        [P in K]: V;
+    };
+};
+/**
+ * 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.
+ *
+ * @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.
+ */
+export declare function runMachine<M extends AsyncMachine<any>>(initial: M, onChange?: (m: M) => void): {
+    /** Gets the context of the current state of the machine. */
+    readonly state: Context<M>;
+    /** Dispatches a type-safe event to the machine, triggering a transition. */
+    dispatch: <E extends Event<M>>(event: E) => Promise<M>;
+};
+/**
+ * An optional base class for creating machines using an Object-Oriented style.
+ *
+ * This class provides the fundamental structure required by the library: a `context`
+ * property to hold the state. By extending `MachineBase`, you get a clear and
+ * type-safe starting point for defining states and transitions as classes and methods.
+ *
+ * Transitions should be implemented as methods that return a new instance of a
+ * state machine class (often `new MyClass(...)` or by using a `createMachineBuilder`).
+ * The `context` is marked `readonly` to enforce the immutable update pattern.
+ *
+ * @template C - The context object type that defines the state for this machine.
+ *
+ * @example
+ * // Define a simple counter state
+ * class Counter extends MachineBase<{ readonly count: number }> {
+ *   constructor(count = 0) {
+ *     super({ count });
+ *   }
+ *
+ *   increment(): Counter {
+ *     // Return a new instance for the next state
+ *     return new Counter(this.context.count + 1);
+ *   }
+ *
+ *   add(n: number): Counter {
+ *     return new Counter(this.context.count + n);
+ *   }
+ * }
+ *
+ * const machine = new Counter(5);
+ * const nextState = machine.increment(); // Returns a new Counter instance
+ *
+ * console.log(machine.context.count);    // 5 (original is unchanged)
+ * console.log(nextState.context.count);  // 6 (new state)
+ */
+export declare class MachineBase<C extends object> {
+    /**
+     * The immutable state of the machine.
+     * To change the state, a transition method must return a new machine instance
+     * with a new context object.
+     */
+    readonly context: C;
+    /**
+     * Initializes a new machine instance with its starting context.
+     * @param context - The initial state of the machine.
+     */
+    constructor(context: C);
+}
+/**
+ * Applies an update function to a machine's context, returning a new machine.
+ * This is a simpler alternative to `setContext` when you always use an updater function.
+ *
+ * @template C - The context object type.
+ * @param m - The machine to update.
+ * @param update - A function that takes the current context and returns the new context.
+ * @returns A new machine with the updated context.
+ *
+ * @example
+ * const updated = next(counter, (ctx) => ({ count: ctx.count + 1 }));
+ */
+export declare function next<C extends object>(m: Machine<C>, update: (ctx: Readonly<C>) => C): Machine<C>;
+/**
+ * A type representing either a synchronous Machine or a Promise that resolves to a Machine.
+ * Useful for functions that can return either sync or async machines.
+ *
+ * @template C - The context object type.
+ *
+ * @example
+ * function getMachine(): MachineLike<{ count: number }> {
+ *   if (Math.random() > 0.5) {
+ *     return createMachine({ count: 0 }, { ... });
+ *   } else {
+ *     return Promise.resolve(createMachine({ count: 0 }, { ... }));
+ *   }
+ * }
+ */
+export type MachineLike<C extends object> = Machine<C> | Promise<Machine<C>>;
+/**
+ * A type representing the result of a machine transition.
+ * Can be either:
+ * - A new machine state
+ * - A tuple of [machine, cleanup function] where cleanup is called when leaving the state
+ *
+ * This enables state machines with side effects that need cleanup (e.g., subscriptions, timers).
+ *
+ * @template C - The context object type.
+ *
+ * @example
+ * function transition(): MachineResult<{ count: number }> {
+ *   const interval = setInterval(() => console.log("tick"), 1000);
+ *   const machine = createMachine({ count: 0 }, { ... });
+ *   return [machine, () => clearInterval(interval)];
+ * }
+ */
+export type MachineResult<C extends object> = Machine<C> | [Machine<C>, () => void | Promise<void>];
+export { run, step, yieldMachine, runSequence, createFlow, runWithDebug, runAsync, stepAsync } from './generators';
+//# sourceMappingURL=index.d.ts.map

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

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