@axi-engine/states 0.3.1 → 0.3.3

package/README.md

@@ -149,9 +149,9 @@ await gameState.call(GameState.Paused); // Error: Transition from MainMenu to Pa
 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 });
+const unsubscribe = gameState.onChange.subscribe(event => {
+  const fromState = event.from !== undefined ? GameState[event.from] : 'Start';
+  console.log(`State changed from ${fromState} to ${GameState[event.to]}`, { payload: event.payload });
 });
 
 await gameState.call(GameState.MainMenu);
@@ -176,9 +176,9 @@ enum GameState {
 // --- 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.onChange.subscribe(e => {
+  const fromState = e.from !== undefined ? GameState[e.from] : 'Start';
+  console.log(`[SYSTEM] Transition: ${fromState} -> ${GameState[e.to]}`);
 });
 
 game.register(GameState.MainMenu, {

package/dist/index.d.mts

@@ -1,9 +1,32 @@
 import { Emitter } from '@axijs/emitter';
 
+/**
+ * Represents a lifecycle handler function for a state.
+ * If a payload type `P` is provided and is not `void`, the handler receives the payload.
+ * Supports both synchronous and asynchronous execution.
+ *
+ * @template P The type of the payload passed to the handler.
+ */
 type StateHandler<P = void> = P extends void ? () => void | Promise<void> : (payload: P) => void | Promise<void>;
+/**
+ * Configuration object for defining a state's behavior and transition rules.
+ *
+ * @template T The type used for state identifiers.
+ * @template P The type of the payload passed to the `onEnter` handler.
+ */
 interface StateHandlerConfig<T, P = void> {
+    /**
+     * Hook executed when transitioning into this state.
+     */
     onEnter?: StateHandler<P>;
+    /**
+     * Hook executed when transitioning out of this state.
+     */
     onExit?: () => void | Promise<void>;
+    /**
+     * Optional list of states from which a transition to this state is permitted.
+     * If undefined, the state can be entered from any state.
+     */
     allowedFrom?: T[];
 }
 type StateHandlerRegistration<T, P = void> = StateHandler<P> | StateHandlerConfig<T, P>;
@@ -43,11 +66,15 @@ declare class StateMachine<T, P = void> {
      * 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}`);
+     * fsm.onChange.subscribe(e => {
+     *   console.log(`State transitioned from ${e.from} to ${e.to}`);
      * });
      */
-    readonly onChange: Emitter<[from?: T | undefined, to?: T | undefined, payload?: P | undefined]>;
+    readonly onChange: Emitter<{
+        from?: T;
+        to?: T;
+        payload?: P;
+    }>;
     /**
      * Gets the current state of the machine.
      * @returns The current state identifier, or `undefined` if the machine has not been started.

package/dist/index.d.ts

@@ -1,9 +1,32 @@
 import { Emitter } from '@axijs/emitter';
 
+/**
+ * Represents a lifecycle handler function for a state.
+ * If a payload type `P` is provided and is not `void`, the handler receives the payload.
+ * Supports both synchronous and asynchronous execution.
+ *
+ * @template P The type of the payload passed to the handler.
+ */
 type StateHandler<P = void> = P extends void ? () => void | Promise<void> : (payload: P) => void | Promise<void>;
+/**
+ * Configuration object for defining a state's behavior and transition rules.
+ *
+ * @template T The type used for state identifiers.
+ * @template P The type of the payload passed to the `onEnter` handler.
+ */
 interface StateHandlerConfig<T, P = void> {
+    /**
+     * Hook executed when transitioning into this state.
+     */
     onEnter?: StateHandler<P>;
+    /**
+     * Hook executed when transitioning out of this state.
+     */
     onExit?: () => void | Promise<void>;
+    /**
+     * Optional list of states from which a transition to this state is permitted.
+     * If undefined, the state can be entered from any state.
+     */
     allowedFrom?: T[];
 }
 type StateHandlerRegistration<T, P = void> = StateHandler<P> | StateHandlerConfig<T, P>;
@@ -43,11 +66,15 @@ declare class StateMachine<T, P = void> {
      * 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}`);
+     * fsm.onChange.subscribe(e => {
+     *   console.log(`State transitioned from ${e.from} to ${e.to}`);
      * });
      */
-    readonly onChange: Emitter<[from?: T | undefined, to?: T | undefined, payload?: P | undefined]>;
+    readonly onChange: Emitter<{
+        from?: T;
+        to?: T;
+        payload?: P;
+    }>;
     /**
      * Gets the current state of the machine.
      * @returns The current state identifier, or `undefined` if the machine has not been started.

package/dist/index.js

@@ -43,8 +43,8 @@ var StateMachine = class {
    * 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}`);
+   * fsm.onChange.subscribe(e => {
+   *   console.log(`State transitioned from ${e.from} to ${e.to}`);
    * });
    */
   onChange = new import_emitter.Emitter();
@@ -98,7 +98,7 @@ var StateMachine = class {
    */
   async call(newState, payload) {
     const oldState = this._state;
-    const oldStateConfig = this._state ? this.states.get(this._state) : void 0;
+    const oldStateConfig = (0, import_ensure.isUndefined)(this._state) ? void 0 : this.states.get(this._state);
     const newStateConfig = this.states.get(newState);
     (0, import_ensure.throwIfEmpty)(newStateConfig, `State ${String(newState)} is not registered.`);
     (0, import_ensure.throwIf)(
@@ -108,7 +108,7 @@ var StateMachine = class {
     await oldStateConfig?.onExit?.();
     this._state = newState;
     await newStateConfig.onEnter?.(payload);
-    this.onChange.emit(oldState, newState, payload);
+    this.onChange.emit({ from: oldState, to: newState, payload });
   }
   /**
    * Removes a single state configuration from the machine.

package/dist/index.mjs

@@ -17,8 +17,8 @@ var StateMachine = class {
    * 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}`);
+   * fsm.onChange.subscribe(e => {
+   *   console.log(`State transitioned from ${e.from} to ${e.to}`);
    * });
    */
   onChange = new Emitter();
@@ -72,7 +72,7 @@ var StateMachine = class {
    */
   async call(newState, payload) {
     const oldState = this._state;
-    const oldStateConfig = this._state ? this.states.get(this._state) : void 0;
+    const oldStateConfig = isUndefined(this._state) ? void 0 : this.states.get(this._state);
     const newStateConfig = this.states.get(newState);
     throwIfEmpty(newStateConfig, `State ${String(newState)} is not registered.`);
     throwIf(
@@ -82,7 +82,7 @@ var StateMachine = class {
     await oldStateConfig?.onExit?.();
     this._state = newState;
     await newStateConfig.onEnter?.(payload);
-    this.onChange.emit(oldState, newState, payload);
+    this.onChange.emit({ from: oldState, to: newState, payload });
   }
   /**
    * Removes a single state configuration from the machine.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axi-engine/states",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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",
   "repository": {
@@ -32,15 +32,16 @@
   },
   "scripts": {
     "build": "tsup",
-    "docs": "typedoc src/index.ts --out docs/api --options ../../typedoc.json",
-    "test": "echo 'No tests yet for @axi-engine/states'"
+    "prebuild": "npm test",
+    "test": "vitest run",
+    "docs": "typedoc src/index.ts --out docs/api --options ../../typedoc.json"
   },
   "files": [
     "dist"
   ],
   "peerDependencies": {
-    "@axijs/emitter": "^1.0.0",
-    "@axijs/ensure": "^1.0.0",
+    "@axijs/emitter": "^1.1.1",
+    "@axijs/ensure": "^1.0.2",
     "@axi-engine/utils": "^0.3.0"
   }
 }