@joycostudio/susano 0.2.0 → 1.1.0

package/dist/index.d.ts

@@ -1,70 +1,101 @@
-import { TinyEmitter } from 'tiny-emitter';
+/**
+ * Thin typed wrapper around `tiny-emitter`. Subclasses pin an event-map type
+ * (`{ eventName: payloadType }`) so `on`/`emit` are fully typed.
+ */
+declare class TypedEmitter<EventMap extends Record<string, unknown>> {
+    private readonly emitter;
+    on<K extends keyof EventMap & string>(event: K, listener: (payload: EventMap[K]) => void): () => void;
+    once<K extends keyof EventMap & string>(event: K, listener: (payload: EventMap[K]) => void): void;
+    off<K extends keyof EventMap & string>(event: K, listener?: (payload: EventMap[K]) => void): void;
+    protected emit<K extends keyof EventMap & string>(event: K, payload: EventMap[K]): void;
+}
 
-type SusanoLoaderConfig<T, R = T> = {
-    onLoaded?: (loader: SusanoLoader<T, R>) => void;
-    onProgress?: (loader: SusanoLoader<T, R>) => void;
-    postprocess?: (content: T, loader: SusanoLoader<T, R>) => R | Promise<R>;
+type LoaderStatus = 'idle' | 'loading' | 'loaded' | 'error';
+/** Events emitted by a {@link SusanoLoader} over the content fetch lifecycle. */
+type SusanoLoaderEventMap<T> = {
+    /** Content fetch settled successfully. Payload is the loader itself (read `.content`). */
+    loaded: SusanoLoader<T>;
+    /** Fetch progress advanced. Payload is the loader itself (read `.progress`). */
+    progress: SusanoLoader<T>;
+    /** Content fetch failed. Payload is the underlying error. */
+    error: unknown;
 };
-declare class SusanoLoader<T, R = T> extends TinyEmitter implements ISusanoLoader<T, R> {
+/**
+ * Base loader. Owns and caches a single piece of raw **content** per URL (the expensive fetch),
+ * deduped and idempotent. It does NOT run `postprocess` — that is a per-call projection applied
+ * by `Susano` (`_runLoad`). If you want to cache a transformed result, encode the transform in a
+ * loader subclass so its output becomes the cached content.
+ *
+ * Subclasses add their own construction args as a second constructor parameter (see `LoaderRegistry`).
+ */
+declare class SusanoLoader<T> extends TypedEmitter<SusanoLoaderEventMap<T>> {
     url: string;
     loaded: boolean;
+    status: LoaderStatus;
     content: T;
-    config: SusanoLoaderConfig<T, R>;
-    weight: number;
     progress: number;
-    promise: Promise<R>;
+    promise: Promise<T>;
     private _resolve;
     private _reject;
-    constructor(url: string, _cnfg?: SusanoLoaderConfig<T, R>);
-    load(): Promise<R>;
+    constructor(url: string);
+    /** `true` while a content load is in flight (`status === 'loading'`). */
+    get loading(): boolean;
+    /**
+     * Load (or join) the content fetch. Idempotent: repeat calls return the same promise without
+     * re-fetching.
+     *
+     * An in-flight fetch can never be preempted: while `status === 'loading'`, every call joins the
+     * same promise regardless of `cache`. This keeps the invariant that at most one fetch runs per
+     * URL, so resetting the promise can never orphan a consumer already awaiting it. `cache: false`
+     * therefore acts on a *completed* load — it busts the cached content and forces a fresh fetch —
+     * not on concurrent work. Resolves with the raw content `T`; postprocessing happens per call in
+     * `Susano`.
+     */
+    load(cache?: boolean): Promise<T>;
+    /** Subclasses implement the raw fetch here, calling `_onLoaded` / `_onError` / `_onProgress`. */
+    protected _load(): void;
     _onLoaded(): void;
-    private _finalize;
     _onError(error: unknown): void;
     private _resetPromise;
     _onProgress(value: number): void;
-    /**
-     * This is ment to be used as a way to attach to master loader events
-     */
-    _appendConfig(cnfg: SusanoLoaderConfig<T, R>): void;
-}
-interface ISusanoLoader<T, R = T> {
-    load: () => Promise<R>;
 }
 
-type SusanoImageLoaderConfig<R = HTMLImageElement> = SusanoLoaderConfig<HTMLImageElement, R> & {
+type SusanoImageLoaderConfig = {
     srcSet?: string;
     sizes?: string;
 };
-declare class ImageLoader<R = HTMLImageElement> extends SusanoLoader<HTMLImageElement, R> implements ISusanoLoader<HTMLImageElement, R> {
+declare class ImageLoader extends SusanoLoader<HTMLImageElement> {
     static type: "image";
     srcSet?: string;
     sizes?: string;
-    constructor(url: string, cnfg?: SusanoImageLoaderConfig<R>);
-    load(): Promise<R>;
+    constructor(url: string, cnfg?: SusanoImageLoaderConfig);
+    protected _load(): void;
 }
 
 type LoadEvent$1 = 'canplay' | 'canplaythrough';
-type SusanoVideoLoaderConfig<R = HTMLVideoElement> = SusanoLoaderConfig<HTMLVideoElement, R> & {
+type SusanoVideoLoaderConfig = {
     video?: HTMLVideoElement;
     loadEvent?: LoadEvent$1;
 };
-declare class VideoLoader<R = HTMLVideoElement> extends SusanoLoader<HTMLVideoElement, R> implements ISusanoLoader<HTMLVideoElement, R> {
+declare class VideoLoader extends SusanoLoader<HTMLVideoElement> {
     static type: "video";
     loadEvent: LoadEvent$1;
-    constructor(url: string, cnfg?: SusanoVideoLoaderConfig<R>);
-    load(): Promise<R>;
+    private _attempt;
+    constructor(url: string, cnfg?: SusanoVideoLoaderConfig);
+    protected _load(): void;
 }
 
 type LoadEvent = 'canplay' | 'canplaythrough';
-type SusanoAudioLoaderConfig<R = HTMLAudioElement> = SusanoLoaderConfig<HTMLAudioElement, R> & {
+type SusanoAudioLoaderConfig = {
     audio?: HTMLAudioElement;
     loadEvent?: LoadEvent;
 };
-declare class AudioLoader<R = HTMLAudioElement> extends SusanoLoader<HTMLAudioElement, R> implements ISusanoLoader<HTMLAudioElement, R> {
+declare class AudioLoader extends SusanoLoader<HTMLAudioElement> {
     static type: "audio";
     loadEvent: LoadEvent;
-    constructor(url: string, cnfg?: SusanoAudioLoaderConfig<R>);
-    load(): Promise<R>;
+    private _attempt;
+    constructor(url: string, cnfg?: SusanoAudioLoaderConfig);
+    protected _load(): void;
 }
 
 type GenericLoadFn = (config: {
@@ -73,81 +104,157 @@ type GenericLoadFn = (config: {
     error: (error: Error) => void;
     progress: (progress: number) => void;
 }) => void;
-type SusanoGenericLoaderConfig<R = any> = SusanoLoaderConfig<any, R> & {
+type SusanoGenericLoaderConfig = {
     loadFn: GenericLoadFn;
 };
-declare class GenericLoader<R = any> extends SusanoLoader<any, R> {
+declare class GenericLoader extends SusanoLoader<any> {
     static type: "generic";
     loadFn: GenericLoadFn;
-    constructor(url: string, cnfg: SusanoGenericLoaderConfig<R>);
-    load(): Promise<R>;
+    constructor(url: string, cnfg: SusanoGenericLoaderConfig);
+    protected _load(): void;
 }
 
-type LoaderTypes = {
-    [K: string]: {
-        type: typeof K;
-        loader: typeof SusanoLoader<any>;
-    };
+/** One tracked load within a batch: a content loader and its per-call result promise. */
+type BatchItem = {
+    loader: SusanoLoader<unknown>;
+    promise: Promise<unknown>;
 };
-type LoaderMap<T extends LoaderTypes> = {
-    [K in keyof T]: T[K]['loader'];
-};
-type ProgressEventArgs = {
+type BatchProgressEventArgs = {
     value: number;
-    item: SusanoLoader<unknown, unknown>;
-    susano: Susano<any>;
+    /** The loader that just settled, or `null` for a batch-level tick (e.g. an empty batch). */
+    loader: SusanoLoader<unknown> | null;
+    batch: Batch;
+};
+type BatchErrorEventArgs = {
+    loader: SusanoLoader<unknown>;
+    error: unknown;
+    batch: Batch;
+};
+/** Events emitted by a {@link Batch} over its lifecycle. */
+type BatchEventMap = {
+    /** An item settled (or an empty batch ticked). */
+    progress: BatchProgressEventArgs;
+    /** An item failed. Fail-soft: the batch still advances. */
+    error: BatchErrorEventArgs;
+    /** Every item settled. One-shot. */
+    completed: Batch;
+};
+type BatchHandlers = {
+    onProgress?: (progress: BatchProgressEventArgs) => void;
+    onCompleted?: (batch: Batch) => void;
+    onError?: (error: BatchErrorEventArgs) => void;
 };
 /**
- * Main loader class that manages loading of different asset types
- * @template T Type definition for the loaders to be used, extending LoaderTypes
- * @extends TinyEmitter
+ * Tracks progress and completion for a fixed set of loads, independent of other loading activity.
+ * Each batch owns its own counter and completion promise, so concurrent batches (and lazy
+ * `susano.load()` calls) never interfere.
+ *
+ * Completion is the resolution of `Promise.all` over the set — one-shot by construction. A failed
+ * item is fail-soft: it surfaces via `onError` / the `'error'` event and still advances the batch.
  */
-declare class Susano<T extends LoaderTypes> extends TinyEmitter {
-    private loaders;
-    queue: InstanceType<T[keyof T]['loader']>[];
-    active: InstanceType<T[keyof T]['loader']>[];
-    items: Map<string, InstanceType<T[keyof T]['loader']>>;
+declare class Batch extends TypedEmitter<BatchEventMap> {
+    readonly items: BatchItem[];
+    readonly loadLength: number;
     loadCount: number;
-    loadLength: number;
-    constructor();
-    add<K extends keyof T>(url: string, cnfg: {
-        type: K;
-        loaderArgs?: ConstructorParameters<T[K]['loader']>[1];
-    }): InstanceType<T[K]['loader']>;
-    load<K extends keyof T>(url: string, cnfg: {
-        type: K;
-        loaderArgs?: ConstructorParameters<T[K]['loader']>[1];
-    }): InstanceType<T[keyof T]["loader"]>;
-    registerLoader<K extends keyof T>(type: K, loader: T[K]['loader']): void;
-    _onProgress(item: SusanoLoader<unknown, unknown>): void;
-    start({ onCompleted, onProgress, }?: {
-        onCompleted?: (susano: Susano<T>) => void;
-        onProgress?: (progress: {
-            value: number;
-            item: SusanoLoader<unknown, unknown>;
-            susano: Susano<T>;
-        }) => void;
-    }): void;
+    progress: number;
+    completed: boolean;
+    readonly promise: Promise<Batch>;
+    private _counted;
+    private _resolve;
+    constructor(items: BatchItem[], handlers?: BatchHandlers);
+    private _start;
+    /** Count an item at most once so the progress fraction can't be inflated by repeat settles. */
+    private _tick;
+    private _finish;
+}
+
+/**
+ * Per-call options. `postprocess` is the projection from cached content `T` to this call's
+ * result `R` — it runs **every call**, never cached. `onProgress` observes the shared content
+ * fetch; `onLoaded` / `onError` fire for this call's result.
+ */
+type LoadOptions<T, R> = {
+    postprocess?: (content: T, loader: SusanoLoader<T>) => R | Promise<R>;
+    onLoaded?: (result: R, loader: SusanoLoader<T>) => void;
+    onProgress?: (value: number, loader: SusanoLoader<T>) => void;
+    onError?: (error: unknown, loader: SusanoLoader<T>) => void;
+};
+/**
+ * The common shape of any loader class: constructs a `SusanoLoader` from a `url` plus that
+ * loader's own construction args. The two `any`s are deliberate and contained to this bound:
+ * - `args` — each loader narrows it to its own config; the precise type is recovered per call via
+ *   `ConstructorParameters<R[K]>` in `LoadConfig` / `BatchEntry`.
+ * - `SusanoLoader<any>` — `SusanoLoader<T>` is *invariant* in `T` (it holds `(value: T) => void`
+ *   resolve/reject callbacks), so no single concrete content type bounds every loader. `any` admits
+ *   them all here; per-call typing stays precise via `ContentOf<R, K>`.
+ */
+type AnyLoaderConstructor = new (url: string, args?: any) => SusanoLoader<any>;
+/** The loader registry: a map from `type` key to loader class. The single source of truth. */
+type LoaderRegistry = Record<string, AnyLoaderConstructor>;
+/** The content type produced by the loader registered under `K`. */
+type ContentOf<R extends LoaderRegistry, K extends keyof R> = InstanceType<R[K]> extends SusanoLoader<infer C> ? C : never;
+/** Construction args + cache flag for a load. */
+type LoadConfig<R extends LoaderRegistry, K extends keyof R> = {
+    type: K;
+    loaderArgs?: ConstructorParameters<R[K]>[1];
+    /** Opt out of dedup; force a fresh content fetch that overwrites the cached content. Defaults to `true`. */
+    cache?: boolean;
+};
+/** A single entry in a {@link Susano.batch} call — construction + per-call options, typed per `type`. */
+type BatchEntry<R extends LoaderRegistry> = {
+    [K in keyof R]: LoadConfig<R, K> & {
+        url: string;
+    } & LoadOptions<ContentOf<R, K>, unknown>;
+}[keyof R];
+/**
+ * Registry + per-URL **content** cache. The loader map passed to the constructor is the single
+ * source of truth: its keys are the valid `type`s and its values are the loader classes, so
+ * `load()` / `batch()` are fully inferred — no separate type map, no drift.
+ *
+ * Content (the expensive fetch) is deduped per URL; a `postprocess` is a per-call projection
+ * (see `_runLoad`), so two call sites can derive different results from one shared fetch.
+ *
+ * @template R The loader registry — `{ [type]: LoaderClass }`.
+ */
+declare class Susano<R extends LoaderRegistry> {
+    private loaders;
+    items: Map<string, SusanoLoader<unknown>>;
+    constructor(loaders: R);
+    /** The shared content loader cached for `url`, if one exists. Shorthand for `items.get(url)`. */
+    get(url: string): SusanoLoader<unknown> | undefined;
+    /**
+     * Get-or-create the content loader for `url`, typed to the loader registered under `type`.
+     * The one unavoidable cast: `items` is keyed by URL (a string), which can't carry the content
+     * type, so a cache hit is asserted back to the loader's known type.
+     */
+    private _resolve;
+    /**
+     * Load one asset immediately and return a promise of *this call's result* (content after this
+     * call's `postprocess`). The content fetch is deduped per URL. Reach the shared content loader —
+     * for raw content or events — via `susano.items.get(url)`.
+     */
+    load<K extends keyof R, Result = ContentOf<R, K>>(url: string, cnfg: LoadConfig<R, K> & LoadOptions<ContentOf<R, K>, Result>): Promise<Result>;
+    /**
+     * Run a single load against a shared content loader: ensure content (deduped), then apply this
+     * call's `postprocess` to produce the result. Two calls for the same URL share one content fetch
+     * but each get their own result promise. Stays a function of (loader, options) — it never touches
+     * the registry.
+     */
+    private _runLoad;
+    /**
+     * Load a fixed set and track *only* that set's progress/completion, independent of other
+     * loading activity. Content fetches are deduped across entries; each entry's `postprocess` runs
+     * per call. Auto-starts; returns a {@link Batch} exposing `.promise`, `.progress`, `.completed`.
+     */
+    batch(entries: BatchEntry<R>[], handlers?: BatchHandlers): Batch;
 }
 declare const susano: Susano<{
-    image: {
-        type: "image";
-        loader: typeof ImageLoader;
-    };
-    video: {
-        type: "video";
-        loader: typeof VideoLoader;
-    };
-    audio: {
-        type: "audio";
-        loader: typeof AudioLoader;
-    };
-    generic: {
-        type: "generic";
-        loader: typeof GenericLoader;
-    };
+    image: typeof ImageLoader;
+    video: typeof VideoLoader;
+    audio: typeof AudioLoader;
+    generic: typeof GenericLoader;
 }>;
 
 declare const VERSION: string;
 
-export { AudioLoader, type GenericLoadFn, GenericLoader, type ISusanoLoader, ImageLoader, type LoaderMap, type LoaderTypes, type ProgressEventArgs, Susano, type SusanoAudioLoaderConfig, type SusanoGenericLoaderConfig, type SusanoImageLoaderConfig, SusanoLoader, type SusanoLoaderConfig, type SusanoVideoLoaderConfig, VERSION, VideoLoader, susano };
+export { type AnyLoaderConstructor, AudioLoader, Batch, type BatchEntry, type BatchErrorEventArgs, type BatchEventMap, type BatchHandlers, type BatchItem, type BatchProgressEventArgs, type ContentOf, type GenericLoadFn, GenericLoader, ImageLoader, type LoadConfig, type LoadOptions, type LoaderRegistry, type LoaderStatus, Susano, type SusanoAudioLoaderConfig, type SusanoGenericLoaderConfig, type SusanoImageLoaderConfig, SusanoLoader, type SusanoLoaderEventMap, type SusanoVideoLoaderConfig, VERSION, VideoLoader, susano };