@league-of-foundry-developers/foundry-vtt-types 12.331.3-beta → 12.331.4-beta

package/src/foundry/client-esm/audio/convolver.d.mts

@@ -1,4 +1,4 @@
-import type { InexactPartial } from "../../../types/utils.d.mts";
+import type { Identity, InexactPartial, NullishProps } from "fvtt-types/utils";
 
 declare namespace ConvolverEffect {}
 
@@ -16,24 +16,8 @@ declare class ConvolverEffect extends ConvolverNode {
    * @param context - The audio context required by the ConvolverNode
    * @param options - Additional options which modify the ConvolverEffect behavior
    */
-  constructor(
-    context: AudioContext,
-    options?: InexactPartial<
-      {
-        /**
-         * The file path to the impulse response buffer to use
-         * @defaultValue `"sounds/impulse-responses/ir-full.wav"`
-         */
-        impulseResponsePath: string;
-
-        /**
-         * The initial intensity of the effect
-         * @defaultValue `5`
-         */
-        intensity: number;
-      } & ConvolverOptions
-    >,
-  );
+  // options: not null (destructured)
+  constructor(context: AudioContext, options?: ConvolverEffect.ConstructorOptions);
 
   /**
    * Adjust the intensity of the effect on a scale of 0 to 10.
@@ -46,18 +30,17 @@ declare class ConvolverEffect extends ConvolverNode {
    * Update the state of the effect node given the active flag and numeric intensity.
    * @param options - Options which are updated
    */
-  update(
-    options?: InexactPartial<{
-      /** A new effect intensity */
-      intensity: number;
-    }>,
-  ): void;
+  // options: not null (destructured)
+  update(options?: ConvolverEffect.UpdateOptions): void;
 
+  /** @privateRemarks This override only does side effects then forwards args to super, no type changes */
   override disconnect(output?: number): void;
   override disconnect(destinationNode?: AudioNode, output?: number, input?: number): void;
   override disconnect(destinationParam?: AudioParam, output?: number): void;
 
+  /** @remarks Foundry only supports the "pass a node, get that node returned" signature */
   override connect(destinationNode: AudioNode, output?: number, input?: number): AudioNode;
+  /** @deprecated Foundry does not support this signature, only the other overload */
   override connect(destinationParam: AudioParam, output?: number): AudioParam;
 
   /**
@@ -68,4 +51,43 @@ declare class ConvolverEffect extends ConvolverNode {
   onConnectFrom(sourceNode: AudioNode): void;
 }
 
+declare namespace ConvolverEffect {
+  interface Any extends AnyConvolverEffect {}
+  interface AnyConstructor extends Identity<typeof AnyConvolverEffect> {}
+
+  /** @internal */
+  type _ConstructorOptions = InexactPartial<{
+    /**
+     * The file path to the impulse response buffer to use
+     * @defaultValue `"sounds/impulse-responses/ir-full.wav"`
+     * @remarks Can't be `null` as it only has a parameter default
+     */
+    impulseResponsePath: string;
+
+    /**
+     * The initial intensity of the effect
+     * @defaultValue `5`
+     * @remarks Can't be `null` as it only has a parameter default
+     */
+    intensity: number;
+  }>;
+
+  interface ConstructorOptions extends _ConstructorOptions, ConvolverOptions {}
+
+  /** @internal */
+  type _UpdateOptions = NullishProps<{
+    /**
+     * A new effect intensity
+     * @remarks This is ignored if it fails a `Number.isFinite` check
+     */
+    intensity: number;
+  }>;
+
+  interface UpdateOptions extends _UpdateOptions {}
+}
+
 export default ConvolverEffect;
+
+declare abstract class AnyConvolverEffect extends ConvolverEffect {
+  constructor(...args: never);
+}

package/src/foundry/client-esm/audio/helper.d.mts

@@ -1,12 +1,12 @@
 import type Sound from "./sound.d.mts";
 import type AudioBufferCache from "./cache.d.mts";
-import type { InexactPartial } from "../../../types/utils.d.mts";
+import type { Identity, InexactPartial, IntentionalPartial, NullishProps } from "fvtt-types/utils";
 
 /**
  * A helper class to provide common functionality for working with the Web Audio API.
  * https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API
  * A singleton instance of this class is available as game#audio.
- * @see Game#audio
+ * @see {@link Game.audio | `Game#audio`}
  */
 declare class AudioHelper {
   constructor();
@@ -28,7 +28,7 @@ declare class AudioHelper {
   /**
    * The set of singleton Sound instances which are cached for different audio paths
    */
-  sounds: Map<string, Sound>;
+  sounds: Map<string, WeakRef<Sound>>;
 
   /**
    * Get a map of the Sound objects which are currently playing.
@@ -39,15 +39,17 @@ declare class AudioHelper {
    * A user gesture must be registered before audio can be played.
    * This Array contains the Sound instances which are requested for playback prior to a gesture.
    * Once a gesture is observed, we begin playing all elements of this Array.
-   * @see Sound
+   * @see {@link Sound | `Sound`}
    * @defaultValue `[]`
+   * @remarks Foundry only populates this in one place, {@link SoundsLayer.refresh | `SoundsLayer#refresh`}
    */
   pending: (() => void)[];
 
   /**
    * A Promise which resolves once the game audio API is unlocked and ready to use.
+   * @privateRemarks Not initialized to a value, but set during construction to `this.awaitFirstGesture()`
    */
-  unlock: ReturnType<this["awaitFirstGesture"]>;
+  unlock: Promise<void>;
 
   /**
    * A flag for whether video playback is currently locked by awaiting a user gesture
@@ -57,18 +59,24 @@ declare class AudioHelper {
 
   /**
    * A singleton audio context used for playback of music
+   * @remarks Not initialized to a value, set in {@link AudioHelper._onFirstGesture | `AudioHelper#_onFirstGesture`};
+   * In practice, `undefined` until the first audio is played after page load
    */
-  music: AudioContext;
+  music: AudioContext | undefined;
 
   /**
    * A singleton audio context used for playback of environmental audio.
+   * @remarks Not initialized to a value, set in {@link AudioHelper._onFirstGesture | `AudioHelper#_onFirstGesture`};
+   * In practice, `undefined` until the first audio is played after page load
    */
-  environment: AudioContext;
+  environment: AudioContext | undefined;
 
   /**
    * A singleton audio context used for playback of interface sounds and effects.
+   * @remarks Not initialized to a value, set in {@link AudioHelper._onFirstGesture | `AudioHelper#_onFirstGesture`};
+   * In practice, `undefined` until the first audio is played after page load
    */
-  interface: AudioContext;
+  interface: AudioContext | undefined;
 
   /**
    * For backwards compatibility, AudioHelper#context refers to the context used for music playback.
@@ -83,6 +91,7 @@ declare class AudioHelper {
   /**
    * Create a Sound instance for a given audio source URL
    * @param options - Sound creation options
+   * @remarks `options` has no `={}`, an object with a valid `src` string must be passed
    */
   create(options: AudioHelper.SoundCreationOptions): Sound;
 
@@ -106,18 +115,13 @@ declare class AudioHelper {
    * @param options - Additional options which configure playback
    * @returns The created Sound which is now playing
    */
-  play(
-    src: string,
-    options?: Sound.PlaybackOptions &
-      InexactPartial<{
-        /** A specific AudioContext within which to play */
-        context: AudioContext;
-      }>,
-  ): Promise<Sound>;
+  // options: not null (destructured)
+  play(src: string, options?: AudioHelper.PlayOptions): Promise<Sound>;
 
   /**
    * Register an event listener to await the first mousemove gesture and begin playback once observed
    * @returns The unlocked audio context
+   * @remarks Actually returns a `Promise<void>` that resolves when the audio context is unlocked
    */
   awaitFirstGesture(): Promise<void>;
 
@@ -153,15 +157,7 @@ declare class AudioHelper {
    * AudioHelper.play({src: "sounds/lock.wav", volume: 0.8, loop: false}, true);
    * ```
    */
-  static play(
-    data: AudioHelper.PlayData,
-    socketOptions?:
-      | boolean
-      | {
-          /** An array of user IDs to push audio playback to. All users by default. */
-          recipients: string[];
-        },
-  ): Promise<Sound>;
+  static play(data: AudioHelper.PlayData, socketOptions?: boolean | AudioHelper.SocketOptions | null): Promise<Sound>;
 
   /**
    * Begin loading the sound for a provided source URL adding its
@@ -174,8 +170,8 @@ declare class AudioHelper {
    * Returns the volume value based on a range input volume control's position.
    * This is using an exponential approximation of the logarithmic nature of audio level perception
    * @param value - Value between [0, 1] of the range input
-   * @param order - The exponent of the curve
-   *                (default: `1.5`)
+   * @param order - The exponent of the curve (default: `1.5`)
+   * @remarks String `value`s will be `parseFloat`ed, so an empty string produces `NaN`
    */
   static inputToVolume(value: number | string, order?: number): number;
 
@@ -183,7 +179,7 @@ declare class AudioHelper {
    * Counterpart to inputToVolume()
    * Returns the input range value based on a volume
    * @param volume - Value between [0, 1] of the volume level
-   * @param order  - The exponent of the curve
+   * @param order  - The exponent of the curve (default: `1.5`)
    */
   static volumeToInput(volume: number, order?: number): number;
 
@@ -193,8 +189,10 @@ declare class AudioHelper {
    * in which case null will be returned
    *
    * @returns A singleton AudioContext or null if one is not available
+   * @remarks Despite Foundry's description of the return, always returns an `AudioContext`, freshly
+   * created if `AudioHelper.#analyzerContext` has not previously been initialized
    */
-  getAnalyzerContext(): AudioContext | null;
+  getAnalyzerContext(): AudioContext;
 
   /**
    * Registers a stream for periodic reports of audio levels.
@@ -205,19 +203,18 @@ declare class AudioHelper {
    * @param id        - An id to assign to this report. Can be used to stop reports
    * @param stream    - The MediaStream instance to report activity on.
    * @param callback  - The callback function to call with the decibel level.
-   * @param interval  - The interval at which to produce reports.
-   *                    (default: `50`)
-   * @param smoothing - The smoothingTimeConstant to set on the audio analyser.
-   *                    (default: `0.1`)
+   * @param interval  - The interval at which to produce reports. (default: `50`)
+   * @param smoothing - The smoothingTimeConstant to set on the audio analyser. (default: `0.1`)
    * @returns Returns whether listening to the stream was successful
    */
+  // interval, smoothing: not null (parameter default only)
   startLevelReports(
     id: string,
     stream: MediaStream,
-    callback: (maxDecibel: number, fftArray: Float32Array) => void,
+    callback: AudioHelper.LevelReportCallback,
     interval?: number,
     smoothing?: number,
-  ): boolean | undefined;
+  ): boolean;
 
   /**
    * Stop sending audio level reports
@@ -243,84 +240,131 @@ declare class AudioHelper {
 
   /**
    * @deprecated since v12, will be removed in v14
+   * @remarks "`AudioHelper#getCache` is deprecated in favor of {@link AudioBufferCache | `AudioHelper#buffers#get`}"
    */
   getCache(src: string): AudioBuffer | undefined;
 
   /**
    * @deprecated since v12, will be removed in v14
+   * @remarks "`AudioHelper#updateCache` is deprecated without replacement"
    */
   updateCache(src: string, playing: boolean): void;
 
   /**
    * @deprecated since v12, will be removed in v14
+   * @remarks "`AudioHelper#setCache` is deprecated in favor of {@link AudioBufferCache | `AudioHelper#buffers#set`}"
    */
   setCache(src: string, buffer: AudioBuffer): void;
 }
 
 declare namespace AudioHelper {
-  interface SoundCreationOptions {
-    /**
-     * The source URL for the audio file
-     */
-    src: string;
-
-    /**
-     * A specific AudioContext to attach the sound to
-     */
-    context: AudioContext;
-
-    /**
-     * Reuse an existing Sound for this source?
-     * @defaultValue `true`
-     */
-    singleton?: boolean;
-
-    /**
-     * Begin loading the audio immediately?
-     * @defaultValue `false`
-     */
-    preload?: boolean;
-
-    /**
-     * Begin playing the audio as soon as it is ready?
-     * @defaultValue `false`
-     */
-    autoplay?: boolean;
+  interface Any extends AnyAudioHelper {}
+  interface AnyConstructor extends Identity<typeof AnyAudioHelper> {}
 
+  /** @internal */
+  type _SoundCreationOptions = InexactPartial<{
     /**
      * Additional options passed to the play method if autoplay is true
      * @defaultValue `{}`
+     * @remarks Can't be `null` as it only has a parameter default
      */
-    autoplayOptions?: Sound.PlaybackOptions;
-  }
-
-  interface PlayData {
-    /**
-     * The audio source file path, either a public URL or a local path relative to the public directory
-     */
+    autoplayOptions: Sound.PlaybackOptions;
+  }> &
+    NullishProps<{
+      /**
+       * A specific AudioContext to attach the sound to
+       * @remarks Has no default, but if it's falsey, the {@link Sound | `Sound`} constructor
+       * (where this is forwarded) will use {@link AudioHelper.music | `game.audio.music`} instead
+       */
+      context: AudioContext;
+
+      /**
+       * Reuse an existing Sound for this source?
+       * @defaultValue `true`
+       */
+      singleton: boolean;
+
+      /**
+       * Begin loading the audio immediately?
+       * @defaultValue `false`
+       */
+      preload: boolean;
+
+      /**
+       * Begin playing the audio as soon as it is ready?
+       * @defaultValue `false`
+       */
+      autoplay: boolean;
+    }>;
+
+  interface SoundCreationOptions extends _SoundCreationOptions {
+    /** The source URL for the audio file */
     src: string;
+  }
 
-    /** An audio channel in CONST.AUDIO_CHANNELS where the sound should play */
-    channel?: keyof typeof CONST.AUDIO_CHANNELS;
+  /**
+   * {@link AudioHelper#play | `AudioHelper#play`} pulls `context` out of this object then forwards the rest to {@link Sound.play | `Sound#play`}
+   */
+  interface PlayOptions extends Pick<SoundCreationOptions, "context">, Sound.PlaybackOptions {}
 
+  /** @internal */
+  type _PlayData = IntentionalPartial<{
     /**
-     * The volume level at which to play the audio, between 0 and 1.
-     * @defaultValue `1.0`
+     * An audio channel in CONST.AUDIO_CHANNELS where the sound should play
+     * @defaultValue `"interface"`
+     * @remarks Can't be nullish as the only default is provided by `mergeObject`
      */
-    volume?: number;
+    channel: keyof typeof CONST.AUDIO_CHANNELS;
 
     /**
      * Begin playback of the audio effect immediately once it is loaded.
-     * @deprecated You are using the autoplay option of AudioHelper.play which is no longer supported in 0.8.0
+     * @remarks Can't be nullish as it has no default and is checked for `=== false`
+     * @privateRemarks This formerly (some time before v11) had a deprecation warning associated with it:
+     *
+     * "You are using the autoplay option of AudioHelper.play which is no longer supported in 0.8.0"
+     *
+     * In v11+, it's simply checked for an early return with `=== false`, with a comment that doesn't indicate a deprecation period:
+     *
+     * "// Backwards compatibility, if autoplay was passed as false take no further action"
      */
-    autoplay?: boolean;
+    autoplay: false;
+  }> &
+    NullishProps<{
+      /**
+       * The volume level at which to play the audio, between 0 and 1.
+       * @defaultValue `1.0`
+       * @privateRemarks Despite the initial default being via `mergeObject`, there's a second `??` default so it's allowed to be nullish
+       */
+      volume: number;
+
+      /**
+       * Loop the audio effect and continue playing it until it is manually stopped.
+       * @defaultValue `false`
+       * @privateRemarks Despite the default being via `mergeObject`, {@link Sound.PlaybackOptions.loop | `Sound.PlaybackOptions["loop"]`} can be nullish, therefor so can this
+       */
+      loop: boolean;
+    }>;
+
+  interface PlayData extends _PlayData {
+    /**
+     * The audio source file path, either a public URL or a local path relative to the public directory
+     */
+    src: string;
+  }
 
+  interface SocketOptions {
     /**
-     * Loop the audio effect and continue playing it until it is manually stopped.
-     * @defaultValue `false`
+     * An array of user IDs to push audio playback to. All users by default.
+     * @remarks Nullish values cause errors, but omitting this key (passing an empty object) is the same as passing `true` (all players)
      */
-    loop?: boolean;
+    recipients?: string[];
   }
+
+  type LevelReportCallback = (maxDecibel: number, fftArray: Float32Array) => void;
 }
 
 export default AudioHelper;
+
+declare abstract class AnyAudioHelper extends AudioHelper {
+  constructor(...args: never);
+}