/**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */

/**
 * Descriptor for one entry in an `AssetBatch`.
 *
 * `format`  — texture format constant (`Texture.FORMAT_*`). Alias for `input`
 *             when the type is `Asset.TYPE_TEXTURE`.
 * `axis`    — mesh axis constant (`Asset.MESH_AXIS_*`). Alias for `input`
 *             when the type is `Asset.TYPE_MESH`.
 * `input`   — generic numeric input for all other loader types.
 */
interface AssetBatchDescriptor {
  path: string;
  type: number;
  format?: number;
  axis?: number;
  input?: number;
}

/** A group of asset entries locked and queued for loading together. */
interface AssetBatch {
  /** Number of entries in the batch. */
  readonly count: number;
  /** `true` when every entry has reached `LOADED`. */
  readonly isLoaded: boolean;
  /** `true` if any entry is in an `ERROR` state. */
  readonly hasError: boolean;
  /**
   * Blocks until every entry is loaded.
   * Returns `this` for chaining.
   * @throws If any entry fails to load.
   */
  requireLoaded(): this;
  /**
   * Acquires one additional lock on every entry.
   * Returns `this` for chaining.
   */
  lock(): this;
  /**
   * Releases all locks and clears the batch.
   * After this call the object is invalid — do not use it again.
   */
  unlock(): void;
  /**
   * Returns the `AssetEntry` at `index`, adding an independent lock.
   * The returned entry must be unlocked separately when no longer needed.
   * Returns `undefined` if `index` is out of range or the batch is disposed.
   */
  entry(index: number): AssetEntry | undefined;

  /**
   * Fires once when every entry has loaded successfully.
   * Subscribe with `onLoaded[0] = () => { ... }`.
   */
  readonly onLoaded: AssetEventProxy;
  /**
   * Fires each time a single entry finishes loading.
   * Subscribe with `onEntryLoaded[0] = () => { ... }`.
   */
  readonly onEntryLoaded: AssetEventProxy;
  /**
   * Fires once when all entries have finished but at least one errored.
   * Subscribe with `onError[0] = () => { ... }`.
   */
  readonly onError: AssetEventProxy;
  /**
   * Fires each time a single entry transitions to an error state.
   * Subscribe with `onEntryError[0] = () => { ... }`.
   */
  readonly onEntryError: AssetEventProxy;

  toString(): string;
}

interface AssetBatchConstructor {
  /** Creates a batch from an array of descriptors. Works with or without `new`. */
  (descriptors: AssetBatchDescriptor[]): AssetBatch;
  new(descriptors: AssetBatchDescriptor[]): AssetBatch;
}

declare var AssetBatch: AssetBatchConstructor;