@axi-engine/states 0.1.0

package/README.md

@@ -0,0 +1,228 @@
+# StateMachine
+
+A lightweight, type-safe, and easy-to-use state machine 
+designed for managing game logic and component states
+within the Axi Engine.
+
+This implementation prioritizes simplicity, 
+a clean API, and robust error handling for common use cases. 
+It is perfect for managing character states, 
+UI flows, game session lifecycles, and more. 
+It has minimal dependencies, relying only on the `Emitter` 
+utility from `@axi-engine/utils` for its event system.
+
+For highly complex scenarios involving hierarchical (nested) states, 
+parallel states, or state history, 
+I recommend considering more powerful, 
+dedicated libraries like [XState](https://xstate.js.org/). 
+
+My goal is to provide a solid, built-in tool that covers 80% of typical game development needs 
+without adding external dependencies or unnecessary complexity.
+
+## Features
+
+-   **Simple and Clean API:** Registering states and transitioning between them is straightforward.
+-   **Type-Safe:** Leverages TypeScript generics to provide type safety for state names and event payloads.
+-   **Lifecycle Hooks:** States can have `onEnter` and `onExit` handlers for setup and cleanup logic.
+-   **Transition Guards:** You can define which states are allowed to transition to a new state, preventing logical errors.
+-   **Observable State:** A public `onChange` emitter allows you to subscribe to all state transitions for debugging, logging, or reacting to changes.
+-   **Minimal Dependencies:** Relies only on a tiny, self-contained `Emitter` utility.
+
+## Getting Started
+
+First, define the possible states, typically using an `enum` for type safety.
+
+```typescript
+enum GameState {
+  MainMenu,
+  Loading,
+  Playing,
+  Paused,
+  GameOver,
+}
+```
+
+Then, create an instance of the `StateMachine`. The machine starts in an `undefined` state.
+
+```typescript
+import { StateMachine } from './@axi-engine/states';
+
+const gameState = new StateMachine<GameState>();
+```
+
+## API and Usage
+
+### 1. Registering States
+
+You can register a state with a simple handler function. This function will be treated as the `onEnter` hook.
+
+```typescript
+// Simple registration
+gameState.register(GameState.MainMenu, () => {
+  console.log('Welcome to the Main Menu!');
+  showMainMenu();
+});
+
+gameState.register(GameState.GameOver, () => {
+  console.log('Game Over!');
+  showGameOverScreen();
+});
+```
+
+### 2. Changing States
+
+Use the `call` method to transition to a new state. The method is asynchronous to handle any `async` logic within state handlers. The first call will formally start the machine.
+
+```typescript
+// Start the machine by calling the initial state
+await gameState.call(GameState.MainMenu);
+
+// ... later in the game
+await gameState.call(GameState.GameOver);
+```
+
+### 3. Using Payloads
+
+You can pass data during a state transition. The payload type can be defined in the `StateMachine` generic.
+
+```typescript
+// State machine that accepts a string payload for the 'Loading' state
+const sm = new StateMachine<GameState, string>();
+
+sm.register(GameState.Loading, async (levelId: string) => {
+  console.log(`Loading level: ${levelId}...`);
+  await loadLevelAssets(levelId);
+});
+
+await sm.call(GameState.Loading, 'level-2');
+```
+
+### 4. Advanced Registration
+
+For more control, you can register a state with a configuration object. This allows you to define `onEnter`, `onExit` hooks, and transition guards.
+
+#### `onEnter` and `onExit`
+
+-   `onEnter`: Called when the machine enters the state.
+-   `onExit`: Called when the machine leaves the state. This is perfect for cleanup.
+
+```typescript
+gameState.register(GameState.Playing, {
+  onEnter: () => {
+    console.log('Starting game...');
+    gameMusic.play();
+    player.enableControls();
+  },
+  onExit: () => {
+    console.log('Exiting gameplay...');
+    gameMusic.stop();
+    player.disableControls();
+  },
+});
+```
+
+#### `allowedFrom` (Transition Guards)
+
+Specify an array of states from which a transition to this state is permitted. An attempt to transition from any other state will throw an error.
+
+```typescript
+gameState.register(GameState.Paused, {
+  // You can only pause the game if you are currently playing.
+  allowedFrom: [GameState.Playing],
+  onEnter: () => {
+    console.log('Game paused.');
+    showPauseMenu();
+  },
+});
+
+// This will work:
+await gameState.call(GameState.Playing);
+await gameState.call(GameState.Paused);
+
+// This will throw an error:
+await gameState.call(GameState.MainMenu);
+await gameState.call(GameState.Paused); // Error: Transition from MainMenu to Paused is not allowed.
+```
+
+### 5. Subscribing to Changes
+
+The public `onChange` property is an `Emitter`. You can use its `subscribe` method to be notified of any state change. The method returns a function to unsubscribe.
+
+```typescript
+const unsubscribe = gameState.onChange.subscribe((from, to, payload) => {
+  const fromState = from !== undefined ? GameState[from] : 'Start';
+  console.log(`State changed from ${fromState} to ${GameState[to]}`, { payload });
+});
+
+await gameState.call(GameState.MainMenu);
+// Console output: State changed from Start to MainMenu
+
+// To stop listening later:
+unsubscribe();
+```
+
+## Full Example
+
+```typescript
+import { StateMachine } from '@axi-engine/states';
+
+enum GameState {
+  MainMenu,
+  Playing,
+  Paused,
+  GameOver,
+}
+
+// --- Setup ---
+const game = new StateMachine<GameState>();
+
+game.onChange.subscribe((from, to) => {
+  const fromState = from !== undefined ? GameState[from] : 'Start';
+  console.log(`[SYSTEM] Transition: ${fromState} -> ${GameState[to]}`);
+});
+
+game.register(GameState.MainMenu, {
+  onEnter: () => console.log('Showing Main Menu.'),
+});
+
+game.register(GameState.Playing, {
+  allowedFrom: [GameState.MainMenu, GameState.Paused],
+  onEnter: () => console.log('Game has started! Player controls enabled.'),
+  onExit: () => console.log('Player controls disabled.'),
+});
+
+game.register(GameState.Paused, {
+  allowedFrom: [GameState.Playing],
+  onEnter: () => console.log('Game is paused.'),
+});
+
+game.register(GameState.GameOver, {
+  allowedFrom: [GameState.Playing],
+  onEnter: () => console.log('You lose!'),
+});
+
+// --- Simulation ---
+async function runGame() {
+  await game.call(GameState.MainMenu);
+  // [SYSTEM] Transition: Start -> MainMenu
+  // Showing Main Menu.
+
+  await game.call(GameState.Playing);
+  // [SYSTEM] Transition: MainMenu -> Playing
+  // Game has started! Player controls enabled.
+
+  await game.call(GameState.Paused);
+  // [SYSTEM] Transition: Playing -> Paused
+  // Player controls disabled.
+  // Game is paused.
+
+  try {
+    // This transition will fail because of the 'allowedFrom' guard
+    await game.call(GameState.MainMenu);
+  } catch (e) {
+    console.error(e.message); // Error: Transition from Paused to MainMenu is not allowed.
+  }
+}
+
+runGame();
+```

package/dist/index.d.mts

@@ -0,0 +1,117 @@
+import { Emitter } from '@axi-engine/utils';
+
+type StateHandler<P = void> = P extends void ? () => void | Promise<void> : (payload: P) => void | Promise<void>;
+interface StateHandlerConfig<T, P = void> {
+    onEnter?: StateHandler<P>;
+    onExit?: () => void | Promise<void>;
+    allowedFrom?: T[];
+}
+type StateHandlerRegistration<T, P = void> = StateHandler<P> | StateHandlerConfig<T, P>;
+
+/**
+ * A minimal, type-safe finite state machine.
+ * It manages states, transitions, and associated lifecycle hooks (`onEnter`, `onExit`).
+ *
+ * @template T The type used for state identifiers (e.g., a string or an enum).
+ * @template P The default payload type for state handlers. Can be overridden per state.
+ * @example
+ * enum PlayerState { Idle, Walk, Run }
+ *
+ * const playerFsm = new StateMachine<PlayerState>();
+ *
+ * playerFsm.register(PlayerState.Idle, () => console.log('Player is now idle.'));
+ * playerFsm.register(PlayerState.Walk, () => console.log('Player is walking.'));
+ *
+ * async function start() {
+ *   await playerFsm.call(PlayerState.Idle);
+ *   await playerFsm.call(PlayerState.Walk);
+ * }
+ */
+declare class StateMachine<T, P = void> {
+    /**
+     * @protected
+     * The internal representation of the current state.
+     */
+    protected _state?: T;
+    /**
+     * @protected
+     * A map storing all registered state configurations.
+     */
+    protected states: Map<T, StateHandlerConfig<T, P> | undefined>;
+    /**
+     * Public emitter that fires an event whenever the state changes.
+     * The event provides the old state, the new state, and the payload.
+     * @see Emitter
+     * @example
+     * fsm.onChange.subscribe((from, to, payload) => {
+     *   console.log(`State transitioned from ${from} to ${to}`);
+     * });
+     */
+    readonly onChange: Emitter<[from?: T | undefined, to?: T | undefined, payload?: P | undefined]>;
+    /**
+     * Gets the current state of the machine.
+     * @returns The current state identifier, or `undefined` if the machine has not been started.
+     */
+    get state(): T | undefined;
+    /**
+     * Registers a state and its associated handler or configuration.
+     * If a handler is already registered for the given state, it will be overwritten.
+     *
+     * @param state The identifier for the state to register.
+     * @param handler A handler function (`onEnter`) or a full configuration object.
+     * @example
+     * // Simple registration
+     * fsm.register(MyState.Idle, () => console.log('Entering Idle'));
+     *
+     * // Advanced registration
+     * fsm.register(MyState.Walking, {
+     *   onEnter: () => console.log('Start walking animation'),
+     *   onExit: () => console.log('Stop walking animation'),
+     *   allowedFrom: [MyState.Idle]
+     * });
+     */
+    register(state: T, handler?: StateHandlerRegistration<T, P>): void;
+    /**
+     * Transitions the machine to a new state.
+     * This method is asynchronous to accommodate async `onEnter` and `onExit` handlers.
+     * It will execute the `onExit` handler of the old state, then the `onEnter` handler of the new state.
+     *
+     * @param newState The identifier of the state to transition to.
+     * @param payload An optional payload to pass to the new state's `onEnter` handler.
+     * @returns A promise that resolves when the transition is complete.
+     * @throws {Error} if the `newState` has not been registered.
+     * @throws {Error} if the transition from the current state to the `newState` is not allowed by the `allowedFrom` rule.
+     * @example
+     * try {
+     *   await fsm.call(PlayerState.Run, { speed: 10 });
+     * } catch (e) {
+     *   console.error('State transition failed:', e.message);
+     * }
+     */
+    call(newState: T, payload?: P): Promise<void>;
+    /**
+     * Removes a single state configuration from the machine.
+     * If the removed state is the currently active one, the machine's state will be reset to `undefined`.
+     *
+     * @param state The identifier of the state to remove.
+     * @returns `true` if the state was found and removed, otherwise `false`.
+     * @example
+     * fsm.register(MyState.Temp, () => {});
+     * // ...
+     * const wasRemoved = fsm.unregister(MyState.Temp);
+     * console.log('Temporary state removed:', wasRemoved);
+     */
+    unregister(state: T): boolean;
+    /**
+     * Removes all registered states and resets the machine to its initial, undefined state.
+     * This does not clear `onChange` subscribers.
+     * @example
+     * fsm.register(MyState.One);
+     * fsm.register(MyState.Two);
+     * // ...
+     * fsm.clear(); // The machine is now empty.
+     */
+    clear(): void;
+}
+
+export { type StateHandler, type StateHandlerConfig, type StateHandlerRegistration, StateMachine };

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+import { Emitter } from '@axi-engine/utils';
+
+type StateHandler<P = void> = P extends void ? () => void | Promise<void> : (payload: P) => void | Promise<void>;
+interface StateHandlerConfig<T, P = void> {
+    onEnter?: StateHandler<P>;
+    onExit?: () => void | Promise<void>;
+    allowedFrom?: T[];
+}
+type StateHandlerRegistration<T, P = void> = StateHandler<P> | StateHandlerConfig<T, P>;
+
+/**
+ * A minimal, type-safe finite state machine.
+ * It manages states, transitions, and associated lifecycle hooks (`onEnter`, `onExit`).
+ *
+ * @template T The type used for state identifiers (e.g., a string or an enum).
+ * @template P The default payload type for state handlers. Can be overridden per state.
+ * @example
+ * enum PlayerState { Idle, Walk, Run }
+ *
+ * const playerFsm = new StateMachine<PlayerState>();
+ *
+ * playerFsm.register(PlayerState.Idle, () => console.log('Player is now idle.'));
+ * playerFsm.register(PlayerState.Walk, () => console.log('Player is walking.'));
+ *
+ * async function start() {
+ *   await playerFsm.call(PlayerState.Idle);
+ *   await playerFsm.call(PlayerState.Walk);
+ * }
+ */
+declare class StateMachine<T, P = void> {
+    /**
+     * @protected
+     * The internal representation of the current state.
+     */
+    protected _state?: T;
+    /**
+     * @protected
+     * A map storing all registered state configurations.
+     */
+    protected states: Map<T, StateHandlerConfig<T, P> | undefined>;
+    /**
+     * Public emitter that fires an event whenever the state changes.
+     * The event provides the old state, the new state, and the payload.
+     * @see Emitter
+     * @example
+     * fsm.onChange.subscribe((from, to, payload) => {
+     *   console.log(`State transitioned from ${from} to ${to}`);
+     * });
+     */
+    readonly onChange: Emitter<[from?: T | undefined, to?: T | undefined, payload?: P | undefined]>;
+    /**
+     * Gets the current state of the machine.
+     * @returns The current state identifier, or `undefined` if the machine has not been started.
+     */
+    get state(): T | undefined;
+    /**
+     * Registers a state and its associated handler or configuration.
+     * If a handler is already registered for the given state, it will be overwritten.
+     *
+     * @param state The identifier for the state to register.
+     * @param handler A handler function (`onEnter`) or a full configuration object.
+     * @example
+     * // Simple registration
+     * fsm.register(MyState.Idle, () => console.log('Entering Idle'));
+     *
+     * // Advanced registration
+     * fsm.register(MyState.Walking, {
+     *   onEnter: () => console.log('Start walking animation'),
+     *   onExit: () => console.log('Stop walking animation'),
+     *   allowedFrom: [MyState.Idle]
+     * });
+     */
+    register(state: T, handler?: StateHandlerRegistration<T, P>): void;
+    /**
+     * Transitions the machine to a new state.
+     * This method is asynchronous to accommodate async `onEnter` and `onExit` handlers.
+     * It will execute the `onExit` handler of the old state, then the `onEnter` handler of the new state.
+     *
+     * @param newState The identifier of the state to transition to.
+     * @param payload An optional payload to pass to the new state's `onEnter` handler.
+     * @returns A promise that resolves when the transition is complete.
+     * @throws {Error} if the `newState` has not been registered.
+     * @throws {Error} if the transition from the current state to the `newState` is not allowed by the `allowedFrom` rule.
+     * @example
+     * try {
+     *   await fsm.call(PlayerState.Run, { speed: 10 });
+     * } catch (e) {
+     *   console.error('State transition failed:', e.message);
+     * }
+     */
+    call(newState: T, payload?: P): Promise<void>;
+    /**
+     * Removes a single state configuration from the machine.
+     * If the removed state is the currently active one, the machine's state will be reset to `undefined`.
+     *
+     * @param state The identifier of the state to remove.
+     * @returns `true` if the state was found and removed, otherwise `false`.
+     * @example
+     * fsm.register(MyState.Temp, () => {});
+     * // ...
+     * const wasRemoved = fsm.unregister(MyState.Temp);
+     * console.log('Temporary state removed:', wasRemoved);
+     */
+    unregister(state: T): boolean;
+    /**
+     * Removes all registered states and resets the machine to its initial, undefined state.
+     * This does not clear `onChange` subscribers.
+     * @example
+     * fsm.register(MyState.One);
+     * fsm.register(MyState.Two);
+     * // ...
+     * fsm.clear(); // The machine is now empty.
+     */
+    clear(): void;
+}
+
+export { type StateHandler, type StateHandlerConfig, type StateHandlerRegistration, StateMachine };

package/dist/index.js

@@ -0,0 +1,144 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  StateMachine: () => StateMachine
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/state-machine.ts
+var import_utils = require("@axi-engine/utils");
+var StateMachine = class {
+  constructor() {
+    /**
+     * @protected
+     * A map storing all registered state configurations.
+     */
+    this.states = /* @__PURE__ */ new Map();
+    /**
+     * Public emitter that fires an event whenever the state changes.
+     * The event provides the old state, the new state, and the payload.
+     * @see Emitter
+     * @example
+     * fsm.onChange.subscribe((from, to, payload) => {
+     *   console.log(`State transitioned from ${from} to ${to}`);
+     * });
+     */
+    this.onChange = new import_utils.Emitter();
+  }
+  /**
+   * Gets the current state of the machine.
+   * @returns The current state identifier, or `undefined` if the machine has not been started.
+   */
+  get state() {
+    return this._state;
+  }
+  /**
+   * Registers a state and its associated handler or configuration.
+   * If a handler is already registered for the given state, it will be overwritten.
+   *
+   * @param state The identifier for the state to register.
+   * @param handler A handler function (`onEnter`) or a full configuration object.
+   * @example
+   * // Simple registration
+   * fsm.register(MyState.Idle, () => console.log('Entering Idle'));
+   *
+   * // Advanced registration
+   * fsm.register(MyState.Walking, {
+   *   onEnter: () => console.log('Start walking animation'),
+   *   onExit: () => console.log('Stop walking animation'),
+   *   allowedFrom: [MyState.Idle]
+   * });
+   */
+  register(state, handler) {
+    if ((0, import_utils.isUndefined)(handler) || typeof handler === "function") {
+      this.states.set(state, { onEnter: handler });
+    } else {
+      this.states.set(state, handler);
+    }
+  }
+  /**
+   * Transitions the machine to a new state.
+   * This method is asynchronous to accommodate async `onEnter` and `onExit` handlers.
+   * It will execute the `onExit` handler of the old state, then the `onEnter` handler of the new state.
+   *
+   * @param newState The identifier of the state to transition to.
+   * @param payload An optional payload to pass to the new state's `onEnter` handler.
+   * @returns A promise that resolves when the transition is complete.
+   * @throws {Error} if the `newState` has not been registered.
+   * @throws {Error} if the transition from the current state to the `newState` is not allowed by the `allowedFrom` rule.
+   * @example
+   * try {
+   *   await fsm.call(PlayerState.Run, { speed: 10 });
+   * } catch (e) {
+   *   console.error('State transition failed:', e.message);
+   * }
+   */
+  async call(newState, payload) {
+    const oldState = this._state;
+    const oldStateConfig = this._state ? this.states.get(this._state) : void 0;
+    const newStateConfig = this.states.get(newState);
+    (0, import_utils.throwIfEmpty)(newStateConfig, `State ${String(newState)} is not registered.`);
+    (0, import_utils.throwIf)(
+      !(0, import_utils.isNullOrUndefined)(newStateConfig.allowedFrom) && !(0, import_utils.isNullOrUndefined)(oldState) && !newStateConfig.allowedFrom.includes(oldState),
+      `Transition from ${String(oldState)} to ${String(newState)} is not allowed.`
+    );
+    await oldStateConfig?.onExit?.();
+    this._state = newState;
+    await newStateConfig.onEnter?.(payload);
+    this.onChange.emit(oldState, newState, payload);
+  }
+  /**
+   * Removes a single state configuration from the machine.
+   * If the removed state is the currently active one, the machine's state will be reset to `undefined`.
+   *
+   * @param state The identifier of the state to remove.
+   * @returns `true` if the state was found and removed, otherwise `false`.
+   * @example
+   * fsm.register(MyState.Temp, () => {});
+   * // ...
+   * const wasRemoved = fsm.unregister(MyState.Temp);
+   * console.log('Temporary state removed:', wasRemoved);
+   */
+  unregister(state) {
+    if (this._state === state) {
+      this._state = void 0;
+    }
+    return this.states.delete(state);
+  }
+  /**
+   * Removes all registered states and resets the machine to its initial, undefined state.
+   * This does not clear `onChange` subscribers.
+   * @example
+   * fsm.register(MyState.One);
+   * fsm.register(MyState.Two);
+   * // ...
+   * fsm.clear(); // The machine is now empty.
+   */
+  clear() {
+    this.states.clear();
+    this._state = void 0;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StateMachine
+});

package/dist/index.mjs

@@ -0,0 +1,117 @@
+// src/state-machine.ts
+import { Emitter, isNullOrUndefined, isUndefined, throwIf, throwIfEmpty } from "@axi-engine/utils";
+var StateMachine = class {
+  constructor() {
+    /**
+     * @protected
+     * A map storing all registered state configurations.
+     */
+    this.states = /* @__PURE__ */ new Map();
+    /**
+     * Public emitter that fires an event whenever the state changes.
+     * The event provides the old state, the new state, and the payload.
+     * @see Emitter
+     * @example
+     * fsm.onChange.subscribe((from, to, payload) => {
+     *   console.log(`State transitioned from ${from} to ${to}`);
+     * });
+     */
+    this.onChange = new Emitter();
+  }
+  /**
+   * Gets the current state of the machine.
+   * @returns The current state identifier, or `undefined` if the machine has not been started.
+   */
+  get state() {
+    return this._state;
+  }
+  /**
+   * Registers a state and its associated handler or configuration.
+   * If a handler is already registered for the given state, it will be overwritten.
+   *
+   * @param state The identifier for the state to register.
+   * @param handler A handler function (`onEnter`) or a full configuration object.
+   * @example
+   * // Simple registration
+   * fsm.register(MyState.Idle, () => console.log('Entering Idle'));
+   *
+   * // Advanced registration
+   * fsm.register(MyState.Walking, {
+   *   onEnter: () => console.log('Start walking animation'),
+   *   onExit: () => console.log('Stop walking animation'),
+   *   allowedFrom: [MyState.Idle]
+   * });
+   */
+  register(state, handler) {
+    if (isUndefined(handler) || typeof handler === "function") {
+      this.states.set(state, { onEnter: handler });
+    } else {
+      this.states.set(state, handler);
+    }
+  }
+  /**
+   * Transitions the machine to a new state.
+   * This method is asynchronous to accommodate async `onEnter` and `onExit` handlers.
+   * It will execute the `onExit` handler of the old state, then the `onEnter` handler of the new state.
+   *
+   * @param newState The identifier of the state to transition to.
+   * @param payload An optional payload to pass to the new state's `onEnter` handler.
+   * @returns A promise that resolves when the transition is complete.
+   * @throws {Error} if the `newState` has not been registered.
+   * @throws {Error} if the transition from the current state to the `newState` is not allowed by the `allowedFrom` rule.
+   * @example
+   * try {
+   *   await fsm.call(PlayerState.Run, { speed: 10 });
+   * } catch (e) {
+   *   console.error('State transition failed:', e.message);
+   * }
+   */
+  async call(newState, payload) {
+    const oldState = this._state;
+    const oldStateConfig = this._state ? this.states.get(this._state) : void 0;
+    const newStateConfig = this.states.get(newState);
+    throwIfEmpty(newStateConfig, `State ${String(newState)} is not registered.`);
+    throwIf(
+      !isNullOrUndefined(newStateConfig.allowedFrom) && !isNullOrUndefined(oldState) && !newStateConfig.allowedFrom.includes(oldState),
+      `Transition from ${String(oldState)} to ${String(newState)} is not allowed.`
+    );
+    await oldStateConfig?.onExit?.();
+    this._state = newState;
+    await newStateConfig.onEnter?.(payload);
+    this.onChange.emit(oldState, newState, payload);
+  }
+  /**
+   * Removes a single state configuration from the machine.
+   * If the removed state is the currently active one, the machine's state will be reset to `undefined`.
+   *
+   * @param state The identifier of the state to remove.
+   * @returns `true` if the state was found and removed, otherwise `false`.
+   * @example
+   * fsm.register(MyState.Temp, () => {});
+   * // ...
+   * const wasRemoved = fsm.unregister(MyState.Temp);
+   * console.log('Temporary state removed:', wasRemoved);
+   */
+  unregister(state) {
+    if (this._state === state) {
+      this._state = void 0;
+    }
+    return this.states.delete(state);
+  }
+  /**
+   * Removes all registered states and resets the machine to its initial, undefined state.
+   * This does not clear `onChange` subscribers.
+   * @example
+   * fsm.register(MyState.One);
+   * fsm.register(MyState.Two);
+   * // ...
+   * fsm.clear(); // The machine is now empty.
+   */
+  clear() {
+    this.states.clear();
+    this._state = void 0;
+  }
+};
+export {
+  StateMachine
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@axi-engine/states",
+  "version": "0.1.0",
+  "description": "A minimal, type-safe state machine for the Axi Engine, designed for managing game logic and component states with a simple API.",
+  "license": "MIT",
+  "keywords": [
+    "axi-engine",
+    "typescript",
+    "gamedev",
+    "game-development",
+    "game-engine",
+    "state-machine",
+    "finite-state-machine",
+    "fsm",
+    "state-management",
+    "events"
+  ],
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "docs": "typedoc src/index.ts --out docs/api --options ../../typedoc.json",
+    "test": "echo 'No tests yet for @axi-engine/states'"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@axi-engine/utils": "^0.1.5"
+  }
+}