@league-of-foundry-developers/foundry-vtt-types 9.280.1 → 12.331.1-beta

package/src/foundry/common/types.d.mts

@@ -0,0 +1,332 @@
+import type { AnyConstructor, AnyFunction, DeepPartial } from "../../types/utils.d.mts";
+import type ApplicationV2 from "../client-esm/applications/api/application.mts";
+import type { CustomFormInput } from "../client-esm/applications/forms/fields.mts";
+import type { Document } from "./abstract/module.d.mts";
+
+interface DocumentConstructionContext extends Document.ConstructionContext<Document.Any | null> {}
+
+// TODO: deprecated in V12, will be removed in V14
+// note: this was removed from this file in V12, but there are still (deprecated) methods
+//    in Document that use it, so we should retain it until V14 when those
+//    methods are removed
+/** @deprecated since v12 */
+interface DocumentModificationContext extends Document.ModificationContext<Document.Any | null> {}
+
+declare global {
+  /**
+   * A single point, expressed as an object \{x, y\}
+   */
+  type Point = PIXI.Point | { x: number; y: number };
+
+  /**
+   * A single point, expressed as an array \[x,y\]
+   */
+  type PointArray = [x: number, y: number];
+
+  /**
+   * Make all properties in T recursively readonly.
+   */
+  type DeepReadonly<T> = Readonly<{
+    [K in keyof T]: T[K] extends
+      | undefined
+      | null
+      | boolean
+      | number
+      | string
+      | symbol
+      | bigint
+      | AnyFunction
+      | AnyConstructor
+      ? T[K]
+      : T[K] extends Array<infer V>
+        ? ReadonlyArray<DeepReadonly<V>>
+        : T[K] extends Map<infer K, infer V>
+          ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>>
+          : T[K] extends Set<infer V>
+            ? ReadonlySet<DeepReadonly<V>>
+            : DeepReadonly<T[K]>;
+  }>;
+
+  /**
+   * A class constructor.
+   * Used for functions with generic class constructor parameters.
+   */
+  type Constructor = new (...args: any[]) => any;
+
+  /**
+   * A standard rectangle interface.
+   */
+  interface Rectangle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }
+
+  type BuiltInTypes = typeof Number | typeof String | typeof Boolean;
+
+  type RGBColorVector = [r: number, g: number, b: number];
+  type HSVColorVector = [h: number, s: number, v: number];
+  type HSLColorVector = [h: number, s: number, l: number];
+
+  type ColorSource = number | RGBColorVector | string | Color;
+
+  /** A Client Setting */
+  interface SettingOptions<T extends ClientSettings.Type = (value: unknown) => unknown>
+    extends _SettingOptions<ClientSettings.ToRuntimeType<T>, ClientSettings.ToSettingAssignmentType<T>> {}
+
+  /**
+   * A Client Setting Submenu
+   */
+  interface SettingSubmenuConfig {
+    key: string;
+
+    namespace: string;
+
+    /** The human-readable name */
+    name?: string | undefined;
+
+    /** An additional human-readable hint */
+    label?: string | undefined;
+
+    /** An additional human readable hint */
+    hint?: string | undefined;
+
+    /** The classname of an Icon to render */
+    icon?: string | undefined;
+
+    /** The FormApplication or ApplicationV2 to render */
+    type:
+      | (new () => FormApplication.Any)
+      | (new (options?: DeepPartial<ApplicationV2.Configuration>) => ApplicationV2.Any);
+
+    /** If true, only a GM can edit this Setting */
+    restricted?: boolean | undefined;
+  }
+
+  /** A Client Keybinding Action Configuration */
+  interface KeybindingActionConfig {
+    /** The namespace within which the action was registered */
+    namespace?: string;
+
+    /** The human readable name */
+    name: string;
+
+    /** An additional human readable hint */
+    hint?: string | undefined;
+
+    /** The default bindings that can never be changed nor removed. */
+    uneditable?: KeybindingActionBinding[] | undefined;
+
+    /** The default bindings that can be changed by the user. */
+    editable?: KeybindingActionBinding[] | undefined;
+
+    /** A function to execute when a key down event occurs. If True is returned, the event is consumed and no further keybinds execute. */
+    onDown?: ((ctx: KeyboardEventContext) => boolean | void) | undefined;
+
+    /** A function to execute when a key up event occurs. If True is returned, the event is consumed and no further keybinds execute. */
+    onUp?: ((ctx: KeyboardEventContext) => boolean | void) | undefined;
+
+    /** If True, allows Repeat events to execute the Action's onDown. Defaults to false. */
+    repeat?: boolean | undefined;
+
+    /** If true, only a GM can edit and execute this Action */
+    restricted?: boolean | undefined;
+
+    /** Modifiers such as [ "CONTROL" ] that can be also pressed when executing this Action. Prevents using one of these modifiers as a Binding. */
+    reservedModifiers?: string[] | undefined;
+
+    /** The preferred precedence of running this Keybinding Action */
+    precedence?: number | undefined; // TODO: KEYBINDING_PRECEDENCE?
+
+    /** The recorded registration order of the action */
+    order?: number | undefined;
+  }
+
+  /** A Client Keybinding Action Binding */
+  interface KeybindingActionBinding {
+    /** A numeric index which tracks this bindings position during form rendering */
+    index?: number | undefined;
+
+    /** The KeyboardEvent#code value from https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code/code_values */
+    key: string;
+
+    /** An array of modifiers keys from KeyboardManager.MODIFIER_KEYS which are required for this binding to be activated */
+    modifiers?: string[] | undefined;
+  }
+
+  /** 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?: ((ctx: KeyboardEventContext) => boolean | void) | undefined;
+
+    /** The handler that executes onUp */
+    onUp?: ((ctx: KeyboardEventContext) => boolean | void) | undefined;
+
+    /** 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 */
+  interface KeyboardEventContext {
+    /** The normalized string key, such as "A" */
+    key: string;
+
+    /** The originating keypress event */
+    event: KeyboardEvent;
+
+    /** Is the Shift modifier being pressed */
+    isShift: boolean;
+
+    /** Is the Control or Meta modifier being processed */
+    isControl: boolean;
+
+    /** Is the Alt modifier being pressed */
+    isAlt: boolean;
+
+    /** Are any of the modifiers being pressed */
+    hasModifier: boolean;
+
+    /** A list of string modifiers applied to this context, such as [ "CONTROL" ] */
+    modifiers: string[];
+
+    /** True if the Key is Up, else False if down */
+    up: boolean;
+
+    /** True if the given key is being held down such that it is automatically repeating. */
+    repeat: boolean;
+
+    /** The executing Keybinding Action. May be undefined until the action is known. */
+    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 = Record<string, unknown> | Record<string, unknown>[] | string | string[];
+
+  interface SocketRequest {
+    /** Additional options applied to the request */
+    options?: Record<string, unknown> | undefined;
+    broadcast?: boolean | undefined;
+  }
+
+  interface SocketResponse {
+    /**
+     * The initial request
+     */
+    request: SocketRequest;
+
+    /**
+     * An error, if one occurred
+     */
+    error?: Error | undefined;
+
+    /**
+     * The status of the request
+     */
+    status?: string | undefined;
+
+    /**
+     * The ID of the requesting User
+     */
+    userId?: string | undefined;
+
+    /**
+     * Data returned as a result of the request
+     */
+    data?: RequestData | undefined;
+
+    /**
+     * An Array of created data objects
+     */
+    result?: Record<string, unknown>[] | string[] | undefined;
+  }
+}
+
+// This type is named `SettingConfig` in FoundryVTT but that name is confusing within fvtt-types because of the `Config` nomenclature meaning declaration merging.
+interface _SettingOptions<RuntimeType extends ClientSettings.RuntimeType, AssignmentType> {
+  /** 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?: RuntimeType;
+
+  /** For string Types, defines the allowable values */
+  choices?: AssignmentType extends string
+    ? {
+        readonly [K in AssignmentType]?: string;
+      }
+    : never;
+
+  /** For numeric Types, defines the allowable range */
+  range?: AssignmentType extends number
+    ? {
+        max: number;
+        min: number;
+        step: number;
+      }
+    : never;
+
+  /** The default value */
+  default: AssignmentType;
+
+  /** Whether setting requires Foundry to be reloaded on change  */
+  requiresReload?: boolean;
+
+  /** Executes when the value of this Setting changes */
+  onChange?: (value: AssignmentType) => void;
+
+  /**
+   * A custom form field input used in conjunction with a DataField type
+   */
+  input?: CustomFormInput | undefined;
+}

package/src/foundry/common/utils/bitmask.d.mts

@@ -0,0 +1,110 @@
+export default class BitMask extends Number {
+  /**
+   * Create a new BitMask instance.
+   * @param states    - An object containing valid states and their corresponding initial boolean values (default is null).
+   */
+  constructor(states?: Record<string, boolean> | null);
+
+  // a placeholder private method to help subclassing
+  #bitmask: true;
+
+  /**
+   * The enum associated with this structure.
+   * @readonly
+   */
+  states: Record<string, string>;
+
+  /**
+   * True if this bitmask is empty (no active states).
+   */
+  get isEmpty(): boolean;
+
+  /**
+   * Check if a specific state is active.
+   * @param state   - The state to check.
+   * @returns True if the state is active, false otherwise.
+   */
+  hasState(state: string): boolean;
+
+  /**
+   * Add a state to the bitmask.
+   * @param state - The state to add. Throws an error if the provided state is not valid.
+   */
+  addState(state: string): void;
+
+  /**
+   * Remove a state from the bitmask.
+   * @param state   - The state to remove. Throws an error if the provided state is not valid.
+   */
+  removeState(state: string): void;
+
+  /**
+   * Toggle the state of a specific state in the bitmask.
+   * @param state   - The state to toggle. Throws an error if the provided state is not valid.
+   * @param enabled - Toggle on (true) or off (false)? If undefined, the state is switched automatically.
+   */
+  toggleState(state: string, enabled: boolean): void;
+
+  /**
+   * Toggle the state of a specific state in the bitmask.
+   * @param state - The state to toggle.
+   * @returns  The updated bitmask. Throws an error if the provided state is not valid.
+   */
+  toggleState(state: string): number;
+
+  /**
+   * Clear the bitmask, setting all states to inactive.
+   */
+  clear(): void;
+
+  /**
+   * Get the current value of the bitmask.
+   * @returns The current value of the bitmask.
+   */
+  valueOf(): number;
+
+  /**
+   * Get a string representation of the bitmask in binary format.
+   * @returns The string representation of the bitmask.
+   */
+  toString(): string;
+
+  /**
+   * Checks if two bitmasks structures are compatible (the same valid states).
+   * @param otherBitMask  - The bitmask structure to compare with.
+   * @returns True if the two bitmasks have the same structure, false otherwise.
+   */
+  isCompatible(otherBitMask: BitMask): boolean;
+
+  /**
+   * Serializes the bitmask to a JSON string.
+   * @returns The JSON string representing the bitmask.
+   */
+  toJSON(): string;
+
+  /**
+   * Creates a new BitMask instance from a JSON string.
+   * @param jsonString    - The JSON string representing the bitmask.
+   * @returns A new BitMask instance created from the JSON string.
+   */
+  static fromJSON(jsonString: string): BitMask;
+
+  /**
+   * Convert value of this BitMask to object representation according to structure.
+   * @returns The data represented by the bitmask.
+   */
+  toObject(): Record<string, boolean>;
+
+  /**
+   * Creates a clone of this BitMask instance.
+   * @returns A new BitMask instance with the same value and valid states as this instance.
+   */
+  clone(): BitMask;
+
+  /**
+   * Generates shader constants based on the provided states.
+   * @param states    - An array containing valid states.
+   * @returns Shader bit mask constants generated from the states.
+   */
+  static generateShaderBitMaskConstants(states: string[]): string;
+}

package/src/foundry/common/utils/collection.d.mts

@@ -0,0 +1,176 @@
+interface MapReplacementMembers<K, V> {
+  set(key: K, value: V): this;
+}
+
+type PatchedMap<K, V> = Omit<Map<K, V>, "forEach" | typeof Symbol.iterator | "get" | "set"> &
+  MapReplacementMembers<K, V>;
+
+declare namespace PatchedMap {
+  type Any = PatchedMap<any, any>;
+}
+
+interface PatchedMapConstructor {
+  new (): PatchedMap.Any;
+  new <K, V>(entries?: readonly (readonly [K, V])[] | null): PatchedMap<K, V>;
+  new <K, V>(iterable: Iterable<readonly [K, V]>): PatchedMap<K, V>;
+  readonly [Symbol.species]: PatchedMapConstructor;
+  readonly prototype: PatchedMap.Any;
+}
+
+declare const Map: PatchedMapConstructor;
+
+/**
+ * A reusable storage concept which blends the functionality of an Array with the efficient key-based lookup of a Map.
+ * This concept is reused throughout Foundry VTT where a collection of uniquely identified elements is required.
+ * @typeParam T - The type of the objects contained in the Collection
+ */
+declare class Collection<V> extends Map<string, V> {
+  constructor(entries?: readonly (readonly [string, V])[] | null);
+
+  /**
+   * When iterating over a Collection, we should iterate over its values instead of over its entries
+   */
+  [Symbol.iterator](): IterableIterator<V>;
+
+  /**
+   * Return an Array of all the entry values in the Collection
+   */
+  get contents(): V[];
+
+  /**
+   * Find an entry in the Map using an functional condition.
+   * @see {@link Array#find}
+   *
+   * @param condition - The functional condition to test. Positional arguments are the value, the index of
+   *                    iteration, and the collection being searched.
+   * @returns The value, if found, otherwise undefined
+   *
+   * @example Create a new Collection and reference its contents
+   * ```typescript
+   * let c = new Collection([["a", "A"], ["b", "B"], ["c", "C"]]);
+   * c.get("a") === c.find(entry => entry === "A"); // true
+   * ```
+   */
+  find<S extends V>(condition: (e: V, index: number, collection: Collection<V>) => e is S): S | undefined;
+  find(condition: (e: V, index: number, collection: Collection<V>) => boolean): V | undefined;
+
+  /**
+   * Filter the Collection, returning an Array of entries which match a functional condition.
+   * @see {@link Array#filter}
+   *
+   * @param condition - The functional condition to test. Positional arguments are the value, the
+   *                    index of iteration, and the collection being filtered.
+   * @returns An Array of matched values
+   *
+   * @example Filter the Collection for specific entries
+   * ```typescript
+   * let c = new Collection([["a", "AA"], ["b", "AB"], ["c", "CC"]]);
+   * let hasA = c.filters(entry => entry.slice(0) === "A");
+   * ```
+   */
+  filter<S extends V>(condition: (e: V, index: number, collection: Collection<V>) => e is S): S[];
+  filter(condition: (e: V, index: number, collection: Collection<V>) => boolean): V[];
+
+  /**
+   * Apply a function to each element of the collection
+   * @see Array#forEach
+   * @param fn - The function to apply to each element
+   *
+   * @example Apply a function to each value in the collection
+   * ```typescript
+   * let c = new Collection([["a", {active: false}], ["b", {active: false}], ["c", {active: false}]]);
+   * c.forEach(e => e.active = true);
+   * ```
+   */
+  forEach(fn: (e: V) => void): void;
+
+  /**
+   * Get an element from the Collection by its key.
+   * @param key     - The key of the entry to retrieve
+   * @param strict  - Throw an Error if the requested key does not exist,
+   *                  otherwise return undefined. (default: `false`)
+   * @returns The retrieved entry value, if the key exists, otherwise undefined
+   *
+   * @example Get an element from the Collection by key
+   * ```typescript
+   * let c = new Collection([["a", "A"], ["b", "B"], ["c", "C"]]);
+   * c.get("a"); // "A"
+   * c.get("d"); // null
+   * c.get("d", {strict: true}); // throws Error
+   * ```
+   */
+  get(key: string, { strict }: { strict: true }): V;
+  get(key: string, { strict }?: { strict?: false }): V | undefined;
+
+  /**
+   * Get an entry from the Collection by name.
+   * Use of this method assumes that the objects stored in the collection have a "name" attribute.
+   * @param name    - The name of the entry to retrieve
+   * @param strict  - Throw an Error if the requested name does not exist,
+   *                  otherwise return undefined. (default: `false`)
+   * @returns The retrieved Entity, if one was found, otherwise undefined
+   *
+   * @example Get an element from the Collection by name (if applicable)
+   * ```typescript
+   * let c = new Collection([["a", "Alfred"], ["b", "Bob"], ["c", "Cynthia"]]);
+   * c.getName("Alfred"); // "Alfred"
+   * c.getName("D"); // undefined
+   * c.getName("D", {strict: true}); // throws Error
+   * ```
+   */
+  getName(name: string, { strict }: { strict: true }): V;
+  getName(name: string, { strict }?: { strict?: false }): V | undefined;
+
+  /**
+   * Transform each element of the Collection into a new form, returning an Array of transformed values
+   * @param transformer - A transformation function applied to each entry value. Positional arguments are the value, the
+   *                      index of iteration, and the collection being mapped.
+   * @typeParam M       - The type of the mapped values
+   * @returns An Array of transformed values
+   */
+  map<M>(transformer: (entity: V, index: number, collection: Collection<V>) => M): M[];
+
+  /**
+   * Reduce the Collection by applying an evaluator function and accumulating entries
+   * @see {@link Array#reduce}
+   * @param reducer   - A reducer function applied to each entry value. Positional arguments are the accumulator, the
+   *                    value, the index of iteration, and the collection being reduced.
+   * @param initial   - An initial value which accumulates with each iteration
+   * @typeParam A     - The type of the accumulator and the return value
+   * @returns The accumulated result
+   *
+   * @example Reduce a collection to an array of transformed values
+   * ```typescript
+   * let c = new Collection([["a", "A"], ["b", "B"], ["c", "C"]]);
+   * let letters = c.reduce((s, l) => {
+   *   return s + l;
+   * }, ""); // "ABC"
+   * ```
+   */
+  reduce<A>(evaluator: (accumulator: A, entity: V, index: number, collection: Collection<V>) => A, initial: A): A;
+
+  /**
+   * Test whether a condition is met by some entry in the Collection.
+   * @see Array#some
+   * @param condition - The functional condition to test. Positional arguments are the value, the index of iteration,
+   *                    and the collection being tested.
+   * @returns Was the test condition passed by at least one entry?
+   */
+  some(condition: (e: V, index: number, collection: Collection<V>) => boolean): boolean;
+
+  /**
+   * Convert the Collection to a primitive array of its contents.
+   * @returns An array of contained values
+   */
+  toJSON(): Array<V extends { toJSON: (...args: any[]) => infer U } ? U : V>;
+}
+
+declare namespace Collection {
+  type AnyConstructor = typeof AnyCollection;
+}
+
+declare abstract class AnyCollection extends Collection<any> {
+  constructor(arg0: never, ...args: never[]);
+}
+
+export default Collection;