@hkdigital/lib-core 0.4.27 → 0.4.29

package/dist/network/loaders/base/SceneBase.svelte.js

@@ -0,0 +1,283 @@
+import { LoadingStateMachine } from '../../../state/machines.js';
+
+import {
+  STATE_INITIAL,
+  STATE_LOADING,
+  STATE_LOADED,
+  STATE_ABORTING,
+  STATE_ABORTED,
+  STATE_ERROR,
+  LOAD,
+  LOADED,
+  ABORT,
+  ABORTED
+} from '../../../state/machines.js';
+
+import { waitForState } from '../../../util/svelte.js';
+
+/**
+ * Base class for scene loaders that manage collections of media sources
+ */
+export default class SceneBase {
+  #state = new LoadingStateMachine();
+
+  // @note this exported state is set by onenter
+  state = $state(STATE_INITIAL);
+
+  loaded = $derived.by(() => {
+    return this.state === STATE_LOADED;
+  });
+
+  #progress = $derived.by(() => {
+    let totalSize = 0;
+    let totalBytesLoaded = 0;
+    let sourcesLoaded = 0;
+
+    const sources = this.sources;
+    const numberOfSources = sources.length;
+
+    for (let j = 0; j < numberOfSources; j++) {
+      const source = sources[j];
+      const loader = this.getLoaderFromSource(source);
+
+      const { bytesLoaded, size, loaded } = loader.progress;
+
+      totalSize += size;
+      totalBytesLoaded += bytesLoaded;
+
+      if (loaded) {
+        sourcesLoaded++;
+      }
+    }
+
+    return {
+      totalBytesLoaded,
+      totalSize,
+      sourcesLoaded,
+      numberOfSources
+    };
+  });
+
+  #abortProgress = $derived.by(() => {
+    let sourcesAborted = 0;
+    const sources = this.sources;
+    const numberOfSources = sources.length;
+
+    for (let j = 0; j < numberOfSources; j++) {
+      const source = sources[j];
+      const loader = this.getLoaderFromSource(source);
+      const loaderState = loader.state;
+
+      if (loaderState === STATE_ABORTED || loaderState === STATE_ERROR) {
+        sourcesAborted++;
+      }
+    }
+
+    return {
+      sourcesAborted,
+      numberOfSources
+    };
+  });
+
+  /**
+   * Construct SceneBase
+   */
+  constructor() {
+    const state = this.#state;
+
+    $effect(() => {
+      if (state.current === STATE_LOADING) {
+        const { sourcesLoaded, numberOfSources } = this.#progress;
+
+        if (sourcesLoaded === numberOfSources) {
+          this.#state.send(LOADED);
+        }
+      }
+    });
+
+    $effect(() => {
+      if (state.current === STATE_ABORTING) {
+        const { sourcesAborted, numberOfSources } = this.#abortProgress;
+
+        if (sourcesAborted === numberOfSources) {
+          this.#state.send(ABORTED);
+        }
+      }
+    });
+
+    state.onenter = (currentState) => {
+      if (currentState === STATE_LOADING) {
+        this.#startLoading();
+      } else if (currentState === STATE_ABORTING) {
+        this.#startAbort();
+      }
+
+      this.state = currentState;
+    };
+  }
+
+  /* ==== Abstract methods - must be implemented by subclasses */
+
+  /**
+   * Get the array of sources managed by this scene
+   *
+   * @returns {Array} Array of source objects
+   */
+  get sources() {
+    throw new Error('Subclass must implement sources getter');
+  }
+
+  /**
+   * Extract the loader from a source object
+   *
+   * @param {*} source
+   *
+   * @returns {*} Loader object with progress and state properties
+   */
+  // eslint-disable-next-line no-unused-vars
+  getLoaderFromSource(source) {
+    throw new Error('Subclass must implement getLoaderFromSource method');
+  }
+
+  /* ==== Common loader interface */
+
+  /**
+   * Get scene loading progress
+   */
+  get progress() {
+    return this.#progress;
+  }
+
+  /**
+   * Get scene abort progress
+   */
+  get abortProgress() {
+    return this.#abortProgress;
+  }
+
+  /**
+   * Start loading all sources
+   */
+  load() {
+    this.#state.send(LOAD);
+  }
+
+  /**
+   * Abort loading all sources
+   */
+  abort() {
+    this.#state.send(ABORT);
+  }
+
+  /**
+   * Preload all sources with progress tracking and abort capability
+   * - Starts loading and waits for completion
+   * - Supports timeout and progress callbacks
+   * - Returns object with promise and abort function
+   *
+   * @param {object} [options]
+   * @param {number} [options.timeoutMs=10000] - Timeout in milliseconds
+   * @param {Function} [options.onProgress] - Progress callback function
+   *
+   * @returns {object} Object with promise and abort function
+   * @returns {Promise<SceneBase>} returns.promise - Promise that resolves when loaded
+   * @returns {Function} returns.abort - Function to abort preloading
+   */
+  preload({ timeoutMs = 10000, onProgress } = {}) {
+    let timeoutId = null;
+    let progressIntervalId = null;
+    let isAborted = false;
+
+    const abort = () => {
+      if (isAborted) return;
+      isAborted = true;
+
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+        timeoutId = null;
+      }
+
+      if (progressIntervalId) {
+        clearInterval(progressIntervalId);
+        progressIntervalId = null;
+      }
+
+      this.abort();
+    };
+
+    const promise = new Promise((resolve, reject) => {
+      // Set up progress tracking with polling
+      if (onProgress) {
+        progressIntervalId = setInterval(() => {
+          if (!isAborted) {
+            onProgress(this.progress);
+          }
+        }, 50); // Poll every 50ms
+      }
+
+      // Set up timeout
+      if (timeoutMs > 0) {
+        timeoutId = setTimeout(() => {
+          abort();
+          reject(new Error(`Preload timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+      }
+
+      // Start loading
+      this.load();
+
+      // Wait for completion with extended timeout
+      const waitTimeout = Math.max(timeoutMs + 1000, 2000);
+      waitForState(() => {
+        return this.loaded ||
+               this.state === STATE_ABORTED ||
+               this.state === STATE_ERROR;
+      }, waitTimeout)
+        .then(() => {
+          if (timeoutId) {
+            clearTimeout(timeoutId);
+            timeoutId = null;
+          }
+
+          if (progressIntervalId) {
+            clearInterval(progressIntervalId);
+            progressIntervalId = null;
+          }
+
+          if (isAborted || this.state === STATE_ABORTED) {
+            reject(new Error('Preload was aborted'));
+          } else if (this.state === STATE_ERROR) {
+            reject(new Error('Preload failed due to error'));
+          } else if (this.loaded) {
+            resolve(this);
+          } else {
+            reject(new Error(`Preload failed: unexpected state ${this.state}`));
+          }
+        })
+        .catch(reject);
+    });
+
+    return { promise, abort };
+  }
+
+  destroy() {
+    // TODO: disconnect all sources?
+    // TODO: Unload loaders?
+  }
+
+  /* ==== Internal methods */
+
+  #startLoading() {
+    for (const source of this.sources) {
+      const loader = this.getLoaderFromSource(source);
+      loader.load();
+    }
+  }
+
+  #startAbort() {
+    for (const source of this.sources) {
+      const loader = this.getLoaderFromSource(source);
+      loader.abort();
+    }
+  }
+}

package/dist/network/loaders/image/ImageScene.svelte.d.ts

@@ -7,34 +7,21 @@
  * @property {string} label
  * @property {ImageLoader} imageLoader
  */
-export default class ImageScene {
-    state: string;
-    loaded: boolean;
+export default class ImageScene extends SceneBase {
     /**
-     * Get image scene loading progress
-     */
-    get progress(): {
-        totalBytesLoaded: number;
-        totalSize: number;
-        sourcesLoaded: number;
-        numberOfSources: number;
-    };
-    /**
-     * Get image scene abort progress
-     */
-    get abortProgress(): {
-        sourcesAborted: number;
-        numberOfSources: number;
-    };
-    /**
-     * Start loading all image sources
+     * Get the array of image sources managed by this scene
+     *
+     * @returns {ImageSceneSource[]}
      */
-    load(): void;
+    get sources(): ImageSceneSource[];
     /**
-     * Abort loading all image sources
+     * Extract the image loader from a source object
+     *
+     * @param {ImageSceneSource} source
+     *
+     * @returns {ImageLoader}
      */
-    abort(): void;
-    destroy(): void;
+    getLoaderFromSource(source: ImageSceneSource): ImageLoader;
     /**
      * Add image source
      * - Uses an ImageLoader instance to load image data from network
@@ -84,4 +71,5 @@ export type ImageSceneSource = {
     label: string;
     imageLoader: ImageLoader;
 };
+import SceneBase from '../base/SceneBase.svelte.js';
 import ImageLoader from './ImageLoader.svelte.js';

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

@@ -2,21 +2,7 @@
 
 import * as expect from '../../../util/expect.js';
 
-import { LoadingStateMachine } from '../../../state/machines.js';
-
-import {
-  STATE_INITIAL,
-  STATE_LOADING,
-  STATE_LOADED,
-  STATE_ABORTING,
-  STATE_ABORTED,
-  STATE_ERROR,
-  LOAD,
-  LOADED,
-  ABORT,
-  ABORTED
-} from '../../../state/machines.js';
-
+import SceneBase from '../base/SceneBase.svelte.js';
 import ImageLoader from './ImageLoader.svelte.js';
 
 /**
@@ -30,152 +16,40 @@ import ImageLoader from './ImageLoader.svelte.js';
  * @property {ImageLoader} imageLoader
  */
 
-export default class ImageScene {
-  #state = new LoadingStateMachine();
-
-  // @note this exported state is set by onenter
-  state = $state(STATE_INITIAL);
-
-  loaded = $derived.by(() => {
-    return this.state === STATE_LOADED;
-  });
+export default class ImageScene extends SceneBase {
 
   /** @type {ImageSceneSource[]} */
   #imageSources = $state([]);
 
-  #progress = $derived.by(() => {
-    // console.log('update progress');
-
-    let totalSize = 0;
-    let totalBytesLoaded = 0;
-    let sourcesLoaded = 0;
-
-    const sources = this.#imageSources;
-    const numberOfSources = sources.length;
-
-    for (let j = 0; j < numberOfSources; j++) {
-      const source = sources[j];
-      const { imageLoader } = source;
-
-      const { bytesLoaded, size, loaded } = imageLoader.progress;
-
-      totalSize += size;
-      totalBytesLoaded += bytesLoaded;
-
-      if (loaded) {
-        sourcesLoaded++;
-      }
-    } // end for
-
-    return {
-      totalBytesLoaded,
-      totalSize,
-      sourcesLoaded,
-      numberOfSources
-    };
-  });
-
-  #abortProgress = $derived.by(() => {
-    let sourcesAborted = 0;
-    const sources = this.#imageSources;
-    const numberOfSources = sources.length;
-
-    for (let j = 0; j < numberOfSources; j++) {
-      const source = sources[j];
-      const { imageLoader } = source;
-      const loaderState = imageLoader.state;
-
-      if (loaderState === STATE_ABORTED || loaderState === STATE_ERROR) {
-        sourcesAborted++;
-      }
-    } // end for
-
-    return {
-      sourcesAborted,
-      numberOfSources
-    };
-  });
-
-  #sourcesLoaded = $derived( this.#progress.sourcesLoaded );
-  #numberOfSources = $derived( this.#progress.numberOfSources );
 
   /**
    * Construct ImageScene
    */
   constructor() {
-    const state = this.#state;
-
-    $effect( () => {
-      if (state.current === STATE_LOADING) {
-        if (this.#sourcesLoaded === this.#numberOfSources) {
-          // console.log(`All [${this.#numberOfSources}] sources loaded`);
-          this.#state.send(LOADED);
-        }
-      }
-    } );
-
-    $effect(() => {
-      if (state.current === STATE_ABORTING) {
-        const { sourcesAborted, numberOfSources } = this.#abortProgress;
-
-        if (sourcesAborted === numberOfSources) {
-          // console.debug(`ImageScene: ${numberOfSources} sources aborted`);
-          this.#state.send(ABORTED);
-        }
-      }
-    });
-
-    state.onenter = ( currentState ) => {
-      // console.log('onenter', currentState );
-
-      if(currentState === STATE_LOADING )
-      {
-        // console.log('ImageScene:loading');
-        this.#startLoading();
-      }
-      else if(currentState === STATE_ABORTING )
-      {
-        // console.log('ImageScene:aborting');
-        this.#startAbort();
-      }
-
-      this.state = currentState;
-    };
-  }
-
-  /* ==== Common loader interface */
-
-  /**
-   * Get image scene loading progress
-   */
-  get progress() {
-    return this.#progress;
+    super();
   }
 
-  /**
-   * Get image scene abort progress
-   */
-  get abortProgress() {
-    return this.#abortProgress;
-  }
+  /* ==== SceneBase implementation */
 
   /**
-   * Start loading all image sources
+   * Get the array of image sources managed by this scene
+   *
+   * @returns {ImageSceneSource[]}
    */
-  load() {
-    this.#state.send(LOAD);
+  get sources() {
+    return this.#imageSources;
   }
 
   /**
-   * Abort loading all image sources
+   * Extract the image loader from a source object
+   *
+   * @param {ImageSceneSource} source
+   *
+   * @returns {ImageLoader}
    */
-  abort() {
-    this.#state.send(ABORT);
-  }
-
-  destroy() {
-    // TODO: disconnect all image sources?
-    // TODO: Unload ImageLoaders?
+  // eslint-disable-next-line no-unused-vars
+  getLoaderFromSource(source) {
+    return source.imageLoader;
   }
 
   /* ==== Source definitions */
@@ -241,18 +115,6 @@ export default class ImageScene {
     return source.imageLoader.getObjectURL();
   }
 
-  async #startLoading() {
-    for (const { imageLoader } of this.#imageSources) {
-      imageLoader.load();
-    }
-  }
-
-  #startAbort() {
-    for (const { imageLoader } of this.#imageSources) {
-      imageLoader.abort();
-    }
-  }
-
   /* ==== Internals */
 
   /**

package/dist/services/service-manager/ServiceManager.d.ts

@@ -129,12 +129,32 @@ export class ServiceManager extends EventEmitter {
      */
     isRunning(name: string): Promise<boolean>;
     /**
-     * Set log level for a service or globally
+     * Listen to log messages emitted by individual services
      *
-     * @param {string} name - Service name or '*' for global
-     * @param {string} level - Log level to set
+     * @param {Function} listener - Log event handler
+     *
+     * @returns {Function} Unsubscribe function
+     */
+    onServiceLogEvent(listener: Function): Function;
+    /**
+     * Set log level for the ServiceManager itself
+     *
+     * @param {string} level - Log level to set for the ServiceManager
+     */
+    setManagerLogLevel(level: string): void;
+    /**
+     * Set log level for individual services
+     *
+     * @param {string|Object<string,string>} nameOrConfig
+     *   Service configuration:
+     *   - String with service name: 'auth' (requires level parameter)
+     *   - String with config: 'auth:debug,database:info'
+     *   - Object: { auth: 'debug', database: 'info' }
+     * @param {string} [level] - Log level (required when nameOrConfig is service name)
      */
-    setLogLevel(name: string, level: string): void;
+    setServiceLogLevel(nameOrConfig: string | {
+        [x: string]: string;
+    }, level?: string): void;
     /**
      * Get all services with a specific tag
      *