@hkdigital/lib-core 0.4.23 → 0.4.25

package/dist/network/loaders/image/ImageScene.svelte.js

@@ -2,7 +2,7 @@
 
 import * as expect from '../../../util/expect.js';
 
-import { LoadingStateMachine } from '../../../state/classes.js';
+import { LoadingStateMachine } from '../../../state/machines.js';
 
 import {
   STATE_INITIAL,
@@ -13,7 +13,7 @@ import {
   STATE_ERROR,
   LOAD,
   LOADED
-} from '../../../state/classes/loading-state-machine/constants.js';
+} from '../../../state/machines.js';
 
 import ImageLoader from './ImageLoader.svelte.js';
 
@@ -74,30 +74,28 @@ export default class ImageScene {
     };
   });
 
+  #sourcesLoaded = $derived( this.#progress.sourcesLoaded );
+  #numberOfSources = $derived( this.#progress.numberOfSources );
+
   /**
    * Construct ImageScene
    */
   constructor() {
     const state = this.#state;
 
-    $effect(() => {
+    $effect( () => {
       if (state.current === STATE_LOADING) {
-        // console.log(
-        //   'progress',
-        //   JSON.stringify($state.snapshot(this.#progress))
-        // );
-
-        const { sourcesLoaded, numberOfSources } = this.#progress;
-
-        if (sourcesLoaded === numberOfSources) {
-          // console.log(`All [${numberOfSources}] sources loaded`);
+        if (this.#sourcesLoaded === this.#numberOfSources) {
+          // console.log(`All [${this.#numberOfSources}] sources loaded`);
           this.#state.send(LOADED);
         }
       }
-    });
+    } );
 
-    $effect(() => {
-      switch (state.current) {
+    state.onenter = ( state ) => {
+      // console.log('onenter', state );
+
+      switch (state) {
         case STATE_LOADING:
           {
             // console.log('ImageScene:loading');
@@ -129,13 +127,13 @@ export default class ImageScene {
 
         case STATE_ERROR:
           {
-            console.log('ImageScene:error', state.error);
+            console.log('ImageScene:error', state);
           }
           break;
       } // end switch
 
-      this.state = state.current;
-    });
+      this.state = state;
+    };
   }
 
   destroy() {
@@ -166,22 +164,14 @@ export default class ImageScene {
    */
   load() {
     this.#state.send(LOAD);
+  }
 
-    // FIXME: in unit test when moved to startloading it hangs!
-
+  async #startLoading() {
     for (const { imageLoader } of this.#imageSources) {
       imageLoader.load();
     }
   }
 
-  async #startLoading() {
-    // console.log('#startLoading');
-    // FIXME: in unit test when moved to startloading it hangs!
-    // for (const { audioLoader } of this.#memorySources) {
-    //   audioLoader.load();
-    // }
-  }
-
   /**
    * Get Image source
    *

package/dist/network/states/NetworkLoader.svelte.d.ts

@@ -42,6 +42,12 @@ export default class NetworkLoader {
      * Unoad all network data
      */
     unload(): void;
+    /**
+     * Abort the current loading operation
+     * - Only works when in STATE_LOADING
+     * - Aborts network requests and transitions to STATE_CANCELLED
+     */
+    doAbort(): void;
     /**
      * Get network data size in bytes
      * - Info comes from the content length response header
@@ -88,4 +94,4 @@ export default class NetworkLoader {
     getObjectURL(): string;
     #private;
 }
-import { LoadingStateMachine } from '../../state/classes.js';
+import { LoadingStateMachine } from '../../state/machines.js';

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

@@ -1,6 +1,6 @@
 import { CONTENT_TYPE } from '../../constants/http.js';
 
-import { LoadingStateMachine } from '../../state/classes.js';
+import { LoadingStateMachine } from '../../state/machines.js';
 
 import {
   STATE_INITIAL,
@@ -13,8 +13,9 @@ import {
   ERROR,
   LOADED,
   UNLOAD,
-  INITIAL
-} from '../../state/classes/loading-state-machine/constants.js';
+  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/README.md

@@ -259,6 +259,29 @@ manager.on(SERVICE_ERROR, async ({ service, error }) => {
 await manager.recoverService('database');
 ```
 
+### Log Event Forwarding
+
+Forward all service log events to a centralised logger:
+
+```javascript
+import { ServiceManager, SERVICE_LOG } from '$lib/services/index.js';
+import { createServerLogger } from '$lib/logging/index.js';
+
+const manager = new ServiceManager();
+const logger = createServerLogger('SystemLogger');
+
+// Listen to all log events and forward them to the logger
+manager.on(SERVICE_LOG, (logEvent) => {
+  logger.logFromEvent('manager:service:log', logEvent);
+});
+
+// Register services
+manager.register('database', DatabaseService, { ... });
+manager.register('auth', AuthService, { ... });
+
+await manager.startAll();
+```
+
 ## Plugins
 
 ServiceManager supports plugins e.g. to resolve service configurations dynamically.

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/classes.d.ts

@@ -1,3 +1 @@
-export { default as FiniteStateMachine } from "./classes/finite-state-machine/FiniteStateMachine.svelte.js";
-export { default as LoadingStateMachine } from "./classes/loading-state-machine/LoadingStateMachine.svelte.js";
 export { default as SubscribersCount } from "./classes/subscribers-count/SubscribersCount.js";

package/dist/state/classes.js

@@ -1,3 +1 @@
-export { default as FiniteStateMachine } from './classes/finite-state-machine/FiniteStateMachine.svelte.js';
-export { default as LoadingStateMachine } from './classes/loading-state-machine/LoadingStateMachine.svelte.js';
 export { default as SubscribersCount } from './classes/subscribers-count/SubscribersCount.js';

package/dist/state/{classes → machines}/finite-state-machine/FiniteStateMachine.svelte.d.ts

@@ -1,8 +1,6 @@
-/**
- * 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 */
 /**
  * Check if the value is valid meta data
  *
@@ -10,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
      *
@@ -29,6 +27,10 @@ export default class FiniteStateMachine {
             [key: string]: string | ((...args: any[]) => void);
         };
     };
+    /** @type {OnEnterCallback | null} */
+    onenter: OnEnterCallback | null;
+    /** @type {OnExitCallback | null} */
+    onexit: OnExitCallback | null;
     /**
      * Triggers a new event and returns the new state.
      *
@@ -48,3 +50,7 @@ export default class FiniteStateMachine {
     get current(): any;
     #private;
 }
+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

@@ -0,0 +1,181 @@
+/**
+ * Initial code borrowed from:
+ *
+ * @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 */
+
+/**
+ * Check if the value is valid meta data
+ *
+ * @param {any} meta
+ */
+export function isLifecycleFnMeta(meta) {
+  return (
+    !!meta &&
+    typeof meta === 'object' &&
+    'to' in meta &&
+    'from' in meta &&
+    'event' in meta &&
+    'args' in meta
+  );
+}
+
+/**
+ * Defines a Finite State Machine that extends EventEmitter
+ */
+export default class FiniteStateMachine extends EventEmitter {
+  #current = $state();
+  states;
+  #timeout = {};
+
+  /** @type {OnEnterCallback | null} */
+  onenter = null;
+
+  /** @type {OnExitCallback | null} */
+  onexit = null;
+
+  /** @type {boolean} */
+  #enableConsoleWarnings = !isTestEnv;
+
+  /**
+   * Constructor
+   *
+   * @param {string} initial
+   * @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.
+    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 });
+  }
+
+  /**
+   * Transition to new state
+   *
+   * @param {string} newState
+   * @param {string} event
+   * @param {any[]} [args]
+   */
+  #transition(newState, event, args) {
+    /** @type {StateTransitionMetadata} */
+    const metadata = { from: this.#current, to: newState, event, args };
+
+    // Call onexit callback before leaving current state
+    this.onexit?.(this.#current, metadata);
+
+    // Emit EXIT event for external listeners
+    this.emit(EXIT, { state: this.#current, metadata });
+
+    this.#executeAction('_exit', metadata);
+    this.#current = newState;
+    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);
+  }
+
+  /**
+   * Execute an action for the given event
+   *
+   * @param {string} event
+   * @param {any} args
+   */
+  #executeAction(event, ...args) {
+    const action =
+      this.states[this.#current]?.[event] ?? this.states['*']?.[event];
+
+    if (action instanceof Function) {
+      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(
+            'No action defined for event',
+            event,
+            'in state',
+            this.#current
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Triggers a new event and returns the new state.
+   *
+   * @param {string} event
+   * @param {any[]} args
+   */
+  send(event, ...args) {
+    const newState = this.#executeAction(event, ...args);
+
+    if (newState && newState !== this.#current) {
+      this.#transition(newState, event, args);
+    }
+
+    return this.#current;
+  }
+  /**
+   * Debounces the triggering of an event.
+   *
+   * @param {number} wait
+   * @param {string} event
+   * @param {any[]} args
+   */
+  async debounce(wait = 500, event, ...args) {
+    if (this.#timeout[event]) {
+      clearTimeout(this.#timeout[event]);
+    }
+    return new Promise((resolve) => {
+      this.#timeout[event] = setTimeout(() => {
+        delete this.#timeout[event];
+        resolve(this.send(event, ...args));
+      }, wait);
+    });
+  }
+
+  /** The current state. */
+  get current() {
+    return this.#current;
+  }
+}