@doeixd/machine 0.0.20 → 0.0.22

package/src/actor.ts

@@ -0,0 +1,284 @@
+import {
+  Event,
+  BaseMachine,
+  TransitionNames,
+  TransitionArgs,
+  MaybePromise,
+  createMachine
+} from './index';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * A standard interface for interacting with any actor-like entity.
+ */
+export interface ActorRef<T> {
+  dispatch: (event: any) => void;
+  getSnapshot: () => T;
+  subscribe: (observer: (state: T) => void) => () => void;
+}
+
+/**
+ * Inspection event type.
+ */
+export type InspectionEvent = {
+  type: '@actor/send'; // Extendable for lifecycle
+  actor: ActorRef<any>;
+  event: any;
+  snapshot: any;
+};
+
+// =============================================================================
+// ACTOR CLASS
+// =============================================================================
+
+/**
+ * A reactive container for a state machine that handles dispatching,
+ * queueing of async transitions, and state observability.
+ */
+export class Actor<M extends BaseMachine<any>> implements ActorRef<M> {
+  private _state: M;
+  private _observers: Set<(state: M) => void> = new Set();
+  private _queue: Array<Event<M>> = [];
+  private _processing = false;
+
+  // Global inspector
+  private static _inspector: ((event: InspectionEvent) => void) | null = null;
+
+  /**
+   * Registers a global inspector.
+   */
+  static inspect(inspector: (event: InspectionEvent) => void) {
+    Actor._inspector = inspector;
+  }
+
+  /**
+   * The "Magic" Dispatcher.
+   * Maps machine transition names to callable functions.
+   */
+  readonly send: {
+    [K in TransitionNames<M>]: (...args: TransitionArgs<M, K>) => void;
+  };
+
+  /**
+   * A stable reference to the dispatch method, useful for passing around.
+   */
+  readonly ref: {
+    send: (event: Event<M>) => void;
+  };
+
+  constructor(initialMachine: M) {
+    this._state = initialMachine;
+
+    // Pattern B: Reference to self for event-based dispatch
+    this.ref = {
+      send: (event) => this.dispatch(event)
+    };
+
+    // Pattern A: Proxy for RPC-style dispatch
+    this.send = new Proxy({} as any, {
+      get: (_target, prop) => {
+        return (...args: any[]) => {
+          this.dispatch({ type: prop as any, args: args as any } as unknown as Event<M>);
+        };
+      }
+    });
+  }
+
+  /**
+   * Returns the current immutable snapshot of the machine.
+   */
+  getSnapshot(): M {
+    return this._state;
+  }
+
+  /**
+   * Subscribes to state changes.
+   * @param observer Callback function to be invoked on every state change.
+   * @returns Unsubscribe function.
+   */
+  subscribe(observer: (state: M) => void): () => void {
+    this._observers.add(observer);
+    return () => {
+      this._observers.delete(observer);
+    };
+  }
+
+  /**
+   * Selects a slice of the state. 
+   */
+  select<T>(selector: (state: M) => T): T {
+    return selector(this._state);
+  }
+
+  /**
+   * Starts the actor.
+   */
+  start(): this {
+    return this;
+  }
+
+  /**
+   * Stops the actor.
+   */
+  stop(): void {
+    this._observers.clear();
+  }
+
+  /**
+   * Dispatches an event to the actor.
+   * Handles both sync and async transitions.
+   */
+  dispatch(event: Event<M>): void {
+    // Inspection
+    if (Actor._inspector) {
+      Actor._inspector({
+        type: '@actor/send',
+        actor: this,
+        event,
+        snapshot: this._state
+      });
+    }
+
+    if (this._processing) {
+      this._queue.push(event);
+      return;
+    }
+
+    this._processing = true;
+    this._queue.push(event);
+    this._flush();
+  }
+
+  private _flush() {
+    while (this._queue.length > 0) {
+      const event = this._queue[0];
+      this._queue.shift();
+
+      const transitions = this._state as any;
+      const fn = transitions[event.type];
+
+      if (typeof fn !== 'function') {
+        console.warn(`[Actor] Transition '${String(event.type)}' not found.`);
+        continue;
+      }
+
+      let result: MaybePromise<M>;
+      try {
+        result = fn.apply(this._state.context, event.args);
+      } catch (error) {
+        console.error(`[Actor] Error in transition '${String(event.type)}':`, error);
+        continue;
+      }
+
+      if (result instanceof Promise) {
+        result.then((nextState) => {
+          this._state = nextState;
+          this._notify();
+          this._flush();
+        }).catch((error) => {
+          console.error(`[Actor] Async error in transition '${String(event.type)}':`, error);
+          this._flush();
+        });
+        return;
+      } else {
+        this._state = result;
+        this._notify();
+      }
+    }
+    this._processing = false;
+  }
+
+  private _notify() {
+    const snapshot = this.getSnapshot();
+    this._observers.forEach(obs => obs(snapshot));
+  }
+}
+
+// =============================================================================
+// INTEROP & HELPERS
+// =============================================================================
+
+/**
+ * Creates a new Actor instance from a machine.
+ */
+export function createActor<M extends BaseMachine<any>>(machine: M): Actor<M> {
+  return new Actor(machine);
+}
+
+/**
+ * Spawns an actor from a machine. Alias for createActor.
+ */
+export function spawn<M extends BaseMachine<any>>(machine: M): ActorRef<M> {
+  return createActor(machine);
+}
+
+/**
+ * Creates an actor-like machine from a Promise.
+ */
+export function fromPromise<T>(promiseFn: () => Promise<T>) {
+  type PromiseContext =
+    | { status: 'pending'; data: undefined; error: undefined }
+    | { status: 'resolved'; data: T; error: undefined }
+    | { status: 'rejected'; data: undefined; error: any };
+
+  const initial: PromiseContext = { status: 'pending', data: undefined, error: undefined };
+
+  const machine = createMachine<PromiseContext>(initial,
+    (next) => ({
+      resolve(data: T) {
+        return next({ status: 'resolved' as const, data, error: undefined });
+      },
+      reject(error: any) {
+        return next({ status: 'rejected' as const, error, data: undefined });
+      }
+    })
+  );
+
+  const actor = createActor(machine);
+
+  promiseFn()
+    .then(data => (actor.send as any).resolve(data))
+    .catch(err => (actor.send as any).reject(err));
+
+  return actor;
+}
+
+/**
+ * Creates an actor-like machine from an Observable.
+ */
+export function fromObservable<T>(observable: { subscribe: (next: (val: T) => void, error?: (err: any) => void, complete?: () => void) => { unsubscribe: () => void } }) {
+  type ObsContext =
+    | { status: 'active'; value: undefined; error: undefined }
+    | { status: 'active'; value: T; error: undefined }
+    | { status: 'done'; value: undefined; error: undefined }
+    | { status: 'error'; value: undefined; error: any };
+
+  const initial: ObsContext = { status: 'active', value: undefined, error: undefined };
+
+  const machine = createMachine<ObsContext>(initial,
+    (next) => ({
+      next(value: T) {
+        return next({ status: 'active' as const, value, error: undefined });
+      },
+      error(error: any) {
+        return next({ status: 'error' as const, error, value: undefined });
+      },
+      complete() {
+        return next({ status: 'done' as const, value: undefined, error: undefined });
+      }
+    })
+  );
+
+  const actor = createActor(machine);
+
+  observable.subscribe(
+    (val) => (actor.send as any).next(val),
+    (err) => (actor.send as any).error(err),
+    () => (actor.send as any).complete()
+  );
+
+  return actor;
+}

package/src/index.ts

@@ -127,7 +127,7 @@ export type TransitionNames<M extends BaseMachine<any>> = keyof Omit<M, "context
 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).
@@ -1102,6 +1102,8 @@ export * from './higher-order'
 
 export * from './middleware/index';
 
+export * from './mixins';
+
 // =============================================================================
 // SECTION: UTILITIES & HELPERS
 // =============================================================================
@@ -1148,4 +1150,18 @@ export {
   type IsExhaustive,
   type WhenBuilder,
   type Matcher
-} from './matcher';
+} from './matcher';
+
+// =============================================================================
+// SECTION: ACTOR MODEL
+// =============================================================================
+
+export {
+  Actor,
+  createActor,
+  spawn,
+  fromPromise,
+  fromObservable,
+  type ActorRef,
+  type InspectionEvent
+} from './actor';

package/src/mixins.ts

@@ -0,0 +1,308 @@
+import { MachineBase } from './index';
+
+// =============================================================================
+// HELPER TYPES
+// =============================================================================
+
+export type Constructor<T = any> = new (...args: any[]) => T;
+
+/**
+ * Helper to convert a tuple of types into an intersection of those types.
+ * e.g. [A, B] -> A & B
+ */
+export type UnionToIntersection<U> =
+  (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+
+/**
+ * Extracts the instance type from a constructor.
+ */
+export type Instance<T> = T extends new (...args: any[]) => infer R ? R : never;
+
+/**
+ * Extracts the Context type from a MachineBase subclass.
+ */
+export type ExtractContext<T> = T extends MachineBase<infer C> ? C : never;
+
+/**
+ * Combined context type for a union of machines.
+ */
+export type CombinedContext<T extends Constructor[]> = UnionToIntersection<ExtractContext<Instance<T[number]>>> & object;
+
+/**
+ * Combined instance type for a union of machines.
+ */
+export type CombinedInstance<T extends Constructor[]> = UnionToIntersection<Instance<T[number]>>;
+
+/**
+ * The instance type of a MachineUnion, with methods remapped to return the union type.
+ */
+export type MachineUnionInstance<T extends Constructor[]> = {
+  [K in keyof CombinedInstance<T>]: CombinedInstance<T>[K] extends (...args: infer Args) => any
+  ? (...args: Args) => MachineUnionInstance<T>
+  : CombinedInstance<T>[K]
+} & CombinedInstance<T>;
+
+/**
+ * The constructor type for a MachineUnion.
+ */
+export type MachineUnionConstructor<T extends Constructor[]> = new (context: CombinedContext<T>) => MachineUnionInstance<T>;
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+function getAllPropertyDescriptors(obj: any) {
+  const descriptors: PropertyDescriptorMap = {};
+  let current = obj;
+  while (current && current !== Object.prototype) {
+    const props = Object.getOwnPropertyDescriptors(current);
+    for (const [key, desc] of Object.entries(props)) {
+      if (key === 'constructor') continue;
+      // Don't overwrite properties from child classes (which we visited first)
+      if (!(key in descriptors)) {
+        descriptors[key] = desc;
+      }
+    }
+    current = Object.getPrototypeOf(current);
+  }
+  return descriptors;
+}
+
+// =============================================================================
+// MACHINE UNION
+// =============================================================================
+
+/**
+ * Creates a new class that combines the functionality of multiple Machine classes.
+ *
+ * This utility effectively implements multiple inheritance for State Machines.
+ * It merges the prototypes of all provided classes into a single new class,
+ * preserving the type safety of contexts and methods.
+ *
+ * Crucially, it **wraps** inherited methods to ensure they return instances
+ * of the *Combined* machine, enabling fluent method chaining across different
+ * mixed-in capabilities.
+ *
+ * @param machines - A list of Machine classes to combine.
+ * @returns A new class constructor that inherits from all input classes.
+ *
+ * @example
+ * ```typescript
+ * class A extends MachineBase<{ a: number }> {
+ *   incA() { return new A({ a: this.context.a + 1 }); }
+ * }
+ * class B extends MachineBase<{ b: number }> {
+ *   incB() { return new B({ b: this.context.b + 1 }); }
+ * }
+ *
+ * class AB extends MachineUnion(A, B) {}
+ *
+ * const machine = new AB({ a: 0, b: 0 });
+ * machine.incA().incB(); // Type-safe chaining!
+ * ```
+ */
+export function MachineUnion<T extends Constructor[]>(...machines: T): MachineUnionConstructor<T> {
+  // calculate the combined context type (intersection of all contexts)
+  type Context = CombinedContext<T>;
+
+  // The base class to extend.
+  const Base = machines[0] as unknown as Constructor<MachineBase<Context>>;
+
+  class CombinedMachine extends Base {
+    constructor(context: Context) {
+      super(context);
+    }
+  }
+
+  // Helper to wrap methods
+  const wrapMethod = (fn: Function) => {
+    return function (this: CombinedMachine, ...args: any[]) {
+      // 1. Call the original method. It will return an instance of the *original* class (e.g. A)
+      //    with the updated context FOR A.
+      //    Inheritance means 'this' is the CombinedMachine, which matches A's expectations
+      //    (covariance) for input, but the output is typed as A.
+      const result = fn.apply(this, args);
+
+      // 2. Check if the result is a Machine (has context)
+      if (result && typeof result === 'object' && 'context' in result) {
+        // 3. Create a NEW CombinedMachine instance.
+        //    We merge the current context (to keep props from B)
+        //    with the result context (updates from A).
+        //    Using Object.assign or spread for performance/safety.
+        const newContext = { ...this.context, ...result.context };
+        return new CombinedMachine(newContext);
+      }
+
+      // If not a machine, returns raw result
+      return result;
+    };
+  };
+
+  // Mixin logic: Copy properties from all prototypes.
+  // We process ALL machines (including the first one) to ensure wrapping logic is applied to all.
+  for (const machine of machines) {
+    const descriptors = getAllPropertyDescriptors(machine.prototype);
+
+    for (const [key, descriptor] of Object.entries(descriptors)) {
+      if (key === 'constructor') continue;
+
+      // Logic: If it's a function (method), wrap it to return CombinedMachine.
+      if (typeof descriptor.value === 'function') {
+        const originalFn = descriptor.value;
+        const wrappedFn = wrapMethod(originalFn);
+
+        Object.defineProperty(CombinedMachine.prototype, key, {
+          ...descriptor,
+          value: wrappedFn,
+        });
+      } else {
+        // Copy getters/setters/values as is
+        Object.defineProperty(CombinedMachine.prototype, key, descriptor);
+      }
+    }
+  }
+
+  return CombinedMachine as unknown as MachineUnionConstructor<T>;
+}
+
+// =============================================================================
+// MACHINE EXCLUDE
+// =============================================================================
+
+/**
+ * Creates a new class that extends a Source machine but excludes methods defined in one or more Excluded classes.
+ *
+ * This is useful for "subtracting" functionality from a combined machine or
+ * creating a restricted view of a larger machine.
+ *
+ * @param Source - The class to extend and extract methods from.
+ * @param Excluded - One or more classes defining methods to remove.
+ * @returns A new class with the subset of methods.
+ *
+ * @example
+ * ```typescript
+ * class Admin extends MachineUnion(Viewer, Editor, Moderator) {}
+ * class Guest extends MachineExclude(Admin, Editor, Moderator) {}
+ * ```
+ */
+export function MachineExclude<
+  S extends Constructor,
+  E extends Constructor[]
+>(Source: S, ...Excluded: E) {
+  // The resulting type: Instance of Source Omit keys of Instance of Excluded[number]
+  // But we still need checking for Context compatibility
+  type SourceInstance = Instance<S>;
+  type ExcludedUnion = Instance<E[number]>;
+  // We must EXCLUDE 'context' from the keys to omit, otherwise we remove the context property!
+  type ResultInstance = Omit<SourceInstance, Exclude<keyof ExcludedUnion, 'context'>>;
+  type ResultContext = ExtractContext<SourceInstance>;
+
+  class ExcludedMachine extends MachineBase<ResultContext> {
+    constructor(context: ResultContext) {
+      super(context);
+    }
+  }
+
+  // 1. Copy everything from Source (flattened)
+  const sourceDescriptors = getAllPropertyDescriptors(Source.prototype);
+  for (const [key, descriptor] of Object.entries(sourceDescriptors)) {
+    if (key === 'constructor') continue;
+    // We bind/wrap methods if source was NOT already wrapped (e.g. if Source is plain A).
+    // If Source is already a MachineUnion, its methods are already wrapped to return Source.
+
+    if (typeof descriptor.value === 'function') {
+      const originalFn = descriptor.value;
+
+      // We wrap to ensure return type is ExcludedMachine (security/safety)
+      // Otherwise calling an allowed method might return the Source type,
+      // which would expose Excluded methods ("leaking" capabilities).
+      const wrappedFn = function (this: ExcludedMachine, ...args: any[]) {
+        const result = originalFn.apply(this, args);
+
+        // Re-wrap to ExcludedMachine to maintain restriction chain
+        if (result && typeof result === 'object' && 'context' in result) {
+          return new ExcludedMachine({ ...this.context, ...result.context });
+        }
+        return result;
+      }
+      Object.defineProperty(ExcludedMachine.prototype, key, { ...descriptor, value: wrappedFn });
+    } else {
+      Object.defineProperty(ExcludedMachine.prototype, key, descriptor);
+    }
+  }
+
+  // 2. Remove things from ALL Excluded classes
+  for (const Excl of Excluded) {
+    const excludedDescriptors = getAllPropertyDescriptors(Excl.prototype);
+    for (const key of Object.keys(excludedDescriptors)) {
+      if (Object.prototype.hasOwnProperty.call(ExcludedMachine.prototype, key)) {
+        // Technically strict delete, though wrapping above already protects return types.
+        // This cleaning is for runtime safety (property won't exist).
+        delete (ExcludedMachine.prototype as any)[key];
+      }
+    }
+  }
+
+  return ExcludedMachine as unknown as new (context: ResultContext) => ResultInstance;
+}
+
+// =============================================================================
+// FUNCTIONAL HELPERS
+// =============================================================================
+
+/**
+ * Functional helper to combine multiple Machine instances into a single union instance.
+ *
+ * Automatically merges the contexts of all provided instances and creates a new
+ * `MachineUnion` class on the fly.
+ *
+ * @param instances - Variadic list of machine instances to combine.
+ * @returns A new instance of the combined machine.
+ *
+ * @example
+ * ```typescript
+ * const counter = new Counter({ count: 0 });
+ * const toggler = new Toggler({ active: true });
+ *
+ * const app = machineUnion(counter, toggler);
+ * app.increment().toggle(); // Works! logic merged.
+ * ```
+ */
+export function machineUnion<T extends MachineBase<any>[]>(
+  ...instances: T
+): Instance<MachineUnionConstructor<{ [K in keyof T]: T[K] extends MachineBase<any> ? Constructor<T[K]> : never }>> {
+  const constructors = instances.map(i => i.constructor as Constructor);
+  const contexts = instances.map(i => i.context);
+  const mergedContext = Object.assign({}, ...contexts); // Shallow merge
+
+  const CombinedClass = MachineUnion(...constructors);
+  return new CombinedClass(mergedContext) as any;
+}
+
+/**
+ * Functional helper to create a restricted machine instance by excluding behaviors
+ * defined in other machine instances.
+ *
+ * @param source - The source machine instance.
+ * @param excluded - Variadic list of machine instances whose methods should be excluded from source.
+ * @returns A new instance restricted to the source's capabilities minus excluded ones.
+ *
+ * @example
+ * ```typescript
+ * const fullApp = new AppMachine({ count: 0, active: true });
+ * const guestApp = machineExclude(fullApp, new Toggler({ active: false }));
+ * // guestApp.toggle(); // Error!
+ * ```
+ */
+export function machineExclude<S extends MachineBase<any>, E extends MachineBase<any>[]>(
+  source: S,
+  ...excluded: E
+) {
+  const sourceCtor = source.constructor as Constructor<S>;
+  const excludedCtors = excluded.map(e => e.constructor as Constructor<E[number]>);
+
+  const ExcludedClass = MachineExclude(sourceCtor, ...excludedCtors);
+
+  // Create instance with source's context (exclusions check prototype, not context)
+  return new ExcludedClass(source.context);
+}