@doeixd/machine 0.0.4

package/src/solid.ts

@@ -0,0 +1,502 @@
+/**
+ * @file Solid.js integration for @doeixd/machine
+ * @description
+ * Provides reactive primitives for using state machines with Solid.js, including
+ * hooks for both sync and async machines, store integration, and signal-based APIs.
+ *
+ * Solid.js uses fine-grained reactivity with signals and stores, which pairs
+ * beautifully with immutable state machines. This integration provides multiple
+ * approaches depending on your needs:
+ *
+ * - `createMachine()` - Signal-based reactive machine
+ * - `createMachineStore()` - Store-based reactive machine (for complex context)
+ * - `createAsyncMachine()` - Async machine with signal state
+ * - `createMachineResource()` - Resource-based async machine
+ */
+
+import {
+  createSignal,
+  createEffect,
+  createMemo,
+  onCleanup,
+  type Accessor,
+  type Setter
+} from 'solid-js';
+import { createStore, type SetStoreFunction, type Store, produce } from 'solid-js/store';
+import { Machine, AsyncMachine, Event, Context, runMachine as runMachineCore } from './index';
+
+// =============================================================================
+// SIGNAL-BASED MACHINE (for simple state)
+// =============================================================================
+
+/**
+ * Creates a reactive machine using Solid signals.
+ *
+ * This is ideal for simple state machines where the entire machine state
+ * needs to be tracked reactively. Every transition creates a new machine
+ * instance, and the signal updates automatically.
+ *
+ * @template M - The machine type.
+ *
+ * @param initialMachine - A function that returns the initial machine state.
+ * @returns A tuple of [accessor, transitions] where:
+ *   - accessor: Reactive accessor for the current machine
+ *   - transitions: Object with all machine transitions bound to update the signal
+ *
+ * @example
+ * ```tsx
+ * const [machine, actions] = createMachine(() =>
+ *   createCounterMachine({ count: 0 })
+ * );
+ *
+ * // In your component
+ * <div>
+ *   <p>Count: {machine().context.count}</p>
+ *   <button onClick={actions.increment}>Increment</button>
+ * </div>
+ * ```
+ *
+ * @example With Type-State
+ * ```tsx
+ * type LoggedOut = Machine<{ status: "loggedOut" }> & {
+ *   login: (user: string) => LoggedIn;
+ * };
+ *
+ * type LoggedIn = Machine<{ status: "loggedIn"; user: string }> & {
+ *   logout: () => LoggedOut;
+ * };
+ *
+ * const [auth, actions] = createMachine<LoggedOut | LoggedIn>(() =>
+ *   createLoggedOut()
+ * );
+ *
+ * // Conditional rendering based on state type
+ * <Show when={auth().context.status === 'loggedIn'}>
+ *   <p>Welcome, {auth().context.user}</p>
+ *   <button onClick={actions.logout}>Logout</button>
+ * </Show>
+ * ```
+ */
+export function createMachine<M extends Machine<any>>(
+  initialMachine: () => M
+): [Accessor<M>, TransitionHandlers<M>] {
+  const [machine, setMachine] = createSignal<M>(initialMachine());
+
+  // Extract all transition methods and bind them to update the signal
+  const { context, ...transitions } = machine();
+
+  const handlers = Object.fromEntries(
+    Object.entries(transitions).map(([key, fn]) => [
+      key,
+      (...args: any[]) => {
+        const currentMachine = machine();
+        const nextMachine = (currentMachine as any)[key](...args);
+        setMachine(() => nextMachine);
+        return nextMachine;
+      }
+    ])
+  ) as TransitionHandlers<M>;
+
+  return [machine, handlers];
+}
+
+/**
+ * Helper type to extract transition handlers from a machine.
+ */
+type TransitionHandlers<M extends Machine<any>> = {
+  [K in keyof Omit<M, 'context'>]: M[K] extends (...args: infer Args) => infer R
+    ? (...args: Args) => R
+    : never;
+};
+
+// =============================================================================
+// STORE-BASED MACHINE (for complex context with fine-grained reactivity)
+// =============================================================================
+
+/**
+ * Creates a reactive machine using Solid stores.
+ *
+ * This is ideal when you have complex nested context and want fine-grained
+ * reactivity on individual properties. Instead of replacing the entire machine,
+ * transitions update the store, triggering only the affected computations.
+ *
+ * @template M - The machine type.
+ *
+ * @param initialMachine - A function that returns the initial machine state.
+ * @returns A tuple of [store, actions] where:
+ *   - store: Reactive store proxy for the machine
+ *   - actions: Transition handlers that update the store
+ *
+ * @example
+ * ```tsx
+ * const [machine, actions] = createMachineStore(() =>
+ *   createUserMachine({
+ *     profile: { name: 'Alice', age: 30 },
+ *     settings: { theme: 'dark', notifications: true }
+ *   })
+ * );
+ *
+ * // Fine-grained reactivity - only updates when profile.name changes
+ * <div>
+ *   <p>Name: {machine.context.profile.name}</p>
+ *   <p>Age: {machine.context.profile.age}</p>
+ *   <button onClick={() => actions.updateName('Bob')}>Change Name</button>
+ * </div>
+ * ```
+ */
+export function createMachineStore<M extends Machine<any>>(
+  initialMachine: () => M
+): [Store<M>, SetStoreFunction<M>, TransitionHandlers<M>] {
+  const initial = initialMachine();
+  const [store, setStore] = createStore<M>(initial);
+
+  const { context, ...transitions } = initial;
+
+  const handlers = Object.fromEntries(
+    Object.entries(transitions).map(([key, fn]) => [
+      key,
+      (...args: any[]) => {
+        const nextMachine = (store as any)[key](...args);
+        setStore(() => nextMachine);
+        return nextMachine;
+      }
+    ])
+  ) as TransitionHandlers<M>;
+
+  return [store, setStore, handlers];
+}
+
+// =============================================================================
+// ASYNC MACHINE WITH SIGNALS
+// =============================================================================
+
+/**
+ * Creates a reactive async machine with event dispatching.
+ *
+ * This wraps the core `runMachine` with Solid reactivity, automatically
+ * updating a signal whenever the machine state changes. Perfect for async
+ * workflows like data fetching, multi-step forms, or any stateful async logic.
+ *
+ * @template M - The async machine type.
+ *
+ * @param initialMachine - A function that returns the initial async machine state.
+ * @returns A tuple of [accessor, dispatch] where:
+ *   - accessor: Reactive accessor for current machine state
+ *   - dispatch: Type-safe event dispatcher
+ *
+ * @example Basic data fetching
+ * ```tsx
+ * type FetchMachine = AsyncMachine<{
+ *   status: 'idle' | 'loading' | 'success' | 'error';
+ *   data: any;
+ * }> & {
+ *   fetch: () => Promise<FetchMachine>;
+ *   retry: () => Promise<FetchMachine>;
+ * };
+ *
+ * const [state, dispatch] = createAsyncMachine(() => createFetchMachine());
+ *
+ * <div>
+ *   <Switch>
+ *     <Match when={state().context.status === 'idle'}>
+ *       <button onClick={() => dispatch({ type: 'fetch', args: [] })}>
+ *         Load Data
+ *       </button>
+ *     </Match>
+ *     <Match when={state().context.status === 'loading'}>
+ *       <p>Loading...</p>
+ *     </Match>
+ *     <Match when={state().context.status === 'success'}>
+ *       <p>Data: {JSON.stringify(state().context.data)}</p>
+ *     </Match>
+ *     <Match when={state().context.status === 'error'}>
+ *       <button onClick={() => dispatch({ type: 'retry', args: [] })}>
+ *         Retry
+ *       </button>
+ *     </Match>
+ *   </Switch>
+ * </div>
+ * ```
+ *
+ * @example With effects
+ * ```tsx
+ * const [state, dispatch] = createAsyncMachine(() => createAuthMachine());
+ *
+ * // React to state changes
+ * createEffect(() => {
+ *   console.log('Auth state changed:', state().context.status);
+ *
+ *   if (state().context.status === 'loggedIn') {
+ *     // Navigate, fetch user data, etc.
+ *   }
+ * });
+ * ```
+ */
+export function createAsyncMachine<M extends AsyncMachine<any>>(
+  initialMachine: () => M
+): [Accessor<M>, (event: Event<M>) => Promise<M>] {
+  const [machine, setMachine] = createSignal<M>(initialMachine());
+
+  // Create the runner with signal update callback
+  const runner = runMachineCore(initialMachine(), (nextMachine) => {
+    setMachine(() => nextMachine as M);
+  });
+
+  const dispatch = async (event: Event<M>): Promise<M> => {
+    const result = await runner.dispatch(event);
+    return result as M;
+  };
+
+  return [machine, dispatch];
+}
+
+// =============================================================================
+// CONTEXT-ONLY STORE (for just the context data)
+// =============================================================================
+
+/**
+ * Creates a Solid store for just the machine's context, with actions that
+ * transition the machine and sync the context back to the store.
+ *
+ * This is useful when you want fine-grained reactivity on context properties
+ * but don't need to track the machine instance itself.
+ *
+ * @template C - The context object type.
+ * @template M - The machine type.
+ *
+ * @param initialMachine - A function that returns the initial machine.
+ * @returns A tuple of [context store, setContext, actions].
+ *
+ * @example
+ * ```tsx
+ * const [context, setContext, actions] = createMachineContext(() =>
+ *   createCounterMachine({ count: 0, name: 'Counter' })
+ * );
+ *
+ * // Direct access to context with fine-grained reactivity
+ * <div>
+ *   <p>{context.name}: {context.count}</p>
+ *   <button onClick={actions.increment}>+</button>
+ * </div>
+ * ```
+ */
+export function createMachineContext<C extends object, M extends Machine<C>>(
+  initialMachine: () => M
+): [Store<C>, SetStoreFunction<C>, TransitionHandlers<M>] {
+  let currentMachine = initialMachine();
+  const [context, setContext] = createStore<C>(currentMachine.context);
+
+  const { context: _, ...transitions } = currentMachine;
+
+  const handlers = Object.fromEntries(
+    Object.entries(transitions).map(([key, fn]) => [
+      key,
+      (...args: any[]) => {
+        const nextMachine = (currentMachine as any)[key](...args);
+        currentMachine = nextMachine;
+        setContext(() => nextMachine.context);
+        return nextMachine;
+      }
+    ])
+  ) as TransitionHandlers<M>;
+
+  return [context, setContext, handlers];
+}
+
+// =============================================================================
+// MEMOIZED MACHINE DERIVATIONS
+// =============================================================================
+
+/**
+ * Creates a memoized derivation from a machine's context.
+ *
+ * This is useful for computed values that depend on the machine state.
+ * The computation only re-runs when the accessed context properties change.
+ *
+ * @template M - The machine type.
+ * @template T - The computed value type.
+ *
+ * @param machine - Machine accessor.
+ * @param selector - Function to compute a value from the context.
+ * @returns A memoized accessor for the computed value.
+ *
+ * @example
+ * ```tsx
+ * const [machine, actions] = createMachine(() => createCart());
+ *
+ * const total = createMachineSelector(machine, (ctx) =>
+ *   ctx.items.reduce((sum, item) => sum + item.price, 0)
+ * );
+ *
+ * <div>
+ *   <p>Total: ${total()}</p>
+ * </div>
+ * ```
+ */
+export function createMachineSelector<M extends Machine<any>, T>(
+  machine: Accessor<M>,
+  selector: (context: Context<M>) => T
+): Accessor<T> {
+  return createMemo(() => selector(machine().context));
+}
+
+// =============================================================================
+// BATCH TRANSITIONS
+// =============================================================================
+
+/**
+ * Batches multiple transitions into a single reactive update.
+ *
+ * In Solid, this uses `batch` to group updates, preventing intermediate
+ * re-renders and effects from firing.
+ *
+ * @template M - The machine type.
+ *
+ * @param machine - The current machine.
+ * @param setMachine - The setter function.
+ * @param transitions - Array of transition functions to apply.
+ * @returns The final machine state.
+ *
+ * @example
+ * ```tsx
+ * import { batch } from 'solid-js';
+ *
+ * const [machine, setMachine] = createSignal(createCounterMachine());
+ *
+ * const batchUpdate = () => {
+ *   batch(() => {
+ *     let m = machine();
+ *     m = m.increment();
+ *     m = m.add(5);
+ *     m = m.increment();
+ *     setMachine(m);
+ *   });
+ * };
+ * ```
+ */
+export function batchTransitions<M extends Machine<any>>(
+  machine: M,
+  setMachine: Setter<M>,
+  ...transitions: Array<(m: M) => M>
+): M {
+  const { batch } = require('solid-js');
+
+  return batch(() => {
+    const finalMachine = transitions.reduce((m, transition) => transition(m), machine);
+    setMachine(finalMachine);
+    return finalMachine;
+  });
+}
+
+// =============================================================================
+// LIFECYCLE EFFECTS
+// =============================================================================
+
+/**
+ * Runs an effect when entering or exiting specific machine states.
+ *
+ * This is useful for side effects that should happen on state transitions,
+ * like analytics, logging, or subscriptions.
+ *
+ * @template M - The machine type.
+ *
+ * @param machine - Machine accessor.
+ * @param statePredicate - Function to determine if we're in the target state.
+ * @param onEnter - Effect to run when entering the state.
+ * @param onExit - Optional effect to run when exiting the state.
+ *
+ * @example
+ * ```tsx
+ * const [machine, actions] = createMachine(() => createAuthMachine());
+ *
+ * createMachineEffect(
+ *   machine,
+ *   (m) => m.context.status === 'loggedIn',
+ *   (m) => {
+ *     console.log('User logged in:', m.context.username);
+ *     // Start session tracking
+ *   },
+ *   () => {
+ *     console.log('User logged out');
+ *     // Clean up session
+ *   }
+ * );
+ * ```
+ */
+export function createMachineEffect<M extends Machine<any>>(
+  machine: Accessor<M>,
+  statePredicate: (m: M) => boolean,
+  onEnter: (m: M) => void,
+  onExit?: () => void
+): void {
+  let wasInState = false;
+
+  createEffect(() => {
+    const m = machine();
+    const isInState = statePredicate(m);
+
+    if (isInState && !wasInState) {
+      // Entering state
+      onEnter(m);
+      wasInState = true;
+    } else if (!isInState && wasInState) {
+      // Exiting state
+      onExit?.();
+      wasInState = false;
+    }
+  });
+
+  onCleanup(() => {
+    if (wasInState && onExit) {
+      onExit();
+    }
+  });
+}
+
+/**
+ * Helper to create effects for specific context values.
+ *
+ * @template M - The machine type.
+ * @template T - The selected value type.
+ *
+ * @param machine - Machine accessor.
+ * @param selector - Function to select a value from context.
+ * @param effect - Effect to run when the selected value changes.
+ *
+ * @example
+ * ```tsx
+ * const [machine, actions] = createMachine(() => createCounterMachine());
+ *
+ * createMachineValueEffect(
+ *   machine,
+ *   (ctx) => ctx.count,
+ *   (count) => {
+ *     console.log('Count changed to:', count);
+ *     if (count > 10) {
+ *       alert('Count is high!');
+ *     }
+ *   }
+ * );
+ * ```
+ */
+export function createMachineValueEffect<M extends Machine<any>, T>(
+  machine: Accessor<M>,
+  selector: (context: Context<M>) => T,
+  effect: (value: T) => void
+): void {
+  createEffect(() => {
+    const value = selector(machine().context);
+    effect(value);
+  });
+}
+
+// =============================================================================
+// EXPORT TYPES FOR BETTER DX
+// =============================================================================
+
+export type {
+  Accessor,
+  Setter,
+  Store,
+  SetStoreFunction
+};

package/src/test.ts

@@ -0,0 +1,207 @@
+/**
+ * A utility type that represents either a value of type T or a Promise that resolves to T.
+ * @template T - The value type
+ */
+type MaybePromise<T> = T | Promise<T>
+
+// /**
+//  * A record of synchronous state transition functions.
+//  * Each function receives the machine context as `this` and returns a new Machine state.
+//  * @template C - The context object type
+//  */
+// type Functions<C extends object> =
+//   Record<string, (this: C, ...args: any[]) => Machine<C>>
+
+/**
+ * A record of asynchronous state transition functions.
+ * Each function receives the machine context as `this` and returns either a Machine or Promise<Machine>.
+ * @template C - The context object type
+ */
+type AsyncFunctions<C extends object> =
+  Record<string, (this: C, ...args: any[]) => MaybePromise<Machine<C>>>
+
+/**
+ * A synchronous state machine with a context object and transition functions.
+ * @template C - The context object type
+ * @example
+ * const machine: Machine<{ count: number }> = {
+ *   context: { count: 0 },
+ *   increment: function() {
+ *     return createMachine({ count: this.count + 1 }, this)
+ *   }
+ * }
+ */
+export type Machine<C extends object> = { context: C } & Functions<C>
+
+/**
+ * An asynchronous state machine with a context object and async transition functions.
+ * @template C - The context object type
+ * @example
+ * const machine: AsyncMachine<{ loading: boolean }> = {
+ *   context: { loading: false },
+ *   fetch: async function() {
+ *     return createAsyncMachine({ loading: true }, this)
+ *   }
+ * }
+ */
+export type AsyncMachine<C extends object> = { context: C } & AsyncFunctions<C>
+
+/**
+ * Creates a synchronous state machine from a context and transition functions.
+ * @template C - The context object type
+ * @param {C} context - The initial state context
+ * @param {Functions<C>} fns - Object containing transition function definitions
+ * @returns {Machine<C>} A new machine instance
+ * @example
+ * const counter = createMachine(
+ *   { count: 0 },
+ *   {
+ *     increment: function() {
+ *       return createMachine({ count: this.count + 1 }, this)
+ *     },
+ *     decrement: function() {
+ *       return createMachine({ count: this.count - 1 }, this)
+ *     }
+ *   }
+ * )
+ * const next = counter.increment() // { context: { count: 1 }, increment, decrement }
+ */
+export function createMachine<C extends object>(
+  context: C,
+  fns: Functions<C>
+): Machine<C> {
+  return Object.assign({ context }, fns)
+}
+
+/**
+ * Creates an asynchronous state machine from a context and async transition functions.
+ * @template C - The context object type
+ * @param {C} context - The initial state context
+ * @param {AsyncFunctions<C>} fns - Object containing async transition function definitions
+ * @returns {AsyncMachine<C>} A new async machine instance
+ * @example
+ * const user = createAsyncMachine(
+ *   { id: null, loading: false },
+ *   {
+ *     fetchUser: async function(userId) {
+ *       const data = await fetch(`/api/users/${userId}`)
+ *       return createAsyncMachine({ id: data.id, loading: false }, this)
+ *     }
+ *   }
+ * )
+ */
+export function createAsyncMachine<C extends object>(
+  context: C,
+  fns: AsyncFunctions<C>
+): AsyncMachine<C> {
+  return Object.assign({ context }, fns)
+}
+
+/**
+ * Creates a new machine state by applying an update function to the current machine's context.
+ * Preserves all transition functions from the original machine.
+ * @template C - The context object type
+ * @param {Machine<C>} m - The current machine state
+ * @param {Function} update - A function that takes the current read-only context and returns an updated context
+ * @returns {Machine<C>} A new machine with updated context but same transition functions
+ * @example
+ * const counter = createMachine({ count: 0 }, { })
+ * const incremented = next(counter, (ctx) => ({ count: ctx.count + 1 }))
+ * // incremented.context.count === 1
+ */
+export function next<C extends object>(
+  m: Machine<C>,
+  update: (ctx: Readonly<C>) => C
+): Machine<C> {
+  return createMachine(update(m.context), m)
+}
+
+/**
+ * A discriminated union type representing an event that can be dispatched to a machine.
+ * Each event has a `type` property matching a transition function name and `args` matching that function's parameters.
+ * @template M - The machine type
+ * @example
+ * type CounterEvent = Event<Machine<{ count: number }>& {
+ *   increment: () => any
+ *   addValue: (n: number) => any
+ * }>
+ * // CounterEvent = { type: "increment"; args: [] } | { type: "addValue"; args: [number] }
+ */
+export type Event<M> = {
+  [K in keyof M & string]: M[K] extends (...args: infer A) => any
+    ? { type: K; args: A }
+    : never
+}[keyof M & string]
+
+/**
+ * Runs an asynchronous state machine with event dispatch capability.
+ * Provides a managed interface to dispatch events and track state changes.
+ * @template C - The context object type
+ * @param {AsyncMachine<C>} initial - The initial machine state
+ * @param {Function} onChange - Optional callback invoked whenever the machine state changes
+ * @returns {Object} An object with a state getter and dispatch function
+ * @returns {C} returns.state - The current machine context
+ * @returns {Function} returns.dispatch - Async function to dispatch events to the machine
+ * @example
+ * const machine = createAsyncMachine(
+ *   { count: 0 },
+ *   {
+ *     increment: async function() {
+ *       return createAsyncMachine({ count: this.count + 1 }, this)
+ *     }
+ *   }
+ * )
+ * const runner = runMachine(machine, (m) => console.log("State changed:", m.context))
+ * await runner.dispatch({ type: "increment", args: [] })
+ * console.log(runner.state) // { count: 1 }
+ */
+export function runMachine<C extends object>(
+  initial: AsyncMachine<C>,
+  onChange?: (m: AsyncMachine<C>) => void
+) {
+  let current = initial
+
+  async function dispatch<E extends Event<typeof current>>(event: E) {
+    const fn = current[event.type] as any
+    if (!fn) throw new Error(`Unknown event: ${event.type}`)
+    const next = await fn.apply(current.context, event.args)
+    current = next
+    onChange?.(current)
+    return current
+  }
+
+  return {
+    get state() {
+      return current.context
+    },
+    dispatch,
+  }
+}
+
+
+
+
+type Functions<C extends object> =
+  Record<string, (this: C, ...args: any[]) => Machine<any>>
+
+// Simple counter example using the functional API
+// Note: In the real library, transition functions receive context as `this`
+const counterFns = {
+  increment: function() {
+    // `this` is bound to the context by the library
+    return createMachine({ count: (this as any).count + 1 }, counterFns);
+  },
+  decrement: function() {
+    // `this` is bound to the context by the library
+    return createMachine({ count: (this as any).count - 1 }, counterFns);
+  }
+};
+
+const counter = createMachine(
+  { count: 0 },
+  counterFns
+);
+
+// Test by calling with proper context binding
+const result = counterFns.increment.call(counter.context);
+console.log('Result:', result.context.count);