@hkdigital/lib-core 0.4.24 → 0.4.25

package/dist/network/states/NetworkLoader.svelte.js

@@ -13,7 +13,8 @@ import {
   ERROR,
   LOADED,
   UNLOAD,
-  INITIAL
+  INITIAL,
+  CANCEL
 } from '../../state/machines.js';
 
 import * as expect from '../../util/expect.js';
@@ -129,7 +130,10 @@ export default class NetworkLoader {
         case STATE_CANCELLED:
           {
             // console.log('NetworkLoader:cancelled');
-            // TODO
+            if (this._abortLoading) {
+              this._abortLoading();
+              this._abortLoading = null;
+            }
           }
           break;
 
@@ -157,6 +161,15 @@ export default class NetworkLoader {
     this._state.send(UNLOAD);
   }
 
+  /**
+   * Abort the current loading operation
+   * - Only works when in STATE_LOADING
+   * - Aborts network requests and transitions to STATE_CANCELLED
+   */
+  doAbort() {
+    this._state.send(CANCEL);
+  }
+
   /**
    * Get network data size in bytes
    * - Info comes from the content length response header

package/dist/services/service-base/ServiceBase.d.ts

@@ -156,36 +156,40 @@ export class ServiceBase extends EventEmitter {
     /**
      * Set the service state and emit event
      *
-     * @private
+     * @protected
+     *
      * @param {ServiceState} newState - New state value
      * @emits {StateChangeEvent} EVENT_STATE_CHANGED
      */
-    private _setState;
+    protected _setState(newState: ServiceState): void;
     /**
      * Set the service target state and emit event
      *
-     * @private
+     * @protected
+     *
      * @param {ServiceState} newTargetState - New target state value
      * @emits {TargetStateChangeEvent} EVENT_TARGET_STATE_CHANGED
      */
-    private _setTargetState;
+    protected _setTargetState(newTargetState: ServiceState): void;
     /**
      * Set the health status and emit event if changed
      *
-     * @private
+     * @protected
+     *
      * @param {boolean} healthy - New health status
      * @emits {HealthChangeEvent} EVENT_HEALTH_CHANGED
      */
-    private _setHealthy;
+    protected _setHealthy(healthy: boolean): void;
     /**
      * Set error state and emit error event
      *
-     * @private
+     * @protected
+     *
      * @param {string} operation - Operation that failed
      * @param {Error} error - Error that occurred
      * @emits {ServiceErrorEvent} EVENT_ERROR
      */
-    private _setError;
+    protected _setError(operation: string, error: Error): void;
     #private;
 }
 export default ServiceBase;

package/dist/services/service-base/ServiceBase.js

@@ -447,12 +447,11 @@ export class ServiceBase extends EventEmitter {
     return {};
   }
 
-  // Private methods
-
   /**
    * Set the service state and emit event
    *
-   * @private
+   * @protected
+   *
    * @param {ServiceState} newState - New state value
    * @emits {StateChangeEvent} EVENT_STATE_CHANGED
    */
@@ -473,7 +472,8 @@ export class ServiceBase extends EventEmitter {
   /**
    * Set the service target state and emit event
    *
-   * @private
+   * @protected
+   *
    * @param {ServiceState} newTargetState - New target state value
    * @emits {TargetStateChangeEvent} EVENT_TARGET_STATE_CHANGED
    */
@@ -493,7 +493,8 @@ export class ServiceBase extends EventEmitter {
   /**
    * Set the health status and emit event if changed
    *
-   * @private
+   * @protected
+   *
    * @param {boolean} healthy - New health status
    * @emits {HealthChangeEvent} EVENT_HEALTH_CHANGED
    */
@@ -515,7 +516,8 @@ export class ServiceBase extends EventEmitter {
   /**
    * Set error state and emit error event
    *
-   * @private
+   * @protected
+   *
    * @param {string} operation - Operation that failed
    * @param {Error} error - Error that occurred
    * @emits {ServiceErrorEvent} EVENT_ERROR

package/dist/state/machines/finite-state-machine/FiniteStateMachine.svelte.d.ts

@@ -1,8 +1,3 @@
-/**
- * Initial code borrowed from:
- *
- * @see {@link https://runed.dev/docs/utilities/finite-state-machine}
- */
 /** @typedef {import('./typedef.js').StateTransitionMetadata} StateTransitionMetadata */
 /** @typedef {import('./typedef.js').OnEnterCallback} OnEnterCallback */
 /** @typedef {import('./typedef.js').OnExitCallback} OnExitCallback */
@@ -13,9 +8,9 @@
  */
 export function isLifecycleFnMeta(meta: any): boolean;
 /**
- * Defines a Finite State Machine
+ * Defines a Finite State Machine that extends EventEmitter
  */
-export default class FiniteStateMachine {
+export default class FiniteStateMachine extends EventEmitter {
     /**
      * Constructor
      *
@@ -58,3 +53,4 @@ export default class FiniteStateMachine {
 export type StateTransitionMetadata = import("./typedef.js").StateTransitionMetadata;
 export type OnEnterCallback = import("./typedef.js").OnEnterCallback;
 export type OnExitCallback = import("./typedef.js").OnExitCallback;
+import EventEmitter from '../../../generic/events/classes/EventEmitter.js';

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

@@ -4,6 +4,10 @@
  * @see {@link https://runed.dev/docs/utilities/finite-state-machine}
  */
 
+import { isTestEnv } from '../../../util/env.js';
+import EventEmitter from '../../../generic/events/classes/EventEmitter.js';
+import { ENTER, EXIT } from './constants.js';
+
 /** @typedef {import('./typedef.js').StateTransitionMetadata} StateTransitionMetadata */
 /** @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 initialMetadata = {
       from: null,
       to: initial,
       event: null,
       args: []
-    });
+    };
+
+    this.#executeAction('_enter', initialMetadata);
+
+    // Emit ENTER event for external listeners for initial state
+    this.emit(ENTER, { state: initial, metadata: initialMetadata });
   }
 
   /**
@@ -70,45 +83,61 @@ export default class FiniteStateMachine {
 
     // Call onexit callback before leaving current state
     this.onexit?.(this.#current, metadata);
-    
-    this.#dispatch('_exit', metadata);
+
+    // Emit EXIT event for external listeners
+    this.emit(EXIT, { state: this.#current, metadata });
+
+    this.#executeAction('_exit', metadata);
     this.#current = newState;
-    this.#dispatch('_enter', metadata);
-    
+    this.#executeAction('_enter', metadata);
+
+    // Emit ENTER event for external listeners
+    this.emit(ENTER, { state: newState, metadata });
+
     // Call onenter callback after state change
     this.onenter?.(newState, metadata);
   }
 
   /**
-   * 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 metadata 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)
@@ -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
@@ -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
 
@@ -268,7 +268,7 @@ machine.onexit = (state) => console.log(`3. onexit ${state}`);
 machine.onenter = (state) => console.log(`6. onenter ${state}`);
 
 // 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' },
@@ -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;
@@ -419,19 +421,19 @@ 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) {
@@ -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
@@ -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.js

@@ -4,25 +4,25 @@
 
 /**
  * Metadata object passed to state transition callbacks
- * 
+ *
  * @typedef {object} StateTransitionMetadata
  * @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 exiting a state
- * 
+ *
  * @typedef {function(string, StateTransitionMetadata): void} OnExitCallback
  */
 
 // Export types for external use (this is just for JSDoc, no actual exports needed)
-export {};
+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);
+  }
 }