@hkdigital/lib-sveltekit 0.0.81 → 0.0.83

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

@@ -0,0 +1,30 @@
+/**
+ * AudioLoader instance
+ * - Loads audio data from network into an ArrayBuffer
+ * - Loaded data can be transferred to an AudioBufferSourceNode
+ */
+export default class AudioLoader extends NetworkLoader {
+    /**
+     * Get an AudioBufferSourceNode instance
+     *
+     * @note AudioBufferSourceNodes can play only once, a new source node
+     *       must be created otherwise
+     *
+     * @param {AudioContext} audioContext
+     *
+     * @returns {Promise<AudioBufferSourceNode>}
+     */
+    getAudioBufferSourceNode(audioContext: AudioContext): Promise<AudioBufferSourceNode>;
+    /**
+     * Gets data as AudioBuffer
+     * - Stores created AudioBuffer instance internally
+     * - Transfers data from internal ArrayBuffer, which will be detached
+     *
+     * @param {AudioContext} audioContext
+     *
+     * @returns {Promise<AudioBuffer>}
+     */
+    getAudioBuffer(audioContext: AudioContext): Promise<AudioBuffer>;
+    #private;
+}
+import { NetworkLoader } from '../network-loader/index.js';

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

@@ -0,0 +1,58 @@
+import {
+  NetworkLoader,
+  ERROR_NOT_LOADED,
+  ERROR_TRANSFERRED
+} from '../network-loader/index.js';
+
+/**
+ * AudioLoader instance
+ * - Loads audio data from network into an ArrayBuffer
+ * - Loaded data can be transferred to an AudioBufferSourceNode
+ */
+export default class AudioLoader extends NetworkLoader {
+  /** @type {AudioBuffer|null} */
+  #audioBuffer = null;
+
+  /**
+   * Get an AudioBufferSourceNode instance
+   *
+   * @note AudioBufferSourceNodes can play only once, a new source node
+   *       must be created otherwise
+   *
+   * @param {AudioContext} audioContext
+   *
+   * @returns {Promise<AudioBufferSourceNode>}
+   */
+  async getAudioBufferSourceNode(audioContext) {
+    if (!this.#audioBuffer) {
+      this.#audioBuffer = await this.getAudioBuffer(audioContext);
+    }
+
+    return new AudioBufferSourceNode(audioContext, {
+      buffer: this.#audioBuffer
+    });
+  }
+
+  /**
+   * Gets data as AudioBuffer
+   * - Stores created AudioBuffer instance internally
+   * - Transfers data from internal ArrayBuffer, which will be detached
+   *
+   * @param {AudioContext} audioContext
+   *
+   * @returns {Promise<AudioBuffer>}
+   */
+  async getAudioBuffer(audioContext) {
+    if (!this._buffer) {
+      throw new Error(ERROR_NOT_LOADED);
+    }
+
+    if (this._buffer.detached) {
+      throw new Error(ERROR_TRANSFERRED);
+    }
+
+    this.#audioBuffer = await audioContext.decodeAudioData(this._buffer);
+
+    return this.#audioBuffer;
+  }
+} // end class

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

@@ -0,0 +1,52 @@
+/**
+ * @typedef {object} SourceConfig
+ * // property ...
+ */
+/**
+ * @typedef {object} MemorySource
+ * @property {string} label
+ * @property {AudioLoader} audioLoader
+ * @property {SourceConfig} [config]
+ */
+export default class AudioScene {
+    state: string;
+    loaded: boolean;
+    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
+     *
+     * @param {AudioContext} audioContext
+     */
+    load(audioContext: AudioContext): void;
+    /**
+     * Get a source that can be used to plat the audio once
+     *
+     * @param {string} label
+     */
+    getSourceNode(label: string): Promise<AudioBufferSourceNode>;
+    #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,282 @@
+import * as expect from '@hkdigital/lib-sveltekit/util/expect/index.js';
+
+import {
+  LoadingStateMachine,
+  STATE_INITIAL,
+  STATE_LOADING,
+  STATE_UNLOADING,
+  STATE_LOADED,
+  STATE_CANCELLED,
+  STATE_ERROR,
+  LOAD,
+  // CANCEL,
+  ERROR,
+  LOADED,
+  UNLOAD,
+  INITIAL
+} 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;
+  });
+
+  /** @type {AudioContext|null} */
+  #audioContext = 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
+   *
+   * @param {object} _
+   * @param {AudioContext} _.audioContext
+   */
+  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.log(`All [${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.log('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
+   *
+   * @param {AudioContext} audioContext
+   */
+  load(audioContext) {
+    this.#audioContext = audioContext;
+    // console.log(123);
+    this.#state.send(LOAD);
+
+    // FIXME: in unit test when moved to startloading it hangs!
+
+    for (const { audioLoader } of this.#memorySources) {
+      audioLoader.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 a source that can be used to plat the audio once
+   *
+   * @param {string} label
+   */
+  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(
+      // @ts-ignore
+      this.#audioContext
+    );
+
+    // @ts-ignore
+    sourceNode.connect(this.#audioContext.destination);
+
+    // Clean up
+    sourceNode.onended = () => {
+      // console.log(`Source [${label}] ended `);
+      sourceNode.disconnect();
+    };
+
+    return sourceNode;
+  }
+
+  /**
+   * 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`);
+  }
+
+  // connect
+  // play
+
+  // source.connect(audioContext.destination);
+  // source.loop = true;
+  // source.start();
+
+  // /**
+  //  * Get the source identified by the specified label
+  //  *
+  //  * @param {string} label
+  //  */
+  // async getBufferSourceNode(label) {
+  //   // expect.notEmptyString( label );
+
+  //   for (const source of this.#memorySources) {
+  //     if (label === source.label) {
+  //       if (!source.bufferSourceNode) {
+  //         source.bufferSourceNode =
+  //           await source.AudioLoader.transferToBufferSource(this.#audioContext);
+  //       }
+
+  //       return source.bufferSourceNode;
+  //     }
+  //   }
+  // }
+
+  // async connectSourceToDestination(label) {
+  //   const source = await this.getBufferSourceNode(label);
+
+  //   if (source) {
+  //     source.connect(this.#audioContext.destination);
+  //   }
+  // }
+}

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 '@hkdigital/lib-sveltekit/constants/http/index.js';
+
+import { AUDIO_WAV } from '@hkdigital/lib-sveltekit/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/final-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/final-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/final-state-machine/index.d.ts

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

package/dist/classes/svelte/final-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,8 @@
+/**
+ * ImageLoader instance
+ * - Loads image data from network
+ * - The loading process can be monitored
+ */
+export default class ImageLoader extends NetworkLoader {
+}
+import { NetworkLoader } from '../network-loader/index.js';

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

@@ -0,0 +1,12 @@
+import {
+  NetworkLoader,
+  ERROR_NOT_LOADED,
+  ERROR_TRANSFERRED
+} from '../network-loader/index.js';
+
+/**
+ * ImageLoader instance
+ * - Loads image data from network
+ * - The loading process can be monitored
+ */
+export default class ImageLoader extends NetworkLoader {} // end class