@doeixd/machine 1.0.2 → 1.1.0

package/src/delegate.ts

@@ -0,0 +1,267 @@
+// ============================================================================
+// DELEGATION: delegate()
+// ============================================================================
+
+/**
+ * Extracts the names of all function properties (transitions) from a type.
+ */
+type TransitionNamesOf<T> = {
+  [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never;
+}[keyof T];
+
+/**
+ * Extracts the argument types of a function.
+ */
+type ArgsOf<F> = F extends (...args: infer A) => any ? A : never;
+
+/**
+ * Creates delegated transitions that forward to a child and return the parent.
+ * 
+ * @typeParam Child - Child machine type
+ * @typeParam Parent - Parent machine return type
+ */
+type DelegatedTransitions<
+  Child extends object,
+  Parent
+> = {
+    [K in TransitionNamesOf<Child>]: (
+      ...args: ArgsOf<Child[K]>
+    ) => Parent;
+  };
+
+/**
+ * Renamed delegated transitions using a mapping object.
+ * 
+ * @typeParam Child - Child machine type
+ * @typeParam Parent - Parent machine return type
+ * @typeParam Mapping - Object mapping child transition names to parent names
+ */
+type RenamedDelegatedTransitions<
+  Child extends object,
+  Parent,
+  Mapping extends Partial<Record<TransitionNamesOf<Child>, string>>
+> = {
+    [K in keyof Mapping as Mapping[K] extends string ? Mapping[K] : never]: K extends TransitionNamesOf<Child>
+    ? (...args: ArgsOf<Child[K]>) => Parent
+    : never;
+  };
+
+/**
+ * Subset of delegated transitions.
+ * 
+ * @typeParam Child - Child machine type
+ * @typeParam Parent - Parent machine return type
+ * @typeParam Keys - Subset of child transition names to delegate
+ */
+type PickedDelegatedTransitions<
+  Child extends object,
+  Parent,
+  Keys extends TransitionNamesOf<Child>
+> = {
+    [K in Keys]: (...args: ArgsOf<Child[K]>) => Parent;
+  };
+
+/**
+ * Options for delegate function.
+ */
+type DelegateOptions<Child extends object> =
+  | { pick: Array<TransitionNamesOf<Child>> }
+  | { omit: Array<TransitionNamesOf<Child>> }
+  | { rename: Partial<Record<TransitionNamesOf<Child>, string>> };
+
+/**
+ * Delegates child machine transitions to the parent level.
+ * 
+ * When a delegated transition is called on the parent, it:
+ * 1. Calls the corresponding transition on the child
+ * 2. Updates the parent's context with the new child state
+ * 3. Returns a new parent machine
+ * 
+ * This enables "flat" composition where child transitions appear directly
+ * on the parent, as opposed to `withChildren()` which namespaces them.
+ * 
+ * @typeParam Ctx - Parent context type
+ * @typeParam Key - Key where child is stored in parent context
+ * @typeParam R - Parent machine return type (e.g. Machine<Ctx, T>)
+ * 
+ * @param ctx - Current parent context (from transition factory)
+ * @param key - Property key of the child machine in context
+ * @param next - The `next` function from the parent's transition factory
+ * @param options - Optional: pick, omit, or rename specific transitions
+ * 
+ * @returns Object of delegated transitions to spread into parent's transitions
+ */
+export function delegate<
+  Ctx extends object,
+  Key extends keyof Ctx,
+  R,
+  Child extends Ctx[Key] & object = Ctx[Key] & object
+>(
+  ctx: Ctx,
+  key: Key,
+  next: (c: Ctx) => R
+): DelegatedTransitions<Child, R>;
+
+export function delegate<
+  Ctx extends object,
+  Key extends keyof Ctx,
+  R,
+  Child extends Ctx[Key] & object,
+  Keys extends TransitionNamesOf<Child>
+>(
+  ctx: Ctx,
+  key: Key,
+  next: (c: Ctx) => R,
+  options: { pick: Keys[] }
+): PickedDelegatedTransitions<Child, R, Keys>;
+
+export function delegate<
+  Ctx extends object,
+  Key extends keyof Ctx,
+  R,
+  Child extends Ctx[Key] & object,
+  Keys extends TransitionNamesOf<Child>
+>(
+  ctx: Ctx,
+  key: Key,
+  next: (c: Ctx) => R,
+  options: { omit: Keys[] }
+): DelegatedTransitions<Omit<Child, Keys>, R>;
+
+export function delegate<
+  Ctx extends object,
+  Key extends keyof Ctx,
+  R,
+  Child extends Ctx[Key] & object,
+  Mapping extends Partial<Record<TransitionNamesOf<Child>, string>>
+>(
+  ctx: Ctx,
+  key: Key,
+  next: (c: Ctx) => R,
+  options: { rename: Mapping }
+): RenamedDelegatedTransitions<Child, R, Mapping>;
+
+export function delegate<
+  Ctx extends object,
+  Key extends keyof Ctx,
+  R
+>(
+  ctx: Ctx,
+  key: Key,
+  next: (c: Ctx) => R,
+  options?: DelegateOptions<Ctx[Key] & object>
+): Record<string, (...args: unknown[]) => R> {
+  const child = ctx[key] as Record<string, unknown>;
+  const delegated: Record<string, (...args: unknown[]) => R> = {};
+
+  // Get all function property names from child
+  const allTransitions = Object.keys(child).filter(
+    (k) => typeof child[k] === 'function'
+  );
+
+  // Determine which transitions to include and how to name them
+  let transitionMap: Record<string, string>; // childName -> parentName
+
+  if (!options) {
+    // Delegate all with same names
+    transitionMap = Object.fromEntries(allTransitions.map((t) => [t, t]));
+  } else if ('pick' in options) {
+    // Only picked transitions
+    transitionMap = Object.fromEntries(
+      (options.pick as string[]).filter((t) => allTransitions.includes(t)).map((t) => [t, t])
+    );
+  } else if ('omit' in options) {
+    // All except omitted
+    const omitSet = new Set(options.omit as string[]);
+    transitionMap = Object.fromEntries(
+      allTransitions.filter((t) => !omitSet.has(t)).map((t) => [t, t])
+    );
+  } else if ('rename' in options) {
+    // Only renamed transitions with new names
+    transitionMap = Object.fromEntries(
+      Object.entries(options.rename as Record<string, string>).filter(
+        ([childName]) => allTransitions.includes(childName)
+      )
+    );
+  } else {
+    transitionMap = {};
+  }
+
+  // Create delegated transitions
+  for (const [childName, parentName] of Object.entries(transitionMap)) {
+    const childTransition = child[childName] as (...args: unknown[]) => unknown;
+
+    delegated[parentName] = (...args: unknown[]) => {
+      const nextChild = childTransition.apply(child, args);
+      return next({ ...ctx, [key]: nextChild } as Ctx);
+    };
+  }
+
+  return delegated;
+}
+
+/**
+ * Type helper to get transition names from a machine or object.
+ * Useful for type-safe pick/omit/rename options.
+ */
+export type TransitionsOf<M> = TransitionNamesOf<M>;
+
+// ============================================================================
+// DELEGATION UTILITIES
+// ============================================================================
+
+/**
+ * Creates a delegate helper bound to a specific context and next function.
+ * Useful when delegating multiple children to avoid repetition.
+ */
+export function createDelegate<Ctx extends object, R>(
+  ctx: Ctx,
+  next: (c: Ctx) => R
+) {
+  return <Key extends keyof Ctx>(
+    key: Key,
+    options?: DelegateOptions<Ctx[Key] & object>
+  ) => delegate(ctx, key, next, options as any);
+}
+
+/**
+ * Delegates all transitions from multiple children, optionally with a prefix.
+ */
+export function delegateAll<
+  Ctx extends object,
+  Keys extends keyof Ctx,
+  R
+>(
+  ctx: Ctx,
+  keys: Keys[],
+  next: (c: Ctx) => R,
+  prefix: boolean = false
+): Record<string, (...args: unknown[]) => R> {
+  const result: Record<string, (...args: unknown[]) => R> = {};
+
+  for (const key of keys) {
+    const child = ctx[key] as Record<string, unknown>;
+    const transitions = Object.keys(child).filter(
+      (k) => typeof child[k] === 'function'
+    );
+
+    for (const transitionName of transitions) {
+      const parentName = prefix ? `${String(key)}_${transitionName}` : transitionName;
+      const childTransition = child[transitionName] as (...args: unknown[]) => unknown;
+
+      result[parentName] = (...args: unknown[]) => {
+        const nextChild = childTransition.apply(child, args);
+        return next({ ...ctx, [key]: nextChild } as Ctx);
+      };
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Type-safe helper to create a rename mapping for delegate.
+ */
+export function renameMap<M extends object>() {
+  return <T extends Partial<Record<TransitionNamesOf<M>, string>>>(mapping: T): T => mapping;
+}

package/src/higher-order.ts

@@ -9,15 +9,15 @@
  * Think of this as the "standard library" of common machine patterns.
  */
 
+import { MachineBase } from './base'; // Import from base to avoid circular dependency
 import {
-  MachineBase,
   Machine,
   Transitions,
   // AsyncMachine,
   setContext,
   Context,
   // MaybePromise,
-} from './index'; // Assuming this is a sibling package or in the same project
+} from './index';
 
 // =============================================================================
 // SECTION 1: CUSTOM PRIMITIVES FOR COMPOSITION

package/src/index.ts

@@ -870,61 +870,8 @@ export function runMachine<M extends AsyncMachine<any>>(
   };
 }
 
-/**
- * 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 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.
-   */
-  public readonly context: C;
-
-  /**
-   * Initializes a new machine instance with its starting context.
-   * @param context - The initial state of the machine.
-   */
-  constructor(context: C) {
-    this.context = context;
-    // Object.freeze can provide additional runtime safety against accidental mutation,
-    // though it comes with a minor performance cost. It's a good practice for ensuring purity.
-    // Object.freeze(this.context);
-  }
-}
+// Export MachineBase from separate file to avoid circular dependency issues
+export { MachineBase } from './base';
 
 
 /**
@@ -1132,3 +1079,16 @@ export {
   isContextBound,
   type ContextBoundMachine
 } from './context-bound';
+
+// =============================================================================
+// SECTION: MINIMAL & DELEGATED API
+// =============================================================================
+
+export * as minimal from './minimal';
+export * as delegate from './delegate';
+
+// =============================================================================
+// SECTION: TAGGED HELPERS & UTILITIES
+// =============================================================================
+
+export * from './types';