@hkdigital/lib-core 0.3.10 → 0.3.12

package/dist/{util → network}/http/json-request.js

@@ -4,7 +4,7 @@ import { APPLICATION_JSON } from '../../constants/mime/application.js';
 import { CONTENT_TYPE } from '../../constants/http/headers.js';
 import { ResponseError } from '../../errors/index.js';
 
-import * as expect from '../expect/index.js';
+import * as expect from '../../util/expect/index.js';
 
 import { toURL } from './url.js';
 import { httpRequest } from './http-request.js';

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

@@ -1,5 +1,5 @@
 import { ResponseError, HttpError } from '../../errors/index.js';
-import * as expect from '../expect/index.js';
+import * as expect from '../../util/expect/index.js';
 import { toURL } from './url.js';
 
 import {

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

@@ -2,7 +2,7 @@ import {
   NetworkLoader,
   ERROR_NOT_LOADED,
   ERROR_TRANSFERRED
-} from '../network-loader/index.js';
+} from '../../states/index.js';
 
 /**
  * AudioLoader instance

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

@@ -10,7 +10,7 @@ import {
 	STATE_ERROR,
 	LOAD,
 	LOADED
-} from '../loading-state-machine/index.js';
+} from '../../../classes/svelte/loading-state-machine/index.js';
 
 import AudioLoader from './AudioLoader.svelte.js';
 

package/dist/network/loaders/audio.d.ts

@@ -0,0 +1,2 @@
+export { default as AudioLoader } from "./audio/AudioLoader.svelte.js";
+export { default as AudioScene } from "./audio/AudioScene.svelte.js";

package/dist/network/loaders/audio.js

@@ -0,0 +1,2 @@
+export { default as AudioLoader } from './audio/AudioLoader.svelte.js';
+export { default as AudioScene } from './audio/AudioScene.svelte.js';

package/dist/{classes/svelte → network/loaders}/image/ImageLoader.svelte.d.ts

@@ -5,15 +5,12 @@
  */
 export default class ImageLoader extends NetworkLoader {
     /**
-     * @param {object} _
-     * @param {ImageMeta|ImageMeta[]} _.imageMeta
+     * @param {import('../typedef.js').ImageSource} imageSource
      */
-    constructor({ imageMeta }: {
-        imageMeta: ImageMeta | ImageMeta[];
-    });
+    constructor(imageSource: import("../typedef.js").ImageSource);
     get imageMeta(): import("./typedef.js").ImageMeta;
     get url(): string;
     #private;
 }
 export type ImageMeta = import("./typedef.js").ImageMeta;
-import { NetworkLoader } from '../network-loader/index.js';
+import { NetworkLoader } from '../../states/index.js';

package/dist/{classes/svelte → network/loaders}/image/ImageLoader.svelte.js

@@ -1,10 +1,10 @@
 /** @typedef {import('./typedef.js').ImageMeta} ImageMeta */
 
-import { toSingleImageMeta } from '../../../util/image/index.js';
+import { toSingleImageMeta } from './utils/index.js';
 
 import {
   NetworkLoader
-} from '../network-loader/index.js';
+} from '../../states/index.js';
 
 /**
  * ImageLoader instance
@@ -16,11 +16,10 @@ export default class ImageLoader extends NetworkLoader {
   #imageMeta;
 
   /**
-   * @param {object} _
-   * @param {ImageMeta|ImageMeta[]} _.imageMeta
+   * @param {import('../typedef.js').ImageSource} imageSource
    */
-  constructor({ imageMeta }) {
-    imageMeta = toSingleImageMeta(imageMeta);
+  constructor(imageSource) {
+    const imageMeta = toSingleImageMeta(imageSource);
 
     super({ url: imageMeta.src });
 

package/dist/{classes/svelte → network/loaders}/image/ImageScene.svelte.d.ts

@@ -3,10 +3,9 @@
  * // property ...
  */
 /**
- * @typedef {object} ImageSource
+ * @typedef {object} ImageSceneSource
  * @property {string} label
  * @property {ImageLoader} imageLoader
- * @property {ImageMeta} [imageMeta]
  */
 export default class ImageScene {
     state: string;
@@ -18,11 +17,11 @@ export default class ImageScene {
      *
      * @param {object} _
      * @param {string} _.label
-     * @param {ImageMeta|ImageMeta[]} _.imageMeta
+     * @param {import('../typedef.js').ImageSource} _.imageSource
      */
-    defineImage({ label, imageMeta }: {
+    defineImage({ label, imageSource }: {
         label: string;
-        imageMeta: ImageMeta | ImageMeta[];
+        imageSource: import("../typedef.js").ImageSource;
     }): void;
     /**
      * Start loading all image sources
@@ -70,9 +69,8 @@ export type ImageMeta = import("./typedef.js").ImageMeta;
  * // property ...
  */
 export type SourceConfig = object;
-export type ImageSource = {
+export type ImageSceneSource = {
     label: string;
     imageLoader: ImageLoader;
-    imageMeta?: ImageMeta;
 };
 import ImageLoader from './ImageLoader.svelte.js';

package/dist/{classes/svelte → network/loaders}/image/ImageScene.svelte.js

@@ -12,7 +12,7 @@ import {
   STATE_ERROR,
   LOAD,
   LOADED
-} from '../loading-state-machine/index.js';
+} from '../../../classes/svelte/loading-state-machine/index.js';
 
 import ImageLoader from './ImageLoader.svelte.js';
 
@@ -22,10 +22,9 @@ import ImageLoader from './ImageLoader.svelte.js';
  */
 
 /**
- * @typedef {object} ImageSource
+ * @typedef {object} ImageSceneSource
  * @property {string} label
  * @property {ImageLoader} imageLoader
- * @property {ImageMeta} [imageMeta]
  */
 
 export default class ImageScene {
@@ -39,7 +38,7 @@ export default class ImageScene {
     return this.state === STATE_LOADED;
   });
 
-  /** @type {ImageSource[]} */
+  /** @type {ImageSceneSource[]} */
   #imageSources = $state([]);
 
   #progress = $derived.by(() => {
@@ -149,16 +148,16 @@ export default class ImageScene {
    *
    * @param {object} _
    * @param {string} _.label
-   * @param {ImageMeta|ImageMeta[]} _.imageMeta
+   * @param {import('../typedef.js').ImageSource} _.imageSource
    */
-  defineImage({ label, imageMeta }) {
+  defineImage({ label, imageSource }) {
     expect.notEmptyString(label);
 
     // expect.notEmptyString(url);
 
-    const imageLoader = new ImageLoader({ imageMeta });
+    const imageLoader = new ImageLoader(imageSource);
 
-    this.#imageSources.push({ label, imageLoader, imageMeta });
+    this.#imageSources.push({ label, imageLoader });
   }
 
   /**
@@ -187,7 +186,7 @@ export default class ImageScene {
    *
    * @param {string} label
    *
-   * @returns {ImageSource}
+   * @returns {ImageSceneSource}
    */
   #getImageSource(label) {
     for (const source of this.#imageSources) {

package/dist/{classes/svelte → network/loaders}/image/ImageVariantsLoader.svelte.d.ts

@@ -1,4 +1,4 @@
-/** @typedef {import('../../../typedef/image.js').ImageMeta} ImageMeta */
+/** @typedef {import('../typedef.js').ImageMeta} ImageMeta */
 export default class ImageVariantsLoader {
     /**
      * @param {ImageMeta[]} imagesMeta
@@ -20,7 +20,7 @@ export default class ImageVariantsLoader {
         fit?: "cover" | "contain" | "fill";
     }): void;
     get loaded(): boolean;
-    get variant(): import("../../../typedef/image.js").ImageMeta;
+    get variant(): import("../typedef.js").ImageMeta;
     /**
      * Get object URL that can be used as src parameter of an HTML image
      *
@@ -29,7 +29,7 @@ export default class ImageVariantsLoader {
      * @returns {string|null}
      */
     getObjectURL(): string | null;
-    get progress(): import("../index.js").LoadingProgress;
+    get progress(): import("../../typedef.js").LoadingProgress;
     /**
      * Get optimal image variant
      *
@@ -40,4 +40,4 @@ export default class ImageVariantsLoader {
     getOptimalImageMeta(containerWidth: number): ImageMeta | null;
     #private;
 }
-export type ImageMeta = import("../../../typedef/image.js").ImageMeta;
+export type ImageMeta = import("../typedef.js").ImageMeta;

package/dist/{classes/svelte → network/loaders}/image/ImageVariantsLoader.svelte.js

@@ -1,8 +1,8 @@
-import { calculateEffectiveWidth } from '../../../util/image/index.js';
+import { calculateEffectiveWidth } from './utils/index.js';
 
 import ImageLoader from './ImageLoader.svelte.js';
 
-/** @typedef {import('../../../typedef/image.js').ImageMeta} ImageMeta */
+/** @typedef {import('../typedef.js').ImageMeta} ImageMeta */
 
 export default class ImageVariantsLoader {
   /** @type {number} */
@@ -71,9 +71,7 @@ export default class ImageVariantsLoader {
         this.#imageLoader.unload();
       }
 
-      this.#imageLoader = new ImageLoader({
-        imageMeta: newVariant
-      });
+      this.#imageLoader = new ImageLoader(newVariant);
 
 
       this.#imageLoader.load();

package/dist/{util/image → network/loaders/image/utils}/index.d.ts

@@ -4,9 +4,9 @@
  * of sorted responsive image formats, so it should be the
  * largest image.
  *
- * @param {ImageMeta|ImageMeta[]} imageMeta
+ * @param {import('../../typedef.js').ImageSource} imageSource
  */
-export function toSingleImageMeta(imageMeta: ImageMeta | ImageMeta[]): import("../../typedef").ImageMeta;
+export function toSingleImageMeta(imageSource: import("../../typedef.js").ImageSource): import("../../typedef.js").ImageMeta;
 /**
  * Calculate effective width based on container dimensions and fit mode
  *

package/dist/{util/image → network/loaders/image/utils}/index.js

@@ -4,23 +4,23 @@
  * of sorted responsive image formats, so it should be the
  * largest image.
  *
- * @param {ImageMeta|ImageMeta[]} imageMeta
+ * @param {import('../../typedef.js').ImageSource} imageSource
  */
-export function toSingleImageMeta(imageMeta) {
-  if (Array.isArray(imageMeta)) {
-    if (!imageMeta.length) {
+export function toSingleImageMeta(imageSource) {
+  if (Array.isArray(imageSource)) {
+    if (!imageSource.length) {
       throw new Error('List of ImageMeta objects is empty');
     }
-    imageMeta = imageMeta[imageMeta.length - 1];
+    imageSource = imageSource[imageSource.length - 1];
   }
 
-  if (typeof imageMeta === 'object') {
-    return imageMeta;
-  } else if (!imageMeta) {
-    throw new Error('Missing [imageMeta]');
+  if (typeof imageSource === 'object') {
+    return imageSource;
+  } else if (!imageSource) {
+    throw new Error('Missing [imageSource]');
   }
 
-  throw new Error('Invalid value for parameter [imageMeta]');
+  throw new Error('Invalid value for parameter [imageSource]');
 }
 
 /**

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

@@ -0,0 +1,5 @@
+export { default as ImageLoader } from "./image/ImageLoader.svelte.js";
+export { default as ImageScene } from "./image/ImageScene.svelte.js";
+export { default as ImageVariantsLoader } from "./image/ImageVariantsLoader.svelte.js";
+export * from "./image/utils/index.js";
+export * from "./image/typedef.js";

package/dist/network/loaders/image.js

@@ -0,0 +1,8 @@
+export { default as ImageLoader } from './image/ImageLoader.svelte.js';
+export { default as ImageScene } from './image/ImageScene.svelte.js';
+export { default as ImageVariantsLoader } from './image/ImageVariantsLoader.svelte.js';
+
+export * from './image/utils/index.js';
+export * from './image/typedef.js';
+
+// export * from './image/constants.js';

package/dist/network/loaders.d.ts

@@ -0,0 +1,2 @@
+export * from "./loaders/audio.js";
+export * from "./loaders/image.js";

package/dist/network/loaders.js

@@ -0,0 +1,2 @@
+export * from './loaders/audio.js';
+export * from './loaders/image.js';

package/dist/{classes/svelte/network-loader → network/states}/NetworkLoader.svelte.d.ts

@@ -88,4 +88,4 @@ export default class NetworkLoader {
     getObjectURL(): string;
     #private;
 }
-import { LoadingStateMachine } from '../loading-state-machine/index.js';
+import { LoadingStateMachine } from '../../classes/svelte/loading-state-machine/index.js';

package/dist/{classes/svelte/network-loader → network/states}/NetworkLoader.svelte.js

@@ -1,4 +1,4 @@
-import { CONTENT_TYPE } from '../../../constants/http/index.js';
+import { CONTENT_TYPE } from '../../constants/http/index.js';
 
 import {
   LoadingStateMachine,
@@ -13,11 +13,11 @@ import {
   LOADED,
   UNLOAD,
   INITIAL
-} from '../loading-state-machine/index.js';
+} from '../../classes/svelte/loading-state-machine/index.js';
 
-import * as expect from '../../../util/expect/index.js';
+import * as expect from '../../util/expect/index.js';
 
-import { httpGet, loadResponseBuffer } from '../../../util/http/index.js';
+import { httpGet, loadResponseBuffer } from '../http.js';
 
 import { ERROR_NOT_LOADED, ERROR_TRANSFERRED } from './constants.js';
 

package/dist/{classes/svelte/network-loader → network/states}/mocks.js

@@ -1,6 +1,6 @@
-import { CONTENT_TYPE, CONTENT_LENGTH } from '../../../constants/http/index.js';
+import { CONTENT_TYPE, CONTENT_LENGTH } from '../../constants/http/index.js';
 
-import { OCTET_STREAM } from '../../../constants/mime/application.js';
+import { OCTET_STREAM } from '../../constants/mime/application.js';
 
 const BASE64_DATA =
   'UklGRnwAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YVgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA';

package/dist/network/typedef.d.ts

@@ -0,0 +1,4 @@
+export * from "./http/typedef.js";
+export * from "./cache/typedef.js";
+export * from "./states/typedef.js";
+export * from "./loaders/typedef.js";

package/dist/network/typedef.js

@@ -0,0 +1,10 @@
+/**
+ * Network module type definitions
+ * 
+ * Re-exports types from all network submodules for convenient access
+ */
+
+export * from './http/typedef.js';
+export * from './cache/typedef.js';
+export * from './states/typedef.js';
+export * from './loaders/typedef.js';