@doeixd/machine 1.0.3 → 1.2.0

package/src/minimal.ts

@@ -0,0 +1,269 @@
+/**
+ * @fileoverview A minimal, type-safe typestate library.
+ */
+
+// ============================================================================
+// CORE TYPES (MUST BE IN THIS FILE FOR INFERENCE)
+// ============================================================================
+
+/**
+ * A state machine combining context (state data) with transitions (methods).
+ */
+export type Machine<C extends object, T> = C & T;
+
+// Re-export utilities
+export * from './types';
+import { type Tagged, type TagOf, type Cleanup } from './types';
+
+// ============================================================================
+// CORE: machine()
+// ============================================================================
+
+/**
+ * Creates a state machine by bundling context with transitions.
+ * 
+ * Note: 'any' is used in the 'next' callback signature to break recursive 
+ * inference cycles. This is required for TypeScript to correctly infer 
+ * transitions 'T' from the return object of the factory.
+ */
+export function machine<C extends object, T>(
+  context: C,
+  factory: (ctx: C, next: (context: C) => any) => T
+): C & T {
+  const next = (newContext: C) => machine(newContext, factory);
+  const transitions = factory(context, next);
+  return Object.assign({}, context, transitions) as C & T;
+}
+
+// ============================================================================
+// PATTERN MATCHING: match()
+// ============================================================================
+
+/**
+ * Handler functions for each case in a tagged union.
+ */
+export type MatchCases<T extends Tagged, R> = {
+  [K in TagOf<T>]: (state: Extract<T, { tag: K }>) => R;
+};
+
+/**
+ * Exhaustive pattern matching on tagged unions.
+ */
+export function match<T extends Tagged, R>(
+  state: T,
+  cases: MatchCases<T, R>
+): R {
+  const handler = cases[state.tag as TagOf<T>];
+  return handler(state as Extract<T, { tag: typeof state.tag }>);
+}
+
+// ============================================================================
+// EFFECTS: runnable() + run()
+// ============================================================================
+
+export interface Lifecycle<E extends string = string> {
+  onEnter?: (send: Send<E>) => Cleanup;
+}
+
+export type Send<E extends string = string> = (event: E, ...args: unknown[]) => void;
+
+export type LifecycleMap<Tags extends string> = {
+  [K in Tags]?: Lifecycle<string>;
+};
+
+const LIFECYCLE = Symbol('lifecycle');
+
+export type RunnableMachine<M, Tags extends string> = M & {
+  [LIFECYCLE]?: LifecycleMap<Tags>;
+};
+
+export function runnable<
+  M extends Tagged,
+  Tags extends string = TagOf<M>
+>(
+  initialMachine: M,
+  lifecycles: LifecycleMap<Tags>
+): RunnableMachine<M, Tags> {
+  const result = { ...initialMachine } as RunnableMachine<M, Tags>;
+  result[LIFECYCLE] = lifecycles;
+  return result;
+}
+
+export interface Runner<M> {
+  get: () => M;
+  send: Send<string>;
+  stop: () => void;
+  subscribe: (listener: (state: M) => void) => () => void;
+}
+
+export function run<M extends Tagged>(
+  initial: RunnableMachine<M, string>
+): Runner<M> {
+  let current: RunnableMachine<M, string> = initial;
+  let cleanup: Cleanup | null = null;
+  const listeners = new Set<(state: M) => void>();
+
+  const notify = () => {
+    listeners.forEach((fn) => fn(current as M));
+  };
+
+  const enter = () => {
+    if (cleanup) {
+      cleanup();
+      cleanup = null;
+    }
+    const lifecycles = current[LIFECYCLE];
+    const tagValue = (current as Tagged).tag;
+    const lifecycle = lifecycles?.[tagValue];
+    if (lifecycle?.onEnter) {
+      cleanup = lifecycle.onEnter(send);
+    }
+  };
+
+  const send: Send<string> = (event, ...args) => {
+    const transition = (current as Record<string, unknown>)[event];
+    if (typeof transition === 'function') {
+      const nextValue = (transition as (...a: unknown[]) => unknown)(...args);
+      if (nextValue && typeof nextValue === 'object' && 'tag' in nextValue) {
+        const nextMachine = nextValue as RunnableMachine<M, string>;
+        if (!nextMachine[LIFECYCLE] && current[LIFECYCLE]) {
+          nextMachine[LIFECYCLE] = current[LIFECYCLE];
+        }
+        current = nextMachine;
+        enter();
+        notify();
+      }
+    }
+  };
+
+  enter();
+
+  return {
+    get: () => current as M,
+    send,
+    stop: () => {
+      if (cleanup) {
+        cleanup();
+        cleanup = null;
+      }
+      listeners.clear();
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+
+// ============================================================================
+// COMPOSITION: withChildren()
+// ============================================================================
+
+export type ParentMachine<P extends object, C extends Record<string, object>> =
+  P & { [K in keyof C]: ChildProxy<P, C, C[K]> };
+
+type ChildProxy<P extends object, C extends Record<string, object>, Child extends object> = {
+  [K in keyof Child]: Child[K] extends (...args: infer A) => unknown
+  ? (...args: A) => ParentMachine<P, C>
+  : Child[K];
+};
+
+export function withChildren<
+  P extends object,
+  C extends Record<string, object>
+>(
+  parent: P,
+  children: C
+): ParentMachine<P, C> {
+  const result = { ...parent } as ParentMachine<P, C>;
+
+  for (const key of Object.keys(children) as Array<keyof C>) {
+    const child = children[key];
+
+    const childProxy = new Proxy(child, {
+      get(target, prop: string | symbol) {
+        const value = (target as Record<string | symbol, unknown>)[prop];
+
+        if (typeof value === 'function') {
+          return (...args: unknown[]) => {
+            const nextChild = (value as (...a: unknown[]) => unknown)(...args);
+            return withChildren(
+              { ...parent },
+              { ...children, [key]: nextChild as object } as C
+            );
+          };
+        }
+
+        return value;
+      }
+    }) as unknown as ChildProxy<P, C, C[keyof C]>;
+    (result as Record<string, unknown>)[key as string] = childProxy;
+  }
+
+  return result;
+}
+
+// ============================================================================
+// UTILITIES
+// ============================================================================
+
+// Re-exports from types.ts are enough
+
+export function factory<C extends object>() {
+  return <T>(
+    transitionFactory: (ctx: C, next: (context: C) => any) => T
+  ) => (context: C): C & T => machine(context, transitionFactory);
+}
+
+/**
+ * Extracts the union of all possible machine states from a union factory.
+ */
+export type UnionOf<F extends (...args: any[]) => any> = ReturnType<F>;
+
+/**
+ * Creates a union factory that routes to different transition factories based on a tag.
+ * This is the primary way to define multi-state machines (Type-States) in the minimal API.
+ * 
+ * @param factories - A map of tags to transition factories.
+ * @returns A single factory function that produces the correct machine based on the input context's tag.
+ * 
+ * @example
+ * const auth = union({
+ *   idle: (ctx, next) => ({ login: () => next({ tag: 'loggedIn', user: 'alice' }) }),
+ *   loggedIn: (ctx, next) => ({ logout: () => next({ tag: 'idle' }) })
+ * });
+ * 
+ * const m = auth({ tag: 'idle' });
+ * const next = m.login(); // Transition to loggedIn state
+ */
+/**
+ * Creates a union factory that routes to different transition factories based on a tag.
+ * This is the primary way to define multi-state machines (Type-States) in the minimal API.
+ * 
+ * @example
+ * const auth = union<AuthState>()({
+ *   idle: (ctx, next) => ({ login: () => next({ tag: 'loggedIn', user: 'alice' }) }),
+ *   loggedIn: (ctx, next) => ({ logout: () => next({ tag: 'idle' }) })
+ * });
+ * 
+ * const m = auth({ tag: 'idle' });
+ * const next = m.login(); // Transition to loggedIn state
+ */
+export function union<C extends Tagged>() {
+  return <F extends { [K in TagOf<C>]: (ctx: Extract<C, { tag: K }>, next: (c: C) => any) => any }>(
+    factories: F
+  ) => {
+    type MachineMap = {
+      [K in TagOf<C> & keyof F]: F[K] extends (ctx: any, next: any) => infer T
+      ? Extract<C, { tag: K }> & T
+      : never
+    };
+
+    const resultFactory = <T extends C>(context: T): MachineMap[T['tag'] & keyof MachineMap] => {
+      const factoryFn = (factories as any)[(context as any).tag];
+      return machine(context as any, (ctx: any, _next: any) => factoryFn(ctx as any, resultFactory as any)) as any;
+    };
+
+    return resultFactory;
+  };
+}

package/src/types.ts

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview Utility types for the machine library.
+ */
+
+/**
+ * Extracts the context type from a machine (works with regular and minimal machines).
+ */
+export type Context<M> = M extends { readonly context: infer C } ? C : M;
+
+/**
+ * Extracts the transitions type from a machine (works with regular and minimal machines).
+ */
+export type Transitions<M> = M extends { readonly context: any } & infer T ? T : M;
+
+/**
+ * A discriminated union type representing an event that can be dispatched to a machine.
+ */
+export type Tagged<T extends string = string> = { readonly tag: T };
+
+/**
+ * Extracts the tag literal type from a tagged object.
+ */
+export type TagOf<T extends Tagged> = T['tag'];
+
+/**
+ * Utility to define a union of tagged states from a mapping type.
+ * @example
+ * type PickMode = States<{
+ *   idle: {},
+ *   active: { isCloseMode: boolean; timeoutId: number }
+ * }>;
+ */
+export type States<M extends Record<string, object>> = {
+  [K in keyof M]: { readonly tag: K } & M[K]
+}[keyof M];
+
+/**
+ * Cleanup function returned from onEnter.
+ */
+export type Cleanup = () => void;
+
+/**
+ * Extracts the return type from a factory function.
+ * @example
+ * const factory = () => machine({ count: 0 }, { ... });
+ * type MyMachine = InferMachine<typeof factory>;
+ */
+export type InferMachine<F extends (...args: any[]) => any> = ReturnType<F>;
+
+/**
+ * Alias for InferMachine, more descriptive for state machine contexts.
+ */
+export type MachineOf<F extends (...args: any[]) => any> = InferMachine<F>;
+
+/**
+ * Creates a tagged object or adds a tag to an existing object.
+ */
+export function tag<T extends string>(name: T): { tag: T };
+export function tag<T extends string, O extends object>(name: T, props: O): { tag: T } & O;
+export function tag<const T extends { tag: string }>(obj: T): T;
+export function tag<T extends string, O extends object>(
+  nameOrObj: T | { tag: string },
+  props?: O
+): { tag: T } | ({ tag: T } & O) | { tag: string } {
+  if (typeof nameOrObj === 'object') {
+    return nameOrObj;
+  }
+  if (props) {
+    return { ...props, tag: nameOrObj };
+  }
+  return { tag: nameOrObj };
+}
+
+/**
+ * Namespace for tag factory utility.
+ */
+export namespace tag {
+  /**
+   * Creates a pre-bound tag factory for a specific state.
+   * 
+   * @typeParam C - Context (data) type
+   * @typeParam T - Transitions type (optional, for machine return types)
+   * @param name - The tag name for this state
+   * @returns A function that takes context data and returns a tagged object
+   * 
+   * @typeParam C - Context (data) type
+   * @typeParam T - Transitions type (optional)
+   * @param name - The tag name
+   * @example const idle = tag.factory<{ count: number }>('idle');
+   */
+  export function factory<C extends object, T extends object = {}>(name: string): (props: C) => { readonly tag: string } & C & T;
+  /**
+   * Creates a curried tag factory, ideal for use with the States utility.
+   * @example const state = tag.factory<AppState>()('idle')({ count: 0 });
+   */
+  export function factory<C extends object, T extends object = {}>(): <K extends string>(name: K) => (props: Omit<Extract<C, { tag: K }>, 'tag'>) => (Extract<C, { tag: K }> extends never ? { readonly tag: K } & C : Extract<C, { tag: K }>) & T;
+
+  export function factory(name?: string) {
+    if (name) {
+      return (props: any) => tag(name, props);
+    }
+    return (name: string) => (props: any) => tag(name, props);
+  }
+}
+
+/**
+ * Type guard to check if a machine or object is in a specific state.
+ */
+export function isState<M extends Tagged, Tag extends TagOf<M>>(
+  machine: M,
+  tagValue: Tag
+): machine is Extract<M, { tag: Tag }> {
+  return (machine as Tagged).tag === tagValue;
+}
+
+/**
+ * Recursively freezes an object and its properties.
+ */
+export function freeze<T extends object>(obj: T): Readonly<T> {
+  Object.freeze(obj);
+  if (typeof (Object as any).values === 'function') {
+    for (const value of Object.values(obj)) {
+      if (value && typeof value === 'object') {
+        freeze(value);
+      }
+    }
+  }
+  return obj;
+}