@ue-too/being 0.9.4 → 0.10.0

package/README.md

@@ -1,16 +1,19 @@
 # being
 
-This is a library that helps with building finite state machines. 
+[![npm version](https://img.shields.io/npm/v/@ue-too/being.svg)](https://www.npmjs.com/package/@ue-too/being)
+[![license](https://img.shields.io/npm/l/@ue-too/being.svg)](https://github.com/ue-too/ue-too/blob/main/LICENSE.txt)
+
+This is a library that helps with building finite state machines.
 
 > Disclaimer: I am not an expert on finite state machines; this is just what I use and it works for me, and the features are tailored to what I need. You would probably be better off using a library like [xstate](https://stately.ai/docs).
 
 If you still want to try it out, here is an example of how to use it:
 
-Let's say we want to build a state machine for a vending machine. 
+Let's say we want to build a state machine for a vending machine.
 
 To make it simple, the vending machine only accepts dollar bills and sells 3 types of items at $1, $2, and $3.
 
-The items are: 
+The items are:
 - Coke (1 dollar)
 - Red Bull (2 dollars)
 - Water (3 dollars)
@@ -46,7 +49,7 @@ const VENDING_MACHINE_STATES = ["IDLE", "ONE_DOLLAR_INSERTED", "TWO_DOLLARS_INSE
 export type VendingMachineStates = CreateStateType<typeof VENDING_MACHINE_STATES>;
 
 ```
-Next, we should define all the possible events and their payload. 
+Next, we should define all the possible events and their payload.
 
 ```ts
 type VendingMachineEvents = {
@@ -60,7 +63,7 @@ type VendingMachineEvents = {
 
 Sometimes we need variables to keep track of certain attributes that can persists across different states; that's where the context comes along.
 
-For this example we don't need keep tabs on any attribute, so we can just use the `BaseContext` as our interface of context. 
+For this example we don't need keep tabs on any attribute, so we can just use the `BaseContext` as our interface of context.
 
 The interface `State` and `StateMachine` only accepts context extending or implements the `BaseContext` to ensure that context has a `setup` and `cleanup` method.
 
@@ -73,9 +76,9 @@ const context: BaseContext = {
 }
 ```
 
-Next, we can start implementing the different states of the state machine. 
+Next, we can start implementing the different states of the state machine.
 
-To do that we can use the `TemplateState` as a starting point. 
+To do that we can use the `TemplateState` as a starting point.
 
 `TemplateState` is an abstract class that covers most of the boilerplate code. You just need to define the reaction corresponding to the events.
 
@@ -88,7 +91,7 @@ It's an object with the key being the event name and the value being the reactio
 The `EventReactions` looks like this:
 ```ts
 export type EventReactions<EventPayloadMapping, Context extends BaseContext, States extends string> = {
-    [K in keyof Partial<EventPayloadMapping>]: { 
+    [K in keyof Partial<EventPayloadMapping>]: {
         action: (context: Context, event: EventPayloadMapping[K], stateMachine: StateMachine<EventPayloadMapping, Context, States>) => void;
         defaultTargetState?: States;
     };

package/index.d.ts

@@ -1 +1,111 @@
+/**
+ * @packageDocumentation
+ * State machine library for TypeScript.
+ *
+ * @remarks
+ * The `@ue-too/being` package provides a type-safe, flexible finite state machine implementation
+ * for TypeScript. It enables you to model complex stateful behavior with clear state transitions,
+ * event handling, and conditional logic through guards.
+ *
+ * ## Core Concepts
+ *
+ * - **States**: Discrete modes that your system can be in (e.g., IDLE, ACTIVE, LOADING)
+ * - **Events**: Triggers that cause state transitions (e.g., "start", "stop", "load")
+ * - **Context**: Shared data that persists across state transitions
+ * - **Guards**: Conditional logic for dynamic state transitions
+ * - **Event Reactions**: Handlers that define what happens when an event occurs in a state
+ *
+ * ## Key Features
+ *
+ * - **Type Safety**: Full TypeScript type inference for events, payloads, and states
+ * - **Event Outputs**: Actions can return values accessible in event results
+ * - **Lifecycle Hooks**: `uponEnter` and `beforeExit` callbacks for state transitions
+ * - **Conditional Transitions**: Guards enable context-based routing to different states
+ * - **Flexible Architecture**: States only define handlers for relevant events
+ *
+ * ## Main Exports
+ *
+ * - {@link TemplateStateMachine}: Concrete state machine implementation
+ * - {@link TemplateState}: Abstract base class for creating states
+ * - {@link BaseContext}: Context interface for shared state data
+ * - {@link EventResult}: Type for event handling results
+ * - {@link createStateGuard}: Utility for creating type guards
+ *
+ * @example
+ * Basic state machine
+ * ```typescript
+ * import { TemplateStateMachine, TemplateState, BaseContext } from '@ue-too/being';
+ *
+ * // Define events and payloads
+ * type Events = {
+ *   start: {};
+ *   stop: {};
+ *   tick: { delta: number };
+ * };
+ *
+ * // Define states
+ * type States = "IDLE" | "RUNNING" | "PAUSED";
+ *
+ * // Define context
+ * interface TimerContext extends BaseContext {
+ *   elapsed: number;
+ *   setup() { this.elapsed = 0; }
+ *   cleanup() {}
+ * }
+ *
+ * // Create state classes
+ * class IdleState extends TemplateState<Events, TimerContext, States> {
+ *   eventReactions = {
+ *     start: {
+ *       action: (context) => {
+ *         console.log('Starting timer');
+ *         context.elapsed = 0;
+ *       },
+ *       defaultTargetState: "RUNNING"
+ *     }
+ *   };
+ * }
+ *
+ * class RunningState extends TemplateState<Events, TimerContext, States> {
+ *   eventReactions = {
+ *     tick: {
+ *       action: (context, event) => {
+ *         context.elapsed += event.delta;
+ *       }
+ *     },
+ *     stop: {
+ *       action: (context) => {
+ *         console.log('Stopped at:', context.elapsed);
+ *       },
+ *       defaultTargetState: "IDLE"
+ *     }
+ *   };
+ * }
+ *
+ * // Create and use the state machine
+ * const context: TimerContext = {
+ *   elapsed: 0,
+ *   setup() { this.elapsed = 0; },
+ *   cleanup() {}
+ * };
+ *
+ * const timer = new TemplateStateMachine<Events, TimerContext, States>(
+ *   {
+ *     IDLE: new IdleState(),
+ *     RUNNING: new RunningState(),
+ *     PAUSED: new PausedState()
+ *   },
+ *   "IDLE",
+ *   context
+ * );
+ *
+ * // Trigger events
+ * timer.happens("start");
+ * timer.happens("tick", { delta: 16 });
+ * timer.happens("stop");
+ * ```
+ *
+ * @see {@link TemplateStateMachine} for the main state machine class
+ * @see {@link TemplateState} for creating state implementations
+ */
 export * from "./interface";

package/index.js

@@ -1,105 +1,3 @@
-// src/interface.ts
-var NO_OP = () => {};
+var x=()=>{};class d{_currentState;_states;_context;_statesArray;_stateChangeCallbacks;_happensCallbacks;_timeouts=void 0;constructor(e,n,t){this._states=e,this._currentState=n,this._context=t,this._statesArray=Object.keys(e),this._stateChangeCallbacks=[],this._happensCallbacks=[],this._states[n].uponEnter(t,this,n)}switchTo(e){this._currentState=e}happens(...e){if(this._timeouts)clearTimeout(this._timeouts);this._happensCallbacks.forEach((t)=>t(e,this._context));let n=this._states[this._currentState].handles(e,this._context,this);if(n.handled&&n.nextState!==void 0&&n.nextState!==this._currentState){let t=this._currentState;this._states[this._currentState].beforeExit(this._context,this,n.nextState),this.switchTo(n.nextState),this._states[this._currentState].uponEnter(this._context,this,t),this._stateChangeCallbacks.forEach((o)=>o(t,this._currentState))}return n}onStateChange(e){this._stateChangeCallbacks.push(e)}onHappens(e){this._happensCallbacks.push(e)}get currentState(){return this._currentState}setContext(e){this._context=e}get possibleStates(){return this._statesArray}get states(){return this._states}}class c{_guards={};_eventGuards={};_delay=void 0;get guards(){return this._guards}get eventGuards(){return this._eventGuards}get delay(){return this._delay}uponEnter(e,n,t){}beforeExit(e,n,t){}handles(e,n,t){let o=e[0],r=e[1];if(this.eventReactions[o]){let s=this.eventReactions[o].action(n,r,t),a=this.eventReactions[o].defaultTargetState,m=this._eventGuards[o];if(m){let p=m.find((i)=>{if(this.guards[i.guard])return this.guards[i.guard](n);return!1});return p?{handled:!0,nextState:p.target,output:s}:{handled:!0,nextState:a,output:s}}return{handled:!0,nextState:a,output:s}}return{handled:!1}}}function l(e){return(n)=>e.includes(n)}export{l as createStateGuard,d as TemplateStateMachine,c as TemplateState,x as NO_OP};
 
-class TemplateStateMachine {
-  _currentState;
-  _states;
-  _context;
-  _statesArray;
-  _stateChangeCallbacks;
-  _happensCallbacks;
-  _timeouts = undefined;
-  constructor(states, initialState, context) {
-    this._states = states;
-    this._currentState = initialState;
-    this._context = context;
-    this._statesArray = Object.keys(states);
-    this._stateChangeCallbacks = [];
-    this._happensCallbacks = [];
-    this._states[initialState].uponEnter(context, this, initialState);
-  }
-  switchTo(state) {
-    this._currentState = state;
-  }
-  happens(...args) {
-    if (this._timeouts) {
-      clearTimeout(this._timeouts);
-    }
-    this._happensCallbacks.forEach((callback) => callback(args, this._context));
-    const result = this._states[this._currentState].handles(args, this._context, this);
-    if (result.handled && result.nextState !== undefined && result.nextState !== this._currentState) {
-      const originalState = this._currentState;
-      this._states[this._currentState].beforeExit(this._context, this, result.nextState);
-      this.switchTo(result.nextState);
-      this._states[this._currentState].uponEnter(this._context, this, originalState);
-      this._stateChangeCallbacks.forEach((callback) => callback(originalState, this._currentState));
-    }
-    return result;
-  }
-  onStateChange(callback) {
-    this._stateChangeCallbacks.push(callback);
-  }
-  onHappens(callback) {
-    this._happensCallbacks.push(callback);
-  }
-  get currentState() {
-    return this._currentState;
-  }
-  setContext(context) {
-    this._context = context;
-  }
-  get possibleStates() {
-    return this._statesArray;
-  }
-  get states() {
-    return this._states;
-  }
-}
-
-class TemplateState {
-  _guards = {};
-  _eventGuards = {};
-  _delay = undefined;
-  get guards() {
-    return this._guards;
-  }
-  get eventGuards() {
-    return this._eventGuards;
-  }
-  get delay() {
-    return this._delay;
-  }
-  uponEnter(context, stateMachine, from) {}
-  beforeExit(context, stateMachine, to) {}
-  handles(args, context, stateMachine) {
-    const eventKey = args[0];
-    const eventPayload = args[1];
-    if (this.eventReactions[eventKey]) {
-      this.eventReactions[eventKey].action(context, eventPayload, stateMachine);
-      const targetState = this.eventReactions[eventKey].defaultTargetState;
-      const guardToEvaluate = this._eventGuards[eventKey];
-      if (guardToEvaluate) {
-        const target = guardToEvaluate.find((guard) => {
-          if (this.guards[guard.guard]) {
-            return this.guards[guard.guard](context);
-          }
-          return false;
-        });
-        return target ? { handled: true, nextState: target.target } : { handled: true, nextState: targetState };
-      }
-      return { handled: true, nextState: targetState };
-    }
-    return { handled: false };
-  }
-}
-function createStateGuard(set) {
-  return (s) => set.includes(s);
-}
-export {
-  createStateGuard,
-  TemplateStateMachine,
-  TemplateState,
-  NO_OP
-};
-
-//# debugId=85B5A2C72A8BC3ED64756E2164756E21
+//# debugId=391A71F13DC7D12B64756E2164756E21

package/index.js.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../src/interface.ts"],
   "sourcesContent": [
-    "export interface BaseContext {\n    setup(): void;\n    cleanup(): void;\n}\n\ntype NOOP = () => void;\n\ntype IsEmptyObject<T> = T extends {} ? {} extends T ? true : false : false;\n\n/**\n * @description Utility type to derive a string literal union from a readonly array of string literals.\n * \n * Example:\n * ```ts\n * const TEST_STATES = [\"one\", \"two\", \"three\"] as const;\n * type TestStates = CreateStateType<typeof TEST_STATES>; // \"one\" | \"two\" | \"three\"\n * ```\n */\nexport type CreateStateType<ArrayLiteral extends readonly string[]> = ArrayLiteral[number];\n\nexport type EventArgs<EventPayloadMapping, K> = \n  K extends keyof EventPayloadMapping\n    ? IsEmptyObject<EventPayloadMapping[K]> extends true\n      ? [event: K] // No payload needed\n      : [event: K, payload: EventPayloadMapping[K]] // Payload required\n    : [event: K, payload?: unknown]; // Unknown events\n\nexport const NO_OP: NOOP = ()=>{};\n\nexport type EventNotHandled = {\n    handled: false;\n}\n\nexport type EventHandled<States extends string> = {\n    handled: true;\n    nextState?: States;\n}\n\nexport type EventHandledResult<States extends string> = EventNotHandled | EventHandled<States>;\n\n/**\n * @description This is the interface for the state machine. The interface takes in a few generic parameters.\n * \n * Generic parameters:\n * - EventPayloadMapping: A mapping of events to their payloads.\n * - Context: The context of the state machine. (which can be used by each state to do calculations that would persist across states)\n * - States: All of the possible states that the state machine can be in. e.g. a string literal union like \"IDLE\" | \"SELECTING\" | \"PAN\" | \"ZOOM\"\n * \n * You can probably get by using the TemplateStateMachine class.\n * The naming is that an event would \"happen\" and the state of the state machine would \"handle\" it.\n *\n * @see {@link TemplateStateMachine}\n * @see {@link KmtInputStateMachine}\n * \n * @category being\n */\nexport interface StateMachine<EventPayloadMapping, Context extends BaseContext, States extends string = 'IDLE'> {\n    switchTo(state: States): void;\n    // Overload for known events - provides IntelliSense\n    happens<K extends keyof EventPayloadMapping>(\n        ...args: EventArgs<EventPayloadMapping, K>\n    ): EventHandledResult<States>;\n    // Overload for unknown events - maintains backward compatibility\n    happens<K extends string>(\n        ...args: EventArgs<EventPayloadMapping, K>\n    ): EventHandledResult<States>;\n    setContext(context: Context): void;\n    states: Record<States, State<EventPayloadMapping, Context, string extends States ? string : States>>;\n    onStateChange(callback: StateChangeCallback<States>): void;\n    possibleStates: States[];\n    onHappens(callback: (args: EventArgs<EventPayloadMapping, keyof EventPayloadMapping | string>, context: Context) => void): void;\n}\n\n/**\n * @description This is the type for the callback that is called when the state changes.\n *\n * @category being\n */\nexport type StateChangeCallback<States extends string = 'IDLE'> = (currentState: States, nextState: States) => void;\n\n/**\n * @description This is the interface for the state. The interface takes in a few generic parameters:\n * You can probably get by extending the TemplateState class. \n *\n * Generic parameters:\n * - EventPayloadMapping: A mapping of events to their payloads.\n * - Context: The context of the state machine. (which can be used by each state to do calculations that would persist across states)\n * - States: All of the possible states that the state machine can be in. e.g. a string literal union like \"IDLE\" | \"SELECTING\" | \"PAN\" | \"ZOOM\"\n * \n * A state's all possible states can be only a subset of the possible states of the state machine. (a state only needs to know what states it can transition to)\n * This allows for a state to be reusable across different state machines.\n *\n * @see {@link TemplateState}\n * \n * @category being\n */\nexport interface State<EventPayloadMapping, Context extends BaseContext, States extends string = 'IDLE'> { \n    uponEnter(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States>, from: States): void;\n    beforeExit(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States>, to: States): void;\n    handles<K extends (keyof EventPayloadMapping | string)>(args: EventArgs<EventPayloadMapping, K>, context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States>): EventHandledResult<States>;\n    eventReactions: EventReactions<EventPayloadMapping, Context, States>;\n    guards: Guard<Context>;\n    eventGuards: Partial<EventGuards<EventPayloadMapping, States, Context, Guard<Context>>>;\n    delay: Delay<Context, EventPayloadMapping, States> | undefined;\n}\n\n/**\n * @description This is the type for the event reactions of a state.\n * \n * Generic parameters:\n * - EventPayloadMapping: A mapping of events to their payloads.\n * - Context: The context of the state machine. (which can be used by each state to do calculations that would persist across states)\n * - States: All of the possible states that the state machine can be in. e.g. a string literal union like \"IDLE\" | \"SELECTING\" | \"PAN\" | \"ZOOM\"\n * \n * @category being\n */\nexport type EventReactions<EventPayloadMapping, Context extends BaseContext, States extends string> = {\n    [K in keyof Partial<EventPayloadMapping>]: { \n        action: (context: Context, event: EventPayloadMapping[K], stateMachine: StateMachine<EventPayloadMapping, Context, States>) => void;\n        defaultTargetState?: States;\n    };\n};\n\n/**\n * @description This is the type for the guard evaluation when a state transition is happening.\n * \n * Guard evaluations are evaluated after the state has handled the event with the action.\n * Guard evaluations can be defined in an array and the first guard that evaluates to true will be used to determine the next state.\n * \n * Generic parameters:\n * - Context: The context of the state machine. (which can be used by each state to do calculations that would persist across states)\n * \n * @category being\n */\nexport type GuardEvaluation<Context extends BaseContext> = (context: Context) => boolean;\n\n/**\n * @description This is the type for the guard of a state.\n * \n * guard is an object that maps a key to a guard evaluation.\n * K is all the possible keys that can be used to evaluate the guard.\n * K is optional but if it is not provided, typescript won't be able to type guard in the EventGuards type.\n * \n * @category being\n */\nexport type Guard<Context extends BaseContext, K extends string = string> = {\n    [P in K]: GuardEvaluation<Context>;\n}\n\nexport type Action<Context extends BaseContext, EventPayloadMapping, States extends string> = {\n    action: (context: Context, event: EventPayloadMapping[keyof EventPayloadMapping], stateMachine: StateMachine<EventPayloadMapping, Context, States>) => void;\n    defaultTargetState?: States;\n}\n\nexport type Delay<Context extends BaseContext, EventPayloadMapping, States extends string> = {\n    time: number;\n    action: Action<Context, EventPayloadMapping, States>;\n}\n\n/**\n * @description This is a mapping of a guard to a target state.\n * \n * Generic parameters:\n * - Context: The context of the state machine. (which can be used by each state to do calculations that would persist across states)\n * - G: The guard type.\n * - States: All of the possible states that the state machine can be in. e.g. a string literal union like \"IDLE\" | \"SELECTING\" | \"PAN\" | \"ZOOM\"\n * \n * You probably don't need to use this type directly.\n * \n * @see {@link TemplateState['eventGuards']}\n * \n * @category being\n */\nexport type GuardMapping<Context extends BaseContext, G, States extends string> = {\n    guard: G extends Guard<Context, infer K> ? K : never;\n    target: States;\n}\n\n/**\n * @description This is a mapping of an event to a guard evaluation.\n * \n * Generic parameters:\n * - EventPayloadMapping: A mapping of events to their payloads.\n * - States: All of the possible states that the state machine can be in. e.g. a string literal union like \"IDLE\" | \"SELECTING\" | \"PAN\" | \"ZOOM\"\n * - Context: The context of the state machine. (which can be used by each state to do calculations that would persist across states)\n * - T: The guard type.\n * \n * You probably don't need to use this type directly.\n * This is a mapping of an event to a guard evaluation.\n * \n * @see {@link TemplateState['eventGuards']}\n * \n * @category being\n */\nexport type EventGuards<EventPayloadMapping, States extends string, Context extends BaseContext, T extends Guard<Context>> = {\n    [K in keyof EventPayloadMapping]: GuardMapping<Context, T, States>[];\n}\n\n/**\n * @description This is the template for the state machine.\n * \n * You can use this class to create a state machine. Usually this is all you need for the state machine. Unless you need extra functionality.\n * To create a state machine, just instantiate this class and pass in the states, initial state and context.\n * \n * @see {@link createKmtInputStateMachine} for an example of how to create a state machine.\n * \n * @category being\n */\nexport class TemplateStateMachine<EventPayloadMapping, Context extends BaseContext, States extends string = 'IDLE'> implements StateMachine<EventPayloadMapping, Context, States> {\n\n    protected _currentState: States;\n    protected _states: Record<States, State<EventPayloadMapping, Context, States>>;\n    protected _context: Context;\n    protected _statesArray: States[];\n    protected _stateChangeCallbacks: StateChangeCallback<States>[];\n    protected _happensCallbacks: ((args: EventArgs<EventPayloadMapping, keyof EventPayloadMapping | string>, context: Context) => void)[];\n    protected _timeouts: ReturnType<typeof setTimeout> | undefined = undefined;\n\n    constructor(states: Record<States, State<EventPayloadMapping, Context, States>>, initialState: States, context: Context){\n        this._states = states;\n        this._currentState = initialState;\n        this._context = context;\n        this._statesArray = Object.keys(states) as States[];\n        this._stateChangeCallbacks = [];\n        this._happensCallbacks = [];\n        this._states[initialState].uponEnter(context, this, initialState);\n    }\n\n    switchTo(state: States): void {\n        this._currentState = state;\n    }\n    \n    // Implementation signature - matches both overloads\n    happens<K extends keyof EventPayloadMapping>(...args: EventArgs<EventPayloadMapping, K>): EventHandledResult<States>;\n    happens<K extends string>(...args: EventArgs<EventPayloadMapping, K>): EventHandledResult<States>;\n    happens<K extends keyof EventPayloadMapping | string>(...args: EventArgs<EventPayloadMapping, K>): EventHandledResult<States> {\n        if(this._timeouts){\n            clearTimeout(this._timeouts);\n        }\n        this._happensCallbacks.forEach(callback => callback(args, this._context));\n        const result = this._states[this._currentState].handles(args, this._context, this);\n        if(result.handled && result.nextState !== undefined && result.nextState !== this._currentState){ // TODO: whether or not to transition to the same state (currently no) (uponEnter and beforeExit will still be called if the state is the same)\n            const originalState = this._currentState;\n            this._states[this._currentState].beforeExit(this._context, this, result.nextState);\n            this.switchTo(result.nextState);\n            this._states[this._currentState].uponEnter(this._context, this, originalState);\n            this._stateChangeCallbacks.forEach(callback => callback(originalState, this._currentState));\n        }\n        return result;\n    }\n\n    onStateChange(callback: StateChangeCallback<States>): void {\n        this._stateChangeCallbacks.push(callback);\n    }\n\n    onHappens(callback: (args: EventArgs<EventPayloadMapping, keyof EventPayloadMapping | string>, context: Context) => void): void {\n        this._happensCallbacks.push(callback);\n    }\n\n    get currentState(): States {\n        return this._currentState;\n    }\n\n    setContext(context: Context): void {\n        this._context = context;\n    }\n\n    get possibleStates(): States[] {\n        return this._statesArray;\n    }\n\n    get states(): Record<States, State<EventPayloadMapping, Context, States>> {\n        return this._states;\n    }\n}\n/**\n * @description This is the template for the state.\n * \n * This is a base template that you can extend to create a state.\n * Unlike the TemplateStateMachine, this class is abstract. You need to implement the specific methods that you need.\n * The core part off the state is the event reactions in which you would define how to handle each event in a state.\n * You can define an eventReactions object that maps only the events that you need. If this state does not need to handle a specific event, you can just not define it in the eventReactions object.\n * \n * @category being\n */\nexport abstract class TemplateState<EventPayloadMapping, Context extends BaseContext, States extends string = 'IDLE'> implements State<EventPayloadMapping, Context, States> {\n\n    public abstract eventReactions: EventReactions<EventPayloadMapping, Context, States>;\n    protected _guards: Guard<Context> = {} as Guard<Context>;\n    protected _eventGuards: Partial<EventGuards<EventPayloadMapping, States, Context, Guard<Context>>> = {} as Partial<EventGuards<EventPayloadMapping, States, Context, Guard<Context>>>;\n    protected _delay: Delay<Context, EventPayloadMapping, States> | undefined = undefined;\n\n    get guards(): Guard<Context> {\n        return this._guards;\n    }\n\n    get eventGuards(): Partial<EventGuards<EventPayloadMapping, States, Context, Guard<Context>>> {\n        return this._eventGuards;\n    }\n\n    get delay(): Delay<Context, EventPayloadMapping, States> | undefined {\n        return this._delay;\n    }\n\n    uponEnter(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States>, from: States): void {\n        // console.log(\"enter\");\n    }\n\n    beforeExit(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States>, to: States): void {\n        // console.log('leave');\n    }\n\n    handles<K extends (keyof EventPayloadMapping | string)>(args: EventArgs<EventPayloadMapping, K>, context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States>): EventHandledResult<States>{\n        const eventKey = args[0] as keyof EventPayloadMapping;\n        const eventPayload = args[1] as EventPayloadMapping[keyof EventPayloadMapping];\n        if (this.eventReactions[eventKey]) {\n            this.eventReactions[eventKey].action(context, eventPayload, stateMachine);\n            const targetState = this.eventReactions[eventKey].defaultTargetState;\n            const guardToEvaluate = this._eventGuards[eventKey];\n            if(guardToEvaluate){\n                const target = guardToEvaluate.find((guard)=>{\n                    if(this.guards[guard.guard]){\n                        return this.guards[guard.guard](context);\n                    }\n                    return false;\n                });\n                return target ? {handled: true, nextState: target.target} : {handled: true, nextState: targetState};\n            }\n            return {handled: true, nextState: targetState};\n        }\n        return {handled: false};\n    }\n}\n\n\n/**\n * Example usage\n * ```ts\n type TestSubStates = \"subOne\" | \"subTwo\" | \"subThree\";\n const TEST_STATES = [\"one\", \"two\", \"three\"] as const;\n type TestStates = CreateStateType<typeof TEST_STATES>;\n type AllStates = TestStates | TestSubStates;\n\n const isTestState = createStateGuard(TEST_STATES);\n\nfunction test(s: AllStates) {\n\tif (isTestState(s)) {\n\t\t// s: TestStates\n    }\n}\n * ```\n\n * @param set \n * @returns \n */\n\nexport function createStateGuard<T extends string>(set: readonly T[]) {\n    return (s: string): s is T => set.includes(s as T);\n}\n"
+    "/**\n * Base context interface for state machines.\n *\n * @remarks\n * The context is shared across all states in a state machine and can be used to store data\n * that persists between state transitions. All custom contexts must extend this interface.\n *\n * The setup and cleanup methods provide lifecycle hooks for resource management:\n * - `setup()`: Called when the context is initialized\n * - `cleanup()`: Called when the context is destroyed\n *\n * @example\n * ```typescript\n * interface MyContext extends BaseContext {\n *   counter: number;\n *   data: string[];\n *   setup() {\n *     this.counter = 0;\n *     this.data = [];\n *   }\n *   cleanup() {\n *     this.data = [];\n *   }\n * }\n * ```\n *\n * @category Core\n */\nexport interface BaseContext {\n    setup(): void;\n    cleanup(): void;\n}\n\ntype NOOP = () => void;\n\n/**\n * Utility type to check if an object type is empty.\n * @internal\n */\ntype IsEmptyObject<T> = T extends {} ? {} extends T ? true : false : false;\n\n/**\n * Utility type to derive a string literal union from a readonly array of string literals.\n *\n * @remarks\n * This helper type extracts the element types from a readonly array to create a union type.\n * Useful for defining state machine states from an array.\n *\n * @example\n * ```typescript\n * const TEST_STATES = [\"one\", \"two\", \"three\"] as const;\n * type TestStates = CreateStateType<typeof TEST_STATES>; // \"one\" | \"two\" | \"three\"\n * ```\n *\n * @category Utilities\n */\nexport type CreateStateType<ArrayLiteral extends readonly string[]> = ArrayLiteral[number];\n\n/**\n * Type for event arguments with conditional payload requirement.\n *\n * @remarks\n * This utility type determines whether an event requires a payload argument based on the\n * event payload mapping. If the payload is an empty object, no payload is required.\n *\n * @typeParam EventPayloadMapping - Mapping of event names to their payload types\n * @typeParam K - The event key\n *\n * @category Utilities\n */\nexport type EventArgs<EventPayloadMapping, K> =\n  K extends keyof EventPayloadMapping\n    ? IsEmptyObject<EventPayloadMapping[K]> extends true\n      ? [event: K] // No payload needed\n      : [event: K, payload: EventPayloadMapping[K]] // Payload required\n    : [event: K, payload?: unknown]; // Unknown events\n\n/**\n * No-operation function constant used as a placeholder for optional actions.\n *\n * @remarks\n * Use this when you need to provide a function but don't want it to do anything,\n * such as for default state transition actions that have no side effects.\n *\n * @category Core\n */\nexport const NO_OP: NOOP = ()=>{};\n\n/**\n * Result type indicating an event was not handled by the current state.\n *\n * @remarks\n * When a state doesn't have a handler defined for a particular event, it returns this type.\n * The state machine will not transition and the event is effectively ignored.\n *\n * @category Core\n */\nexport type EventNotHandled = {\n    handled: false;\n}\n\n/**\n * Result type when an event is successfully handled by a state.\n *\n * @remarks\n * This type represents a successful event handling result. It can optionally include:\n * - `nextState`: The state to transition to (if different from current)\n * - `output`: A return value from the event handler\n *\n * @typeParam States - Union of all possible state names in the state machine\n * @typeParam Output - The output type for this event (defaults to void)\n *\n * @example\n * ```typescript\n * // Simple transition without output\n * const result: EventHandled<\"IDLE\" | \"ACTIVE\"> = {\n *   handled: true,\n *   nextState: \"ACTIVE\"\n * };\n *\n * // With output value\n * const resultWithOutput: EventHandled<\"IDLE\" | \"ACTIVE\", number> = {\n *   handled: true,\n *   nextState: \"IDLE\",\n *   output: 42\n * };\n * ```\n *\n * @category Core\n */\nexport type EventHandled<States extends string, Output = void> = {\n    handled: true;\n    nextState?: States;\n    output?: Output;\n}\n\n/**\n * Discriminated union representing the result of event handling.\n *\n * @remarks\n * Every event handler returns an EventResult, which is either:\n * - {@link EventHandled}: The event was processed successfully\n * - {@link EventNotHandled}: The event was not recognized/handled\n *\n * Use the `handled` discriminant to narrow the type in TypeScript.\n *\n * @typeParam States - Union of all possible state names\n * @typeParam Output - The output type for handled events\n *\n * @category Core\n */\nexport type EventResult<States extends string, Output = void> = EventNotHandled | EventHandled<States, Output>;\n\n/**\n * @description A default output mapping that maps all events to void.\n * Used as default when no output mapping is provided.\n * \n * @category Types\n */\nexport type DefaultOutputMapping<EventPayloadMapping> = {\n    [K in keyof EventPayloadMapping]: void;\n};\n\n/**\n * @description This is the interface for the state machine. The interface takes in a few generic parameters.\n * \n * Generic parameters:\n * - EventPayloadMapping: A mapping of events to their payloads.\n * - Context: The context of the state machine. (which can be used by each state to do calculations that would persist across states)\n * - States: All of the possible states that the state machine can be in. e.g. a string literal union like \"IDLE\" | \"SELECTING\" | \"PAN\" | \"ZOOM\"\n * - EventOutputMapping: A mapping of events to their output types. Defaults to void for all events.\n * \n * You can probably get by using the TemplateStateMachine class.\n * The naming is that an event would \"happen\" and the state of the state machine would \"handle\" it.\n *\n * @see {@link TemplateStateMachine}\n * @see {@link KmtInputStateMachine}\n * \n * @category Types\n */\nexport interface StateMachine<\n    EventPayloadMapping, \n    Context extends BaseContext, \n    States extends string = 'IDLE',\n    EventOutputMapping extends Partial<Record<keyof EventPayloadMapping, unknown>> = DefaultOutputMapping<EventPayloadMapping>\n> {\n    switchTo(state: States): void;\n    // Overload for known events - provides IntelliSense with typed output\n    happens<K extends keyof EventPayloadMapping>(\n        ...args: EventArgs<EventPayloadMapping, K>\n    ): EventResult<States, K extends keyof EventOutputMapping ? EventOutputMapping[K] : void>;\n    // Overload for unknown events - maintains backward compatibility\n    happens<K extends string>(\n        ...args: EventArgs<EventPayloadMapping, K>\n    ): EventResult<States, unknown>;\n    setContext(context: Context): void;\n    states: Record<States, State<EventPayloadMapping, Context, string extends States ? string : States, EventOutputMapping>>;\n    onStateChange(callback: StateChangeCallback<States>): void;\n    possibleStates: States[];\n    onHappens(callback: (args: EventArgs<EventPayloadMapping, keyof EventPayloadMapping | string>, context: Context) => void): void;\n}\n\n/**\n * @description This is the type for the callback that is called when the state changes.\n *\n * @category Types\n */\nexport type StateChangeCallback<States extends string = 'IDLE'> = (currentState: States, nextState: States) => void;\n\n/**\n * @description This is the interface for the state. The interface takes in a few generic parameters:\n * You can probably get by extending the TemplateState class. \n *\n * Generic parameters:\n * - EventPayloadMapping: A mapping of events to their payloads.\n * - Context: The context of the state machine. (which can be used by each state to do calculations that would persist across states)\n * - States: All of the possible states that the state machine can be in. e.g. a string literal union like \"IDLE\" | \"SELECTING\" | \"PAN\" | \"ZOOM\"\n * - EventOutputMapping: A mapping of events to their output types. Defaults to void for all events.\n * \n * A state's all possible states can be only a subset of the possible states of the state machine. (a state only needs to know what states it can transition to)\n * This allows for a state to be reusable across different state machines.\n *\n * @see {@link TemplateState}\n * \n * @category Types\n */\nexport interface State<\n    EventPayloadMapping, \n    Context extends BaseContext, \n    States extends string = 'IDLE',\n    EventOutputMapping extends Partial<Record<keyof EventPayloadMapping, unknown>> = DefaultOutputMapping<EventPayloadMapping>\n> { \n    uponEnter(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>, from: States): void;\n    beforeExit(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>, to: States): void;\n    handles<K extends (keyof EventPayloadMapping | string)>(args: EventArgs<EventPayloadMapping, K>, context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>): EventResult<States, K extends keyof EventOutputMapping ? EventOutputMapping[K] : void>;\n    eventReactions: EventReactions<EventPayloadMapping, Context, States, EventOutputMapping>;\n    guards: Guard<Context>;\n    eventGuards: Partial<EventGuards<EventPayloadMapping, States, Context, Guard<Context>>>;\n    delay: Delay<Context, EventPayloadMapping, States, EventOutputMapping> | undefined;\n}\n\n/**\n * @description This is the type for the event reactions of a state.\n * \n * Generic parameters:\n * - EventPayloadMapping: A mapping of events to their payloads.\n * - Context: The context of the state machine. (which can be used by each state to do calculations that would persist across states)\n * - States: All of the possible states that the state machine can be in. e.g. a string literal union like \"IDLE\" | \"SELECTING\" | \"PAN\" | \"ZOOM\"\n * - EventOutputMapping: A mapping of events to their output types. Defaults to void for all events.\n * \n * The action function can now return an output value that will be included in the EventHandledResult.\n * \n * @category Types\n */\nexport type EventReactions<\n    EventPayloadMapping, \n    Context extends BaseContext, \n    States extends string,\n    EventOutputMapping extends Partial<Record<keyof EventPayloadMapping, unknown>> = DefaultOutputMapping<EventPayloadMapping>\n> = {\n    [K in keyof Partial<EventPayloadMapping>]: { \n        action: (\n            context: Context, \n            event: EventPayloadMapping[K], \n            stateMachine: StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>\n        ) => K extends keyof EventOutputMapping ? (EventOutputMapping[K] | void) : void;\n        defaultTargetState?: States;\n    };\n};\n\n/**\n * @description This is the type for the guard evaluation when a state transition is happening.\n * \n * Guard evaluations are evaluated after the state has handled the event with the action.\n * Guard evaluations can be defined in an array and the first guard that evaluates to true will be used to determine the next state.\n * \n * Generic parameters:\n * - Context: The context of the state machine. (which can be used by each state to do calculations that would persist across states)\n * \n * @category Types\n */\nexport type GuardEvaluation<Context extends BaseContext> = (context: Context) => boolean;\n\n/**\n * @description This is the type for the guard of a state.\n * \n * guard is an object that maps a key to a guard evaluation.\n * K is all the possible keys that can be used to evaluate the guard.\n * K is optional but if it is not provided, typescript won't be able to type guard in the EventGuards type.\n * \n * @category Types\n */\nexport type Guard<Context extends BaseContext, K extends string = string> = {\n    [P in K]: GuardEvaluation<Context>;\n}\n\nexport type Action<\n    Context extends BaseContext, \n    EventPayloadMapping, \n    States extends string,\n    EventOutputMapping extends Partial<Record<keyof EventPayloadMapping, unknown>> = DefaultOutputMapping<EventPayloadMapping>,\n    Output = void\n> = {\n    action: (context: Context, event: EventPayloadMapping[keyof EventPayloadMapping], stateMachine: StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>) => Output | void;\n    defaultTargetState?: States;\n}\n\nexport type Delay<\n    Context extends BaseContext, \n    EventPayloadMapping, \n    States extends string,\n    EventOutputMapping extends Partial<Record<keyof EventPayloadMapping, unknown>> = DefaultOutputMapping<EventPayloadMapping>\n> = {\n    time: number;\n    action: Action<Context, EventPayloadMapping, States, EventOutputMapping>;\n}\n\n/**\n * @description This is a mapping of a guard to a target state.\n * \n * Generic parameters:\n * - Context: The context of the state machine. (which can be used by each state to do calculations that would persist across states)\n * - G: The guard type.\n * - States: All of the possible states that the state machine can be in. e.g. a string literal union like \"IDLE\" | \"SELECTING\" | \"PAN\" | \"ZOOM\"\n * \n * You probably don't need to use this type directly.\n * \n * @see {@link TemplateState['eventGuards']}\n * \n * @category Types\n */\nexport type GuardMapping<Context extends BaseContext, G, States extends string> = {\n    guard: G extends Guard<Context, infer K> ? K : never;\n    target: States;\n}\n\n/**\n * @description This is a mapping of an event to a guard evaluation.\n * \n * Generic parameters:\n * - EventPayloadMapping: A mapping of events to their payloads.\n * - States: All of the possible states that the state machine can be in. e.g. a string literal union like \"IDLE\" | \"SELECTING\" | \"PAN\" | \"ZOOM\"\n * - Context: The context of the state machine. (which can be used by each state to do calculations that would persist across states)\n * - T: The guard type.\n * \n * You probably don't need to use this type directly.\n * This is a mapping of an event to a guard evaluation.\n * \n * @see {@link TemplateState['eventGuards']}\n * \n * @category Types\n */\nexport type EventGuards<EventPayloadMapping, States extends string, Context extends BaseContext, T extends Guard<Context>> = {\n    [K in keyof EventPayloadMapping]: GuardMapping<Context, T, States>[];\n}\n\n/**\n * Concrete implementation of a finite state machine.\n *\n * @remarks\n * This class provides a complete, ready-to-use state machine implementation. It's generic enough\n * to handle most use cases without requiring custom extensions.\n *\n * ## Features\n *\n * - **Type-safe events**: Events and their payloads are fully typed via the EventPayloadMapping\n * - **State transitions**: Automatic state transitions based on event handlers\n * - **Event outputs**: Handlers can return values that are included in the result\n * - **Lifecycle hooks**: States can define `uponEnter` and `beforeExit` callbacks\n * - **State change listeners**: Subscribe to state transitions\n * - **Shared context**: All states access the same context object for persistent data\n *\n * ## Usage Pattern\n *\n * 1. Define your event payload mapping type\n * 2. Define your states as a string union type\n * 3. Create state classes extending {@link TemplateState}\n * 4. Instantiate TemplateStateMachine with your states and initial state\n *\n * @typeParam EventPayloadMapping - Object mapping event names to their payload types\n * @typeParam Context - Context type shared across all states\n * @typeParam States - Union of all possible state names (string literals)\n * @typeParam EventOutputMapping - Optional mapping of events to their output types\n *\n * @example\n * Basic vending machine state machine\n * ```typescript\n * type Events = {\n *   insertCoin: { amount: number };\n *   selectItem: { itemId: string };\n *   cancel: {};\n * };\n *\n * type States = \"IDLE\" | \"PAYMENT\" | \"DISPENSING\";\n *\n * interface VendingContext extends BaseContext {\n *   balance: number;\n *   setup() { this.balance = 0; }\n *   cleanup() {}\n * }\n *\n * const context: VendingContext = {\n *   balance: 0,\n *   setup() { this.balance = 0; },\n *   cleanup() {}\n * };\n *\n * const machine = new TemplateStateMachine<Events, VendingContext, States>(\n *   {\n *     IDLE: new IdleState(),\n *     PAYMENT: new PaymentState(),\n *     DISPENSING: new DispensingState()\n *   },\n *   \"IDLE\",\n *   context\n * );\n *\n * // Trigger events\n * machine.happens(\"insertCoin\", { amount: 100 });\n * machine.happens(\"selectItem\", { itemId: \"A1\" });\n * ```\n *\n * @category State Machine Core\n * @see {@link TemplateState} for creating state implementations\n * @see {@link StateMachine} for the interface definition\n */\nexport class TemplateStateMachine<\n    EventPayloadMapping, \n    Context extends BaseContext, \n    States extends string = 'IDLE',\n    EventOutputMapping extends Partial<Record<keyof EventPayloadMapping, unknown>> = DefaultOutputMapping<EventPayloadMapping>\n> implements StateMachine<EventPayloadMapping, Context, States, EventOutputMapping> {\n\n    protected _currentState: States;\n    protected _states: Record<States, State<EventPayloadMapping, Context, States, EventOutputMapping>>;\n    protected _context: Context;\n    protected _statesArray: States[];\n    protected _stateChangeCallbacks: StateChangeCallback<States>[];\n    protected _happensCallbacks: ((args: EventArgs<EventPayloadMapping, keyof EventPayloadMapping | string>, context: Context) => void)[];\n    protected _timeouts: ReturnType<typeof setTimeout> | undefined = undefined;\n\n    constructor(states: Record<States, State<EventPayloadMapping, Context, States, EventOutputMapping>>, initialState: States, context: Context){\n        this._states = states;\n        this._currentState = initialState;\n        this._context = context;\n        this._statesArray = Object.keys(states) as States[];\n        this._stateChangeCallbacks = [];\n        this._happensCallbacks = [];\n        this._states[initialState].uponEnter(context, this, initialState);\n    }\n\n    switchTo(state: States): void {\n        this._currentState = state;\n    }\n    \n    // Implementation signature - matches both overloads\n    happens<K extends keyof EventPayloadMapping>(...args: EventArgs<EventPayloadMapping, K>): EventResult<States, K extends keyof EventOutputMapping ? EventOutputMapping[K] : void>;\n    happens<K extends string>(...args: EventArgs<EventPayloadMapping, K>): EventResult<States, unknown>;\n    happens<K extends keyof EventPayloadMapping | string>(...args: EventArgs<EventPayloadMapping, K>): EventResult<States, unknown> {\n        if(this._timeouts){\n            clearTimeout(this._timeouts);\n        }\n        this._happensCallbacks.forEach(callback => callback(args, this._context));\n        const result = this._states[this._currentState].handles(args, this._context, this);\n        if(result.handled && result.nextState !== undefined && result.nextState !== this._currentState){ // TODO: whether or not to transition to the same state (currently no) (uponEnter and beforeExit will still be called if the state is the same)\n            const originalState = this._currentState;\n            this._states[this._currentState].beforeExit(this._context, this, result.nextState);\n            this.switchTo(result.nextState);\n            this._states[this._currentState].uponEnter(this._context, this, originalState);\n            this._stateChangeCallbacks.forEach(callback => callback(originalState, this._currentState));\n        }\n        return result;\n    }\n\n    onStateChange(callback: StateChangeCallback<States>): void {\n        this._stateChangeCallbacks.push(callback);\n    }\n\n    onHappens(callback: (args: EventArgs<EventPayloadMapping, keyof EventPayloadMapping | string>, context: Context) => void): void {\n        this._happensCallbacks.push(callback);\n    }\n\n    get currentState(): States {\n        return this._currentState;\n    }\n\n    setContext(context: Context): void {\n        this._context = context;\n    }\n\n    get possibleStates(): States[] {\n        return this._statesArray;\n    }\n\n    get states(): Record<States, State<EventPayloadMapping, Context, States, EventOutputMapping>> {\n        return this._states;\n    }\n}\n/**\n * Abstract base class for state machine states.\n *\n * @remarks\n * This abstract class provides the foundation for implementing individual states in a state machine.\n * Each state defines how it responds to events through the `eventReactions` object.\n *\n * ## Key Concepts\n *\n * - **Event Reactions**: Define handlers for events this state cares about. Unhandled events are ignored.\n * - **Guards**: Conditional logic that determines which state to transition to based on context\n * - **Lifecycle Hooks**: `uponEnter` and `beforeExit` callbacks for state transition side effects\n * - **Selective Handling**: Only define reactions for events relevant to this state\n *\n * ## Implementation Pattern\n *\n * 1. Extend this class for each state in your state machine\n * 2. Implement the `eventReactions` property with handlers for relevant events\n * 3. Optionally override `uponEnter` and `beforeExit` for lifecycle logic\n * 4. Optionally define `guards` and `eventGuards` for conditional transitions\n *\n * @typeParam EventPayloadMapping - Object mapping event names to their payload types\n * @typeParam Context - Context type shared across all states\n * @typeParam States - Union of all possible state names (string literals)\n * @typeParam EventOutputMapping - Optional mapping of events to their output types\n *\n * @example\n * Simple state implementation\n * ```typescript\n * class IdleState extends TemplateState<MyEvents, MyContext, MyStates> {\n *   eventReactions = {\n *     start: {\n *       action: (context, event) => {\n *         console.log('Starting...');\n *         context.startTime = Date.now();\n *       },\n *       defaultTargetState: \"ACTIVE\"\n *     },\n *     reset: {\n *       action: (context, event) => {\n *         context.counter = 0;\n *       }\n *       // No state transition - stays in IDLE\n *     }\n *   };\n *\n *   uponEnter(context, stateMachine, fromState) {\n *     console.log(`Entered IDLE from ${fromState}`);\n *   }\n * }\n * ```\n *\n * @example\n * State with guards for conditional transitions\n * ```typescript\n * class PaymentState extends TemplateState<Events, VendingContext, States> {\n *   guards = {\n *     hasEnoughMoney: (context) => context.balance >= context.itemPrice,\n *     needsChange: (context) => context.balance > context.itemPrice\n *   };\n *\n *   eventReactions = {\n *     selectItem: {\n *       action: (context, event) => {\n *         context.selectedItem = event.itemId;\n *         context.itemPrice = getPrice(event.itemId);\n *       },\n *       defaultTargetState: \"IDLE\" // Fallback if no guard matches\n *     }\n *   };\n *\n *   eventGuards = {\n *     selectItem: [\n *       { guard: 'hasEnoughMoney', target: 'DISPENSING' },\n *       // If hasEnoughMoney is false, uses defaultTargetState (IDLE)\n *     ]\n *   };\n * }\n * ```\n *\n * @category State Machine Core\n * @see {@link TemplateStateMachine} for the state machine implementation\n * @see {@link EventReactions} for defining event handlers\n */\nexport abstract class TemplateState<\n    EventPayloadMapping, \n    Context extends BaseContext, \n    States extends string = 'IDLE',\n    EventOutputMapping extends Partial<Record<keyof EventPayloadMapping, unknown>> = DefaultOutputMapping<EventPayloadMapping>\n> implements State<EventPayloadMapping, Context, States, EventOutputMapping> {\n\n    public abstract eventReactions: EventReactions<EventPayloadMapping, Context, States, EventOutputMapping>;\n    protected _guards: Guard<Context> = {} as Guard<Context>;\n    protected _eventGuards: Partial<EventGuards<EventPayloadMapping, States, Context, Guard<Context>>> = {} as Partial<EventGuards<EventPayloadMapping, States, Context, Guard<Context>>>;\n    protected _delay: Delay<Context, EventPayloadMapping, States, EventOutputMapping> | undefined = undefined;\n\n    get guards(): Guard<Context> {\n        return this._guards;\n    }\n\n    get eventGuards(): Partial<EventGuards<EventPayloadMapping, States, Context, Guard<Context>>> {\n        return this._eventGuards;\n    }\n\n    get delay(): Delay<Context, EventPayloadMapping, States, EventOutputMapping> | undefined {\n        return this._delay;\n    }\n\n    uponEnter(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>, from: States): void {\n        // console.log(\"enter\");\n    }\n\n    beforeExit(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>, to: States): void {\n        // console.log('leave');\n    }\n\n    handles<K extends (keyof EventPayloadMapping | string)>(args: EventArgs<EventPayloadMapping, K>, context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>): EventResult<States, K extends keyof EventOutputMapping ? EventOutputMapping[K] : void>{\n        const eventKey = args[0] as keyof EventPayloadMapping;\n        const eventPayload = args[1] as EventPayloadMapping[keyof EventPayloadMapping];\n        if (this.eventReactions[eventKey]) {\n            // Capture the output from the action\n            const output = this.eventReactions[eventKey].action(context, eventPayload, stateMachine);\n            const targetState = this.eventReactions[eventKey].defaultTargetState;\n            const guardsToEvaluate = this._eventGuards[eventKey];\n            if(guardsToEvaluate){\n                const target = guardsToEvaluate.find((guard)=>{\n                    if(this.guards[guard.guard]){\n                        return this.guards[guard.guard](context);\n                    }\n                    return false;\n                });\n                return target \n                    ? {handled: true, nextState: target.target, output: output as any} \n                    : {handled: true, nextState: targetState, output: output as any};\n            }\n            return {handled: true, nextState: targetState, output: output as any};\n        }\n        return {handled: false};\n    }\n}\n\n\n/**\n * Creates a type guard function for checking if a value belongs to a specific set of states.\n *\n * @remarks\n * This utility function generates a TypeScript type guard that narrows a string type\n * to a specific union of string literals. Useful when you have multiple state types\n * and need to distinguish between them at runtime.\n *\n * @typeParam T - String literal type to guard for\n * @param set - Readonly array of string literals defining the valid states\n * @returns A type guard function that checks if a string is in the set\n *\n * @example\n * Creating state guards for hierarchical state machines\n * ```typescript\n * type MainStates = \"idle\" | \"active\" | \"paused\";\n * type SubStates = \"loading\" | \"processing\" | \"complete\";\n * type AllStates = MainStates | SubStates;\n *\n * const MAIN_STATES = [\"idle\", \"active\", \"paused\"] as const;\n * const isMainState = createStateGuard(MAIN_STATES);\n *\n * function handleState(state: AllStates) {\n *   if (isMainState(state)) {\n *     // TypeScript knows state is MainStates here\n *     console.log('Main state:', state);\n *   } else {\n *     // TypeScript knows state is SubStates here\n *     console.log('Sub state:', state);\n *   }\n * }\n * ```\n *\n * @category Utilities\n */\nexport function createStateGuard<T extends string>(set: readonly T[]) {\n    return (s: string): s is T => set.includes(s as T);\n}\n"
   ],
-  "mappings": ";AA2BO,IAAM,QAAc,MAAI;AAAA;AAqLxB,MAAM,qBAAqK;AAAA,EAEpK;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,YAAuD;AAAA,EAEjE,WAAW,CAAC,QAAqE,cAAsB,SAAiB;AAAA,IACpH,KAAK,UAAU;AAAA,IACf,KAAK,gBAAgB;AAAA,IACrB,KAAK,WAAW;AAAA,IAChB,KAAK,eAAe,OAAO,KAAK,MAAM;AAAA,IACtC,KAAK,wBAAwB,CAAC;AAAA,IAC9B,KAAK,oBAAoB,CAAC;AAAA,IAC1B,KAAK,QAAQ,cAAc,UAAU,SAAS,MAAM,YAAY;AAAA;AAAA,EAGpE,QAAQ,CAAC,OAAqB;AAAA,IAC1B,KAAK,gBAAgB;AAAA;AAAA,EAMzB,OAAqD,IAAI,MAAqE;AAAA,IAC1H,IAAG,KAAK,WAAU;AAAA,MACd,aAAa,KAAK,SAAS;AAAA,IAC/B;AAAA,IACA,KAAK,kBAAkB,QAAQ,cAAY,SAAS,MAAM,KAAK,QAAQ,CAAC;AAAA,IACxE,MAAM,SAAS,KAAK,QAAQ,KAAK,eAAe,QAAQ,MAAM,KAAK,UAAU,IAAI;AAAA,IACjF,IAAG,OAAO,WAAW,OAAO,cAAc,aAAa,OAAO,cAAc,KAAK,eAAc;AAAA,MAC3F,MAAM,gBAAgB,KAAK;AAAA,MAC3B,KAAK,QAAQ,KAAK,eAAe,WAAW,KAAK,UAAU,MAAM,OAAO,SAAS;AAAA,MACjF,KAAK,SAAS,OAAO,SAAS;AAAA,MAC9B,KAAK,QAAQ,KAAK,eAAe,UAAU,KAAK,UAAU,MAAM,aAAa;AAAA,MAC7E,KAAK,sBAAsB,QAAQ,cAAY,SAAS,eAAe,KAAK,aAAa,CAAC;AAAA,IAC9F;AAAA,IACA,OAAO;AAAA;AAAA,EAGX,aAAa,CAAC,UAA6C;AAAA,IACvD,KAAK,sBAAsB,KAAK,QAAQ;AAAA;AAAA,EAG5C,SAAS,CAAC,UAAsH;AAAA,IAC5H,KAAK,kBAAkB,KAAK,QAAQ;AAAA;AAAA,MAGpC,YAAY,GAAW;AAAA,IACvB,OAAO,KAAK;AAAA;AAAA,EAGhB,UAAU,CAAC,SAAwB;AAAA,IAC/B,KAAK,WAAW;AAAA;AAAA,MAGhB,cAAc,GAAa;AAAA,IAC3B,OAAO,KAAK;AAAA;AAAA,MAGZ,MAAM,GAAgE;AAAA,IACtE,OAAO,KAAK;AAAA;AAEpB;AAAA;AAWO,MAAe,cAAuJ;AAAA,EAG/J,UAA0B,CAAC;AAAA,EAC3B,eAA2F,CAAC;AAAA,EAC5F,SAAkE;AAAA,MAExE,MAAM,GAAmB;AAAA,IACzB,OAAO,KAAK;AAAA;AAAA,MAGZ,WAAW,GAA+E;AAAA,IAC1F,OAAO,KAAK;AAAA;AAAA,MAGZ,KAAK,GAA4D;AAAA,IACjE,OAAO,KAAK;AAAA;AAAA,EAGhB,SAAS,CAAC,SAAkB,cAAkE,MAAoB;AAAA,EAIlH,UAAU,CAAC,SAAkB,cAAkE,IAAkB;AAAA,EAIjH,OAAuD,CAAC,MAAyC,SAAkB,cAA6F;AAAA,IAC5M,MAAM,WAAW,KAAK;AAAA,IACtB,MAAM,eAAe,KAAK;AAAA,IAC1B,IAAI,KAAK,eAAe,WAAW;AAAA,MAC/B,KAAK,eAAe,UAAU,OAAO,SAAS,cAAc,YAAY;AAAA,MACxE,MAAM,cAAc,KAAK,eAAe,UAAU;AAAA,MAClD,MAAM,kBAAkB,KAAK,aAAa;AAAA,MAC1C,IAAG,iBAAgB;AAAA,QACf,MAAM,SAAS,gBAAgB,KAAK,CAAC,UAAQ;AAAA,UACzC,IAAG,KAAK,OAAO,MAAM,QAAO;AAAA,YACxB,OAAO,KAAK,OAAO,MAAM,OAAO,OAAO;AAAA,UAC3C;AAAA,UACA,OAAO;AAAA,SACV;AAAA,QACD,OAAO,SAAS,EAAC,SAAS,MAAM,WAAW,OAAO,OAAM,IAAI,EAAC,SAAS,MAAM,WAAW,YAAW;AAAA,MACtG;AAAA,MACA,OAAO,EAAC,SAAS,MAAM,WAAW,YAAW;AAAA,IACjD;AAAA,IACA,OAAO,EAAC,SAAS,MAAK;AAAA;AAE9B;AAwBO,SAAS,gBAAkC,CAAC,KAAmB;AAAA,EAClE,OAAO,CAAC,MAAsB,IAAI,SAAS,CAAM;AAAA;",
-  "debugId": "85B5A2C72A8BC3ED64756E2164756E21",
+  "mappings": "AAsFO,IAAM,EAAc,IAAI,GAoVxB,MAAM,CAKuE,CAEtE,cACA,QACA,SACA,aACA,sBACA,kBACA,UAAuD,OAEjE,WAAW,CAAC,EAAyF,EAAsB,EAAiB,CACxI,KAAK,QAAU,EACf,KAAK,cAAgB,EACrB,KAAK,SAAW,EAChB,KAAK,aAAe,OAAO,KAAK,CAAM,EACtC,KAAK,sBAAwB,CAAC,EAC9B,KAAK,kBAAoB,CAAC,EAC1B,KAAK,QAAQ,GAAc,UAAU,EAAS,KAAM,CAAY,EAGpE,QAAQ,CAAC,EAAqB,CAC1B,KAAK,cAAgB,EAMzB,OAAqD,IAAI,EAAuE,CAC5H,GAAG,KAAK,UACJ,aAAa,KAAK,SAAS,EAE/B,KAAK,kBAAkB,QAAQ,KAAY,EAAS,EAAM,KAAK,QAAQ,CAAC,EACxE,IAAM,EAAS,KAAK,QAAQ,KAAK,eAAe,QAAQ,EAAM,KAAK,SAAU,IAAI,EACjF,GAAG,EAAO,SAAW,EAAO,YAAc,QAAa,EAAO,YAAc,KAAK,cAAc,CAC3F,IAAM,EAAgB,KAAK,cAC3B,KAAK,QAAQ,KAAK,eAAe,WAAW,KAAK,SAAU,KAAM,EAAO,SAAS,EACjF,KAAK,SAAS,EAAO,SAAS,EAC9B,KAAK,QAAQ,KAAK,eAAe,UAAU,KAAK,SAAU,KAAM,CAAa,EAC7E,KAAK,sBAAsB,QAAQ,KAAY,EAAS,EAAe,KAAK,aAAa,CAAC,EAE9F,OAAO,EAGX,aAAa,CAAC,EAA6C,CACvD,KAAK,sBAAsB,KAAK,CAAQ,EAG5C,SAAS,CAAC,EAAsH,CAC5H,KAAK,kBAAkB,KAAK,CAAQ,KAGpC,aAAY,EAAW,CACvB,OAAO,KAAK,cAGhB,UAAU,CAAC,EAAwB,CAC/B,KAAK,SAAW,KAGhB,eAAc,EAAa,CAC3B,OAAO,KAAK,gBAGZ,OAAM,EAAoF,CAC1F,OAAO,KAAK,QAEpB,CAqFO,MAAe,CAKuD,CAG/D,QAA0B,CAAC,EAC3B,aAA2F,CAAC,EAC5F,OAAsF,UAE5F,OAAM,EAAmB,CACzB,OAAO,KAAK,WAGZ,YAAW,EAA+E,CAC1F,OAAO,KAAK,gBAGZ,MAAK,EAAgF,CACrF,OAAO,KAAK,OAGhB,SAAS,CAAC,EAAkB,EAAsF,EAAoB,EAItI,UAAU,CAAC,EAAkB,EAAsF,EAAkB,EAIrI,OAAuD,CAAC,EAAyC,EAAkB,EAA6K,CAC5R,IAAM,EAAW,EAAK,GAChB,EAAe,EAAK,GAC1B,GAAI,KAAK,eAAe,GAAW,CAE/B,IAAM,EAAS,KAAK,eAAe,GAAU,OAAO,EAAS,EAAc,CAAY,EACjF,EAAc,KAAK,eAAe,GAAU,mBAC5C,EAAmB,KAAK,aAAa,GAC3C,GAAG,EAAiB,CAChB,IAAM,EAAS,EAAiB,KAAK,CAAC,IAAQ,CAC1C,GAAG,KAAK,OAAO,EAAM,OACjB,OAAO,KAAK,OAAO,EAAM,OAAO,CAAO,EAE3C,MAAO,GACV,EACD,OAAO,EACD,CAAC,QAAS,GAAM,UAAW,EAAO,OAAQ,OAAQ,CAAa,EAC/D,CAAC,QAAS,GAAM,UAAW,EAAa,OAAQ,CAAa,EAEvE,MAAO,CAAC,QAAS,GAAM,UAAW,EAAa,OAAQ,CAAa,EAExE,MAAO,CAAC,QAAS,EAAK,EAE9B,CAsCO,SAAS,CAAkC,CAAC,EAAmB,CAClE,MAAO,CAAC,IAAsB,EAAI,SAAS,CAAM",
+  "debugId": "391A71F13DC7D12B64756E2164756E21",
   "names": []
 }

package/interface.d.ts

@@ -1,29 +1,151 @@
+/**
+ * Base context interface for state machines.
+ *
+ * @remarks
+ * The context is shared across all states in a state machine and can be used to store data
+ * that persists between state transitions. All custom contexts must extend this interface.
+ *
+ * The setup and cleanup methods provide lifecycle hooks for resource management:
+ * - `setup()`: Called when the context is initialized
+ * - `cleanup()`: Called when the context is destroyed
+ *
+ * @example
+ * ```typescript
+ * interface MyContext extends BaseContext {
+ *   counter: number;
+ *   data: string[];
+ *   setup() {
+ *     this.counter = 0;
+ *     this.data = [];
+ *   }
+ *   cleanup() {
+ *     this.data = [];
+ *   }
+ * }
+ * ```
+ *
+ * @category Core
+ */
 export interface BaseContext {
     setup(): void;
     cleanup(): void;
 }
 type NOOP = () => void;
+/**
+ * Utility type to check if an object type is empty.
+ * @internal
+ */
 type IsEmptyObject<T> = T extends {} ? {} extends T ? true : false : false;
 /**
- * @description Utility type to derive a string literal union from a readonly array of string literals.
+ * Utility type to derive a string literal union from a readonly array of string literals.
+ *
+ * @remarks
+ * This helper type extracts the element types from a readonly array to create a union type.
+ * Useful for defining state machine states from an array.
  *
- * Example:
- * ```ts
+ * @example
+ * ```typescript
  * const TEST_STATES = ["one", "two", "three"] as const;
  * type TestStates = CreateStateType<typeof TEST_STATES>; // "one" | "two" | "three"
  * ```
+ *
+ * @category Utilities
  */
 export type CreateStateType<ArrayLiteral extends readonly string[]> = ArrayLiteral[number];
+/**
+ * Type for event arguments with conditional payload requirement.
+ *
+ * @remarks
+ * This utility type determines whether an event requires a payload argument based on the
+ * event payload mapping. If the payload is an empty object, no payload is required.
+ *
+ * @typeParam EventPayloadMapping - Mapping of event names to their payload types
+ * @typeParam K - The event key
+ *
+ * @category Utilities
+ */
 export type EventArgs<EventPayloadMapping, K> = K extends keyof EventPayloadMapping ? IsEmptyObject<EventPayloadMapping[K]> extends true ? [event: K] : [event: K, payload: EventPayloadMapping[K]] : [event: K, payload?: unknown];
+/**
+ * No-operation function constant used as a placeholder for optional actions.
+ *
+ * @remarks
+ * Use this when you need to provide a function but don't want it to do anything,
+ * such as for default state transition actions that have no side effects.
+ *
+ * @category Core
+ */
 export declare const NO_OP: NOOP;
+/**
+ * Result type indicating an event was not handled by the current state.
+ *
+ * @remarks
+ * When a state doesn't have a handler defined for a particular event, it returns this type.
+ * The state machine will not transition and the event is effectively ignored.
+ *
+ * @category Core
+ */
 export type EventNotHandled = {
     handled: false;
 };
-export type EventHandled<States extends string> = {
+/**
+ * Result type when an event is successfully handled by a state.
+ *
+ * @remarks
+ * This type represents a successful event handling result. It can optionally include:
+ * - `nextState`: The state to transition to (if different from current)
+ * - `output`: A return value from the event handler
+ *
+ * @typeParam States - Union of all possible state names in the state machine
+ * @typeParam Output - The output type for this event (defaults to void)
+ *
+ * @example
+ * ```typescript
+ * // Simple transition without output
+ * const result: EventHandled<"IDLE" | "ACTIVE"> = {
+ *   handled: true,
+ *   nextState: "ACTIVE"
+ * };
+ *
+ * // With output value
+ * const resultWithOutput: EventHandled<"IDLE" | "ACTIVE", number> = {
+ *   handled: true,
+ *   nextState: "IDLE",
+ *   output: 42
+ * };
+ * ```
+ *
+ * @category Core
+ */
+export type EventHandled<States extends string, Output = void> = {
     handled: true;
     nextState?: States;
+    output?: Output;
+};
+/**
+ * Discriminated union representing the result of event handling.
+ *
+ * @remarks
+ * Every event handler returns an EventResult, which is either:
+ * - {@link EventHandled}: The event was processed successfully
+ * - {@link EventNotHandled}: The event was not recognized/handled
+ *
+ * Use the `handled` discriminant to narrow the type in TypeScript.
+ *
+ * @typeParam States - Union of all possible state names
+ * @typeParam Output - The output type for handled events
+ *
+ * @category Core
+ */
+export type EventResult<States extends string, Output = void> = EventNotHandled | EventHandled<States, Output>;
+/**
+ * @description A default output mapping that maps all events to void.
+ * Used as default when no output mapping is provided.
+ *
+ * @category Types
+ */
+export type DefaultOutputMapping<EventPayloadMapping> = {
+    [K in keyof EventPayloadMapping]: void;
 };
-export type EventHandledResult<States extends string> = EventNotHandled | EventHandled<States>;
 /**
  * @description This is the interface for the state machine. The interface takes in a few generic parameters.
  *
@@ -31,6 +153,7 @@ export type EventHandledResult<States extends string> = EventNotHandled | EventH
  * - EventPayloadMapping: A mapping of events to their payloads.
  * - Context: The context of the state machine. (which can be used by each state to do calculations that would persist across states)
  * - States: All of the possible states that the state machine can be in. e.g. a string literal union like "IDLE" | "SELECTING" | "PAN" | "ZOOM"
+ * - EventOutputMapping: A mapping of events to their output types. Defaults to void for all events.
  *
  * You can probably get by using the TemplateStateMachine class.
  * The naming is that an event would "happen" and the state of the state machine would "handle" it.
@@ -38,14 +161,14 @@ export type EventHandledResult<States extends string> = EventNotHandled | EventH
  * @see {@link TemplateStateMachine}
  * @see {@link KmtInputStateMachine}
  *
- * @category being
+ * @category Types
  */
-export interface StateMachine<EventPayloadMapping, Context extends BaseContext, States extends string = 'IDLE'> {
+export interface StateMachine<EventPayloadMapping, Context extends BaseContext, States extends string = 'IDLE', EventOutputMapping extends Partial<Record<keyof EventPayloadMapping, unknown>> = DefaultOutputMapping<EventPayloadMapping>> {
     switchTo(state: States): void;
-    happens<K extends keyof EventPayloadMapping>(...args: EventArgs<EventPayloadMapping, K>): EventHandledResult<States>;
-    happens<K extends string>(...args: EventArgs<EventPayloadMapping, K>): EventHandledResult<States>;
+    happens<K extends keyof EventPayloadMapping>(...args: EventArgs<EventPayloadMapping, K>): EventResult<States, K extends keyof EventOutputMapping ? EventOutputMapping[K] : void>;
+    happens<K extends string>(...args: EventArgs<EventPayloadMapping, K>): EventResult<States, unknown>;
     setContext(context: Context): void;
-    states: Record<States, State<EventPayloadMapping, Context, string extends States ? string : States>>;
+    states: Record<States, State<EventPayloadMapping, Context, string extends States ? string : States, EventOutputMapping>>;
     onStateChange(callback: StateChangeCallback<States>): void;
     possibleStates: States[];
     onHappens(callback: (args: EventArgs<EventPayloadMapping, keyof EventPayloadMapping | string>, context: Context) => void): void;
@@ -53,7 +176,7 @@ export interface StateMachine<EventPayloadMapping, Context extends BaseContext,
 /**
  * @description This is the type for the callback that is called when the state changes.
  *
- * @category being
+ * @category Types
  */
 export type StateChangeCallback<States extends string = 'IDLE'> = (currentState: States, nextState: States) => void;
 /**
@@ -64,22 +187,23 @@ export type StateChangeCallback<States extends string = 'IDLE'> = (currentState:
  * - EventPayloadMapping: A mapping of events to their payloads.
  * - Context: The context of the state machine. (which can be used by each state to do calculations that would persist across states)
  * - States: All of the possible states that the state machine can be in. e.g. a string literal union like "IDLE" | "SELECTING" | "PAN" | "ZOOM"
+ * - EventOutputMapping: A mapping of events to their output types. Defaults to void for all events.
  *
  * A state's all possible states can be only a subset of the possible states of the state machine. (a state only needs to know what states it can transition to)
  * This allows for a state to be reusable across different state machines.
  *
  * @see {@link TemplateState}
  *
- * @category being
+ * @category Types
  */
-export interface State<EventPayloadMapping, Context extends BaseContext, States extends string = 'IDLE'> {
-    uponEnter(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States>, from: States): void;
-    beforeExit(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States>, to: States): void;
-    handles<K extends (keyof EventPayloadMapping | string)>(args: EventArgs<EventPayloadMapping, K>, context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States>): EventHandledResult<States>;
-    eventReactions: EventReactions<EventPayloadMapping, Context, States>;
+export interface State<EventPayloadMapping, Context extends BaseContext, States extends string = 'IDLE', EventOutputMapping extends Partial<Record<keyof EventPayloadMapping, unknown>> = DefaultOutputMapping<EventPayloadMapping>> {
+    uponEnter(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>, from: States): void;
+    beforeExit(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>, to: States): void;
+    handles<K extends (keyof EventPayloadMapping | string)>(args: EventArgs<EventPayloadMapping, K>, context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>): EventResult<States, K extends keyof EventOutputMapping ? EventOutputMapping[K] : void>;
+    eventReactions: EventReactions<EventPayloadMapping, Context, States, EventOutputMapping>;
     guards: Guard<Context>;
     eventGuards: Partial<EventGuards<EventPayloadMapping, States, Context, Guard<Context>>>;
-    delay: Delay<Context, EventPayloadMapping, States> | undefined;
+    delay: Delay<Context, EventPayloadMapping, States, EventOutputMapping> | undefined;
 }
 /**
  * @description This is the type for the event reactions of a state.
@@ -88,12 +212,15 @@ export interface State<EventPayloadMapping, Context extends BaseContext, States
  * - EventPayloadMapping: A mapping of events to their payloads.
  * - Context: The context of the state machine. (which can be used by each state to do calculations that would persist across states)
  * - States: All of the possible states that the state machine can be in. e.g. a string literal union like "IDLE" | "SELECTING" | "PAN" | "ZOOM"
+ * - EventOutputMapping: A mapping of events to their output types. Defaults to void for all events.
  *
- * @category being
+ * The action function can now return an output value that will be included in the EventHandledResult.
+ *
+ * @category Types
  */
-export type EventReactions<EventPayloadMapping, Context extends BaseContext, States extends string> = {
+export type EventReactions<EventPayloadMapping, Context extends BaseContext, States extends string, EventOutputMapping extends Partial<Record<keyof EventPayloadMapping, unknown>> = DefaultOutputMapping<EventPayloadMapping>> = {
     [K in keyof Partial<EventPayloadMapping>]: {
-        action: (context: Context, event: EventPayloadMapping[K], stateMachine: StateMachine<EventPayloadMapping, Context, States>) => void;
+        action: (context: Context, event: EventPayloadMapping[K], stateMachine: StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>) => K extends keyof EventOutputMapping ? (EventOutputMapping[K] | void) : void;
         defaultTargetState?: States;
     };
 };
@@ -106,7 +233,7 @@ export type EventReactions<EventPayloadMapping, Context extends BaseContext, Sta
  * Generic parameters:
  * - Context: The context of the state machine. (which can be used by each state to do calculations that would persist across states)
  *
- * @category being
+ * @category Types
  */
 export type GuardEvaluation<Context extends BaseContext> = (context: Context) => boolean;
 /**
@@ -116,18 +243,18 @@ export type GuardEvaluation<Context extends BaseContext> = (context: Context) =>
  * K is all the possible keys that can be used to evaluate the guard.
  * K is optional but if it is not provided, typescript won't be able to type guard in the EventGuards type.
  *
- * @category being
+ * @category Types
  */
 export type Guard<Context extends BaseContext, K extends string = string> = {
     [P in K]: GuardEvaluation<Context>;
 };
-export type Action<Context extends BaseContext, EventPayloadMapping, States extends string> = {
-    action: (context: Context, event: EventPayloadMapping[keyof EventPayloadMapping], stateMachine: StateMachine<EventPayloadMapping, Context, States>) => void;
+export type Action<Context extends BaseContext, EventPayloadMapping, States extends string, EventOutputMapping extends Partial<Record<keyof EventPayloadMapping, unknown>> = DefaultOutputMapping<EventPayloadMapping>, Output = void> = {
+    action: (context: Context, event: EventPayloadMapping[keyof EventPayloadMapping], stateMachine: StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>) => Output | void;
     defaultTargetState?: States;
 };
-export type Delay<Context extends BaseContext, EventPayloadMapping, States extends string> = {
+export type Delay<Context extends BaseContext, EventPayloadMapping, States extends string, EventOutputMapping extends Partial<Record<keyof EventPayloadMapping, unknown>> = DefaultOutputMapping<EventPayloadMapping>> = {
     time: number;
-    action: Action<Context, EventPayloadMapping, States>;
+    action: Action<Context, EventPayloadMapping, States, EventOutputMapping>;
 };
 /**
  * @description This is a mapping of a guard to a target state.
@@ -141,7 +268,7 @@ export type Delay<Context extends BaseContext, EventPayloadMapping, States exten
  *
  * @see {@link TemplateState['eventGuards']}
  *
- * @category being
+ * @category Types
  */
 export type GuardMapping<Context extends BaseContext, G, States extends string> = {
     guard: G extends Guard<Context, infer K> ? K : never;
@@ -161,81 +288,230 @@ export type GuardMapping<Context extends BaseContext, G, States extends string>
  *
  * @see {@link TemplateState['eventGuards']}
  *
- * @category being
+ * @category Types
  */
 export type EventGuards<EventPayloadMapping, States extends string, Context extends BaseContext, T extends Guard<Context>> = {
     [K in keyof EventPayloadMapping]: GuardMapping<Context, T, States>[];
 };
 /**
- * @description This is the template for the state machine.
+ * Concrete implementation of a finite state machine.
+ *
+ * @remarks
+ * This class provides a complete, ready-to-use state machine implementation. It's generic enough
+ * to handle most use cases without requiring custom extensions.
+ *
+ * ## Features
+ *
+ * - **Type-safe events**: Events and their payloads are fully typed via the EventPayloadMapping
+ * - **State transitions**: Automatic state transitions based on event handlers
+ * - **Event outputs**: Handlers can return values that are included in the result
+ * - **Lifecycle hooks**: States can define `uponEnter` and `beforeExit` callbacks
+ * - **State change listeners**: Subscribe to state transitions
+ * - **Shared context**: All states access the same context object for persistent data
  *
- * You can use this class to create a state machine. Usually this is all you need for the state machine. Unless you need extra functionality.
- * To create a state machine, just instantiate this class and pass in the states, initial state and context.
+ * ## Usage Pattern
  *
- * @see {@link createKmtInputStateMachine} for an example of how to create a state machine.
+ * 1. Define your event payload mapping type
+ * 2. Define your states as a string union type
+ * 3. Create state classes extending {@link TemplateState}
+ * 4. Instantiate TemplateStateMachine with your states and initial state
  *
- * @category being
+ * @typeParam EventPayloadMapping - Object mapping event names to their payload types
+ * @typeParam Context - Context type shared across all states
+ * @typeParam States - Union of all possible state names (string literals)
+ * @typeParam EventOutputMapping - Optional mapping of events to their output types
+ *
+ * @example
+ * Basic vending machine state machine
+ * ```typescript
+ * type Events = {
+ *   insertCoin: { amount: number };
+ *   selectItem: { itemId: string };
+ *   cancel: {};
+ * };
+ *
+ * type States = "IDLE" | "PAYMENT" | "DISPENSING";
+ *
+ * interface VendingContext extends BaseContext {
+ *   balance: number;
+ *   setup() { this.balance = 0; }
+ *   cleanup() {}
+ * }
+ *
+ * const context: VendingContext = {
+ *   balance: 0,
+ *   setup() { this.balance = 0; },
+ *   cleanup() {}
+ * };
+ *
+ * const machine = new TemplateStateMachine<Events, VendingContext, States>(
+ *   {
+ *     IDLE: new IdleState(),
+ *     PAYMENT: new PaymentState(),
+ *     DISPENSING: new DispensingState()
+ *   },
+ *   "IDLE",
+ *   context
+ * );
+ *
+ * // Trigger events
+ * machine.happens("insertCoin", { amount: 100 });
+ * machine.happens("selectItem", { itemId: "A1" });
+ * ```
+ *
+ * @category State Machine Core
+ * @see {@link TemplateState} for creating state implementations
+ * @see {@link StateMachine} for the interface definition
  */
-export declare class TemplateStateMachine<EventPayloadMapping, Context extends BaseContext, States extends string = 'IDLE'> implements StateMachine<EventPayloadMapping, Context, States> {
+export declare class TemplateStateMachine<EventPayloadMapping, Context extends BaseContext, States extends string = 'IDLE', EventOutputMapping extends Partial<Record<keyof EventPayloadMapping, unknown>> = DefaultOutputMapping<EventPayloadMapping>> implements StateMachine<EventPayloadMapping, Context, States, EventOutputMapping> {
     protected _currentState: States;
-    protected _states: Record<States, State<EventPayloadMapping, Context, States>>;
+    protected _states: Record<States, State<EventPayloadMapping, Context, States, EventOutputMapping>>;
     protected _context: Context;
     protected _statesArray: States[];
     protected _stateChangeCallbacks: StateChangeCallback<States>[];
     protected _happensCallbacks: ((args: EventArgs<EventPayloadMapping, keyof EventPayloadMapping | string>, context: Context) => void)[];
     protected _timeouts: ReturnType<typeof setTimeout> | undefined;
-    constructor(states: Record<States, State<EventPayloadMapping, Context, States>>, initialState: States, context: Context);
+    constructor(states: Record<States, State<EventPayloadMapping, Context, States, EventOutputMapping>>, initialState: States, context: Context);
     switchTo(state: States): void;
-    happens<K extends keyof EventPayloadMapping>(...args: EventArgs<EventPayloadMapping, K>): EventHandledResult<States>;
-    happens<K extends string>(...args: EventArgs<EventPayloadMapping, K>): EventHandledResult<States>;
+    happens<K extends keyof EventPayloadMapping>(...args: EventArgs<EventPayloadMapping, K>): EventResult<States, K extends keyof EventOutputMapping ? EventOutputMapping[K] : void>;
+    happens<K extends string>(...args: EventArgs<EventPayloadMapping, K>): EventResult<States, unknown>;
     onStateChange(callback: StateChangeCallback<States>): void;
     onHappens(callback: (args: EventArgs<EventPayloadMapping, keyof EventPayloadMapping | string>, context: Context) => void): void;
     get currentState(): States;
     setContext(context: Context): void;
     get possibleStates(): States[];
-    get states(): Record<States, State<EventPayloadMapping, Context, States>>;
+    get states(): Record<States, State<EventPayloadMapping, Context, States, EventOutputMapping>>;
 }
 /**
- * @description This is the template for the state.
+ * Abstract base class for state machine states.
+ *
+ * @remarks
+ * This abstract class provides the foundation for implementing individual states in a state machine.
+ * Each state defines how it responds to events through the `eventReactions` object.
  *
- * This is a base template that you can extend to create a state.
- * Unlike the TemplateStateMachine, this class is abstract. You need to implement the specific methods that you need.
- * The core part off the state is the event reactions in which you would define how to handle each event in a state.
- * You can define an eventReactions object that maps only the events that you need. If this state does not need to handle a specific event, you can just not define it in the eventReactions object.
+ * ## Key Concepts
  *
- * @category being
+ * - **Event Reactions**: Define handlers for events this state cares about. Unhandled events are ignored.
+ * - **Guards**: Conditional logic that determines which state to transition to based on context
+ * - **Lifecycle Hooks**: `uponEnter` and `beforeExit` callbacks for state transition side effects
+ * - **Selective Handling**: Only define reactions for events relevant to this state
+ *
+ * ## Implementation Pattern
+ *
+ * 1. Extend this class for each state in your state machine
+ * 2. Implement the `eventReactions` property with handlers for relevant events
+ * 3. Optionally override `uponEnter` and `beforeExit` for lifecycle logic
+ * 4. Optionally define `guards` and `eventGuards` for conditional transitions
+ *
+ * @typeParam EventPayloadMapping - Object mapping event names to their payload types
+ * @typeParam Context - Context type shared across all states
+ * @typeParam States - Union of all possible state names (string literals)
+ * @typeParam EventOutputMapping - Optional mapping of events to their output types
+ *
+ * @example
+ * Simple state implementation
+ * ```typescript
+ * class IdleState extends TemplateState<MyEvents, MyContext, MyStates> {
+ *   eventReactions = {
+ *     start: {
+ *       action: (context, event) => {
+ *         console.log('Starting...');
+ *         context.startTime = Date.now();
+ *       },
+ *       defaultTargetState: "ACTIVE"
+ *     },
+ *     reset: {
+ *       action: (context, event) => {
+ *         context.counter = 0;
+ *       }
+ *       // No state transition - stays in IDLE
+ *     }
+ *   };
+ *
+ *   uponEnter(context, stateMachine, fromState) {
+ *     console.log(`Entered IDLE from ${fromState}`);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * State with guards for conditional transitions
+ * ```typescript
+ * class PaymentState extends TemplateState<Events, VendingContext, States> {
+ *   guards = {
+ *     hasEnoughMoney: (context) => context.balance >= context.itemPrice,
+ *     needsChange: (context) => context.balance > context.itemPrice
+ *   };
+ *
+ *   eventReactions = {
+ *     selectItem: {
+ *       action: (context, event) => {
+ *         context.selectedItem = event.itemId;
+ *         context.itemPrice = getPrice(event.itemId);
+ *       },
+ *       defaultTargetState: "IDLE" // Fallback if no guard matches
+ *     }
+ *   };
+ *
+ *   eventGuards = {
+ *     selectItem: [
+ *       { guard: 'hasEnoughMoney', target: 'DISPENSING' },
+ *       // If hasEnoughMoney is false, uses defaultTargetState (IDLE)
+ *     ]
+ *   };
+ * }
+ * ```
+ *
+ * @category State Machine Core
+ * @see {@link TemplateStateMachine} for the state machine implementation
+ * @see {@link EventReactions} for defining event handlers
  */
-export declare abstract class TemplateState<EventPayloadMapping, Context extends BaseContext, States extends string = 'IDLE'> implements State<EventPayloadMapping, Context, States> {
-    abstract eventReactions: EventReactions<EventPayloadMapping, Context, States>;
+export declare abstract class TemplateState<EventPayloadMapping, Context extends BaseContext, States extends string = 'IDLE', EventOutputMapping extends Partial<Record<keyof EventPayloadMapping, unknown>> = DefaultOutputMapping<EventPayloadMapping>> implements State<EventPayloadMapping, Context, States, EventOutputMapping> {
+    abstract eventReactions: EventReactions<EventPayloadMapping, Context, States, EventOutputMapping>;
     protected _guards: Guard<Context>;
     protected _eventGuards: Partial<EventGuards<EventPayloadMapping, States, Context, Guard<Context>>>;
-    protected _delay: Delay<Context, EventPayloadMapping, States> | undefined;
+    protected _delay: Delay<Context, EventPayloadMapping, States, EventOutputMapping> | undefined;
     get guards(): Guard<Context>;
     get eventGuards(): Partial<EventGuards<EventPayloadMapping, States, Context, Guard<Context>>>;
-    get delay(): Delay<Context, EventPayloadMapping, States> | undefined;
-    uponEnter(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States>, from: States): void;
-    beforeExit(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States>, to: States): void;
-    handles<K extends (keyof EventPayloadMapping | string)>(args: EventArgs<EventPayloadMapping, K>, context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States>): EventHandledResult<States>;
+    get delay(): Delay<Context, EventPayloadMapping, States, EventOutputMapping> | undefined;
+    uponEnter(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>, from: States): void;
+    beforeExit(context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>, to: States): void;
+    handles<K extends (keyof EventPayloadMapping | string)>(args: EventArgs<EventPayloadMapping, K>, context: Context, stateMachine: StateMachine<EventPayloadMapping, Context, States, EventOutputMapping>): EventResult<States, K extends keyof EventOutputMapping ? EventOutputMapping[K] : void>;
 }
 /**
- * Example usage
- * ```ts
- type TestSubStates = "subOne" | "subTwo" | "subThree";
- const TEST_STATES = ["one", "two", "three"] as const;
- type TestStates = CreateStateType<typeof TEST_STATES>;
- type AllStates = TestStates | TestSubStates;
-
- const isTestState = createStateGuard(TEST_STATES);
-
-function test(s: AllStates) {
-    if (isTestState(s)) {
-        // s: TestStates
-    }
-}
+ * Creates a type guard function for checking if a value belongs to a specific set of states.
+ *
+ * @remarks
+ * This utility function generates a TypeScript type guard that narrows a string type
+ * to a specific union of string literals. Useful when you have multiple state types
+ * and need to distinguish between them at runtime.
+ *
+ * @typeParam T - String literal type to guard for
+ * @param set - Readonly array of string literals defining the valid states
+ * @returns A type guard function that checks if a string is in the set
+ *
+ * @example
+ * Creating state guards for hierarchical state machines
+ * ```typescript
+ * type MainStates = "idle" | "active" | "paused";
+ * type SubStates = "loading" | "processing" | "complete";
+ * type AllStates = MainStates | SubStates;
+ *
+ * const MAIN_STATES = ["idle", "active", "paused"] as const;
+ * const isMainState = createStateGuard(MAIN_STATES);
+ *
+ * function handleState(state: AllStates) {
+ *   if (isMainState(state)) {
+ *     // TypeScript knows state is MainStates here
+ *     console.log('Main state:', state);
+ *   } else {
+ *     // TypeScript knows state is SubStates here
+ *     console.log('Sub state:', state);
+ *   }
+ * }
  * ```
-
- * @param set
- * @returns
+ *
+ * @category Utilities
  */
 export declare function createStateGuard<T extends string>(set: readonly T[]): (s: string) => s is T;
 export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ue-too/being",
   "type": "module",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/ue-too/ue-too.git"

package/vending-machine-example.d.ts

@@ -7,5 +7,5 @@ type VendingMachineEvents = {
     cancelTransaction: {};
 };
 type VendingMachineStates = "IDLE" | "ONE_DOLLAR_INSERTED" | "TWO_DOLLARS_INSERTED" | "THREE_DOLLARS_INSERTED";
-export declare const createVendingMachine: () => TemplateStateMachine<VendingMachineEvents, BaseContext, VendingMachineStates>;
+export declare const createVendingMachine: () => TemplateStateMachine<VendingMachineEvents, BaseContext, VendingMachineStates, import("./interface").DefaultOutputMapping<VendingMachineEvents>>;
 export {};