@hkdigital/lib-core 0.3.1

package/dist/classes/svelte/audio/AudioScene.svelte.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @typedef {object} SourceConfig
+ * // property ...
+ */
+/**
+ * @typedef {object} MemorySource
+ * @property {string} label
+ * @property {AudioLoader} audioLoader
+ * @property {SourceConfig} [config]
+ */
+export default class AudioScene {
+    state: string;
+    loaded: boolean;
+    muted: boolean;
+    targetGain: number;
+    destroy(): void;
+    /**
+     * Add in-memory audio source
+     * - Uses an AudioLoader instance to load audio data from network
+     *
+     * @param {object} _
+     * @param {string} _.label
+     * @param {string} _.url
+     * @param {SourceConfig} [_.config]
+     */
+    defineMemorySource({ label, url, config }: {
+        label: string;
+        url: string;
+        config?: SourceConfig;
+    }): void;
+    /**
+     * Start loading all audio sources
+     */
+    load(): void;
+    /**
+     * Set an audio context to use
+     *
+     * @param {AudioContext} [audioContext]
+     */
+    setAudioContext(audioContext?: AudioContext): void;
+    /**
+     * Get a source that can be used to play the audio once
+     *
+     * @param {string} label
+     *
+     * @returns {Promise<AudioBufferSourceNode>}
+     */
+    getSourceNode(label: string): Promise<AudioBufferSourceNode>;
+    /**
+     * Set target gain
+     *
+     * @param {number} value
+     */
+    setTargetGain(value: number): void;
+    /**
+     * Get the scene gain
+     *
+     * @returns {number} value
+     */
+    getTargetGain(): number;
+    mute(): void;
+    unmute(): void;
+    #private;
+}
+/**
+ * // property ...
+ */
+export type SourceConfig = object;
+export type MemorySource = {
+    label: string;
+    audioLoader: AudioLoader;
+    config?: SourceConfig;
+};
+import AudioLoader from './AudioLoader.svelte.js';

package/dist/classes/svelte/audio/AudioScene.svelte.js

@@ -0,0 +1,324 @@
+import * as expect from '../../../util/expect/index.js';
+
+import {
+	LoadingStateMachine,
+	STATE_INITIAL,
+	STATE_LOADING,
+	STATE_UNLOADING,
+	STATE_LOADED,
+	STATE_CANCELLED,
+	STATE_ERROR,
+	LOAD,
+	LOADED
+} from '../loading-state-machine/index.js';
+
+import AudioLoader from './AudioLoader.svelte.js';
+
+/**
+ * @typedef {object} SourceConfig
+ * // property ...
+ */
+
+/**
+ * @typedef {object} MemorySource
+ * @property {string} label
+ * @property {AudioLoader} audioLoader
+ * @property {SourceConfig} [config]
+ */
+
+export default class AudioScene {
+	#state = new LoadingStateMachine();
+
+	// @note this exported state is set by $effect's
+	state = $state(STATE_INITIAL);
+
+	// @note this exported state is set by $effect's
+	loaded = $derived.by(() => {
+		return this.state === STATE_LOADED;
+	});
+
+	#targetGain = $state(1);
+
+	#unmutedTargetGain = 1;
+
+	muted = $derived( this.#targetGain === 0 );
+
+	targetGain = $derived( this.#targetGain );
+
+	/** @type {AudioContext|null} */
+	#audioContext = null;
+
+	/** {GainNode} */
+	#targetGainNode = null;
+
+	/** @type {MemorySource[]} */
+	#memorySources = $state([]);
+
+	#progress = $derived.by(() => {
+		// console.log('update progress');
+
+		let totalSize = 0;
+		let totalBytesLoaded = 0;
+		let sourcesLoaded = 0;
+
+		const sources = this.#memorySources;
+		const numberOfSources = sources.length;
+
+		for (let j = 0; j < numberOfSources; j++) {
+			const source = sources[j];
+			const { audioLoader } = source;
+
+			const { bytesLoaded, size, loaded } = audioLoader.progress;
+
+			totalSize += size;
+			totalBytesLoaded += bytesLoaded;
+
+			if (loaded) {
+				sourcesLoaded++;
+			}
+		} // end for
+
+		return {
+			totalBytesLoaded,
+			totalSize,
+			sourcesLoaded,
+			numberOfSources
+		};
+	});
+
+	/**
+	 * Construct AudioScene
+	 */
+	constructor() {
+		const state = this.#state;
+
+		$effect(() => {
+			if (state.current === STATE_LOADING) {
+				// console.log(
+				//   'progress',
+				//   JSON.stringify($state.snapshot(this.#progress))
+				// );
+
+				const { sourcesLoaded, numberOfSources } = this.#progress;
+
+				if (sourcesLoaded === numberOfSources) {
+					// console.debug(`AudioScene: ${numberOfSources} sources loaded`);
+					this.#state.send(LOADED);
+				}
+			}
+		});
+
+		$effect(() => {
+			switch (state.current) {
+				case STATE_LOADING:
+					{
+						// console.log('AudioScene:loading');
+						this.#startLoading();
+					}
+					break;
+
+				case STATE_UNLOADING:
+					{
+						// console.log('AudioScene:unloading');
+						// this.#startUnLoading();
+					}
+					break;
+
+				case STATE_LOADED:
+					{
+						// console.log('AudioScene:loaded');
+
+						// tODO
+						// this.#abortLoading = null;
+					}
+					break;
+
+				case STATE_CANCELLED:
+					{
+						// console.log('AudioScene:cancelled');
+						// TODO
+					}
+					break;
+
+				case STATE_ERROR:
+					{
+						console.error('AudioScene:error', state.error);
+					}
+					break;
+			} // end switch
+
+			this.state = state.current;
+		});
+	}
+
+	destroy() {
+		// TODO: disconnect all audio sources?
+		// TODO: Unload AUdioLoaders?
+	}
+
+	/**
+	 * Add in-memory audio source
+	 * - Uses an AudioLoader instance to load audio data from network
+	 *
+	 * @param {object} _
+	 * @param {string} _.label
+	 * @param {string} _.url
+	 * @param {SourceConfig} [_.config]
+	 */
+	defineMemorySource({ label, url, config }) {
+		expect.notEmptyString(label);
+		expect.notEmptyString(url);
+
+		const audioLoader = new AudioLoader({ url });
+
+		this.#memorySources.push({ label, audioLoader, config });
+	}
+
+	/**
+	 * Start loading all audio sources
+	 */
+	load() {
+		this.#state.send(LOAD);
+
+		// FIXME: in unit test when moved to startloading it hangs!
+
+		for (const { audioLoader } of this.#memorySources) {
+			audioLoader.load();
+		}
+	}
+
+	/**
+ 	 * Set an audio context to use
+ 	 *
+	 * @param {AudioContext} [audioContext]
+	 */
+	setAudioContext( audioContext ) {
+		this.#audioContext = audioContext;
+	}
+
+	async #startLoading() {
+		// console.log('#startLoading');
+
+		// FIXME: in unit test when moved to startloading it hangs!
+		// for (const { audioLoader } of this.#memorySources) {
+		//   audioLoader.load();
+		// }
+	}
+
+	/**
+	 * Get a source that can be used to play the audio once
+	 *
+	 * @param {string} label
+	 *
+	 * @returns {Promise<AudioBufferSourceNode>}
+	 */
+	async getSourceNode(label) {
+		// @note Gain setup
+		// https://stackoverflow.com/questions/46203191/should-i-disconnect-nodes-that-cant-be-used-anymore
+
+		const { audioLoader /*, config */ } = this.#getMemorySource(label);
+
+		if (!audioLoader.loaded) {
+			throw new Error(`Source [${label}] has not been loaded yet`);
+		}
+
+		const sourceNode = await audioLoader.getAudioBufferSourceNode(
+			this.#getAudioContext()
+		);
+
+		// @ts-ignore
+		sourceNode.connect(this.#getGainNode());
+		// sourceNode.connect(this.#getAudioContext().destination);
+
+		// Clean up
+		sourceNode.onended = () => {
+			// console.log(`Source [${label}] ended `);
+			sourceNode.disconnect();
+		};
+
+		return sourceNode;
+	}
+
+	/**
+	 * Set target gain
+	 *
+	 * @param {number} value
+	 */
+	setTargetGain( value ) {
+		this.#targetGain = value;
+
+		// Set immediate
+		this.#getGainNode().gain.value = value;
+	}
+
+	/**
+	 * Get the scene gain
+	 *
+	 * @returns {number} value
+	 */
+	getTargetGain()
+	{
+		return this.#targetGain;
+	}
+
+	mute() {
+		if( this.muted )
+		{
+			return;
+		}
+
+		this.#unmutedTargetGain = this.#targetGain;
+		this.setTargetGain(0);
+	}
+
+	unmute() {
+		if( !this.muted )
+		{
+			return;
+		}
+
+		this.setTargetGain(this.#unmutedTargetGain);
+	}
+
+
+	#getGainNode()
+	{
+		if( !this.#targetGainNode )
+		{
+			const audioContext = this.#getAudioContext();
+
+			this.#targetGainNode = audioContext.createGain();
+			this.#targetGainNode.connect(audioContext.destination);
+			this.setTargetGain(this.#targetGain);
+		}
+
+		return this.#targetGainNode;
+	}
+
+	#getAudioContext()
+	{
+		if( !this.#audioContext )
+		{
+			this.#audioContext = new AudioContext();
+		}
+
+		return this.#audioContext;
+	}
+
+	/**
+	 * Get memory source
+	 *
+	 * @param {string} label
+	 *
+	 * @returns {MemorySource}
+	 */
+	#getMemorySource(label) {
+		for (const source of this.#memorySources) {
+			if (label === source.label) {
+				return source;
+			}
+		}
+
+		throw new Error(`Source [${label}] has not been defined`);
+	}
+}

package/dist/classes/svelte/audio/mocks.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Create a response value that can be used by a mocked
+ * fetch function
+ *
+ * @returns {Response}
+ */
+export function createWavResponse(): Response;

package/dist/classes/svelte/audio/mocks.js

@@ -0,0 +1,35 @@
+import { CONTENT_TYPE, CONTENT_LENGTH } from '../../../constants/http/index.js';
+
+import { AUDIO_WAV } from '../../../constants/mime/audio.js';
+
+// import MockWav from './tiny-silence.wav?raw';
+
+const BASE64_WAV =
+	'UklGRnwAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YVgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA';
+
+/**
+ * Create a response value that can be used by a mocked
+ * fetch function
+ *
+ * @returns {Response}
+ */
+export function createWavResponse(/* data , options */) {
+	// @note encode as Uint8Array to get the proper byte size of data
+	// const bytes = new TextEncoder().encode(MockWav);
+
+	const binaryString = atob(BASE64_WAV);
+	const bytes = new Uint8Array(binaryString.length);
+
+	for (let i = 0; i < binaryString.length; i++) {
+		bytes[i] = binaryString.charCodeAt(i);
+	}
+
+	const response = new Response(bytes, {
+		headers: new Headers({
+			[CONTENT_TYPE]: AUDIO_WAV,
+			[CONTENT_LENGTH]: String(bytes.length)
+		})
+	});
+
+	return response;
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Initial code borrowed from:
+ *
+ * @see {@link https://runed.dev/docs/utilities/finite-state-machine}
+ */
+/**
+ * Check if the value is valid meta data
+ *
+ * @param {any} meta
+ */
+export function isLifecycleFnMeta(meta: any): boolean;
+/**
+ * Defines a Finite State Machine
+ */
+export default class FiniteStateMachine {
+    /**
+     * Constructor
+     *
+     * @param {string} initial
+     * @param {{ [key: string]: { [key: string]: (string|((...args: any[])=>void)) } }} states
+     */
+    constructor(initial: string, states: {
+        [key: string]: {
+            [key: string]: (string | ((...args: any[]) => void));
+        };
+    });
+    states: {
+        [key: string]: {
+            [key: string]: string | ((...args: any[]) => void);
+        };
+    };
+    /**
+     * Triggers a new event and returns the new state.
+     *
+     * @param {string} event
+     * @param {any[]} args
+     */
+    send(event: string, ...args: any[]): any;
+    /**
+     * Debounces the triggering of an event.
+     *
+     * @param {number} wait
+     * @param {string} event
+     * @param {any[]} args
+     */
+    debounce(wait: number, event: string, ...args: any[]): Promise<any>;
+    /** The current state. */
+    get current(): any;
+    #private;
+}

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

@@ -0,0 +1,133 @@
+/**
+ * Initial code borrowed from:
+ *
+ * @see {@link https://runed.dev/docs/utilities/finite-state-machine}
+ */
+
+/**
+ * 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
+ */
+export default class FiniteStateMachine {
+  #current = $state();
+  states;
+  #timeout = {};
+
+  /**
+   * Constructor
+   *
+   * @param {string} initial
+   * @param {{ [key: string]: { [key: string]: (string|((...args: any[])=>void)) } }} states
+   */
+  constructor(initial, states) {
+    this.#current = initial;
+    this.states = states;
+
+    // synthetically trigger _enter for the initial state.
+    this.#dispatch('_enter', {
+      from: null,
+      to: initial,
+      event: null,
+      args: []
+    });
+  }
+
+  /**
+   * Transition to new state
+   *
+   * @param {string} newState
+   * @param {string} event
+   * @param {any[]} [args]
+   */
+  #transition(newState, event, args) {
+    const metadata = { from: this.#current, to: newState, event, args };
+    this.#dispatch('_exit', metadata);
+    this.#current = newState;
+    this.#dispatch('_enter', metadata);
+  }
+
+  /**
+   * Dispatch an event
+   *
+   * @param {string} event
+   * @param {any[]} args
+   */
+  #dispatch(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 {
+          console.warn(
+            'Invalid metadata passed to lifecycle function of the FSM.'
+          );
+        }
+      } 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
+      );
+    }
+  }
+  /**
+   * Triggers a new event and returns the new state.
+   *
+   * @param {string} event
+   * @param {any[]} args
+   */
+  send(event, ...args) {
+    const newState = this.#dispatch(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;
+  }
+}

package/dist/classes/svelte/finite-state-machine/index.d.ts

@@ -0,0 +1 @@
+export { default as FiniteStateMachine } from "./FiniteStateMachine.svelte";

package/dist/classes/svelte/finite-state-machine/index.js

@@ -0,0 +1 @@
+export { default as FiniteStateMachine } from './FiniteStateMachine.svelte';

package/dist/classes/svelte/image/ImageLoader.svelte.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ImageLoader instance
+ * - Loads image data from network
+ * - The loading process can be monitored
+ */
+export default class ImageLoader extends NetworkLoader {
+    /**
+     * @param {object} _
+     * @param {ImageMeta|ImageMeta[]} _.imageMeta
+     */
+    constructor({ imageMeta }: {
+        imageMeta: ImageMeta | ImageMeta[];
+    });
+    get imageMeta(): import("./typedef.js").ImageMeta;
+    get url(): string;
+    #private;
+}
+export type ImageMeta = import("./typedef.js").ImageMeta;
+import { NetworkLoader } from '../network-loader/index.js';

package/dist/classes/svelte/image/ImageLoader.svelte.js

@@ -0,0 +1,45 @@
+/** @typedef {import('./typedef.js').ImageMeta} ImageMeta */
+
+import { toSingleImageMeta } from '../../../util/image/index.js';
+
+import {
+  NetworkLoader
+} from '../network-loader/index.js';
+
+/**
+ * ImageLoader instance
+ * - Loads image data from network
+ * - The loading process can be monitored
+ */
+export default class ImageLoader extends NetworkLoader {
+  /** @type {ImageMeta} */
+  #imageMeta;
+
+  /**
+   * @param {object} _
+   * @param {ImageMeta|ImageMeta[]} _.imageMeta
+   */
+  constructor({ imageMeta }) {
+    imageMeta = toSingleImageMeta(imageMeta);
+
+    super({ url: imageMeta.src });
+
+    this.#imageMeta = imageMeta;
+  }
+
+  get imageMeta() {
+    return this.#imageMeta;
+  }
+
+  get url() {
+    return this._url;
+  }
+
+  // /**
+  //  * Get object URL that can be used as src parameter of an HTML image
+  //  *
+  //  * @note the objectURL should be revoked when no longer used
+  //  */
+  // getObjectURL() {}
+  //
+} // end class