@league-of-foundry-developers/foundry-vtt-types 9.255.0 → 9.255.1

package/README.md

@@ -17,7 +17,7 @@ TypeScript type definitions for [Foundry Virtual Tabletop](https://foundryvtt.co
 
 We aim to support the latest release of each Foundry VTT version (0.7, 0.8, 9, etc.), starting with 0.7.
 
-At the moment, both version 0.7 and 0.8 are fully supported. Version 9 is already partially supported, but there is still a lot to be done. See https://github.com/League-of-Foundry-Developers/foundry-vtt-types/issues?q=is%3Aopen+is%3Aissue+label%3A%22foundry+V9%22 to keep track of the progress.
+At the moment, both version 0.7 and 0.8 are fully supported. Version 9 is already partially supported, but there is still a lot to be done. See the [open foundry V9 issues](https://github.com/League-of-Foundry-Developers/foundry-vtt-types/issues?q=is%3Aopen+is%3Aissue+label%3A%22foundry+V9%22) to keep track of the progress.
 
 
 ## Installation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@league-of-foundry-developers/foundry-vtt-types",
-  "version": "9.255.0",
+  "version": "9.255.1",
   "description": "TypeScript type definitions for Foundry VTT",
   "exports": {
     ".": {

package/src/foundry/common/types.mjs.d.ts

@@ -1,17 +1,17 @@
 /**
  * A single point, expressed as an object \{x, y\}
  */
-declare type Point = PIXI.Point | { x: number; y: number };
+type Point = PIXI.Point | { x: number; y: number };
 
 /**
  * A single point, expressed as an array \[x,y\]
  */
-declare type PointArray = [x: number, y: number];
+type PointArray = [x: number, y: number];
 
 /**
  * A standard rectangle interface.
  */
-declare type Rectangle =
+type Rectangle =
   | PIXI.Rectangle
   | {
       x: number;
@@ -20,8 +20,89 @@ declare type Rectangle =
       height: number;
     };
 
+/** A Client Setting */
+interface SettingConfig<T = unknown> {
+  /** A unique machine-readable id for the setting */
+  key: string;
+
+  /** The namespace the setting belongs to */
+  namespace: string;
+
+  /** The human readable name */
+  name?: string | undefined;
+
+  /** An additional human readable hint */
+  hint?: string | undefined;
+
+  /**
+   * The scope the Setting is stored in, either World or Client
+   * @defaultValue `'client'`
+   */
+  scope: 'world' | 'client';
+
+  /** Indicates if this Setting should render in the Config application */
+  config?: boolean | undefined;
+
+  /** The JS Type that the Setting is storing */
+  type?: T extends string
+    ? typeof String
+    : T extends number
+    ? typeof Number
+    : T extends boolean
+    ? typeof Boolean
+    : T extends Array<any>
+    ? typeof Array
+    : ConstructorOf<T>;
+
+  /** For string Types, defines the allowable values */
+  choices?: (T extends string ? Record<string, string> : never) | undefined;
+
+  /** For numeric Types, defines the allowable range */
+  range?:
+    | (T extends number
+        ? {
+            max: number;
+            min: number;
+            step: number;
+          }
+        : never)
+    | undefined;
+
+  /** The default value */
+  default?: T;
+
+  /** Executes when the value of this Setting changes */
+  onChange?: (value: T) => void;
+
+  filePicker?: (T extends string ? true | 'audio' | 'image' | 'video' | 'imagevideo' | 'folder' : never) | undefined;
+}
+
+interface SettingSubmenuConfig {
+  key: string;
+
+  namespace: string;
+
+  /** The human readable name */
+  name?: string | undefined;
+
+  /** The human readable label */
+  label?: string | undefined;
+
+  /** An additional human readable hint */
+  hint?: string | undefined;
+
+  /** The classname of an Icon to render */
+  icon?: string | undefined;
+
+  /** The FormApplication to render */
+  type: ConstructorOf<FormApplication<FormApplicationOptions, object, undefined>>;
+
+  /** If true, only a GM can edit this Setting */
+  restricted?: boolean | undefined;
+}
+
 /** A Client Keybinding Action Configuration */
-declare interface KeybindingActionConfig {
+interface KeybindingActionConfig {
   /** The namespace within which the action was registered */
   namespace?: string;
 
@@ -60,7 +141,7 @@ declare interface KeybindingActionConfig {
 }
 
 /** A Client Keybinding Action Binding */
-declare interface KeybindingActionBinding {
+interface KeybindingActionBinding {
   /** The KeyboardEvent#code value from https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values */
   key: string;
 
@@ -68,22 +149,44 @@ declare interface KeybindingActionBinding {
   modifiers?: string[];
 }
 
-declare interface KeybindingAction {
+/** An action that can occur when a key is pressed */
+interface KeybindingAction {
+  /** The namespaced machine identifier of the Action */
   action: string;
+
+  /** The Keyboard key */
   key: string;
+
+  /** The human readable name */
   name: string;
+
+  /** Required modifiers */
   requiredModifiers: string[];
+
+  /** Optional (reserved) modifiers */
   optionalModifiers: string[];
+
+  /** The handler that executes onDown */
   onDown: Function;
+
+  /** The handler that executes onUp */
   onUp: Function;
+
+  /** If True, allows Repeat events to execute this Action's onDown */
   repeat: boolean;
+
+  /** If true, only a GM can execute this Action */
   restricted: boolean;
+
+  /** The registration precedence */
   precedence: number;
+
+  /** The registration order */
   order: number;
 }
 
 /** Keyboard event context */
-declare interface KeyboardEventContext {
+interface KeyboardEventContext {
   /** The normalized string key, such as "A" */
   key: string;
 
@@ -115,6 +218,15 @@ declare interface KeyboardEventContext {
   action: string | undefined;
 }
 
+/** Connected Gamepad info */
+interface ConnectedGamepad {
+  /** A map of axes values */
+  axes: Map<string, number>;
+
+  /** The Set of pressed Buttons */
+  activeButtons: Set<string>;
+}
+
 type RequestData = object | object[] | string | string[];
 
 interface SocketRequest {
@@ -183,5 +295,5 @@ interface SocketResponse {
   /**
    * An Array of created data objects
    */
-  result?: object[];
+  result?: object[] | string[];
 }

package/src/foundry/common/utils/http.mjs.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A wrapper method around `fetch` that attaches an AbortController signal to the `fetch` call for clean timeouts
+ * @see https://www.npmjs.com/package/node-fetch#request-cancellation-with-abortsignal
+ * @param url            - The URL to make the Request to
+ * @param data           - The data of the Request
+ *                         (defalt: `{}`)
+ * @param timeoutOptions - (default: `{}`)
+ * @throws {@link HttpError}
+ */
+export function fetchWithTimeout(
+  url: string,
+  data?: RequestInit | undefined,
+  { timeoutMs, onTimeout }?: TimeoutOptions | undefined
+): Promise<Response>;
+
+/**
+ * A small wrapper that automatically asks for JSON
+ * @param url            - The URL to make the Request to
+ * @param data           - The data of the Request
+ *                         (defalt: `{}`)
+ * @param timeoutOptions - (default: `{}`)
+ */
+export function fetchJsonWithTimeout(
+  url: string,
+  data?: RequestInit | undefined,
+  { timeoutMs, onTimeout }?: TimeoutOptions | undefined
+): Promise<unknown>;
+
+/**
+ * Represents an HTTP Error when a non-OK response is returned by Fetch
+ */
+export class HttpError extends Error {
+  constructor(statusText: string, code: number, displayMessage?: string | undefined);
+
+  code: number;
+
+  displayMessage: string;
+}
+
+interface TimeoutOptions {
+  /**
+   * How long to wait for a Response before cleanly aborting
+   * @defaultValue `30000`
+   */
+  timeoutMs?: number | undefined;
+
+  /**
+   * A method to invoke if and when the timeout is reached
+   * @defaultValue `() => {}`
+   */
+  onTimeout?: (() => void) | undefined;
+}

package/src/foundry/common/utils/module.mjs.d.ts

@@ -1,4 +1,5 @@
 export * from './geometry.mjs';
 export * from './helpers.mjs';
+export * from './http.mjs';
 export { default as Collection } from './collection.mjs';
 export { default as Semaphore } from './semaphore.mjs';

package/src/foundry/common/utils/semaphore.mjs.d.ts

@@ -35,6 +35,7 @@ declare class Semaphore {
   /**
    * A queue of pending function signatures
    * @defaultValue `[]`
+   * @internal
    * @remarks The first element of an element of `_queue` is always a function and the rest of the elements are
    * parameters to be passed to that function.
    */
@@ -43,6 +44,7 @@ declare class Semaphore {
   /**
    * The number of tasks which are currently underway
    * @defaultValue `0`
+   * @internal
    */
   protected _active: number;
 
@@ -60,8 +62,9 @@ declare class Semaphore {
    * Add a new tasks to the managed queue
    * @param fn   - A callable function
    * @param args - Function arguments
+   * @returns A promise that resolves once the added function is executed
    */
-  add<F extends (...args: any[]) => any>(fn: F, ...args: Parameters<F>): void;
+  add<F extends (...args: any[]) => any>(fn: F, ...args: Parameters<F>): Promise<Awaited<ReturnType<F>>>;
 
   /**
    * Abandon any tasks which have not yet concluded
@@ -72,9 +75,9 @@ declare class Semaphore {
    * Attempt to perform a task from the queue.
    * If all workers are busy, do nothing.
    * If successful, try again.
-   * @returns Was a function called?
+   * @internal
    */
-  protected _try(): Promise<boolean>;
+  protected _try(): Promise<false | void>;
 }
 
 export default Semaphore;

package/src/foundry/foundry.js/applications/formApplications/documentSheets/actorSheet.d.ts

@@ -41,7 +41,7 @@ declare global {
     get title(): string;
 
     /**
-     * A convenience reference to the Actor entity
+     * A convenience reference to the Actor document
      */
     get actor(): this['object'];
 
@@ -72,11 +72,6 @@ declare global {
      */
     protected _onConfigureToken(event: JQuery.ClickEvent): void;
 
-    /**
-     * Handle requests to configure the default sheet used by this Actor
-     */
-    protected _onConfigureSheet(event: JQuery.ClickEvent): void;
-
     /**
      * Handle changing the actor profile image by opening a FilePicker
      */
@@ -156,6 +151,13 @@ declare global {
       event: DragEvent,
       itemData: foundry.data.ItemData['_source']
     ): undefined | Promise<InstanceType<ConfiguredDocumentClass<typeof Item>>[]>;
+
+    /**
+     * Is the drop data coming from the same actor?
+     * @param data - The drop data.
+     * @internal
+     */
+    protected _isFromSameActor(data: ActorSheet.DropData.Item): Promise<boolean>;
   }
 
   namespace ActorSheet {

package/src/foundry/foundry.js/applications/formApplications/settingsConfig.d.ts

@@ -66,20 +66,20 @@ declare global {
       interface Data {
         core: {
           version: string;
-          menus: ClientSettings.CompleteMenuSetting[];
+          menus: SettingSubmenuConfig[];
           settings: Setting[];
           none: boolean;
         };
         system: {
           title: Game['system']['data']['title'];
-          menus: ClientSettings.CompleteMenuSetting[];
+          menus: SettingSubmenuConfig[];
           settings: Setting[];
           none: boolean;
         };
-        modules: { title: string; menus: ClientSettings.CompleteMenuSetting[]; settings: Setting[] }[];
+        modules: { title: string; menus: SettingSubmenuConfig[]; settings: Setting[] }[];
       }
 
-      interface Setting extends Omit<ClientSettings.CompleteSetting, 'type'> {
+      interface Setting extends Omit<SettingConfig, 'type'> {
         id: string;
         name: string;
         hint: string;

package/src/foundry/foundry.js/avClient.d.ts

@@ -82,7 +82,7 @@ declare abstract class AVClient {
    * @param kind - The type of device source being requested
    * @internal
    */
-  _getSourcesOfType(kind: MediaDeviceKind): Promise<Record<string, string>>;
+  protected _getSourcesOfType(kind: MediaDeviceKind): Promise<Record<string, string>>;
 
   /**
    * Return an array of Foundry User IDs which are currently connected to A/V.
@@ -98,6 +98,14 @@ declare abstract class AVClient {
    */
   abstract getMediaStreamForUser(userId: string): MediaStream | null | undefined;
 
+  /**
+   * Provide a MediaStream for monitoring a given user's voice volume levels.
+   * @param userId - The User ID.
+   * @returns The MediaStream for the user, or null if the user does not have one.
+   * @remarks The getLevelsStreamForUser() method must be defined by an AVClient subclass and will be strictly required starting in v10
+   */
+  getLevelsStreamForUser(userId: string): MediaStream | null | undefined;
+
   /**
    * Is outbound audio enabled for the current user?
    */
@@ -141,4 +149,10 @@ declare abstract class AVClient {
    * @param changed - The settings which have changed
    */
   onSettingsChanged(changed: DeepPartial<AVSettings.Settings>): void;
+
+  /**
+   * Replace the local stream for each connected peer with a re-generated MediaStream.
+   * @remarks The updateLocalStream() method must be defined by an AVClient subclass.
+   */
+  abstract updateLocalStream(): Promise<void>;
 }

package/src/foundry/foundry.js/avClients/index.d.ts

@@ -1,2 +1 @@
-import './easyRTCClient';
 import './simplePeerAVClient';

package/src/foundry/foundry.js/avClients/simplePeerAVClient.d.ts

@@ -9,6 +9,12 @@ declare class SimplePeerAVClient extends AVClient {
    */
   localStream: MediaStream | null;
 
+  /**
+   * The dedicated audio stream used to measure volume levels for voice activity detection.
+   * @defaultValue `null`
+   */
+  levelsStream: MediaStream | null;
+
   /**
    * A mapping of connected peers
    */
@@ -24,7 +30,7 @@ declare class SimplePeerAVClient extends AVClient {
    * @defaultValue `false`
    * @internal
    */
-  _initialized: boolean;
+  protected _initialized: boolean;
 
   /**
    * Is outbound broadcast of local audio enabled?
@@ -32,9 +38,21 @@ declare class SimplePeerAVClient extends AVClient {
    */
   audioBroadcastEnabled: boolean;
 
+  /**
+   * The polling interval ID for connected users that might have unexpectedly dropped out of our peer network.
+   * @internal
+   */
+  protected _connectionPoll: number | null;
+
   /** @override */
   connect(): Promise<boolean>;
 
+  /**
+   * Try to establish a peer connection with each user connected to the server.
+   * @internal
+   */
+  protected _connect(): Promise<SimplePeer.Instance[]>;
+
   /** @override */
   disconnect(): Promise<boolean>;
 
@@ -47,6 +65,9 @@ declare class SimplePeerAVClient extends AVClient {
   /** @override */
   getMediaStreamForUser(userId: string): MediaStream | null | undefined;
 
+  /** @override */
+  getLevelsStreamForUser(userId: string): MediaStream | null | undefined;
+
   /** @override */
   isAudioEnabled(): boolean;
 
@@ -70,6 +91,14 @@ declare class SimplePeerAVClient extends AVClient {
    */
   initializeLocalStream(): Promise<MediaStream | null>;
 
+  /**
+   * Attempt to create local media streams.
+   * @param params - Parameters for the getUserMedia request.
+   * @returns The created MediaStream or an error.
+   * @internal
+   */
+  protected _createMediaStream(params: MediaStreamConstraints): Promise<MediaStream | Error>;
+
   /**
    * Listen for Audio/Video updates on the av socket to broker connections between peers
    */
@@ -131,8 +160,6 @@ declare class SimplePeerAVClient extends AVClient {
   /** @override */
   onSettingsChanged(changed: DeepPartial<AVSettings.Settings>): Promise<void>;
 
-  /**
-   * Replace the local stream for each connected peer with a re-generated MediaStream
-   */
+  /** @override */
   updateLocalStream(): Promise<void>;
 }

package/src/foundry/foundry.js/avMaster.d.ts

@@ -29,24 +29,26 @@ declare class AVMaster {
   protected _connected: boolean;
 
   /**
-   * A flag to track whether the A/V system is currently in the process of reconnecting.
-   * This occurs if the connection is lost or interrupted.
-   * @defaultValue `false`
+   * The cached connection promise.
+   * This is required to prevent re-triggering a connection while one is already in progress.
+   * @defaultValue `null`
    * @internal
    */
-  protected _reconnecting: boolean;
+  protected _connecting: Promise<boolean> | null;
 
   /**
-   * @defaultValue `{}`
+   * A flag to track whether the A/V system is currently in the process of reconnecting.
+   * This occurs if the connection is lost or interrupted.
+   * @defaultValue `false`
    * @internal
    */
-  protected _speakingData: AVMaster.SpeakingData;
+  protected _reconnecting: boolean;
 
   /**
    * @defaultValue `{}`
    * @internal
    */
-  protected _pttHandlers: AVMaster.PTTHandlers;
+  protected _speakingData: { speaking: boolean; volumeHistories: number[] };
 
   /**
    * @defaultValue `0`
@@ -54,7 +56,7 @@ declare class AVMaster {
    */
   protected _pttMuteTimeout: number;
 
-  get mode(): AVSettings.VoiceMode;
+  get mode(): AVSettings.AV_MODES;
 
   /**
    * Connect to the Audio/Video client.
@@ -111,29 +113,27 @@ declare class AVMaster {
    * @param mode - The currently selected voice broadcasting mode
    * @internal
    */
-  protected _initializeUserVoiceDetection(mode: AVSettings.VoiceMode): void;
+  protected _initializeUserVoiceDetection(mode: AVSettings.VOICE_MODES): void;
 
   /**
    * Activate voice detection tracking for a userId on a provided MediaStream.
    * Currently only a MediaStream is supported because MediaStreamTrack processing is not yet supported cross-browser.
-   * @param userId - The Foundry User ID whose voice is being processed
    * @param stream - The MediaStream which corresponds to that User
    * @param ms     - A number of milliseconds which represents the voice activation volume interval
    *                 (default: `CONFIG.WebRTC.detectPeerVolumeInterval`)
    */
-  activateVoiceDetection(userId: string, stream: MediaStream, ms?: number): void;
+  activateVoiceDetection(stream: MediaStream, ms?: number): void;
 
   /**
    * Actions which the orchestration layer should take when a peer user disconnects from the audio/video service.
-   * @param userId - The id of the disconnecting User
    */
-  deactivateVoiceDetection(userId: string): void;
+  deactivateVoiceDetection(): void;
 
   /**
    * Periodic notification of user audio level
    *
-   * This function uses the audio level (in dB) of each stream it's listening to to determine if a user
-   * is speaking or not and notifies the UI of such changes.
+   * This function uses the audio level (in dB) of the audio stream to determine if the user is speaking or not and
+   * notifies the UI of such changes.
    *
    * The User is considered speaking if they are above the decibel threshold in any of the history values.
    * This marks them as speaking as soon as they have a high enough volume, and marks them as not speaking only after
@@ -142,46 +142,31 @@ declare class AVMaster {
    * There can be more optimal ways to do this and which uses whether the user was already considered speaking before
    * or not, in order to eliminate short bursts of audio (coughing for example).
    *
-   * @param userId  - The user ID of the user whose audio levels are being reported
    * @param dbLevel - The audio level in decibels of the user within the last 50ms
    * @internal
    */
-  protected _onAudioLevel(userId: string, dbLevel: number): void;
-
-  /**
-   * Set up interactivity and handling of push-to-talk broadcasting workflow.
-   * @internal
-   */
-  protected _initializePushToTalk(): void;
+  protected _onAudioLevel(dbLevel: number): void;
 
   /**
    * Resets the speaking history of a user
    * If the user was considered speaking, then mark them as not speaking
-   * @param userId - The ID of the user
    * @internal
    */
-  protected _resetSpeakingHistory(userId: string): void;
+  protected _resetSpeakingHistory(): void;
 
   /**
    * Handle activation of a push-to-talk key or button.
-   * @param event - The original keydown event
+   * @param context - The context data of the event
    * @internal
    */
-  _onPTTStart(event: KeyboardEvent | MouseEvent): void;
+  _onPTTStart(context: KeyboardEventContext): void;
 
   /**
    * Handle deactivation of a push-to-talk key or button.
-   * @param event - The original keyup event
+   * @param context - The context data of the event
    * @internal
    */
-  _onPTTEnd(event: KeyboardEvent | MouseEvent): void;
-
-  /**
-   * Handle matching old and new PTT configurations against the mouse or keyboard event.
-   * @param event - The original event
-   * @internal
-   */
-  _isPTTKey(event: KeyboardEvent | MouseEvent): boolean;
+  _onPTTEnd(context: KeyboardEventContext): void;
 
   render(): void;
 
@@ -200,15 +185,3 @@ declare class AVMaster {
 
   debug(message: string): void;
 }
-
-declare namespace AVMaster {
-  type SpeakingData = Partial<Record<string, { speaking: boolean; volumeHistories: number[] }>>;
-  type PTTHandler = (event: KeyboardEvent | MouseEvent) => void;
-  type PTTHandlers =
-    | {}
-    | { mousedown: PTTHandler; mouseup: PTTHandler }
-    | {
-        keydown: PTTHandler;
-        keyup: PTTHandler;
-      };
-}