@hkdigital/lib-core 0.3.9 → 0.3.11

package/dist/{util → network}/http/typedef.js

@@ -1,93 +1,93 @@
-/**
- * @typedef {Object} HttpRequestOptions
- * @property {string|URL} url URL string or URL object for the request
- * @property {string} [method] HTTP method to use (GET, POST, etc.)
- *
- * @property {Object|URLSearchParams} [urlSearchParams]
- *   Parameters to add to the URL
- *
- * @property {*} [body] Request body (for POST, PUT, etc.)
- * @property {Object} [headers] HTTP headers as name-value pairs
- * @property {boolean} [withCredentials] Whether to include credentials
- * @property {number} [timeoutMs] Request timeout in milliseconds
- * @property {Function} [requestHandler] Handler for abort/timeout control
- * @property {string} [mode] CORS mode ('cors', 'no-cors', 'same-origin')
- * @property {string} [cache] Cache mode ('default', 'no-cache', etc.)
- * @property {string} [redirect] Redirect mode ('follow', 'error', 'manual')
- * @property {string} [referrerPolicy] Referrer policy
- * @property {boolean} [cacheEnabled] Enable or disabled automatic caching
- */
-
-/**
- * @typedef {Object} RequestHandlerParams
- *
- * @property {AbortController} controller
- *   The AbortController instance for this request
- *
- * @property {(reason?: Error) => void} abort Function to abort the request
- * @property {(delayMs: number) => void} timeout Function to set a timeout
- */
-
-/**
- * @callback RequestHandler
- * @param {RequestHandlerParams} params Parameters for controlling the request
- * @returns {void}
- */
-
-/**
- * @typedef {Object} JsonGetOptions
- * @property {string|URL} url URL string or URL object for the request
- *
- * @property {Object|URLSearchParams} [urlSearchParams]
- *   Parameters to add to the URL
- *
- * @property {Object} [headers] HTTP headers as name-value pairs
- * @property {boolean} [withCredentials] Whether to include credentials
- * @property {number} [timeoutMs] Request timeout in milliseconds
- * @property {RequestHandler} [requestHandler] Handler for abort/timeout control
- * @property {string} [mode] CORS mode ('cors', 'no-cors', 'same-origin')
- * @property {string} [cache] Cache mode ('default', 'no-cache', etc.)
- * @property {string} [redirect] Redirect mode ('follow', 'error', 'manual')
- * @property {string} [referrerPolicy] Referrer policy
- * @property {boolean} [cacheEnabled] Enable or disabled automatic caching
- */
-
-/**
- * @typedef {Object} JsonPostOptions
- * @property {string|URL} url URL string or URL object for the request
- * @property {*} body Request body (will be sent as JSON)
- *
- * @property {Object|URLSearchParams} [urlSearchParams]
- *   Parameters to add to the URL
- *
- * @property {Object} [headers] HTTP headers as name-value pairs
- * @property {boolean} [withCredentials] Whether to include credentials
- * @property {number} [timeoutMs] Request timeout in milliseconds
- * @property {RequestHandler} [requestHandler] Handler for abort/timeout control
- * @property {string} [mode] CORS mode ('cors', 'no-cors', 'same-origin')
- * @property {string} [cache] Cache mode ('default', 'no-cache', etc.)
- * @property {string} [redirect] Redirect mode ('follow', 'error', 'manual')
- * @property {string} [referrerPolicy] Referrer policy
- * @property {boolean} [cacheEnabled] Enable or disabled automatic caching
- */
-
-/**
- * @typedef {Object} StaleInfo
- * @property {boolean} isStale Whether the response contains stale data
- *
- * @property {Promise<Response>|null} fresh
- *   Promise that resolves to fresh data (if available)
- *
- * @property {number} timestamp When the response was originally cached
- * @property {number|null} expires When the response expires
- */
-
-/**
- * @typedef {Response} ResponseWithStale
- * @property {boolean} isStale Whether this response contains stale data
- *
- * @property {Promise<Response>|null} fresh
- *   Promise for fresh data if this is stale
- */
-
-export {};
+/**
+ * @typedef {Object} HttpRequestOptions
+ * @property {string|URL} url URL string or URL object for the request
+ * @property {string} [method] HTTP method to use (GET, POST, etc.)
+ *
+ * @property {Object|URLSearchParams} [urlSearchParams]
+ *   Parameters to add to the URL
+ *
+ * @property {*} [body] Request body (for POST, PUT, etc.)
+ * @property {Object} [headers] HTTP headers as name-value pairs
+ * @property {boolean} [withCredentials] Whether to include credentials
+ * @property {number} [timeoutMs] Request timeout in milliseconds
+ * @property {Function} [requestHandler] Handler for abort/timeout control
+ * @property {string} [mode] CORS mode ('cors', 'no-cors', 'same-origin')
+ * @property {string} [cache] Cache mode ('default', 'no-cache', etc.)
+ * @property {string} [redirect] Redirect mode ('follow', 'error', 'manual')
+ * @property {string} [referrerPolicy] Referrer policy
+ * @property {boolean} [cacheEnabled] Enable or disabled automatic caching
+ */
+
+/**
+ * @typedef {Object} RequestHandlerParams
+ *
+ * @property {AbortController} controller
+ *   The AbortController instance for this request
+ *
+ * @property {(reason?: Error) => void} abort Function to abort the request
+ * @property {(delayMs: number) => void} timeout Function to set a timeout
+ */
+
+/**
+ * @callback RequestHandler
+ * @param {RequestHandlerParams} params Parameters for controlling the request
+ * @returns {void}
+ */
+
+/**
+ * @typedef {Object} JsonGetOptions
+ * @property {string|URL} url URL string or URL object for the request
+ *
+ * @property {Object|URLSearchParams} [urlSearchParams]
+ *   Parameters to add to the URL
+ *
+ * @property {Object} [headers] HTTP headers as name-value pairs
+ * @property {boolean} [withCredentials] Whether to include credentials
+ * @property {number} [timeoutMs] Request timeout in milliseconds
+ * @property {RequestHandler} [requestHandler] Handler for abort/timeout control
+ * @property {string} [mode] CORS mode ('cors', 'no-cors', 'same-origin')
+ * @property {string} [cache] Cache mode ('default', 'no-cache', etc.)
+ * @property {string} [redirect] Redirect mode ('follow', 'error', 'manual')
+ * @property {string} [referrerPolicy] Referrer policy
+ * @property {boolean} [cacheEnabled] Enable or disabled automatic caching
+ */
+
+/**
+ * @typedef {Object} JsonPostOptions
+ * @property {string|URL} url URL string or URL object for the request
+ * @property {*} body Request body (will be sent as JSON)
+ *
+ * @property {Object|URLSearchParams} [urlSearchParams]
+ *   Parameters to add to the URL
+ *
+ * @property {Object} [headers] HTTP headers as name-value pairs
+ * @property {boolean} [withCredentials] Whether to include credentials
+ * @property {number} [timeoutMs] Request timeout in milliseconds
+ * @property {RequestHandler} [requestHandler] Handler for abort/timeout control
+ * @property {string} [mode] CORS mode ('cors', 'no-cors', 'same-origin')
+ * @property {string} [cache] Cache mode ('default', 'no-cache', etc.)
+ * @property {string} [redirect] Redirect mode ('follow', 'error', 'manual')
+ * @property {string} [referrerPolicy] Referrer policy
+ * @property {boolean} [cacheEnabled] Enable or disabled automatic caching
+ */
+
+/**
+ * @typedef {Object} StaleInfo
+ * @property {boolean} isStale Whether the response contains stale data
+ *
+ * @property {Promise<Response>|null} fresh
+ *   Promise that resolves to fresh data (if available)
+ *
+ * @property {number} timestamp When the response was originally cached
+ * @property {number|null} expires When the response expires
+ */
+
+/**
+ * @typedef {Response} ResponseWithStale
+ * @property {boolean} isStale Whether this response contains stale data
+ *
+ * @property {Promise<Response>|null} fresh
+ *   Promise for fresh data if this is stale
+ */
+
+export {};

package/dist/{util → network}/http/url.js

@@ -1,52 +1,52 @@
-import { TypeOrValueError } from '../../errors/index.js';
-
-/**
- * Returns an URL instance
- * - Prefixes the URL with the current orign if the url is relative
- *
- * @param {string|URL} url
- *
- * @returns {URL} url instance
- */
-export function toURL(url) {
-	if (typeof url === 'string') {
-		if (hasProtocol(url)) {
-			return new URL(url);
-		} else {
-			// Use location.origin aas baseUrl
-			return new URL(url, location.origin);
-		}
-	} else if (!(url instanceof URL)) {
-		throw new TypeOrValueError('Missing or invalid parameter [url]');
-	}
-
-	// already an URL instance
-	return url;
-}
-
-/**
- * Checks if the url starts with a protocol specification such
- * as https://
- *
- * @param {string} url
- *
- * @return {boolean} true if the value looks like an array
- */
-export function hasProtocol(url) {
-	if (/^([a-zA-Z]{2,})s?:\/\//.test(url)) {
-		return true;
-	}
-
-	return false;
-}
-
-/**
- * Convert an url to an absolute url and apply decodeURI to
- * convert URI encoded characters to normal characters
- *
- * @param {string|URL} url
- */
-export function href(url) {
-	const urlObj = toURL(url);
-	return decodeURI(urlObj.href);
-}
+import { TypeOrValueError } from '../../errors/index.js';
+
+/**
+ * Returns an URL instance
+ * - Prefixes the URL with the current orign if the url is relative
+ *
+ * @param {string|URL} url
+ *
+ * @returns {URL} url instance
+ */
+export function toURL(url) {
+	if (typeof url === 'string') {
+		if (hasProtocol(url)) {
+			return new URL(url);
+		} else {
+			// Use location.origin aas baseUrl
+			return new URL(url, location.origin);
+		}
+	} else if (!(url instanceof URL)) {
+		throw new TypeOrValueError('Missing or invalid parameter [url]');
+	}
+
+	// already an URL instance
+	return url;
+}
+
+/**
+ * Checks if the url starts with a protocol specification such
+ * as https://
+ *
+ * @param {string} url
+ *
+ * @return {boolean} true if the value looks like an array
+ */
+export function hasProtocol(url) {
+	if (/^([a-zA-Z]{2,})s?:\/\//.test(url)) {
+		return true;
+	}
+
+	return false;
+}
+
+/**
+ * Convert an url to an absolute url and apply decodeURI to
+ * convert URI encoded characters to normal characters
+ *
+ * @param {string|URL} url
+ */
+export function href(url) {
+	const urlObj = toURL(url);
+	return decodeURI(urlObj.href);
+}

package/dist/network/http.d.ts

@@ -0,0 +1,6 @@
+export * from "./http/headers.js";
+export * from "./http/errors.js";
+export * from "./http/url.js";
+export * from "./http/response.js";
+export * from "./http/http-request.js";
+export * from "./http/json-request.js";

package/dist/network/http.js

@@ -0,0 +1,6 @@
+export * from './http/headers.js';
+export * from './http/errors.js';
+export * from './http/url.js';
+export * from './http/response.js';
+export * from './http/http-request.js';
+export * from './http/json-request.js';

package/dist/network/loaders/README.md

@@ -0,0 +1,255 @@
+# Media Loaders
+
+Advanced media loading and processing classes for audio and images with loading state management, streaming support, and responsive image handling.
+
+## Quick Start
+
+```javascript
+import * as image from '$lib/network/loaders.js';
+import * as audio from '$lib/network/loaders.js';
+```
+
+## Image Loaders
+
+### ImageLoader
+
+Loads single images with chunked streaming and loading states.
+
+```javascript
+import { ImageLoader } from '$lib/network/loaders.js';
+
+// Create image loader with single image or responsive variants
+const imageSource = { src: '/path/to/image.jpg', width: 800, height: 600 };
+const imageLoader = new ImageLoader({ imageSource });
+
+// Start loading
+imageLoader.load();
+
+// Access loading states
+console.log(imageLoader.loading); // true while loading
+console.log(imageLoader.loaded);  // true when complete
+console.log(imageLoader.error);   // error object if failed
+
+// Get object URL when loaded
+if (imageLoader.loaded) {
+  const objectURL = imageLoader.getObjectURL();
+  // Use objectURL in img src
+}
+```
+
+### ImageVariantsLoader
+
+Loads responsive image variants, automatically selecting the best size for container dimensions.
+
+```javascript
+import { ImageVariantsLoader } from '$lib/network/loaders.js';
+
+const loader = new ImageVariantsLoader();
+
+// Load responsive variants
+const imageSource = [
+  { src: '/image-400.jpg', width: 400, height: 300 },
+  { src: '/image-800.jpg', width: 800, height: 600 },
+  { src: '/image-1200.jpg', width: 1200, height: 900 }
+];
+
+await loader.load({
+  imageSource,
+  containerWidth: 600,
+  containerHeight: 400,
+  fit: 'cover', // or 'contain', 'fill'
+  devicePixelRatio: window.devicePixelRatio
+});
+```
+
+### ImageScene
+
+High-level loader that manages multiple image sources with loading states.
+
+```javascript
+import { ImageScene } from '$lib/network/loaders.js';
+
+const imageScene = new ImageScene();
+
+// Configure multiple image sources
+imageScene.updateSources({
+  'thumbnail': { src: '/thumb.jpg', width: 200, height: 150 },
+  'full': { src: '/full.jpg', width: 1920, height: 1080 }
+});
+
+// Load specific source
+imageScene.load('full');
+
+// Monitor state changes
+imageScene.state; // 'initial', 'loading', 'loaded', 'error'
+```
+
+## Audio Components
+
+### AudioLoader
+
+Loads audio files with streaming support and loading state management.
+
+```javascript
+import { AudioLoader } from '$lib/network/loaders.js';
+
+const audioLoader = new AudioLoader({
+  url: '/path/to/audio.mp3'
+});
+
+// Start loading
+audioLoader.load();
+
+// Access audio data when loaded
+if (audioLoader.loaded) {
+  const audioBuffer = audioLoader.getAudioBuffer();
+  const objectURL = audioLoader.getObjectURL();
+}
+```
+
+### AudioScene
+
+Manages multiple audio sources with scene-based loading.
+
+```javascript
+import { AudioScene } from '$lib/network/loaders.js';
+
+const audioScene = new AudioScene();
+
+// Configure audio sources
+audioScene.updateSources({
+  'background': { url: '/bg-music.mp3' },
+  'sfx': { url: '/sound-effect.wav' }
+});
+
+// Load and play audio
+audioScene.load('background');
+```
+
+## Image Utilities
+
+### Responsive Image Helpers
+
+```javascript
+import { 
+  toSingleImageMeta, 
+  calculateEffectiveWidth 
+} from '$lib/network/loaders/image/utils/index.js';
+
+// Extract single image from array of variants
+const imageMeta = toSingleImageMeta([
+  { src: '/small.jpg', width: 400, height: 300 },
+  { src: '/large.jpg', width: 800, height: 600 }
+]); // Returns the largest (last) image
+
+// Calculate optimal width for container
+const effectiveWidth = calculateEffectiveWidth({
+  containerWidth: 600,
+  containerHeight: 400,
+  imageAspectRatio: 16/9,
+  fit: 'contain' // or 'cover', 'fill'
+});
+```
+
+## Loading States
+
+All loaders implement consistent loading state management:
+
+- **`initial`** - Not started loading
+- **`loading`** - Currently loading 
+- **`loaded`** - Successfully loaded
+- **`error`** - Failed to load
+- **`cancelled`** - Loading was cancelled
+
+## Integration with SvelteKit
+
+### Using in Components
+
+```svelte
+<script>
+  import { ImageLoader } from '$lib/network/loaders.js';
+  import { onMount } from 'svelte';
+
+  let imageLoader = $state();
+  let objectURL = $state();
+
+  const imageMeta = { src: '/image.jpg', width: 800, height: 600 };
+
+  onMount(() => {
+    imageLoader = new ImageLoader({ imageMeta });
+    imageLoader.load();
+  });
+
+  $effect(() => {
+    if (imageLoader?.loaded) {
+      objectURL = imageLoader.getObjectURL();
+    }
+
+    return () => {
+      if (objectURL) {
+        URL.revokeObjectURL(objectURL);
+      }
+    };
+  });
+</script>
+
+{#if objectURL}
+  <img src={objectURL} alt="Loaded image" />
+{:else if imageLoader?.loading}
+  <p>Loading...</p>
+{:else if imageLoader?.error}
+  <p>Error: {imageLoader.error.message}</p>
+{/if}
+```
+
+### Responsive Images
+
+```svelte
+<script>
+  import { ImageBox } from '$lib/ui/components/index.js';
+  
+  // ImageBox uses ImageVariantsLoader internally
+  const imageSource = [
+    { src: '/image-400.jpg', width: 400, height: 300 },
+    { src: '/image-800.jpg', width: 800, height: 600 }
+  ];
+</script>
+
+<ImageBox 
+  imageSource={imageSource}
+  width="600px"
+  height="400px"
+  fit="cover"
+/>
+```
+
+## Error Handling
+
+```javascript
+try {
+  const imageLoader = new ImageLoader({ imageMeta });
+  await imageLoader.load();
+  
+  if (imageLoader.error) {
+    console.error('Loading failed:', imageLoader.error);
+  }
+} catch (error) {
+  console.error('Setup failed:', error);
+}
+```
+
+## Available Exports
+
+### Image (`$lib/network/loaders.js`)
+- `ImageLoader` - Single image loading with streaming
+- `ImageVariantsLoader` - Responsive image variant selection
+
+### Audio (`$lib/network/loaders.js`) 
+- `AudioLoader` - Audio file loading with streaming
+- `AudioScene` - Multi-source audio management
+
+### Utilities (`$lib/network/loaders/image/utils/`)
+- `toSingleImageMeta()` - Extract single image from variants
+- `calculateEffectiveWidth()` - Calculate optimal image dimensions
+
+All loaders provide built-in loading states, error handling, and memory management with automatic cleanup of object URLs.

package/dist/{classes/svelte → network/loaders}/audio/AudioLoader.svelte.d.ts

@@ -27,4 +27,4 @@ export default class AudioLoader extends NetworkLoader {
     getAudioBuffer(audioContext: AudioContext): Promise<AudioBuffer>;
     #private;
 }
-import { NetworkLoader } from '../network-loader/index.js';
+import { NetworkLoader } from '../../states/index.js';

package/dist/{classes/svelte → network/loaders}/audio/AudioLoader.svelte.js

@@ -1,58 +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
+import {
+  NetworkLoader,
+  ERROR_NOT_LOADED,
+  ERROR_TRANSFERRED
+} from '../../states/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