@hkdigital/lib-core 0.4.24 → 0.4.26

package/dist/state/machines/finite-state-machine/FiniteStateMachine.svelte.js

@@ -4,7 +4,11 @@
  * @see {@link https://runed.dev/docs/utilities/finite-state-machine}
  */
 
-/** @typedef {import('./typedef.js').StateTransitionMetadata} StateTransitionMetadata */
+import { isTestEnv } from '../../../util/env.js';
+import EventEmitter from '../../../generic/events/classes/EventEmitter.js';
+import { ENTER, EXIT } from './constants.js';
+
+/** @typedef {import('./typedef.js').TransitionData} TransitionData */
 /** @typedef {import('./typedef.js').OnEnterCallback} OnEnterCallback */
 /** @typedef {import('./typedef.js').OnExitCallback} OnExitCallback */
 
@@ -25,9 +29,9 @@ export function isLifecycleFnMeta(meta) {
 }
 
 /**
- * Defines a Finite State Machine
+ * Defines a Finite State Machine that extends EventEmitter
  */
-export default class FiniteStateMachine {
+export default class FiniteStateMachine extends EventEmitter {
   #current = $state();
   states;
   #timeout = {};
@@ -38,6 +42,9 @@ export default class FiniteStateMachine {
   /** @type {OnExitCallback | null} */
   onexit = null;
 
+  /** @type {boolean} */
+  #enableConsoleWarnings = !isTestEnv;
+
   /**
    * Constructor
    *
@@ -45,16 +52,22 @@ export default class FiniteStateMachine {
    * @param {{ [key: string]: { [key: string]: (string|((...args: any[])=>void)) } }} states
    */
   constructor(initial, states) {
+    super();
     this.#current = initial;
     this.states = states;
 
     // synthetically trigger _enter for the initial state.
-    this.#dispatch('_enter', {
+    const initialTransitionData = {
       from: null,
       to: initial,
       event: null,
       args: []
-    });
+    };
+
+    this.#executeAction('_enter', initialTransitionData);
+
+    // Emit ENTER event for external listeners for initial state
+    this.emit(ENTER, { state: initial, transition: initialTransitionData });
   }
 
   /**
@@ -65,50 +78,66 @@ export default class FiniteStateMachine {
    * @param {any[]} [args]
    */
   #transition(newState, event, args) {
-    /** @type {StateTransitionMetadata} */
-    const metadata = { from: this.#current, to: newState, event, args };
+    /** @type {TransitionData} */
+    const transition = { from: this.#current, to: newState, event, args };
 
     // Call onexit callback before leaving current state
-    this.onexit?.(this.#current, metadata);
-    
-    this.#dispatch('_exit', metadata);
+    this.onexit?.(this.#current, transition);
+
+    // Emit EXIT event for external listeners
+    this.emit(EXIT, { state: this.#current, transition });
+
+    this.#executeAction('_exit', transition);
     this.#current = newState;
-    this.#dispatch('_enter', metadata);
-    
+    this.#executeAction('_enter', transition);
+
+    // Emit ENTER event for external listeners
+    this.emit(ENTER, { state: newState, transition });
+
     // Call onenter callback after state change
-    this.onenter?.(newState, metadata);
+    this.onenter?.(newState, transition);
   }
 
   /**
-   * Dispatch an event
+   * Execute an action for the given event
    *
    * @param {string} event
    * @param {any} args
    */
-  #dispatch(event, ...args) {
+  #executeAction(event, ...args) {
     const action =
       this.states[this.#current]?.[event] ?? this.states['*']?.[event];
+
     if (action instanceof Function) {
-      if (event === '_enter' || event === '_exit') {
-        if (isLifecycleFnMeta(args[0])) {
-          action(args[0]);
-        } else {
+      switch (event) {
+        // Internal lifecycle events
+        case ENTER:
+        case EXIT:
+          if (isLifecycleFnMeta(args[0])) {
+            return action(args[0]);
+          } else {
+            throw new Error(`Invalid transition data passed to lifecycle function`);
+          }
+
+        // Normal state events
+        default:
+          return action(...args);
+      }
+    } else if (typeof action === 'string') {
+      // No function execution => just return target state
+      return action;
+    } else {
+      // No action found - only warn for non-lifecycle events
+      if (event !== ENTER && event !== EXIT) {
+        if (this.#enableConsoleWarnings) {
           console.warn(
-            'Invalid metadata passed to lifecycle function of the FSM.'
+            'No action defined for event',
+            event,
+            'in state',
+            this.#current
           );
         }
-      } else {
-        return action(...args);
       }
-    } else if (typeof action === 'string') {
-      return action;
-    } else if (event !== '_enter' && event !== '_exit') {
-      console.warn(
-        'No action defined for event',
-        event,
-        'in state',
-        this.#current
-      );
     }
   }
   /**
@@ -118,7 +147,8 @@ export default class FiniteStateMachine {
    * @param {any[]} args
    */
   send(event, ...args) {
-    const newState = this.#dispatch(event, ...args);
+    const newState = this.#executeAction(event, ...args);
+
     if (newState && newState !== this.#current) {
       this.#transition(newState, event, args);
     }

package/dist/state/machines/finite-state-machine/README.md

@@ -39,7 +39,7 @@ console.log(machine.current); // 'paused'
 ## Constructor
 
 ```javascript
-new FiniteStateMachine(initialState, states)
+new FiniteStateMachine(initialState, states);
 ```
 
 - `initialState`: The starting state (string)
@@ -56,16 +56,16 @@ Each state can define:
 ```javascript
 const machine = new FiniteStateMachine('idle', {
   idle: {
-    _enter: (metadata) => {
+    _enter: (transition) => {
       console.log('Entered idle state');
     },
-    _exit: (metadata) => {
+    _exit: (transition) => {
       console.log('Leaving idle state');
     },
     start: 'running'
   },
   running: {
-    _enter: (metadata) => {
+    _enter: (transition) => {
       console.log('Started running');
     },
     stop: 'idle'
@@ -73,14 +73,14 @@ const machine = new FiniteStateMachine('idle', {
 });
 ```
 
-## Callback Metadata
+## Callback TransitionData
 
-Enter and exit callbacks receive metadata about the transition:
+Enter and exit callbacks receive transition data about the state change:
 
 ```javascript
-/** @typedef {import('./typedef.js').StateTransitionMetadata} StateTransitionMetadata */
+/** @typedef {import('./typedef.js').TransitionData} TransitionData */
 
-// Metadata structure:
+// TransitionData structure:
 {
   from: 'previousState',    // State being exited
   to: 'newState',          // State being entered
@@ -94,18 +94,18 @@ Enter and exit callbacks receive metadata about the transition:
 For better type safety, import the type definitions:
 
 ```javascript
-/** @typedef {import('./typedef.js').StateTransitionMetadata} StateTransitionMetadata */
+/** @typedef {import('./typedef.js').TransitionData} TransitionData */
 /** @typedef {import('./typedef.js').OnEnterCallback} OnEnterCallback */
 /** @typedef {import('./typedef.js').OnExitCallback} OnExitCallback */
 
 /** @type {OnEnterCallback} */
-const handleEnter = (state, metadata) => {
-  console.log(`Entering ${state} from ${metadata.from}`);
+const handleEnter = (currentState, transition) => {
+  console.log(`Entering ${currentState} from ${transition.from}`);
 };
 
 /** @type {OnExitCallback} */
-const handleExit = (state, metadata) => {
-  console.log(`Leaving ${state} to ${metadata.to}`);
+const handleExit = (currentState, transition) => {
+  console.log(`Leaving ${currentState} to ${transition.to}`);
 };
 
 machine.onenter = handleEnter;
@@ -160,7 +160,7 @@ const machine = new FiniteStateMachine('idle', {
     resume: 'running'
   },
   '*': {
-    reset: 'idle',  // Available from any state
+    reset: 'idle', // Available from any state
     error: 'error'
   },
   error: {
@@ -171,7 +171,7 @@ const machine = new FiniteStateMachine('idle', {
 
 ### Same-State Transitions
 
-Same-state transitions (e.g., `idle → idle`) do NOT trigger enter/exit 
+Same-state transitions (e.g., `idle → idle`) do NOT trigger enter/exit
 callbacks. The state remains unchanged.
 
 ```javascript
@@ -209,8 +209,8 @@ const machine = new FiniteStateMachine('idle', {
   error: { retry: 'loading', reset: 'idle' }
 });
 
-machine.onexit = (state, metadata) => {
-  switch (state) {
+machine.onexit = (currentState, transition) => {
+  switch (currentState) {
     case 'loading':
       console.log('Leaving loading state...');
       // Cancel ongoing requests
@@ -224,8 +224,8 @@ machine.onexit = (state, metadata) => {
   }
 };
 
-machine.onenter = (state, metadata) => {
-  switch (state) {
+machine.onenter = (currentState, transition) => {
+  switch (currentState) {
     case 'loading':
       console.log('Started loading...');
       showSpinner();
@@ -236,7 +236,7 @@ machine.onenter = (state, metadata) => {
       break;
     case 'error':
       console.log('Loading failed');
-      showError(metadata.args[0]);
+      showError(transition.args[0]);
       break;
   }
 };
@@ -247,7 +247,7 @@ machine.onenter = (state, metadata) => {
 The callbacks are executed in this specific order during state transitions:
 
 1. **`onexit`** - Called before leaving current state
-2. **`_exit`** - Individual state exit callback  
+2. **`_exit`** - Individual state exit callback
 3. **`_enter`** - Individual state enter callback
 4. **`onenter`** - Called after entering new state
 
@@ -264,11 +264,11 @@ const machine = new FiniteStateMachine('idle', {
   }
 });
 
-machine.onexit = (state) => console.log(`3. onexit ${state}`);
-machine.onenter = (state) => console.log(`6. onenter ${state}`);
+machine.onexit = (currentState) => console.log(`3. onexit ${currentState}`);
+machine.onenter = (currentState) => console.log(`6. onenter ${currentState}`);
 
 // Initial state triggers _enter and onenter
-// Output: 
+// Output:
 // 2. idle _enter
 // 6. onenter idle
 
@@ -276,7 +276,7 @@ machine.send('start');
 // Output:
 // 3. onexit idle
 // 4. idle _exit
-// 5. loading _enter  
+// 5. loading _enter
 // 6. onenter loading
 ```
 
@@ -294,6 +294,7 @@ When using FiniteStateMachine with Svelte's reactive derived state, use this pat
 ### Pattern: Separate onenter from Reactive Monitoring
 
 **✅ Use `onexit` and `onenter` for immediate state actions:**
+
 ```javascript
 const machine = new FiniteStateMachine('idle', {
   idle: { start: 'loading' },
@@ -312,8 +313,8 @@ machine.onexit = (state) => {
   }
 };
 
-machine.onenter = (state) => {
-  switch (state) {
+machine.onenter = (label) => {
+  switch (label) {
     case 'loading':
       this.#startProcess(); // Start async process immediately
       break;
@@ -326,6 +327,7 @@ machine.onenter = (state) => {
 ```
 
 **✅ Use `$effect` for reactive state monitoring:**
+
 ```javascript
 // Monitor derived/computed values and trigger transitions when conditions are met
 $effect(() => {
@@ -341,8 +343,8 @@ $effect(() => {
 ### Why This Pattern?
 
 - **`onexit`**: Handles cleanup and teardown when leaving states
-- **`onenter`**: Handles setup and initialization when entering states  
-- **`$effect`**: Handles reactive monitoring of derived/computed values over time  
+- **`onenter`**: Handles setup and initialization when entering states
+- **`$effect`**: Handles reactive monitoring of derived/computed values over time
 - **Avoids timing issues**: Doesn't check completion status immediately on state entry
 - **Leverages Svelte reactivity**: Automatically responds to changes in reactive variables
 - **Clean separation**: State machine handles discrete transitions, effects handle continuous monitoring
@@ -365,9 +367,9 @@ export default class TaskProcessor {
     finished: { reset: 'idle' },
     failed: { retry: 'processing', reset: 'idle' }
   });
-  
+
   #tasks = $state([]);
-  
+
   // Derived progress calculation
   #progress = $derived.by(() => {
     let completed = 0;
@@ -379,8 +381,8 @@ export default class TaskProcessor {
 
   constructor() {
     // onexit: Handle cleanup when leaving states
-    this.#machine.onexit = (state) => {
-      switch (state) {
+    this.#machine.onexit = (currentState) => {
+      switch (currentState) {
         case 'processing':
           this.#cancelTasks(); // Cancel ongoing tasks if interrupted
           break;
@@ -388,8 +390,8 @@ export default class TaskProcessor {
     };
 
     // onenter: Handle immediate state actions
-    this.#machine.onenter = (state) => {
-      switch (state) {
+    this.#machine.onenter = (currentState) => {
+      switch (currentState) {
         case 'processing':
           this.#startAllTasks(); // Start processing immediately
           break;
@@ -397,7 +399,7 @@ export default class TaskProcessor {
           this.#notifyComplete(); // Cleanup/notify when done
           break;
       }
-      this.state = state;
+      this.state = currentState;
     };
 
     // $effect: Monitor reactive completion
@@ -419,22 +421,22 @@ export default class TaskProcessor {
 // Component.svelte
 <script>
   import { FiniteStateMachine } from '$lib/state/classes.js';
-  
+
   const machine = new FiniteStateMachine('idle', {
     idle: { start: 'loading' },
     loading: { complete: 'loaded', error: 'error' },
     loaded: { reset: 'idle' },
     error: { retry: 'loading', reset: 'idle' }
   });
-  
+
   // Reactive state updates
   $effect(() => {
     console.log('State changed to:', machine.current);
   });
-  
+
   // Handle state-specific actions
-  machine.onexit = (state) => {
-    switch (state) {
+  machine.onexit = (currentState) => {
+    switch (currentState) {
       case 'loading':
         // Cancel any ongoing requests
         cancelRequests();
@@ -442,8 +444,8 @@ export default class TaskProcessor {
     }
   };
 
-  machine.onenter = (state) => {
-    switch (state) {
+  machine.onenter = (currentState) => {
+    switch (currentState) {
       case 'loading':
         loadData();
         break;
@@ -475,7 +477,7 @@ console.log(machine.current); // Still 'idle'
 
 ## Best Practices
 
-1. **Clear state names**: Use descriptive state names like `loading`, `error`, 
+1. **Clear state names**: Use descriptive state names like `loading`, `error`,
    `authenticated` rather than generic ones
 2. **Minimal state count**: Keep the number of states manageable
 3. **Explicit transitions**: Define all valid transitions explicitly
@@ -524,7 +526,7 @@ const auth = new FiniteStateMachine('anonymous', {
     failure: 'anonymous'
   },
   authenticated: {
-    _enter: (meta) => console.log('Welcome!'),
+    _enter: (transition) => console.log('Welcome!'),
     logout: 'anonymous',
     expire: 'anonymous'
   }
@@ -542,4 +544,4 @@ The state machine includes comprehensive tests covering:
 - Immediate state access
 - Callback execution order
 
-See `FiniteStateMachine.test.js` for detailed examples.
+See `FiniteStateMachine.test.js` for detailed examples.

package/dist/state/machines/finite-state-machine/constants.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Constants for FiniteStateMachine events
+ */
+/**
+ * Event emitted when entering a state
+ * @type {string}
+ */
+export const ENTER: string;
+/**
+ * Event emitted when exiting a state
+ * @type {string}
+ */
+export const EXIT: string;

package/dist/state/machines/finite-state-machine/constants.js

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Constants for FiniteStateMachine events
+ */
+
+/**
+ * Event emitted when entering a state
+ * @type {string}
+ */
+export const ENTER = 'enter';
+
+/**
+ * Event emitted when exiting a state
+ * @type {string}
+ */
+export const EXIT = 'exit';

package/dist/state/machines/finite-state-machine/index.d.ts

@@ -1 +1,2 @@
 export { default as FiniteStateMachine } from "./FiniteStateMachine.svelte.js";
+export * from "./constants.js";

package/dist/state/machines/finite-state-machine/index.js

@@ -1 +1,2 @@
 export { default as FiniteStateMachine } from './FiniteStateMachine.svelte.js';
+export * from './constants.js';

package/dist/state/machines/finite-state-machine/typedef.d.ts

@@ -1,7 +1,7 @@
 /**
  * Metadata object passed to state transition callbacks
  */
-export type StateTransitionMetadata = {
+export type TransitionData = {
     /**
      * - The state being exited
      */
@@ -22,8 +22,8 @@ export type StateTransitionMetadata = {
 /**
  * Callback function called when entering a state
  */
-export type OnEnterCallback = (arg0: string, arg1: StateTransitionMetadata) => void;
+export type OnEnterCallback = (currentState: string, transition: TransitionData) => void;
 /**
  * Callback function called when exiting a state
  */
-export type OnExitCallback = (arg0: string, arg1: StateTransitionMetadata) => void;
+export type OnExitCallback = (currentState: string, transition: TransitionData) => void;

package/dist/state/machines/finite-state-machine/typedef.js

@@ -4,25 +4,31 @@
 
 /**
  * Metadata object passed to state transition callbacks
- * 
- * @typedef {object} StateTransitionMetadata
+ *
+ * @typedef {object} TransitionData
  * @property {string} from - The state being exited
- * @property {string} to - The state being entered  
+ * @property {string} to - The state being entered
  * @property {string} event - The event that triggered the transition
  * @property {any[]} args - Arguments passed to the send() method
  */
 
-/**
- * Callback function called when entering a state
- * 
- * @typedef {function(string, StateTransitionMetadata): void} OnEnterCallback
- */
+  /**
+   * Callback function called when entering a state
+   *
+   * @callback OnEnterCallback
+   * @param {string} currentState - The state being entered
+   * @param {TransitionData} transition - Details about the transition
+   * @returns {void}
+   */
 
-/**
- * Callback function called when exiting a state
- * 
- * @typedef {function(string, StateTransitionMetadata): void} OnExitCallback
- */
+  /**
+   * Callback function called when exiting a state
+   *
+   * @callback OnExitCallback
+   * @param {string} currentState - The state being exited
+   * @param {TransitionData} transition - Details about the transition
+   * @returns {void}
+   */
 
-// Export types for external use (this is just for JSDoc, no actual exports needed)
-export {};
+// Export types for JSdoc
+export {};

package/dist/state/machines/loading-state-machine/LoadingStateMachine.svelte.d.ts

@@ -5,6 +5,18 @@ export default class LoadingStateMachine extends FiniteStateMachine {
     constructor();
     /** The last error */
     get error(): Error;
+    /**
+     * Transition to timeout state
+     * - Only valid when currently loading
+     * - Useful for external timeout management
+     */
+    doTimeout(): void;
+    /**
+     * Transition to cancelled state
+     * - Only valid when currently loading
+     * - Useful for external cancellation management
+     */
+    doCancel(): void;
     #private;
 }
 import FiniteStateMachine from '../finite-state-machine/FiniteStateMachine.svelte.js';

package/dist/state/machines/loading-state-machine/LoadingStateMachine.svelte.js

@@ -10,6 +10,7 @@ import {
   STATE_LOADED,
   STATE_CANCELLED,
   STATE_ERROR,
+  STATE_TIMEOUT,
 
   // > Signals
   INITIAL,
@@ -17,7 +18,8 @@ import {
   CANCEL,
   ERROR,
   LOADED,
-  UNLOAD
+  UNLOAD,
+  TIMEOUT
 } from './constants.js';
 
 /**
@@ -41,7 +43,8 @@ export default class LoadingStateMachine extends FiniteStateMachine {
         // },
         [CANCEL]: STATE_CANCELLED,
         [ERROR]: STATE_ERROR,
-        [LOADED]: STATE_LOADED
+        [LOADED]: STATE_LOADED,
+        [TIMEOUT]: STATE_TIMEOUT
       },
       [STATE_LOADED]: {
         // _enter: () => {
@@ -58,6 +61,10 @@ export default class LoadingStateMachine extends FiniteStateMachine {
         [LOAD]: STATE_LOADING,
         [UNLOAD]: STATE_UNLOADING
       },
+      [STATE_TIMEOUT]: {
+        [LOAD]: STATE_LOADING,
+        [UNLOAD]: STATE_UNLOADING
+      },
       [STATE_ERROR]: {
         _enter: ({ /*from, to, event,*/ args }) => {
           if (args[0] instanceof Error) {
@@ -86,4 +93,22 @@ export default class LoadingStateMachine extends FiniteStateMachine {
   get error() {
     return this.#error;
   }
+
+  /**
+   * Transition to timeout state
+   * - Only valid when currently loading
+   * - Useful for external timeout management
+   */
+  doTimeout() {
+    this.send(TIMEOUT);
+  }
+
+  /**
+   * Transition to cancelled state
+   * - Only valid when currently loading
+   * - Useful for external cancellation management
+   */
+  doCancel() {
+    this.send(CANCEL);
+  }
 }