npm install @doeixd/machine
# or
yarn add @doeixd/machine
# or
pnpm add @doeixd/machine

type Machine<C extends object> = {
  context: C;  // Encodes the current state (s ∈ S)
} & Record<string, (...args: any[]) => Machine<any>>; // Transition functions (δ)

import { createMachine } from "@doeixd/machine";

const counter = createMachine(
  { count: 0 }, // Initial state (s₀)
  (next) => ({
    // Transitions (δ) - access state via this.context
    increment() {
      return next({ count: this.context.count + 1 });
    },
    add(n: number) {
      return next({ count: this.context.count + n });
    }
  })
);

const next = counter.increment();
console.log(next.context.count); // 1

// Original is untouched (immutability by default)
console.log(counter.context.count); // 0

const transitions = {
  increment: function() {
    return createMachine({ count: this.context.count + 1 }, transitions);
  },
  add: function(n: number) {
    return createMachine({ count: this.context.count + n }, transitions);
  }
};
const counter = createMachine({ count: 0 }, transitions);

// If you prefer mutable state, just return `this`
const counter = createMachine(
  { count: 0 },
  {
    increment: function() {
      (this.context as any).count++;
      return this; // Return same instance
    }
  }
);

counter.increment();
console.log(counter.context.count); // 1 (mutated in place)

import { state } from "@doeixd/machine";

// Traditional pattern (like createMachine)
const counter1 = state({ count: 0 }, {
  increment() { return state({ count: this.context.count + 1 }, this); }
});

// Functional pattern (like createFunctionalMachine)
const createCounter = state({ count: 0 });
const counter2 = createCounter({
  increment: ctx => ({ count: ctx.count + 1 }),
  add: (ctx, n: number) => ({ count: ctx.count + n })
});

console.log(counter1.increment().context.count); // 1
console.log(counter2.increment().add(5).context.count); // 6

import { MachineBase } from "@doeixd/machine";

/**
 * Type-State Programming with classes:
 * - Each distinct class *is* a distinct state.
 * - The methods on that class are the only valid transitions from that state.
 * - Returning a different class type moves you to a different state (at compile time).
 */

/** "LoggedOut" state: only transitions available are methods on this class. */
class LoggedOut extends MachineBase<{ status: "loggedOut" }> {
  constructor() {
    // MachineBase stores state data in `this.context`
    super({ status: "loggedOut" });
  }

  /**
   * Transition: LoggedOut -> LoggedIn
   * Notice: there's no `logout()` method here, so you literally cannot call it.
   */
  login(username: string): LoggedIn {
    return new LoggedIn(username);
  }
}

/** "LoggedIn" state: different data + different allowed transitions. */
class LoggedIn extends MachineBase<{ status: "loggedIn"; username: string }> {
  constructor(username: string) {
    // Context shape changes in this state (now includes `username`)
    super({ status: "loggedIn", username });
  }

  /**
   * Transition: LoggedIn -> LoggedOut
   * This exists only on LoggedIn, so you cannot log out unless you're logged in.
   */
  logout(): LoggedOut {
    return new LoggedOut();
  }

  /**
   * Transition: LoggedIn -> LoggedIn (self-transition)
   * Returning `this` means "stay in the same state".
   */
  viewProfile(): LoggedIn {
    // With MachineBase, context lives under `this.context`
    console.log(`Viewing ${this.context.username}'s profile`);
    return this;
  }
}

// -------------------- Usage --------------------

const machine = new LoggedOut();

/**
 * ✅ Compiler-enforced validity:
 * LoggedOut has only `.login()`, so calling `.logout()` is a type error.
 */
// machine.logout(); // ❌ Property 'logout' does not exist on type 'LoggedOut'

const loggedIn = machine.login("alice");

/**
 * LoggedIn has `.logout()` and `.viewProfile()`.
 * It does NOT have `.login()`, so calling it is a compile-time error.
 */
// loggedIn.login("bob"); // ❌ Property 'login' does not exist on type 'LoggedIn'

const stillLoggedIn = loggedIn.viewProfile(); // ✅ OK (self-transition)
const loggedOut = loggedIn.logout();          // ✅ OK (LoggedIn -> LoggedOut)

/**
 * The key idea:
 * - You never check `status` at runtime to know what you can do.
 * - The *type* tells you what transitions are available.
 * - Autocomplete only offers valid transitions for the current state.
 */

// ❌ State is just data - compiler can't help
type State = { status: "loggedOut" } | { status: "loggedIn"; username: string };

function logout(state: State) {
  if (state.status === "loggedOut") {
    // Oops! Already logged out, but this only fails at runtime
    throw new Error("Already logged out!");
  }
  return { status: "loggedOut" as const };
}

// Nothing prevents you from calling logout on loggedOut state
const state: State = { status: "loggedOut" };
logout(state); // Runtime error!

// ✅ States are distinct types - compiler enforces validity
type LoggedOut = Machine<{ status: "loggedOut" }, {
  login: (user: string) => LoggedIn;
  // No logout method - impossible to call
};

type LoggedIn = Machine<{ status: "loggedIn"; username: string }, {
  logout: () => LoggedOut;
  // No login method - impossible to call
};

const state: LoggedOut = createLoggedOut();
// state.logout(); // ❌ Compile error! Property 'logout' does not exist

const loggedOut: LoggedOut = createLoggedOut();
const loggedIn: LoggedIn = loggedOut.login("alice");

// ❌ Compile error! Can't login when already logged in
// loggedIn.login("bob");
//          ^^^^^
// Property 'login' does not exist on type 'LoggedIn'

// ❌ Compile error! Can't logout when already logged out
// loggedOut.logout();
//           ^^^^^^
// Property 'logout' does not exist on type 'LoggedOut'

const loggedOut: LoggedOut = createLoggedOut();

// ❌ Compile error! 'username' doesn't exist on LoggedOut
// console.log(loggedOut.context.username);
//                                ^^^^^^^^
// Property 'username' does not exist on type '{ status: "loggedOut" }'

const loggedIn: LoggedIn = loggedOut.login("alice");
console.log(loggedIn.context.username); // ✅ OK! TypeScript knows it exists

// TypeScript enforces handling ALL possible states
const message = matchMachine(machine, "status", {
  idle: (ctx) => "Waiting...",
  loading: (ctx) => "Loading...",
  success: (ctx) => `Done: ${ctx.data}`,
  error: (ctx) => `Error: ${ctx.error}`
  // If you forget a case, TypeScript error!
});

declare const machine: IdleMachine | LoadingMachine | SuccessMachine;

if (hasState(machine, "status", "success")) {
  // TypeScript narrows the type to SuccessMachine
  console.log(machine.context.data); // ✅ 'data' is known to exist
  machine.retry(); // ✅ Only methods available on SuccessMachine are accessible
}

type FetchMachine = AsyncMachine<{ status: string }, {
  fetch: (id: number) => Promise<FetchMachine>;
  retry: () => Promise<FetchMachine>;
};

const runner = runMachine(createFetchMachine());

// ✅ TypeScript knows the exact event shape
await runner.dispatch({ type: "fetch", args: [123] });

// ❌ Compile error! Wrong argument type
// await runner.dispatch({ type: "fetch", args: ["abc"] });
//                                               ^^^^^

// ❌ Compile error! Unknown event type
// await runner.dispatch({ type: "unknown", args: [] });
//                                ^^^^^^^^^^

// Define the states as distinct types
type IdleState = Machine<{ status: "idle" }, {
  fetch: (url: string) => LoadingState;
};

type LoadingState = Machine<{ status: "loading"; url: string }, {
  cancel: () => IdleState;
  // Note: No fetch - can't start new request while loading
};

type SuccessState = Machine<{ status: "success"; data: any }, {
  refetch: () => LoadingState;
  clear: () => IdleState;
  // Note: No cancel - nothing to cancel
};

type ErrorState = Machine<{ status: "error"; error: string }, {
  retry: () => LoadingState;
  clear: () => IdleState;
};

// Union type for the overall machine
type FetchMachine = IdleState | LoadingState | SuccessState | ErrorState;

// Implementation
const createIdle = (): IdleState =>
  createMachine({ status: "idle" }, {
    fetch: function(url: string): LoadingState {
      return createLoading(url);
    }
  });

const createLoading = (url: string): LoadingState =>
  createMachine({ status: "loading", url }, {
    cancel: function(): IdleState {
      return createIdle();
    }
  });

// ... implement other states

// Usage - TypeScript guides you
const machine: FetchMachine = createIdle();

if (hasState(machine, "status", "idle")) {
  const loading = machine.fetch("/api/data"); // ✅ OK
  // loading.fetch("/other"); // ❌ Error! Can't fetch while loading
  const idle = loading.cancel(); // ✅ Can cancel loading
}

const machine = createMachine({ count: 0 }, (next) => ({
  increment() {
    // `this` points at the machine; read state via this.context
    return next({ count: this.context.count + 1 });
  },
  add(n: number) {
    return next({ count: this.context.count + n });
  }
}));

const machine = createMachine(
  { count: 0 },  // Context (state data)
  {              // Transitions (state transformations)
    increment: function() {
      return createMachine({ count: this.context.count + 1 }, this);
    }
  }
);

const machine = createMachine({ count: 0 }, (transition) => ({
  increment() {
    // `this` points at the machine; read state via this.context
    return transition({ count: this.context.count + 1 });
  },
  add(n: number) {
    return transition({ count: this.context.count + n });
  }
}));

const machine = createAsyncMachine(
  { status: "idle", data: null },
  (next) => ({
    async fetch() {
      try {
        const data = await api.getData();
        return next({ status: "success", data });
      } catch (error) {
        return next({ status: "error", data: null });
      }
    }
  })
);

import { createMachineFactory } from "@doeixd/machine";

// Define pure transformations
const counterFactory = createMachineFactory<{ count: number }>()({
  increment: (ctx) => ({ count: ctx.count + 1 }),
  add: (ctx, n: number) => ({ count: ctx.count + n }),
  reset: (ctx) => ({ count: 0 })
});

// Create instances
const counter = counterFactory({ count: 0 });
const next = counter.add(5); // { count: 5 }

import { runMachine, Event } from "@doeixd/machine";

const runner = runMachine(
  createFetchMachine(),
  (machine) => {
    console.log("State changed:", machine.context);
  }
);

// Type-safe event dispatch
await runner.dispatch({ type: "fetch", args: [123] });

// Access current state
console.log(runner.state); // Current context

type FetchEvent = Event<FetchMachine>;
// = { type: "fetch", args: [number] } | { type: "retry", args: [] } | ...

import { setContext } from "@doeixd/machine";

// With updater function
const updated = setContext(machine, (ctx) => ({ count: ctx.count + 1 }));

// With direct value
const reset = setContext(machine, { count: 0 });

import { next } from "@doeixd/machine";

const updated = next(counter, (ctx) => ({ count: ctx.count + 1 }));

import { call, Machine } from "@doeixd/machine";

type MyMachine = Machine<{ count: number }>;
const increment = function(this: MyMachine) { 
  return { count: this.context.count + 1 }; 
};

const machine = { context: { count: 5 } } as MyMachine;
const result = call(increment, machine); // Returns { count: 6 }

// Particularly useful with generator-based flows:
const result = run(function* (m) {
  m = yield* step(call(m.increment, m));
  m = yield* step(call(m.add, m, 5));
  return m;
}, counter);

import { bindTransitions, Machine } from "@doeixd/machine";

const counter = bindTransitions(createMachine(
  { count: 0 },
  {
    increment(this: Machine<{ count: number }>) {
      return createMachine({ count: this.context.count + 1 }, this);
    },
    add(this: Machine<{ count: number }>, n: number) {
      return createMachine({ count: this.context.count + n }, this);
    }
  }
));

// All methods are automatically bound - no need for .call()!
const next = counter.increment(); // Works!
const result = counter.add(5);    // Works!

// Great for generator-based flows:
const result = run(function* (m) {
  m = yield* step(m.increment());     // Clean syntax!
  m = yield* step(m.add(5));          // No .call() needed
  return m;
}, counter);

import { matchMachine } from "@doeixd/machine";

const message = matchMachine(machine, "status", {
  idle: (ctx) => "Ready to start",
  loading: (ctx) => "Loading...",
  success: (ctx) => `Loaded: ${ctx.data}`,
  error: (ctx) => `Error: ${ctx.error}`
});

import { createMatcher, classCase, discriminantCase, forContext } from "@doeixd/machine";

// 1. Define the matcher
const match = createMatcher(
  classCase('idle', IdleMachine),
  classCase('loading', LoadingMachine),
  classCase('success', SuccessMachine)
);

// 2. Use it for Type Guards
if (match.is.loading(machine)) {
  // machine is narrowed to LoadingMachine
  console.log(machine.context.url);
}

// 3. Use it for Exhaustive Pattern Matching
const result = match.when(machine).is(
  match.case.idle(() => "Ready"),
  match.case.loading(() => "Loading..."),
  match.case.success((m) => `Data: ${m.context.data}`),
  match.exhaustive
);

// 4. Use it for Simple Matching
const state = match(machine); // 'idle' | 'loading' | 'success' | null

type FetchContext =
  | { status: 'idle' }
  | { status: 'success'; data: string };

const builder = forContext<FetchContext>();

const match = createMatcher(
  builder.case('idle', 'status', 'idle'),
  builder.case('success', 'status', 'success')
);

if (match.is.success(machine)) {
  // machine.context is narrowed to { status: 'success'; data: string }
  console.log(machine.context.data);
}

// Implicit: helper infers return type union and enforces exhaustiveness
const res1 = match.when(machine).is(
  match.case.idle(() => 1),
  match.case.success(() => 2),
  match.exhaustive
); // number - Exhaustive check ENABLED

// Explicit generic: You specify return type, exhaustiveness check is optional (but recommended)
const res2 = match.when(machine).is<string>(
  match.case.idle(() => "Idle")
); // string - Exhaustive check DISABLED (useful for partial matching)

import { hasState } from "@doeixd/machine";

if (hasState(machine, "status", "loading")) {
  // TypeScript knows machine.context.status === "loading"
  console.log("Currently loading");
}

import { overrideTransitions } from "@doeixd/machine";

// Mock for testing
const mocked = overrideTransitions(counter, {
  increment: function() {
    return createMachine({ count: 999 }, this);
  }
});

// Decorate with logging
const logged = overrideTransitions(counter, {
  increment: function() {
    console.log("Before:", this.context.count);
    const next = counter.increment.call(this);
    console.log("After:", next.context.count);
    return next;
  }
});

import { extendTransitions } from "@doeixd/machine";

const extended = extendTransitions(counter, {
  reset: function() {
    return createMachine({ count: 0 }, this);
  }
});

// Compile error if transition already exists:
// extendTransitions(counter, { increment: ... }); // ❌ Error!

import { MachineBase, createMachineBuilder } from "@doeixd/machine";

class User extends MachineBase<{ id: number; name: string }> {
  rename(name: string) {
    return buildUser({ ...this.context, name });
  }
}

const template = new User({ id: 0, name: "" });
const buildUser = createMachineBuilder(template);

// Stamp out instances
const alice = buildUser({ id: 1, name: "Alice" });
const bob = buildUser({ id: 2, name: "Bob" });

class Combined extends MachineUnion(Machine1, Machine2) {}
// Or use instances: const combined = machineUnion(inst1, inst2);

// Create a machine that has all Source features EXCEPT those in Excluded
class Restricted extends MachineExclude(Source, Excluded) {}
// Or use instances: const restricted = machineExclude(sourceInst, excludedInst);

import { createMiddleware, withLogging, withValidation, withAnalytics } from "@doeixd/machine";

// Wrap machines with middleware
const instrumented = createMiddleware(machine, {
  before: ({ transitionName, context, args }) => {
    console.log(`→ ${transitionName}`, args);
  },
  after: ({ transitionName, prevContext, nextContext }) => {
    console.log(`✓ ${transitionName}`);
  },
  error: ({ transitionName, error }) => {
    console.error(`✗ ${transitionName}:`, error);
  }
});

// Or use pre-built middleware
const logged = withLogging(machine);
const validated = withValidation(machine, validateFn);
const tracked = withAnalytics(machine, trackEvent);

import { Context, Transitions, Event, TransitionArgs } from "@doeixd/machine";

type MyMachine = Machine<{ count: number }, {
  add: (n: number) => MyMachine;
};

type Ctx = Context<MyMachine>;           // { count: number }
type Trans = Transitions<MyMachine>;     // { add: (n: number) => MyMachine }
type Evt = Event<MyMachine>;             // { type: "add", args: [number] }
type Args = TransitionArgs<MyMachine, "add">; // [number]

import {
  DeepReadonly,      // Make types deeply immutable
  InferMachine,      // Extract machine type from factory
  TransitionNames,   // Get union of transition names
  BaseMachine,       // Base type for Machine & AsyncMachine
  MachineLike,       // Machine or Promise<Machine>
  MachineResult      // Machine or [Machine, cleanup]
} from "@doeixd/machine";

type Factory = () => createMachine({ count: 0 }, { ... });
type M = InferMachine<Factory>; // Extracts return type

type Names = TransitionNames<MyMachine>; // "add" | "increment" | ...

// For functions that can return sync or async machines
function getMachine(): MachineLike<{ count: number }> {
  // Can return either Machine or Promise<Machine>
}

// For transitions with cleanup effects
function enterState(): MachineResult<{ timer: number }> {
  const interval = setInterval(() => tick(), 1000);
  const machine = createMachine({ timer: 0 }, { ... });
  return [machine, () => clearInterval(interval)];
}

import { createMatcher, classCase, MachineBase } from "@doeixd/machine";

// Define state machines
class IdleMachine extends MachineBase<{ status: 'idle' }> {
  start() { return new LoadingMachine(); }
}

class LoadingMachine extends MachineBase<{ status: 'loading' }> {
  success(data: string) { return new SuccessMachine(data); }
  error(err: Error) { return new ErrorMachine(err); }
}

class SuccessMachine extends MachineBase<{ status: 'success'; data: string }> {
  reset() { return new IdleMachine(); }
}

class ErrorMachine extends MachineBase<{ status: 'error'; error: Error }> {
  retry() { return new LoadingMachine(); }
}

// Create reusable matcher
const match = createMatcher(
  classCase('idle', IdleMachine),
  classCase('loading', LoadingMachine),
  classCase('success', SuccessMachine),
  classCase('error', ErrorMachine)
);

type FetchMachine = IdleMachine | LoadingMachine | SuccessMachine | ErrorMachine;

const machine: FetchMachine = new LoadingMachine();

if (match.is.loading(machine)) {
  // ✓ machine is narrowed to LoadingMachine
  console.log(machine.context.startTime);
}

if (match.is.success(machine)) {
  // ✓ machine is narrowed to SuccessMachine
  console.log(machine.context.data);
}

const message = match.when(machine).is<string>(
  match.case.idle(() => 'Ready to start'),
  match.case.loading(() => 'Loading...'),
  match.case.success(m => `Done: ${m.context.data}`),
  match.case.error(m => `Error: ${m.context.error.message}`),
  match.exhaustive // ← TypeScript error if any case is missing
);

const stateName = match(machine); // 'idle' | 'loading' | 'success' | 'error' | null

switch (stateName) {
  case 'idle': return 'Ready';
  case 'loading': return 'In progress';
  case 'success': return 'Complete';
  case 'error': return 'Failed';
  default: return 'Unknown';
}

createMatcher(
  classCase('idle', IdleMachine),
  classCase('loading', LoadingMachine)
);

type Context =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: string };

const match = createMatcher(
  discriminantCase<'idle', Machine<Context>, 'status', 'idle'>('idle', 'status', 'idle'),
  discriminantCase<'loading', Machine<Context>, 'status', 'loading'>('loading', 'status', 'loading'),
  discriminantCase<'success', Machine<Context>, 'status', 'success'>('success', 'status', 'success')
);

const machine = createMachine<Context>({ status: 'success', data: 'test' }, {});

if (match.is.success(machine)) {
  console.log(machine.context.data); // ✓ TypeScript knows data exists
}

createMatcher(
  customCase('complex', (m): m is ComplexMachine => {
    return m.context.value > 10 && m.context.status === 'active';
  })
);

import { createRunner } from "@doeixd/machine/multi";

const counterMachine = createCounterMachine({ count: 0 });
const runner = createRunner(counterMachine, (newState) => {
  console.log('Count is now:', newState.context.count);
});

// Call transitions without reassignment - runner updates internally
runner.actions.increment(); // Logs: "Count is now: 1"
runner.actions.add(5);      // Logs: "Count is now: 6"

// Access current state
console.log(runner.context.count); // 6
console.log(runner.state.context.count); // 6 (full machine)

// Type narrowing works
if (runner.state.context.status === 'loggedIn') {
  runner.actions.logout(); // TypeScript knows logout exists
}

import { createEnsemble } from "@doeixd/machine/multi";

// Shared application state
type AppState = {
  auth: { status: 'loggedIn' | 'loggedOut'; user?: string };
  data: { status: 'idle' | 'loading' | 'success'; items?: any[] };
  ui: { modal: 'open' | 'closed'; theme: 'light' | 'dark' };
};

const globalStore = {
  getContext: () => appState,
  setContext: (newState) => setAppState(newState)
};

// Auth ensemble - manages auth slice
const authEnsemble = createEnsemble(globalStore, {
  loggedOut: (ctx) => createMachine(ctx, {
    login: (user) => ({ ...ctx, auth: { status: 'loggedIn', user } })
  }),
  loggedIn: (ctx) => createMachine(ctx, {
    logout: () => ({ ...ctx, auth: { status: 'loggedOut' } })
  })
}, (ctx) => ctx.auth.status);

// Data ensemble - manages data slice
const dataEnsemble = createEnsemble(globalStore, {
  idle: (ctx) => createMachine(ctx, {
    fetch: async () => {
      const items = await api.fetch();
      return { ...ctx, data: { status: 'success', items } };
    }
  }),
  loading: (ctx) => createMachine(ctx, { /* ... */ }),
  success: (ctx) => createMachine(ctx, { /* ... */ })
}, (ctx) => ctx.data.status);

// UI ensemble - manages UI slice
const uiEnsemble = createEnsemble(globalStore, {
  closed: (ctx) => createMachine(ctx, {
    open: () => ({ ...ctx, ui: { ...ctx.ui, modal: 'open' } })
  }),
  open: (ctx) => createMachine(ctx, {
    close: () => ({ ...ctx, ui: { ...ctx.ui, modal: 'closed' } })
  })
}, (ctx) => ctx.ui.modal);

// They coordinate through shared state
authEnsemble.actions.login('alice');  // Updates global auth status
dataEnsemble.actions.fetch();         // Reads from same global state
uiEnsemble.actions.showModal();       // Also uses same global state

// Zustand store integration
import { create } from 'zustand';

const useAppStore = create<AppState>((set, get) => ({
  // ... your Zustand store
}));

const zustandStore = {
  getContext: () => useAppStore.getState(),
  setContext: (newState) => useAppStore.setState(newState)
};

const ensemble = createEnsemble(zustandStore, factories, (ctx) => ctx.status);

// Redux integration
import { store } from './reduxStore';

const reduxStore = {
  getContext: () => store.getState(),
  setContext: (newState) => store.dispatch(setAppState(newState))
};

const ensemble = createEnsemble(reduxStore, factories, (ctx) => ctx.status);

// Database/API integration
const apiStore = {
  getContext: async () => await api.getAppState(),
  setContext: async (newState) => {
    await api.saveAppState(newState);
    // Trigger real-time updates to other clients
    socket.emit('state-changed', newState);
  }
};

const ensemble = createEnsemble(apiStore, factories, (ctx) => ctx.status);

// LocalStorage persistence
const persistentStore = {
  getContext: () => {
    const saved = localStorage.getItem('app-state');
    return saved ? JSON.parse(saved) : defaultState;
  },
  setContext: (newState) => {
    localStorage.setItem('app-state', JSON.stringify(newState));
    return newState;
  }
};

const ensemble = createEnsemble(persistentStore, factories, (ctx) => ctx.status);

// Single object reference that mutates
const player = createMutableMachine(
  { state: 'idle', hp: 100 },
  factories,
  (ctx) => ctx.state  // Accessor function - refactor-safe
);

// Keep the reference - it will always reflect current state
const playerRef = player;

player.takeDamage(10);
console.log(playerRef.hp); // 90 - same object!
console.log(playerRef === player); // true

import { createMultiMachine, MultiMachineBase } from "@doeixd/machine/multi";

type CounterContext = { count: number };

class CounterMachine extends MultiMachineBase<CounterContext> {
  increment() {
    this.setContext({ count: this.context.count + 1 });
  }

  add(n: number) {
    this.setContext({ count: this.context.count + n });
  }

  reset() {
    this.setContext({ count: 0 });
  }
}

const store = {
  getContext: () => ({ count: 0 }),
  setContext: (ctx) => { /* update your framework's state */ }
};

const machine = createMultiMachine(CounterMachine, store);

// Direct method calls - feels like traditional OOP
machine.increment();
console.log(machine.count); // 1

machine.add(5);
console.log(machine.count); // 6

machine.reset();
console.log(machine.count); // 0

import { run, step } from "@doeixd/machine";

const result = run(function* (machine) {
  // Write sequential code with generators
  let m = yield* step(machine.increment());
  m = yield* step(m.add(5));

  // Use normal control flow
  if (m.context.count > 10) {
    m = yield* step(m.reset());
  }

  // Loops work naturally
  for (let i = 0; i < 3; i++) {
    m = yield* step(m.increment());
  }

  return m.context.count;
}, counter);

// Async generators for async machines
const result = await runAsync(async function* (m) {
  m = yield* stepAsync(await m.fetchData());
  m = yield* stepAsync(await m.processData());
  return m.context;
}, asyncMachine);

// Reusable flows
const incrementThrice = createFlow(function* (m) {
  m = yield* step(m.increment());
  m = yield* step(m.increment());
  m = yield* step(m.increment());
  return m;
});

const result = run(function* (m) {
  m = yield* incrementThrice(m);  // Compose flows
  m = yield* step(m.add(10));
  return m;
}, counter);

import { useMachine, useMachineSelector } from '@doeixd/machine/react';

import { useMachine } from "@doeixd/machine/react";
import { createCounterMachine } from "./counterMachine";

function Counter() {
  const [machine, actions] = useMachine(() => createCounterMachine({ count: 0 }));

  return (
    <div>
      <p>Count: {machine.context.count}</p>
      {/* Call transitions directly from the stable actions object */}
      <button onClick={() => actions.increment()}>Increment</button>
      <button onClick={() => actions.add(5)}>Add 5</button>
    </div>
  );
}

function UserNameDisplay({ machine }) {
  // This component will NOT re-render if other parts of the machine's
  // context (e.g., user settings) change.
  const userName = useMachineSelector(machine, (m) => m.context.user.name);

  return <p>User: {userName}</p>;
}

import { createMachineContext, useMachine } from "@doeixd/machine/react";

// 1. Create the context
const { Provider, useSelector, useMachineActions } = createMachineContext<AuthMachine>();

// 2. Provide the machine in your root component
function App() {
  const [machine, actions] = useMachine(() => createAuthMachine());
  return (
    <Provider machine={machine} actions={actions}>
      <Header />
    </Provider>
  );
}

// 3. Consume it in any child component
function Header() {
  const status = useSelector(m => m.context.status);
  const actions = useMachineActions();

  return (
    <header>
      {status === 'loggedIn' ? (
        <button onClick={() => actions.logout()}>Logout</button>
      ) : (
        <button onClick={() => actions.login('user', 'pass')}>Login</button>
      )}
    </header>
  );
}

import { useEnsemble } from "@doeixd/machine/react";
import { fetchFactories } from "./fetchFactories"; // Pure, framework-agnostic logic

function DataFetcher() {
  const ensemble = useEnsemble(
    { status: 'idle', data: null }, // Initial context
    fetchFactories, // Your pure machine factories
    (ctx) => ctx.status // Discriminant function
  );

  return (
    <div>
      <p>Status: {ensemble.context.status}</p>
      {ensemble.context.status === 'idle' && (
        <button onClick={() => ensemble.actions.fetch('/api/data')}>
          Fetch
        </button>
      )}
    </div>
  );
}

import { createMachine, createMachineStore, createAsyncMachine } from "@doeixd/machine/solid";

// Signal-based (simple state)
function Counter() {
  const [machine, actions] = createMachine(() => createCounterMachine());

  return (
    <div>
      <p>Count: {machine().context.count}</p>
      <button onClick={actions.increment}>Increment</button>
    </div>
  );
}

// Store-based (fine-grained reactivity for complex context)
function UserProfile() {
  const [machine, setMachine, actions] = createMachineStore(() =>
    createUserMachine()
  );

  return (
    <div>
      <p>Name: {machine.context.profile.name}</p>
      <p>Age: {machine.context.profile.age}</p>
      <button onClick={() => actions.updateName('Alice')}>Change Name</button>
    </div>
  );
}

// Async machine with reactive state
function DataFetcher() {
  const [state, dispatch] = createAsyncMachine(() => createFetchMachine());

  return (
    <Switch>
      <Match when={state().context.status === 'idle'}>
        <button onClick={() => dispatch({ type: 'fetch', args: [] })}>
          Load
        </button>
      </Match>
      <Match when={state().context.status === 'loading'}>
        <p>Loading...</p>
      </Match>
      <Match when={state().context.status === 'success'}>
        <p>Data: {state().context.data}</p>
      </Match>
    </Switch>
  );
}

import { connectToDevTools } from "@doeixd/machine/devtools";

const runner = connectToDevTools(createMachine(...));
// Automatically sends state changes to browser extension

import { transitionTo, guarded, invoke, describe } from "@doeixd/machine/primitives";

class AuthMachine extends MachineBase<{ status: "idle" }> {
  // Annotate transitions with metadata
  login = describe(
    "Authenticates the user",
    transitionTo(LoggedInMachine, (username: string) => {
      return new LoggedInMachine({ username });
    })
  );

  // Add guards
  adminAction = guarded(
    { name: "isAdmin" },
    transitionTo(AdminMachine, () => new AdminMachine())
  );

  // Declare async effects
  fetchData = invoke(
    {
      src: "fetchUserData",
      onDone: SuccessMachine,
      onError: ErrorMachine
    },
    async () => { /* ... */ }
  );
}

npx ts-node src/extract.ts > statechart.json

import { MachineBase, Context } from "@doeixd/machine";

class Counter extends MachineBase<{ count: number }> {
  constructor(count = 0) {
    super({ count });
  }

  increment(): Counter {
    return new Counter(this.context.count + 1);
  }

  add(n: number): Counter {
    return new Counter(this.context.count + n);
  }
}

const counter = new Counter(5);
const next = counter.increment(); // count: 6

import {
  isState,           // Type-safe state checking (for classes)
  createEvent,       // Event factory with inference
  mergeContext,      // Shallow merge context updates
  pipeTransitions,   // Compose transitions sequentially
  logState          // Debug helper (tap function)
} from "@doeixd/machine/utils";

// Type-safe class instance check
if (isState(machine, LoggedInMachine)) {
  machine.logout(); // TypeScript knows it's LoggedInMachine
}

// Event creation
const event = createEvent<MyMachine, "add">("add", 5);

// Merge partial context
const updated = mergeContext(user, { status: "active" });

// Compose transitions
const result = await pipeTransitions(
  machine,
  (m) => m.increment(),
  (m) => m.add(5),
  (m) => m.increment()
);

// Debug logging
pipeTransitions(
  machine,
  logState, // Logs current state
  (m) => m.increment(),
  (m) => logState(m, "After increment:")
);

import { MachineBase } from '@doeixd/machine';
import { transitionTo, describe, action, guarded } from '@doeixd/machine/primitives';

class LoggedOut extends MachineBase<{ status: 'loggedOut' }> {
  login = describe(
    "Start the login process",
    action(
      { name: "logAttempt", description: "Track login attempts" },
      transitionTo(LoggingIn, (username: string) => new LoggingIn({ username }))
    )
  );
}

class LoggingIn extends MachineBase<{ status: 'loggingIn'; username: string }> {
  success = transitionTo(LoggedIn, (token: string) => new LoggedIn({ token }));
  failure = transitionTo(LoggedOut, () => new LoggedOut());
}

class LoggedIn extends MachineBase<{ status: 'loggedIn'; token: string }> {
  logout = describe(
    "Log out and clear session",
    action(
      { name: "clearSession" },
      transitionTo(LoggedOut, () => new LoggedOut())
    )
  );

  deleteAccount = guarded(
    { name: "isAdmin", description: "Only admins can delete accounts" },
    transitionTo(LoggedOut, () => new LoggedOut())
  );
}

import type { ExtractionConfig } from '@doeixd/machine';

export default {
  machines: [{
    input: 'src/auth.ts',
    classes: ['LoggedOut', 'LoggingIn', 'LoggedIn'],
    output: 'statecharts/auth.json',
    id: 'auth',
    initialState: 'LoggedOut'
  }],
  verbose: true
} satisfies ExtractionConfig;

{
  "id": "auth",
  "initial": "LoggedOut",
  "states": {
    "LoggedOut": {
      "on": {
        "login": {
          "target": "LoggingIn",
          "description": "Start the login process",
          "actions": ["logAttempt"]
        }
      }
    },
    "LoggingIn": {
      "on": {
        "success": { "target": "LoggedIn" },
        "failure": { "target": "LoggedOut" }
      }
    },
    "LoggedIn": {
      "on": {
        "logout": {
          "target": "LoggedOut",
          "description": "Log out and clear session",
          "actions": ["clearSession"]
        },
        "deleteAccount": {
          "target": "LoggedOut",
          "cond": "isAdmin"
        }
      }
    }
  }
}

# Extract from config
npx tsx scripts/extract-statechart.ts --config .statechart.config.ts

# Extract single machine
npx tsx scripts/extract-statechart.ts \
  --input src/machine.ts \
  --id myMachine \
  --classes State1,State2 \
  --initial State1

# Watch mode
npx tsx scripts/extract-statechart.ts --config .statechart.config.ts --watch

# With validation
npx tsx scripts/extract-statechart.ts --config .statechart.config.ts --validate

{
  "scripts": {
    "extract": "tsx scripts/extract-statechart.ts --config .statechart.config.ts",
    "extract:watch": "tsx scripts/extract-statechart.ts --config .statechart.config.ts --watch"
  }
}

// Import from the separate extract entry point (NOT included in main bundle)
import { extractMachine, extractMachines } from '@doeixd/machine/extract';
import { Project } from 'ts-morph';

// Extract single machine
const project = new Project();
project.addSourceFilesAtPaths('src/**/*.ts');

const chart = extractMachine({
  input: 'src/auth.ts',
  classes: ['LoggedOut', 'LoggedIn'],
  id: 'auth',
  initialState: 'LoggedOut'
}, project);

console.log(JSON.stringify(chart, null, 2));

// Extract multiple machines
const charts = extractMachines({
  machines: [
    { input: 'src/auth.ts', classes: [...], id: 'auth', initialState: 'LoggedOut' },
    { input: 'src/fetch.ts', classes: [...], id: 'fetch', initialState: 'Idle' }
  ],
  verbose: true
});

const config: MachineConfig = {
  input: 'src/dashboard.ts',
  classes: ['Dashboard', 'ErrorState'],
  id: 'dashboard',
  initialState: 'Dashboard',
  children: {
    contextProperty: 'child',
    initialState: 'ViewingMachine',
    classes: ['ViewingMachine', 'EditingMachine']
  }
};

{
  "id": "dashboard",
  "initial": "Dashboard",
  "states": {
    "Dashboard": {
      "initial": "ViewingMachine",
      "states": {
        "ViewingMachine": { "on": { /* ... */ } },
        "EditingMachine": { "on": { /* ... */ } }
      }
    }
  }
}

const config: MachineConfig = {
  input: 'src/editor.ts',
  id: 'editor',
  parallel: {
    regions: [
      {
        name: 'fontWeight',
        initialState: 'Normal',
        classes: ['Normal', 'Bold']
      },
      {
        name: 'textDecoration',
        initialState: 'None',
        classes: ['None', 'Underline']
      }
    ]
  }
};

{
  "id": "editor",
  "type": "parallel",
  "states": {
    "fontWeight": {
      "initial": "Normal",
      "states": {
        "Normal": { "on": { /* ... */ } },
        "Bold": { "on": { /* ... */ } }
      }
    },
    "textDecoration": {
      "initial": "None",
      "states": {
        "None": { "on": { /* ... */ } },
        "Underline": { "on": { /* ... */ } }
      }
    }
  }
}

import { generateStatechart, extractFromInstance } from '@doeixd/machine';

// Create machine instances (annotated with DSL primitives)
const loggedOutMachine = new LoggedOut({ status: 'loggedOut' });
const loggedInMachine = new LoggedIn({ status: 'loggedIn', token: 'abc' });

// Generate complete statechart from multiple states
const chart = generateStatechart({
  LoggedOut: loggedOutMachine,
  LoggedIn: loggedInMachine
}, {
  id: 'auth',
  initial: 'LoggedOut'
});

// Or extract from a single instance
const singleChart = extractFromInstance(loggedOutMachine, {
  id: 'auth',
  stateName: 'LoggedOut'
});

// ✅ Good: Typed method reference
const counter = createMachine({ count: 0 }, {
  increment: function() {
    return createMachine({ count: this.context.count + 1 }, this);
  }
});

counter.increment(); // TypeScript knows this exists

// ✅ Good: Events inferred from machine structure
type CounterEvent = Event<typeof counter>;
// Automatically: { type: "increment", args: [] }

// ❌ Bad (other libraries): Magic strings
// send({ type: "INCREMENT" }) // Easy to typo, no refactoring support

// Machine types
type Machine<C extends object>
type AsyncMachine<C extends object>
type BaseMachine<C extends object>

// Type utilities
type Context<M>
type Transitions<M>
type Event<M>
type TransitionArgs<M, K>
type TransitionNames<M>
type DeepReadonly<T>
type InferMachine<F>
type MachineLike<C>
type MachineResult<C>

// Classes
class MachineBase<C extends object>