@codexo/exojs 0.8.4 → 0.9.0

package/dist/esm/resources/Loader.d.ts

@@ -1,15 +1,24 @@
 import { Signal } from '@/core/Signal';
+import { BmFont } from '@/rendering/text/BmFont';
+import { Asset } from './Asset';
+import type { AssetDefinitions, AssetInput, InferAssetResource } from './AssetDefinitions';
 import type { AssetFactory } from './AssetFactory';
 import type { AssetManifest, LoadBundleOptions } from './AssetManifest';
+import { type Assets } from './Assets';
 import type { CacheStore } from './CacheStore';
 import type { CacheStrategy } from './CacheStrategy';
 import type { AssetConstructor } from './FactoryRegistry';
-import { Json, SvgAsset, TextAsset, VttAsset } from './tokens';
+import { LoadingQueue } from './LoadingQueue';
+import { BinaryAsset, CsvAsset, FontAsset, ImageAsset, Json, SubtitleAsset, SvgAsset, TextAsset, WasmAsset, XmlAsset } from './tokens';
 /**
  * Any abstract or concrete constructor that can be used as an asset type token
  * with {@link Loader.load} and related methods.
  */
 export type Loadable = abstract new (...args: any[]) => any;
+/** Maps each key of an `AssetInput` map to its resolved runtime resource type. */
+export type InferLoadedMap<M extends Record<string, AssetInput>> = {
+    [K in keyof M]: InferAssetResource<M[K]>;
+};
 /**
  * Maps a {@link Loadable} constructor to the concrete type returned by
  * {@link Loader.load}.
@@ -19,11 +28,89 @@ export type Loadable = abstract new (...args: any[]) => any;
  * their constructor type. All other loadables return the instance type inferred
  * from the constructor.
  */
-export type LoadReturn<T> = T extends typeof Json ? unknown : T extends typeof TextAsset ? string : T extends typeof SvgAsset ? HTMLImageElement : T extends typeof VttAsset ? VTTCue[] : T extends abstract new (...args: any[]) => infer R ? R : never;
+export type LoadReturn<T> = T extends typeof Json ? unknown : T extends typeof TextAsset ? string : T extends typeof SvgAsset ? HTMLImageElement : T extends typeof SubtitleAsset ? VTTCue[] : T extends typeof XmlAsset ? Document : T extends typeof CsvAsset ? string[][] : T extends typeof ImageAsset ? HTMLImageElement : T extends typeof FontAsset ? FontFace : T extends typeof BinaryAsset ? ArrayBuffer : T extends typeof WasmAsset ? WebAssembly.Module : T extends abstract new (...args: any[]) => infer R ? R : never;
+/**
+ * Maps file extensions (without leading dot, lower-case) to the asset type
+ * returned by {@link Loader.load} when called with a plain path string.
+ *
+ * Extend via declaration merging to register custom extension → type mappings:
+ * ```ts
+ * declare module 'exojs' {
+ *   interface ExtensionTypeMap { tmj: TiledMap; }
+ * }
+ * ```
+ */
+export interface ExtensionTypeMap {
+    fnt: BmFont;
+    woff: FontFace;
+    woff2: FontFace;
+    ttf: FontFace;
+    otf: FontFace;
+}
+type PathExtension<S extends string> = S extends `${string}.${infer E}?${string}` ? Lowercase<E> : S extends `${string}.${infer E}` ? Lowercase<E> : never;
+/**
+ * Resolves the return type for {@link Loader.load} when called with a plain
+ * path string. Returns `unknown` when the extension is not in
+ * {@link ExtensionTypeMap} — the string-path overload rejects such paths at
+ * compile time; use the token form (`load(MyType, path)`) instead.
+ */
+export type LoadByPath<S extends string> = PathExtension<S> extends keyof ExtensionTypeMap ? ExtensionTypeMap[PathExtension<S>] : unknown;
+/**
+ * Constrains a {@link Loadable} token against the types registered for a
+ * given path's extension. When the extension is in {@link ExtensionTypeMap},
+ * `T` must produce a value assignable to the registered union — otherwise
+ * resolves to `never`, triggering a compile-time error.
+ *
+ * For paths with an unregistered extension the constraint is skipped and any
+ * `T` is accepted (runtime behaviour is unchanged).
+ *
+ * ```ts
+ * // ExtensionTypeMap: { ogg: Sound | Video }
+ * loader.load(Sound, 'effect.ogg')      // ✓ Sound ∈ Sound | Video
+ * loader.load(BitmapText, 'effect.ogg') // ✗ BitmapText ∉ Sound | Video
+ * loader.load(Sound, 'theme.custom')    // ✓ .custom not in map → unconstrained
+ * ```
+ */
+export type ConstrainedLoadable<T extends abstract new (...args: any[]) => any, S extends string> = PathExtension<S> extends keyof ExtensionTypeMap ? (LoadReturn<T> extends ExtensionTypeMap[PathExtension<S>] ? T : never) : T;
+/**
+ * Context object passed to custom asset-type load handlers registered via
+ * {@link Loader.registerAssetType}.
+ *
+ * The `fetch*` helpers route through the loader's configured cache strategy
+ * and IDB stores, giving custom handlers the same caching behaviour as
+ * built-in asset types.
+ */
+export interface AssetLoaderContext {
+    /** The owning {@link Loader} instance. */
+    readonly loader: Loader;
+    /**
+     * The identity key for this load — `id:<typeId>:<discriminator>`.
+     * Useful for diagnostics; also equals the key used for in-flight dedup.
+     */
+    readonly identityKey: string;
+    /** Fetches `source` as UTF-8 text, routing through the loader's cache/IDB. */
+    fetchText(source: string): Promise<string>;
+    /** Fetches `source` as an `ArrayBuffer`, routing through the loader's cache/IDB. */
+    fetchArrayBuffer(source: string): Promise<ArrayBuffer>;
+    /**
+     * Fetches `source` as parsed JSON, routing through the loader's cache/IDB.
+     * Supply `T` to narrow the return type at the call site.
+     */
+    fetchJson<T = unknown>(source: string): Promise<T>;
+}
+/**
+ * Accepted value types in the homogeneous batch load API.
+ *
+ * Either a raw source string or a flat config object containing at least
+ * `source` plus any type-specific extra fields.
+ */
+export type BatchValue = string | ({
+    source: string;
+} & Record<string, unknown>);
 /**
  * Construction options for {@link Loader}.
  *
- * `resourcePath` is prepended to relative asset paths at fetch time.
+ * `basePath` is prepended to relative asset paths at fetch time.
  * `cache` accepts one or more {@link CacheStore} instances. `cacheStrategy`
  * picks the policy used to consult them — defaults to
  * {@link CacheFirstStrategy} (check stores → network → write back).
@@ -31,8 +118,8 @@ export type LoadReturn<T> = T extends typeof Json ? unknown : T extends typeof T
  * (default `6`).
  */
 export interface LoaderOptions {
-    resourcePath?: string;
-    requestOptions?: RequestInit;
+    basePath?: string;
+    fetchOptions?: RequestInit;
     cache?: CacheStore | readonly CacheStore[];
     cacheStrategy?: CacheStrategy;
     concurrency?: number;
@@ -59,12 +146,13 @@ export interface LoaderOptions {
  *
  * @example
  * ```ts
- * const loader = new Loader({ resourcePath: '/assets/', cache: new IndexedDbStore('game') });
+ * const loader = new Loader({ basePath: '/assets/', cache: new IndexedDbStore('game') });
  * const texture = await loader.load(Texture, 'hero.png');
  * ```
  */
 export declare class Loader {
     private readonly _registry;
+    private readonly _assetTypeMap;
     private readonly _resources;
     private readonly _manifest;
     private readonly _bundles;
@@ -73,8 +161,13 @@ export declare class Loader {
     private readonly _preventStoreKeys;
     private readonly _stores;
     private readonly _cacheStrategy;
-    private _resourcePath;
-    private _requestOptions;
+    private readonly _aliasKeyToIdentityKey;
+    private readonly _identityKeyToAliases;
+    private readonly _inFlightByIdentity;
+    private readonly _handlerFunctions;
+    private readonly _extensionMap;
+    private _basePath;
+    private _fetchOptions;
     private _concurrency;
     private _nextTypeId;
     private _backgroundQueue;
@@ -100,6 +193,62 @@ export declare class Loader {
      * for the same constructor.
      */
     register<T>(type: AssetConstructor<T>, factory: AssetFactory<T>): this;
+    /**
+     * Associates a string type name with a simple load handler.
+     *
+     * The handler's `load` method receives the full config object (including
+     * `source` and every extra field declared via `AssetDefinitions` augmentation)
+     * plus a {@link AssetLoaderContext} containing the loader instance.
+     *
+     * This form is intended for custom asset types that manage their own
+     * network access; the persistent cache layer is bypassed.
+     *
+     * @example
+     * ```ts
+     * loader.registerAssetType('tileMap', {
+     *   load(config, { loader }) {
+     *     return loadTileMap({ source: config.source, format: config.format, loader });
+     *   },
+     * });
+     * ```
+     */
+    registerAssetType<K extends keyof AssetDefinitions>(typeName: K, handler: {
+        /**
+         * Optional discriminator for in-flight dedup and identity tracking.
+         *
+         * Return a string that uniquely identifies the conceptual asset given its
+         * full config.  The default (when omitted) is `config.source`, which is
+         * correct for assets where the source URL alone determines the result.
+         * Supply this when extra config fields affect the loaded output — e.g.
+         * `\`${config.source}:${config.format}\`` — so that two assets with the
+         * same source but different format are kept separate in the in-flight map.
+         */
+        getIdentityKey?(config: AssetDefinitions[K]['config']): string;
+        load(config: AssetDefinitions[K]['config'], context: AssetLoaderContext): Promise<AssetDefinitions[K]['resource']>;
+    }): this;
+    /**
+     * Associates a string type name (e.g. `'tileMap'`) with the constructor
+     * used as the asset token and, optionally, registers a factory for it.
+     *
+     * Required for declaration-merge extensions of {@link AssetDefinitions}
+     * so that `loader.load({ map: { type: 'tileMap', source: '…' } })` works.
+     */
+    registerAssetType(typeName: string, ctor: AssetConstructor, factory?: AssetFactory): this;
+    /**
+     * Associates a file extension with an asset type so that
+     * `loader.load('path.ext')` (the single-string overload) can infer the
+     * type automatically.
+     *
+     * `ext` is matched case-insensitively and the leading dot is optional.
+     * The type must already have a registered factory (via {@link register} or
+     * {@link registerAssetType}).
+     *
+     * ```ts
+     * loader.registerExtension('tmj', TiledMap);
+     * const map = await loader.load('world.tmj'); // TiledMap
+     * ```
+     */
+    registerExtension(ext: string, type: AssetConstructor): this;
     /**
      * Registers one or more asset aliases in the manifest without immediately
      * loading them.
@@ -146,6 +295,9 @@ export declare class Loader {
      * - **Single path** — resolves with the finished asset.
      * - **Array of paths** — resolves with an ordered array of assets.
      * - **Record** — resolves with a record whose keys match the input keys.
+     * - **Asset<T>** — single typed asset reference.
+     * - **Assets<M>** — typed asset container; keys become aliases.
+     * - **Config map** — inline `{ alias: { type, source, … } }` definition.
      *
      * In-flight and already-loaded assets are de-duplicated: calling `load`
      * for the same (type, alias) pair while a fetch is in progress attaches
@@ -154,12 +306,37 @@ export declare class Loader {
      * Supply a custom `options` object to pass factory-specific configuration
      * (e.g. audio decoding hints or image format overrides).
      */
-    load<T = unknown>(type: typeof Json, path: string, options?: unknown): Promise<T>;
-    load<T = unknown>(type: typeof Json, paths: readonly string[], options?: unknown): Promise<T[]>;
-    load<T = unknown, K extends string = string>(type: typeof Json, items: Readonly<Record<K, string>>, options?: unknown): Promise<Record<K, T>>;
-    load<T extends Loadable>(type: T, path: string, options?: unknown): Promise<LoadReturn<T>>;
-    load<T extends Loadable>(type: T, paths: readonly string[], options?: unknown): Promise<Array<LoadReturn<T>>>;
-    load<T extends Loadable, K extends string>(type: T, items: Readonly<Record<K, string>>, options?: unknown): Promise<Record<K, LoadReturn<T>>>;
+    load<T = unknown>(type: typeof Json, path: string, options?: unknown): LoadingQueue<T>;
+    load<T = unknown>(type: typeof Json, paths: readonly string[], options?: unknown): LoadingQueue<T[]>;
+    load<T = unknown, K extends string = string>(type: typeof Json, items: Readonly<Record<K, string>>, options?: unknown): LoadingQueue<Record<K, T>>;
+    load<T>(asset: Asset<T>): LoadingQueue<T>;
+    load<M extends Record<string, AssetInput>>(assets: Assets<M>): LoadingQueue<InferLoadedMap<M>>;
+    load<M extends Record<string, AssetInput>>(config: M): LoadingQueue<InferLoadedMap<M>>;
+    /**
+     * Fetches an asset by path, inferring the type from the file extension.
+     *
+     * Built-in extension mappings:
+     * - `.fnt` → {@link BmFont}
+     * - `.woff`, `.woff2`, `.ttf`, `.otf` → `FontFace` (family inferred from filename)
+     *
+     * Register additional mappings via {@link registerExtension}.
+     * Extend the return type by augmenting {@link ExtensionTypeMap}.
+     *
+     * Paths whose extension is **not** in {@link ExtensionTypeMap} are rejected at
+     * compile time — use the token form (`load(MyType, path)`) for unregistered
+     * extensions.
+     *
+     * ```ts
+     * const font = await loader.load('fonts/ui.fnt');           // BmFont
+     * const face = await loader.load('fonts/Roboto.woff2');     // FontFace, family='Roboto'
+     * const bm   = await loader.load<BmFont>('fonts/ui.fnt');   // validated cast
+     * ```
+     */
+    load<R, S extends string>(path: PathExtension<S> extends keyof ExtensionTypeMap ? S : never): LoadingQueue<R>;
+    load<S extends string>(path: PathExtension<S> extends keyof ExtensionTypeMap ? S : never): LoadingQueue<LoadByPath<S>>;
+    load<T extends Loadable, S extends string>(type: ConstrainedLoadable<T, S>, path: S, options?: unknown): LoadingQueue<LoadReturn<T>>;
+    load<T extends Loadable>(type: T, paths: readonly string[], options?: unknown): LoadingQueue<Array<LoadReturn<T>>>;
+    load<T extends Loadable, K extends string>(type: T, items: Readonly<Record<K, BatchValue>>, options?: unknown): LoadingQueue<Record<K, LoadReturn<T>>>;
     /**
      * Enqueues all manifest-registered assets that have not yet been loaded
      * into the background fetch queue and begins draining the queue up to
@@ -206,7 +383,10 @@ export declare class Loader {
      * discarded once it arrives rather than written to the store, preventing
      * a stale value from being committed after an explicit unload.
      */
+    unload<T>(asset: Asset<T>): this;
+    unload<M extends Record<string, AssetInput>>(assets: Assets<M>): this;
     unload(type: Loadable, alias: string): this;
+    private _unloadOne;
     /**
      * Removes all loaded assets from the in-memory store.
      *
@@ -219,14 +399,14 @@ export declare class Loader {
      * Absolute URLs (starting with `http://`, `https://`, or `//`) are
      * passed through unchanged.
      */
-    get resourcePath(): string;
-    set resourcePath(value: string);
+    get basePath(): string;
+    set basePath(value: string);
     /**
      * Default `RequestInit` options merged into every `fetch` call.
      * Override per-load with the `options` argument of {@link load}.
      */
-    get requestOptions(): RequestInit;
-    set requestOptions(value: RequestInit);
+    get fetchOptions(): RequestInit;
+    set fetchOptions(value: RequestInit);
     /**
      * Tears down the loader and all resources it owns.
      *
@@ -237,6 +417,41 @@ export declare class Loader {
     destroy(): void;
     private _loadSingle;
     private _loadSingleBackground;
+    private _createLoadingQueue;
+    /**
+     * Loads a single asset from an `Asset<T>` reference using identity-based
+     * in-flight deduplication.
+     *
+     * Multiple aliases that point to the same source share a single network
+     * fetch.  Each alias is stored independently in `_resources` so that
+     * `get(type, alias)` works for all of them.
+     */
+    private _loadSingleAsset;
+    /**
+     * Calls a handler-based custom asset loader and stores the result.
+     *
+     * Unlike `_fetch`, this does NOT automatically bypass caching — the handler
+     * controls caching by calling `context.fetchText` / `context.fetchArrayBuffer`
+     * / `context.fetchJson`, which route through the loader's cache strategy.
+     */
+    private _fetchWithHandler;
+    /**
+     * Builds an {@link AssetLoaderContext} for a handler invocation.
+     *
+     * The `fetch*` helpers on the returned context route through the loader's
+     * configured cache strategy and IDB stores, using `source` as the IDB key
+     * (so the same URL is never fetched twice regardless of the asset alias).
+     */
+    private _buildHandlerContext;
+    /**
+     * Fetches `source` through the loader's cache strategy with an inline
+     * pass-through factory, using `source` as the IDB key.
+     *
+     * `process` converts the raw `Response` to the storable intermediate form
+     * (e.g. `r.text()`, `r.arrayBuffer()`, `r.json()`).  `create` is always the
+     * identity function — the cached value is returned unchanged.
+     */
+    private _contextFetch;
     private _fetch;
     private _drainBackground;
     private _boostFromQueue;
@@ -254,7 +469,18 @@ export declare class Loader {
     private _describeType;
     private _hasResource;
     private _storeResource;
+    private _getTypeId;
     private _key;
+    private _identityKey;
+    /**
+     * Resolves the effective identity key for an `Asset<T>` reference, mirroring
+     * the logic used in `_loadSingleAsset`.
+     *
+     * For handler types with `getIdentityKey`, the config-sensitive discriminator
+     * is used; otherwise source is the discriminator (same as `_identityKey`).
+     */
+    private _resolveAssetIdentityKey;
     private _resolveUrl;
     private _registerBuiltinFactories;
 }
+export {};