@hkdigital/lib-core 0.3.1

package/dist/classes/svelte/loading-state-machine/LoadingStateMachine.svelte.js

@@ -0,0 +1,109 @@
+//import { FiniteStateMachine } from 'runed';
+
+import { FiniteStateMachine } from '../finite-state-machine/index.js';
+
+import {
+  // > States
+  STATE_INITIAL,
+  STATE_LOADING,
+  STATE_UNLOADING,
+  STATE_LOADED,
+  STATE_CANCELLED,
+  STATE_ERROR,
+
+  // > Signals
+  INITIAL,
+  LOAD,
+  CANCEL,
+  ERROR,
+  LOADED,
+  UNLOAD
+} from './constants.js';
+
+/**
+ * extends FiniteStateMachine<StatesT, EventsT>
+ */
+export default class LoadingStateMachine extends FiniteStateMachine {
+  // Inherited from parent class (getter)
+  // current = $state(<string>)
+
+  /** @type {Error|null} */
+  #error = null;
+
+  /** @type {(( state: string )=>void)|null} */
+  onenter = null;
+
+  constructor() {
+    let superCalled = false;
+    super(STATE_INITIAL, {
+      [STATE_INITIAL]: {
+        _enter: () => {
+          if (superCalled) {
+            this.onenter?.(STATE_INITIAL);
+          }
+          superCalled = true;
+        },
+        [LOAD]: STATE_LOADING
+      },
+      [STATE_LOADING]: {
+        _enter: () => {
+          // console.log('LoadingStateMachine: enter LOADING');
+          this.onenter?.(STATE_LOADING);
+        },
+        [CANCEL]: STATE_CANCELLED,
+        [ERROR]: STATE_ERROR,
+        [LOADED]: STATE_LOADED
+      },
+      [STATE_LOADED]: {
+        _enter: () => {
+          // console.log('LoadingStateMachine: enter LOADED');
+          this.onenter?.(STATE_LOADED);
+        },
+        [LOAD]: STATE_LOADING,
+        [UNLOAD]: STATE_UNLOADING
+      },
+      [STATE_UNLOADING]: {
+        _enter: () => {
+          this.onenter?.(STATE_UNLOADING);
+        },
+        [ERROR]: STATE_ERROR,
+        [INITIAL]: STATE_INITIAL
+      },
+      [STATE_CANCELLED]: {
+        _enter: () => {
+          this.onenter?.(STATE_CANCELLED);
+        },
+        [LOAD]: STATE_LOADING,
+        [UNLOAD]: STATE_UNLOADING
+      },
+      [STATE_ERROR]: {
+        _enter: ({ /*from, to, event,*/ args }) => {
+          if (args[0] instanceof Error) {
+            this.#error = args[0];
+          } else {
+            const tmp = args[0]?.error;
+            if (tmp instanceof Error) {
+              this.#error = tmp;
+            } else if (typeof tmp === 'string') {
+              this.#error = new Error(tmp);
+            } else {
+              this.#error = new Error('The state machine entered STATE_ERROR');
+            }
+          }
+
+          this.onenter?.(STATE_CANCELLED);
+        },
+        _leave: () => {
+          this.#error = null;
+        },
+        [LOAD]: STATE_LOADING,
+        [UNLOAD]: STATE_UNLOADING
+      }
+    });
+  }
+
+  /** The last error */
+  get error() {
+    return this.#error;
+  }
+}

package/dist/classes/svelte/loading-state-machine/constants.d.ts

@@ -0,0 +1,12 @@
+export const STATE_INITIAL: "initial";
+export const STATE_LOADING: "loading";
+export const STATE_UNLOADING: "unloading";
+export const STATE_LOADED: "loaded";
+export const STATE_CANCELLED: "cancelled";
+export const STATE_ERROR: "error";
+export const INITIAL: "initial";
+export const LOAD: "load";
+export const CANCEL: "cancel";
+export const ERROR: "error";
+export const LOADED: "loaded";
+export const UNLOAD: "unload";

package/dist/classes/svelte/loading-state-machine/constants.js

@@ -0,0 +1,16 @@
+export const STATE_INITIAL = 'initial';
+export const STATE_LOADING = 'loading';
+export const STATE_UNLOADING = 'unloading';
+export const STATE_LOADED = 'loaded';
+
+export const STATE_CANCELLED = 'cancelled';
+export const STATE_ERROR = 'error';
+
+// > Signals
+
+export const INITIAL = 'initial';
+export const LOAD = 'load';
+export const CANCEL = 'cancel';
+export const ERROR = 'error';
+export const LOADED = 'loaded';
+export const UNLOAD = 'unload';

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

@@ -0,0 +1,2 @@
+export { default as LoadingStateMachine } from "./LoadingStateMachine.svelte.js";
+export * from "./constants.js";

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

@@ -0,0 +1,3 @@
+export { default as LoadingStateMachine } from './LoadingStateMachine.svelte.js';
+
+export * from './constants.js';

package/dist/classes/svelte/network-loader/NetworkLoader.svelte.d.ts

@@ -0,0 +1,91 @@
+/**
+ * NetworkLoader instance
+ * - Loads network data from network into an ArrayBuffer
+ * - Loaded data can be transferred to an AudioBufferSourceNode
+ */
+export default class NetworkLoader {
+    /**
+     * Construct NetworkLoader
+     *
+     * @param {object} _
+     * @param {string} _.url
+     */
+    constructor({ url }: {
+        url: string;
+    });
+    _state: LoadingStateMachine;
+    state: any;
+    initial: boolean;
+    loaded: boolean;
+    /** @type {string|null} */
+    _url: string | null;
+    /** @type {number}  */
+    _bytesLoaded: number;
+    /** @type {number}  */
+    _size: number;
+    /**
+     * Response headers
+     * @type {Headers|null}
+     */
+    _headers: Headers | null;
+    /** @type {ArrayBuffer|null} */
+    _buffer: ArrayBuffer | null;
+    /** @type {import('./typedef.js').LoadingProgress} */
+    progress: import("./typedef.js").LoadingProgress;
+    /** @type {null|(()=>void)} */
+    _abortLoading: null | (() => void);
+    /**
+     * Start loading all network data
+     */
+    load(): void;
+    /**
+     * Unoad all network data
+     */
+    unload(): void;
+    /**
+     * Get network data size in bytes
+     * - Info comes from the content length response header
+     *
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * Get content type from response header
+     *
+     * @returns {string|null}
+     */
+    getContentType(): string | null;
+    /**
+     * Get data as array buffer
+     *
+     * @note If the data has been transferred, the data is
+     *       no longer available as ArrayBuffer
+     *
+     * @returns {ArrayBuffer}
+     */
+    getArrayBuffer(): ArrayBuffer;
+    /**
+     * Get data as Uint8Array
+     *
+     * @returns {Uint8Array}
+     */
+    getUint8Array(): Uint8Array;
+    /**
+     * Get data as Blob
+     * - The Blob type is set using the response header
+     *   content type
+     *
+     * @returns {Blob}
+     */
+    getBlob(): Blob;
+    /**
+     * Get object URL
+     *
+     * @note the objectURL should be revoked when no longer used
+     *
+     * @returns {string}
+     */
+    getObjectURL(): string;
+    #private;
+}
+import { LoadingStateMachine } from '../loading-state-machine/index.js';

package/dist/classes/svelte/network-loader/NetworkLoader.svelte.js

@@ -0,0 +1,338 @@
+import { CONTENT_TYPE } from '../../../constants/http/index.js';
+
+import {
+  LoadingStateMachine,
+  STATE_INITIAL,
+  STATE_LOADING,
+  STATE_UNLOADING,
+  STATE_LOADED,
+  STATE_CANCELLED,
+  STATE_ERROR,
+  LOAD,
+  ERROR,
+  LOADED,
+  UNLOAD,
+  INITIAL
+} from '../loading-state-machine/index.js';
+
+import * as expect from '../../../util/expect/index.js';
+
+import { httpGet, loadResponseBuffer } from '../../../util/http/index.js';
+
+import { ERROR_NOT_LOADED, ERROR_TRANSFERRED } from './constants.js';
+
+/**
+ * NetworkLoader instance
+ * - Loads network data from network into an ArrayBuffer
+ * - Loaded data can be transferred to an AudioBufferSourceNode
+ */
+export default class NetworkLoader {
+  // _state = $state(new LoadingStateMachine());
+  _state = new LoadingStateMachine();
+
+  state = $derived.by(() => {
+    return this._state.current;
+  });
+
+  initial = $derived.by(() => {
+    return this._state.current === STATE_INITIAL;
+  });
+
+  loaded = $derived.by(() => {
+    return this._state.current === STATE_LOADED;
+  });
+
+  /** @type {string|null} */
+  _url = null;
+
+  /** @type {number}  */
+  _bytesLoaded = $state(0);
+
+  /** @type {number}  */
+  _size = $state(0);
+
+  /**
+   * Response headers
+   * @type {Headers|null}
+   */
+  _headers = $state(null);
+
+  /** @type {ArrayBuffer|null} */
+  _buffer = null;
+
+  // Export state property as readonly
+
+  /** @type {import('./typedef.js').LoadingProgress} */
+  progress = $derived.by(() => {
+    return {
+      bytesLoaded: this._bytesLoaded,
+      size: this._size,
+      loaded: this.loaded
+    };
+  });
+
+  /** @type {null|(()=>void)} */
+  _abortLoading = null;
+
+  /**
+   * Construct NetworkLoader
+   *
+   * @param {object} _
+   * @param {string} _.url
+   */
+  constructor({ url }) {
+    expect.absOrRelUrl(url);
+
+    this._url = url;
+
+    const state = this._state;
+    // const progress = this.progress;
+
+    //
+    // ISSUE: $effect is not triggered by  this._state changes,
+    //        using onenter instead
+    //
+    this._state.onenter = () => {
+      switch (state.current) {
+        case STATE_LOADING:
+          {
+            // console.log('**** NetworkLoader:loading');
+            this.#load();
+          }
+          break;
+
+        case STATE_UNLOADING:
+          {
+            // console.log('NetworkLoader:unloading');
+            this.#unload();
+          }
+          break;
+
+        case STATE_LOADED:
+          {
+            // console.debug('NetworkLoader:loaded', $state.snapshot(state));
+
+            // setTimeout(() => {
+            //   console.debug(
+            //     'NetworkLoader:loaded',
+            //     $state.snapshot(state),
+            //     progress
+            //   );
+            // }, 500);
+
+            // Abort function is no longer needed
+            this._abortLoading = null;
+          }
+          break;
+
+        case STATE_CANCELLED:
+          {
+            // console.log('NetworkLoader:cancelled');
+            // TODO
+          }
+          break;
+
+        case STATE_ERROR:
+          {
+            console.log('NetworkLoader:error', state.error);
+          }
+          break;
+      } // end switch
+    };
+  }
+
+  /**
+   * Start loading all network data
+   */
+  load() {
+    // console.debug('NetworkLoader: load() called');
+    this._state.send(LOAD);
+  }
+
+  /**
+   * Unoad all network data
+   */
+  unload() {
+    this._state.send(UNLOAD);
+  }
+
+  /**
+   * Get network data size in bytes
+   * - Info comes from the content length response header
+   *
+   * @returns {number}
+   */
+  get size() {
+    return this._size;
+  }
+
+  /**
+   * Get content type from response header
+   *
+   * @returns {string|null}
+   */
+  getContentType() {
+    if (!this._headers) {
+      throw new Error(ERROR_NOT_LOADED);
+    }
+
+    return this._headers.get(CONTENT_TYPE);
+  }
+
+  /**
+   * Get data as array buffer
+   *
+   * @note If the data has been transferred, the data is
+   *       no longer available as ArrayBuffer
+   *
+   * @returns {ArrayBuffer}
+   */
+  getArrayBuffer() {
+    if (!this._buffer) {
+      throw new Error(ERROR_NOT_LOADED);
+    }
+
+    if (this._buffer.detached) {
+      throw new Error(ERROR_TRANSFERRED);
+    }
+
+    return this._buffer;
+  }
+
+  /**
+   * Get data as Uint8Array
+   *
+   * @returns {Uint8Array}
+   */
+  getUint8Array() {
+    return new Uint8Array(this.getArrayBuffer());
+  }
+
+  /**
+   * Get data as Blob
+   * - The Blob type is set using the response header
+   *   content type
+   *
+   * @returns {Blob}
+   */
+  getBlob() {
+    const type = this.getContentType();
+
+    const options = {};
+
+    if (type) {
+      options.type = type;
+    }
+
+    return new Blob([this.getArrayBuffer()], options);
+  }
+
+  /**
+   * Get object URL
+   *
+   * @note the objectURL should be revoked when no longer used
+   *
+   * @returns {string}
+   */
+  getObjectURL() {
+    //
+    // Example usage:
+    //
+    // $effect(() => {
+    //   if (loader.loaded) {
+    //     // @ts-ignore
+    //     objectUrl = loader.getObjectURL();
+    //   }
+    //
+    //   return () => {
+    //     if (objectUrl) {
+    //       URL.revokeObjectURL(objectUrl);
+    //       objectUrl = null;
+    //     }
+    //   };
+    // });
+
+    return URL.createObjectURL(this.getBlob());
+  }
+
+  /**
+   * Internal method that initializes the loading process
+   * and transitions to state LOADED when done
+   */
+  async #load() {
+    try {
+      // console.log('>>>> NetworkLoader:#load', this._url);
+
+      if (this._abortLoading) {
+        // console.log('Abort loading');
+        this._abortLoading();
+        this._abortLoading = null;
+      }
+
+      /** @type {()=>void} */
+      let abortRequest;
+
+      /**
+       * @param {object} _
+       * @param {()=>void} _.abort
+       */
+      const requestHandler = ({ abort }) => {
+        abortRequest = abort;
+      };
+
+      this._bytesLoaded = 0;
+      this._size = 0;
+
+      // @ts-ignore
+      const response = await httpGet({ url: this._url, requestHandler });
+
+      this._headers = response.headers;
+
+      // console.log('headers', this._headers);
+      // console.log('response', response);
+
+      const { bufferPromise, abort: abortLoadBody } = loadResponseBuffer(
+        response,
+        ({ bytesLoaded, size }) => {
+          this._bytesLoaded = bytesLoaded;
+          this._size = size;
+        }
+      );
+
+      this._abortLoading = () => {
+        abortRequest();
+        abortLoadBody();
+      };
+
+      this._buffer = await bufferPromise;
+
+      // console.debug('#load', this._buffer, this._bytesLoaded);
+
+      this._state.send(LOADED);
+    } catch (e) {
+      this._state.send(ERROR, e);
+    }
+  }
+
+  /**
+   * Internal method that initializes the unloading process
+   * and transitions to state INITIAL when done
+   */
+  async #unload() {
+    try {
+      if (this._abortLoading) {
+        this._abortLoading();
+        this._abortLoading = null;
+      }
+
+      this._bytesLoaded = 0;
+      this._size = 0;
+      this._headers = null;
+      this._buffer = null;
+
+      this._state.send(INITIAL);
+    } catch (e) {
+      this._state.send(ERROR, e);
+    }
+  }
+} // end class

package/dist/classes/svelte/network-loader/constants.d.ts

@@ -0,0 +1,2 @@
+export const ERROR_NOT_LOADED: "No data loaded yet";
+export const ERROR_TRANSFERRED: "Buffer data has been transferred and is no longer available";

package/dist/classes/svelte/network-loader/constants.js

@@ -0,0 +1,3 @@
+export const ERROR_NOT_LOADED = 'No data loaded yet';
+export const ERROR_TRANSFERRED =
+  'Buffer data has been transferred and is no longer available';

package/dist/classes/svelte/network-loader/index.d.ts

@@ -0,0 +1,2 @@
+export { default as NetworkLoader } from "./NetworkLoader.svelte.js";
+export * from "./constants.js";

package/dist/classes/svelte/network-loader/index.js

@@ -0,0 +1,3 @@
+export { default as NetworkLoader } from './NetworkLoader.svelte.js';
+
+export * from './constants.js';

package/dist/classes/svelte/network-loader/mocks.d.ts

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

package/dist/classes/svelte/network-loader/mocks.js

@@ -0,0 +1,30 @@
+import { CONTENT_TYPE, CONTENT_LENGTH } from '../../../constants/http/index.js';
+
+import { OCTET_STREAM } from '../../../constants/mime/application.js';
+
+const BASE64_DATA =
+  'UklGRnwAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YVgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA';
+
+/**
+ * Create a response value that can be used by a mocked
+ * fetch function
+ *
+ * @returns {Response}
+ */
+export function createDataResponse(/* data , options */) {
+  const binaryString = atob(BASE64_DATA);
+  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]: OCTET_STREAM,
+      [CONTENT_LENGTH]: String(bytes.length)
+    })
+  });
+
+  return response;
+}

package/dist/classes/svelte/network-loader/typedef.d.ts

@@ -0,0 +1,7 @@
+declare const _default: {};
+export default _default;
+export type LoadingProgress = {
+    bytesLoaded: number;
+    size: number;
+    loaded: boolean;
+};

package/dist/classes/svelte/network-loader/typedef.js

@@ -0,0 +1,8 @@
+/**
+ * @typedef {Object} LoadingProgress
+ * @property {number} bytesLoaded
+ * @property {number} size
+ * @property {boolean} loaded
+ */
+
+export default {};

package/dist/components/area/HkArea.svelte

@@ -0,0 +1,49 @@
+<script>
+  /**
+   * Area component
+   * An area is actually a DIV that can be styled and can contain content
+   *
+   * Following component guidelines from Skeleton
+   * @see https://next.skeleton.dev/docs/resources/contribute/components
+   */
+
+  /**
+   * @type {{
+   *   base?: string,
+   *   bg?: string,
+   *   padding?: string,
+   *   margin?: string,
+   *   classes?: string,
+   *   style?: string,
+   *   children: import('svelte').Snippet
+   * } & { [attr: string]: any }}
+   */
+  let {
+    // Style
+    base,
+    bg,
+    padding,
+    margin,
+    classes,
+    style,
+
+    // Snippets
+    children,
+
+    // DOM Element
+    domElem = $bindable(),
+
+    // Attributes
+    ...attrs
+  } = $props();
+</script>
+
+<div
+  data-hk-area
+  class="{base} {bg} {padding} {margin} {classes}"
+  bind:this={domElem}
+  {style}
+  {...attrs}
+>
+  {@render children()}
+</div>