@doeixd/machine 0.0.11 → 0.0.12

package/src/functional-combinators.ts

@@ -0,0 +1,267 @@
+import { createMachine, Machine, extendTransitions } from './index';
+
+/**
+ * Creates a factory for building type-safe transitions for a specific machine.
+ * This higher-order function captures the machine's `transitions` object in a closure,
+ * enabling a clean, functional pattern for defining state changes without directly
+ * manipulating the machine's context.
+ *
+ * This pattern promotes:
+ * - Pure functions for state transformations
+ * - Separation of transition logic from machine construction
+ * - Reusable transition factories across similar machines
+ * - Type safety through generic constraints
+ *
+ * @template C The context type of the machine
+ * @template C The context type of the machine
+ * @returns A `createTransition` function that can create transitions for machines with context type C
+ *
+ * @example
+ * ```typescript
+ * // Define your machine's transitions object
+ * const counterTransitions = {
+ *   increment: function(amount: number) {
+ *     return createMachine({ count: this.count + amount }, counterTransitions);
+ *   }
+ * };
+ *
+ * // Create a transition factory
+ * const createCounterTransition = createTransitionFactory<{ count: number }>();
+ *
+ * // Use the factory to create pure, type-safe transitions
+ * const incrementBy = createCounterTransition(
+ *   (ctx, amount: number) => ({ count: ctx.count + amount })
+ * );
+ *
+ * const counter = createMachine({ count: 0 }, counterTransitions);
+ * const newCounter = counter.increment(5); // Direct call
+ * // OR
+ * const incremented = incrementBy.call(counter, 5); // Using factory
+ * ```
+ */
+export function createTransitionFactory<C extends object>() {
+  /**
+   * Takes a pure context transformer function and returns a full, type-safe
+   * machine transition method that can be attached to a machine.
+   *
+   * The transformer function receives the current context as its first argument,
+   * followed by any additional arguments passed to the transition.
+   *
+   * @template TArgs The argument types for the transition (excluding context)
+   * @param transformer A pure function: `(context, ...args) => nextContext`
+   * @returns A machine transition method that can be called on a machine instance
+   *
+   * @example
+   * ```typescript
+   * const createTodoTransition = createTransitionFactory<TodoContext>();
+   *
+   * const addTodo = createTodoTransition(
+   *   (ctx, text: string) => ({
+   *     ...ctx,
+   *     todos: [...ctx.todos, { id: Date.now(), text, completed: false }]
+   *   })
+   * );
+   *
+   * const updateTodo = createTodoTransition(
+   *   (ctx, id: number, updates: Partial<Todo>) => ({
+   *     ...ctx,
+   *     todos: ctx.todos.map(todo =>
+   *       todo.id === id ? { ...todo, ...updates } : todo
+   *     )
+   *   })
+   * );
+   * ```
+   */
+  return function createTransition<TArgs extends any[]>(
+    transformer: (ctx: C, ...args: TArgs) => C
+  ) {
+    return function (this: Machine<C>, ...args: TArgs): Machine<C> {
+      const nextContext = transformer(this.context, ...args);
+      // Use `this` as the transitions object, which includes all current transitions
+      return createMachine(nextContext, this);
+    };
+  };
+}
+
+/**
+ * Creates a factory for adding new, type-safe transitions to an existing machine instance.
+ * This enables a functional, compositional approach to building up a machine's capabilities
+ * incrementally, without modifying the original machine.
+ *
+ * This pattern supports:
+ * - Progressive enhancement of machine behavior
+ * - Plugin-like extension of existing machines
+ * - Immutable composition (original machine unchanged)
+ * - Type-safe addition of new transitions
+ *
+ * @template M The machine type being extended
+ * @param machine The machine instance to extend
+ * @returns An `addTransition` function pre-configured for this machine
+ *
+ * @example
+ * ```typescript
+ * // Start with a basic counter machine
+ * const basicCounter = createMachine({ count: 0 }, {
+ *   increment: function() {
+ *     return createMachine({ count: this.count + 1 }, this);
+ *   }
+ * });
+ *
+ * // Create an extender for this machine
+ * const extendCounter = createTransitionExtender(basicCounter);
+ *
+ * // Add new transitions functionally
+ * const extendedCounter = extendCounter('decrement',
+ *   (ctx) => ({ count: ctx.count - 1 })
+ * ).addTransition('reset',
+ *   (ctx) => ({ count: 0 })
+ * ).addTransition('add',
+ *   (ctx, amount: number) => ({ count: ctx.count + amount })
+ * );
+ *
+ * // The original machine is unchanged
+ * console.log(basicCounter.count); // 0
+ *
+ * // The extended machine has all transitions
+ * const result = extendedCounter.increment().add(10).decrement();
+ * console.log(result.count); // 10
+ * ```
+ */
+export function createTransitionExtender<M extends Machine<any>>(machine: M) {
+  type C = M['context'];
+
+  /**
+   * Adds a new transition to the machine and returns a new extender for chaining.
+   * The new transition is created from a pure context transformer function.
+   *
+   * @template TName The name of the new transition
+   * @template TArgs The argument types for the new transition
+   * @param name The name of the new transition method
+   * @param transformer A pure function that defines how the context should change
+   * @returns A new transition extender with the added transition
+   *
+   * @example
+   * ```typescript
+   * const userMachine = createMachine({ name: '', email: '' }, {});
+   * const extendUser = createTransitionExtender(userMachine);
+   *
+   * const withValidation = extendUser.addTransition('setName',
+   *   (ctx, name: string) => {
+   *     if (name.length < 2) throw new Error('Name too short');
+   *     return { ...ctx, name };
+   *   }
+   * ).addTransition('setEmail',
+   *   (ctx, email: string) => {
+   *     if (!email.includes('@')) throw new Error('Invalid email');
+   *     return { ...ctx, email };
+   *   }
+   * );
+   *
+   * const user = withValidation.machine.setName('John').setEmail('john@example.com');
+   * ```
+   */
+  return {
+    machine,
+
+    addTransition: function<
+      TName extends string,
+      TArgs extends any[],
+    >(
+      name: TName,
+      transformer: (ctx: C, ...args: TArgs) => C
+    ) {
+      const transitionFn = function (this: Machine<C>, ...args: TArgs) {
+        const nextContext = transformer(this.context, ...args);
+
+        // Use `this` as the transitions object, which includes all current transitions
+        return createMachine(nextContext, this);
+      };
+
+      // Create the extended machine
+      const newMachine = extendTransitions(machine, { [name]: transitionFn } as any);
+
+      // Return a new extender that includes this transition
+      return createTransitionExtender(newMachine);
+    }
+  };
+}
+
+/**
+ * A mapped type that creates the final transition method signatures based on
+ * an object of pure context transformers. It infers argument types and sets
+ * the correct return type.
+ */
+type MachineTransitions<
+  T extends Record<string, (ctx: C, ...args: any[]) => C>,
+  C extends object
+> = {
+  [K in keyof T]: T[K] extends (ctx: C, ...args: infer A) => C
+    ? (this: { context: C } & T, ...args: A) => Machine<C>
+    : never;
+};
+
+/**
+ * Creates a complete, type-safe, functional state machine using a curried, two-step
+ * approach that separates the initial data from the transition logic.
+ *
+ * This is a highly declarative and functional pattern for building single-state machines.
+ *
+ * @template C The context type of the machine.
+ * @param initialContext The starting context (data) for the machine.
+ * @returns A new function that takes an object of pure context-transformer
+ *   functions and returns a fully-formed machine instance.
+ */
+export function createFunctionalMachine<C extends object>(initialContext: C) {
+  /**
+   * This returned function is pre-configured with the `initialContext`.
+   *
+   * @template T The type of the transformers object.
+   * @param transformers An object where each key is a transition name and each value
+   *   is a pure function: `(context, ...args) => nextContext`.
+   * @returns A fully-formed, immutable, and type-safe machine instance.
+   *
+   * @example
+   * ```typescript
+   * const createCounter = createFunctionalMachine({ count: 0 });
+   *
+   * const counter = createCounter({
+   *   increment: (ctx) => ({ count: ctx.count + 1 }),
+   *   decrement: (ctx) => ({ count: ctx.count - 1 }),
+   *   add: (ctx, amount: number) => ({ count: ctx.count + amount }),
+   *   reset: (ctx) => ({ count: 0 })
+   * });
+   *
+   * // Use the machine
+   * const updated = counter.increment().add(5).decrement();
+   * console.log(updated.context.count); // 5
+   * ```
+   */
+  return function withTransitions<
+    T extends Record<string, (ctx: C, ...args: any[]) => C>
+  >(
+    transformers: T
+  ): Machine<C> & MachineTransitions<T, C> {
+    // 1. Create a placeholder object for the final transitions.
+    const transitions: any = {};
+
+    // 2. Map the pure transformers to full machine transition methods.
+    const machineTransitions = Object.fromEntries(
+      Object.entries(transformers).map(([key, transformer]) => [
+        key,
+        function (this: { context: C }, ...args: any[]) {
+          // Apply the pure data transformation.
+          const nextContext = transformer(this.context, ...args);
+          // Return a new machine, passing in the `transitions` object from the closure.
+          // At this point, `transitions` will be fully populated.
+          return createMachine(nextContext, transitions);
+        },
+      ])
+    );
+
+    // 3. Populate the placeholder with the real transitions.
+    Object.assign(transitions, machineTransitions);
+
+    // 4. Create and return the initial machine instance using the provided context.
+    return createMachine(initialContext, transitions) as any;
+  };
+}

package/src/index.ts

@@ -778,10 +778,21 @@ export {
 export {
   isState,
   createEvent,
+  createTransition,
   mergeContext,
   pipeTransitions,
   logState,
   call,
   bindTransitions,
   BoundMachine
-} from './utils';
+} from './utils';
+
+// =============================================================================
+// SECTION: FUNCTIONAL COMBINATORS
+// =============================================================================
+
+export {
+  createTransitionFactory,
+  createTransitionExtender,
+  createFunctionalMachine
+} from './functional-combinators';

package/src/multi.ts

@@ -514,6 +514,42 @@ export function createEnsemble<
   };
 }
 
+/**
+ * Creates a factory for building type-safe, framework-agnostic Ensembles.
+ * This is a higher-order function that captures the application's state store
+ * and state-discriminant logic in a closure.
+ *
+ * This allows you to define your application's state "environment" once and then
+ * easily create multiple, consistent ensembles by only providing the behavioral logic.
+ *
+ * @template C The shared context type for the application.
+ * @param store The application's state store (e.g., from React, Zustand, etc.).
+ * @param getDiscriminant An accessor function that determines the current state from the context.
+ * @returns A `withFactories` function that is pre-configured for your app's environment.
+ */
+export function createEnsembleFactory<C extends object>(
+  store: StateStore<C>,
+  getDiscriminant: (context: C) => keyof any
+) {
+  /**
+   * This returned function is pre-configured with the `store` and `getDiscriminant` logic.
+   * It takes the machine factories (the behavioral logic) and returns a complete Ensemble.
+   *
+   * @template F The type of the factories object.
+   * @param factories An object where each key is a state name and each value is a
+   *   function that creates a machine instance for that state.
+   * @returns A fully-formed, reactive, and type-safe Ensemble instance.
+   */
+  return function withFactories<
+    F extends Record<string, (context: C) => Machine<C>>
+  >(
+    factories: F
+  ): Ensemble<ReturnType<F[keyof F]>, C> {
+    // We simply call the original createEnsemble with the captured arguments.
+    return createEnsemble(store, factories, getDiscriminant as (context: C) => keyof F);
+  };
+}
+
 // =============================================================================
 // SECTION 3: GENERATOR INTEGRATION
 // =============================================================================

package/src/utils.ts

@@ -13,6 +13,7 @@ import {
   Transitions,
   TransitionArgs,
   setContext,
+  createMachine,
 } from './index'; // Assuming index.ts is in the same directory
 
 // =============================================================================
@@ -166,6 +167,79 @@ export function logState<M extends Machine<any>>(machine: M, label?: string): M
    return machine;
 }
 
+/**
+ * A generic combinator that creates transition functions from pure context transformers.
+ * This enables writing transitions as simple, testable functions that only transform context,
+ * while automatically handling the machine creation boilerplate.
+ *
+ * @template C - The context object type.
+ * @template TArgs - The argument types for the transition function.
+ * @param getTransitions - A function that returns the transition functions object to use for the new machine.
+ * @param transformer - A pure function that transforms the context based on the current state and arguments.
+ * @returns A transition function that can be used as a machine method.
+ *
+ * @example
+ * ```typescript
+ * // Define transitions object with self-reference
+ * const counterTransitions = {
+ *   increment: createTransition(
+ *     () => counterTransitions,
+ *     (ctx) => ({ count: ctx.count + 1 })
+ *   ),
+ *   add: createTransition(
+ *     () => counterTransitions,
+ *     (ctx, n: number) => ({ count: ctx.count + n })
+ *   )
+ * };
+ *
+ * // Create machine
+ * const counter = createMachine({ count: 0 }, counterTransitions);
+ *
+ * // Use transitions
+ * const incremented = counter.increment(); // { count: 1 }
+ * const added = incremented.add(5);       // { count: 6 }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With class-based machines
+ * class Counter extends MachineBase<{ count: number }> {
+ *   constructor(count = 0) {
+ *     super({ count });
+ *   }
+ *
+ *   increment = createTransition(
+ *     () => ({ increment: this.increment, add: this.add }),
+ *     (ctx) => ({ count: ctx.count + 1 })
+ *   );
+ *
+ *   add = createTransition(
+ *     () => ({ increment: this.increment, add: this.add }),
+ *     (ctx, n: number) => ({ count: ctx.count + n })
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * This function promotes the library's philosophy of pure, immutable transitions.
+ * The transformer function should be pure and only depend on its parameters.
+ * The returned transition function automatically creates a new machine instance,
+ * preserving all transitions while updating only the context.
+ * The getTransitions function is called lazily to avoid circular reference issues.
+ */
+export function createTransition<
+  C extends object,
+  TArgs extends any[]
+>(
+  getTransitions: () => Record<string, (this: C, ...args: any[]) => any>,
+  transformer: (ctx: C, ...args: TArgs) => C
+): (this: { context: C }, ...args: TArgs) => Machine<C> {
+  return function (this: { context: C }, ...args: TArgs): Machine<C> {
+    const nextContext = transformer(this.context, ...args);
+    return createMachine(nextContext, getTransitions());
+  };
+}
+
 // =============================================================================
 // SECTION: TRANSITION BINDING HELPERS
 // =============================================================================