@doeixd/machine 0.0.20 → 0.0.21

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).
@@ -1148,4 +1148,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/react.ts

@@ -33,6 +33,10 @@
  *     - **Returns:** A `Provider` and consumer hooks (`useContext`, `useSelector`, etc.).
  *     - A utility to provide a machine created with `useMachine` or `useEnsemble` to
  *       the entire component tree below it.
+ * 
+ * 5.  **`useActor(actor)`**:
+ *     - **Best for:** Using the Actor model.
+ *     - **Returns:** The current machine snapshot.
  */
 
 import {
@@ -43,18 +47,22 @@ import {
   createContext,
   useContext,
   createElement,
+  useSyncExternalStore,
   type ReactNode,
 } from 'react';
 
 import {
   Machine,
-  createRunner,
+  runMachine, // Was createRunner
   createEnsemble,
-  type Runner,
   type Ensemble,
   type StateStore,
+  type Actor,
+  BaseMachine
 } from './index';
 
+export type Runner<M extends Machine<any>> = ReturnType<typeof runMachine<M>>;
+
 // =============================================================================
 // HOOK 1: useMachine (Ergonomic local state)
 // =============================================================================
@@ -62,7 +70,7 @@ import {
 /**
  * A React hook for using a self-contained, immutable state machine within a component.
  * It provides a more ergonomic API than a raw dispatcher by returning a stable `actions`
- * object, similar to the `createRunner` primitive.
+ * object, similar to the `runMachine` primitive.
  *
  * This is the ideal hook for managing component-level state.
  *
@@ -75,57 +83,33 @@ import {
  *     for type-narrowing.
  *   - `actions`: A stable object containing all possible transition methods,
  *     pre-bound to update the machine's state.
- *
- * @example
- * ```tsx
- * const [machine, actions] = useMachine(() => createCounterMachine({ count: 0 }));
- *
- * return (
- *   <div>
- *     <p>Count: {machine.context.count}</p>
- *     <button onClick={() => actions.increment()}>Increment</button>
- *     <button onClick={() => actions.add(5)}>Add 5</button>
- *   </div>
- * );
- * ```
- *
- * @example With Type-State Programming
- * ```tsx
- * const [auth, actions] = useMachine(() => createLoggedOutMachine());
- *
- * return (
- *   <div>
- *     {auth.context.status === 'loggedOut' && (
- *       <button onClick={() => actions.login('user')}>Login</button>
- *     )}
- *     {auth.context.status === 'loggedIn' && (
- *       <p>Welcome, {auth.context.username}!</p>
- *       <button onClick={() => actions.logout()}>Logout</button>
- *     )}
- *   </div>
- * );
- * ```
  */
 export function useMachine<M extends Machine<any>>(
   machineFactory: () => M
-): [M, Runner<M>['actions']] {
+): [M, Record<string, (...args: any[]) => void>] {
   // useState holds the machine state, triggering re-renders.
-  // The factory is passed directly to useState to ensure it's only called once.
   const [machine, setMachine] = useState(machineFactory);
 
   // useMemo creates a stable runner instance that survives re-renders.
-  // The runner's job is to hold the *current* machine state and update our
-  // React state when a transition occurs.
   const runner = useMemo(
-    () => createRunner(machine, (newState) => {
-      // This is the magic link: when the runner's internal state changes,
-      // we update React's state, causing a re-render.
+    () => runMachine(machine, (newState) => {
       setMachine(newState);
     }),
-    [] // Empty dependency array ensures the runner is created only once.
+    []
   );
 
-  return [machine, runner.actions];
+  // Create a stable actions object that proxies calls to the dispatcher
+  const actions = useMemo(() => {
+    return new Proxy({} as any, {
+      get: (_target, prop) => {
+        return (...args: any[]) => {
+          runner.dispatch({ type: prop as any, args: args as any } as any);
+        };
+      }
+    });
+  }, [runner]);
+
+  return [machine, actions];
 }
 
 // =============================================================================
@@ -149,21 +133,6 @@ export function useMachine<M extends Machine<any>>(
  *   values. Defaults to `Object.is` for strict equality checking. Provide your own
  *   for deep comparisons of objects or arrays.
  * @returns The selected, memoized value from the machine's state.
- *
- * @example
- * ```tsx
- * // In parent component:
- * const [machine, actions] = useMachine(() => createUserMachine());
- *
- * // In child component (only re-renders when the user's name changes):
- * function UserNameDisplay({ machine }) {
- *   const userName = useMachineSelector(
- *     machine,
- *     (m) => m.context.user.name
- *   );
- *   return <p>User: {userName}</p>;
- * }
- * ```
  */
 export function useMachineSelector<M extends Machine<any>, T>(
   machine: M,
@@ -172,7 +141,7 @@ export function useMachineSelector<M extends Machine<any>, T>(
 ): T {
   // Store the selected value in local state.
   const [selectedValue, setSelectedValue] = useState(() => selector(machine));
-  
+
   // Keep refs to the latest selector and comparison functions.
   const selectorRef = useRef(selector);
   const isEqualRef = useRef(isEqual);
@@ -209,32 +178,6 @@ export function useMachineSelector<M extends Machine<any>, T>(
  *   from the context.
  * @returns A stable `Ensemble` instance. The component will reactively update
  *   when the ensemble's underlying context changes.
- *
- * @example
- * ```tsx
- * const fetchFactories = {
- *   idle: (ctx) => createMachine(ctx, { fetch: () => ({ ...ctx, status: 'loading' }) }),
- *   loading: (ctx) => createMachine(ctx, { succeed: (data) => ({ status: 'success', data }) }),
- *   // ...
- * };
- *
- * function MyComponent() {
- *   const ensemble = useEnsemble(
- *     { status: 'idle', data: null },
- *     fetchFactories,
- *     (ctx) => ctx.status
- *   );
- *
- *   return (
- *     <div>
- *       <p>Status: {ensemble.context.status}</p>
- *       {ensemble.state.context.status === 'idle' && (
- *          <button onClick={() => ensemble.actions.fetch()}>Fetch</button>
- *       )}
- *     </div>
- *   );
- * }
- * ```
  */
 export function useEnsemble<
   C extends object,
@@ -280,46 +223,9 @@ export function useEnsemble<
  *
  * It returns a `Provider` component and a suite of consumer hooks for accessing
  * the state and actions.
- *
- * @returns An object containing:
- *  - `Provider`: The context provider component.
- *  - `useMachineContext`: Hook to get the full `[machine, actions]` tuple.
- *  - `useMachineState`: Hook to get only the reactive `machine` instance.
- *  - `useMachineActions`: Hook to get only the stable `actions` object.
- *  - `useSelector`: Hook to get a memoized slice of the machine's state.
- *
- * @example
- * ```tsx
- * // 1. Create the context
- * const { Provider, useMachineState, useMachineActions } = createMachineContext<MyMachine>();
- *
- * // 2. In your top-level component, create the machine and provide it
- * function App() {
- *   const [machine, actions] = useMachine(() => createMyMachine());
- *   return (
- *     <Provider machine={machine} actions={actions}>
- *       <ChildComponent />
- *     </Provider>
- *   );
- * }
- *
- * // 3. In a deeply nested child component
- * function ChildComponent() {
- *   const machine = useMachineState(); // Gets the current state
- *   const actions = useMachineActions(); // Gets the stable actions
- *   const name = useSelector(m => m.context.name); // Selects a slice
- *
- *   return (
- *     <div>
- *       <p>Name: {name}</p>
- *       <button onClick={() => actions.rename('new name')}>Rename</button>
- *     </div>
- *   );
- * }
- * ```
  */
 export function createMachineContext<M extends Machine<any>>() {
-  type MachineContextValue = [M, Runner<M>['actions']];
+  type MachineContextValue = [M, Record<string, (...args: any[]) => void>];
   const Context = createContext<MachineContextValue | null>(null);
 
   const Provider = ({
@@ -328,7 +234,7 @@ export function createMachineContext<M extends Machine<any>>() {
     children,
   }: {
     machine: M;
-    actions: Runner<M>['actions'];
+    actions: Record<string, (...args: any[]) => void>;
     children: ReactNode;
   }) => {
     // Memoize the context value to prevent unnecessary re-renders in consumers.
@@ -345,7 +251,7 @@ export function createMachineContext<M extends Machine<any>>() {
   };
 
   const useMachineState = (): M => useMachineContext()[0];
-  const useMachineActions = (): Runner<M>['actions'] => useMachineContext()[1];
+  const useMachineActions = (): Record<string, (...args: any[]) => void> => useMachineContext()[1];
 
   const useSelector = <T,>(
     selector: (state: M) => T,
@@ -362,4 +268,69 @@ export function createMachineContext<M extends Machine<any>>() {
     useMachineActions,
     useSelector,
   };
+}
+
+// =============================================================================
+// HOOK 5: useActor (Actor Model)
+// =============================================================================
+
+/**
+ * Subscribes to an Actor and returns the current snapshot.
+ * Uses `useSyncExternalStore` for concurrent features compatibility.
+ * 
+ * @param actor The actor instance to subscribe to.
+ * @returns The current machine snapshot.
+ */
+export function useActor<M extends BaseMachine<any>>(actor: Actor<M>): M {
+  // bind is important if subscribe methods rely on `this`
+  const subscribe = useMemo(() => actor.subscribe.bind(actor), [actor]);
+  const getSnapshot = useMemo(() => actor.getSnapshot.bind(actor), [actor]);
+
+  return useSyncExternalStore(subscribe, getSnapshot);
+}
+
+/**
+ * Subscribes to an Actor and selects a slice of the state.
+ * Only re-renders when the selected slice changes.
+ * 
+ * @param actor The actor instance.
+ * @param selector Function to select a part of the state.
+ * @param isEqual Optional equality function.
+ */
+export function useActorSelector<M extends BaseMachine<any>, T>(
+  actor: Actor<M>,
+  selector: (state: M) => T,
+  isEqual: (a: T, b: T) => boolean = Object.is
+): T {
+  const subscribe = useMemo(() => actor.subscribe.bind(actor), [actor]);
+  const getSnapshot = useMemo(() => actor.getSnapshot.bind(actor), [actor]);
+
+  const getSelection = () => selector(getSnapshot());
+
+  const [selection, setSelection] = useState(getSelection);
+
+  // Custom selector logic since useSyncExternalStoreWithSelector is not available directly
+  // and we want to avoid extra deps.
+  // Actually, we can just use useSyncExternalStore and manage the selection stability,
+  // but useSyncExternalStore triggers if the result of getSnapshot changes (strict eq).
+  // If we wrap getSnapshot to return the selection, standard useSyncExternalStore handles it?
+  // No, useSyncExternalStore calls getSnapshot continuously during render to check for tearing.
+  // It needs to be cheap and consistent.
+
+  // Simple implementation: Subscribe and update local state only on change.
+  useEffect(() => {
+    const checkUpdate = () => {
+      const nextSelection = selector(actor.getSnapshot());
+      setSelection(prev => isEqual(prev, nextSelection) ? prev : nextSelection);
+    };
+
+    // Check immediately in case it changed between render and effect
+    checkUpdate();
+
+    return actor.subscribe(() => {
+      checkUpdate();
+    });
+  }, [actor, selector, isEqual]);
+
+  return selection;
 }