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

package/src/foundry/common/prosemirror/util.d.mts

@@ -23,7 +23,7 @@ export declare function serializeHTMLString(
   options?: {
     /** The ProseMirror schema to use instead of the default one. */
     schema?: Schema;
-    /** The number of spaces to use for indentation. See {@link StringNode#toString} for details. */
+    /** The number of spaces to use for indentation. See {@link StringNode.toString | `StringNode#toString`} for details. */
     spaces?: string | number;
   },
 ): string;

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

@@ -1,4 +1,4 @@
-import type { AnyConcreteConstructor, AnyConstructor, AnyFunction } from "../../types/utils.d.mts";
+import type { AnyConcreteConstructor, AnyConstructor, AnyFunction } from "fvtt-types/utils";
 import type { Document } from "./abstract/module.d.mts";
 
 // After seeing that none of these types add anything or are even exported a
@@ -39,13 +39,13 @@ type DeepReadonly<T> = Readonly<{
 /**
  * A class constructor.
  * Used for functions with generic class constructor parameters.
- * @privateRemarks We have better tools like {@link AnyConcreteConstructor} and {@link AnyConstructor}
+ * @privateRemarks We have better tools like {@link AnyConcreteConstructor | `AnyConcreteConstructor`} and {@link AnyConstructor | `AnyConstructor`}
  */
 type Constructor = new (...args: any[]) => any;
 
 type Point = Canvas.Point;
 
-type PointArray = Canvas.PointArray;
+type PointArray = Canvas.PointTuple;
 
 type Rectangle = Canvas.Rectangle;
 

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

@@ -1,9 +1,11 @@
-export default class BitMask extends Number {
+import type { Identity } from "fvtt-types/utils";
+
+declare class InternalBitMask<T extends Record<string, boolean>> 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);
+  constructor(states?: T | null);
 
   // a placeholder private method to help subclassing
   #bitmask: true;
@@ -12,7 +14,7 @@ export default class BitMask extends Number {
    * The enum associated with this structure.
    * @readonly
    */
-  states: Record<string, string>;
+  states: Readonly<{ [K in keyof T]: K }>;
 
   /**
    * True if this bitmask is empty (no active states).
@@ -24,33 +26,33 @@ export default class BitMask extends Number {
    * @param state   - The state to check.
    * @returns True if the state is active, false otherwise.
    */
-  hasState(state: string): boolean;
+  hasState(state: keyof T): 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;
+  addState(state: keyof T): 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;
+  removeState(state: keyof T): 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;
+  toggleState(state: keyof T, 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;
+  toggleState(state: keyof T): number;
 
   /**
    * Clear the bitmask, setting all states to inactive.
@@ -74,7 +76,7 @@ export default class BitMask extends Number {
    * @param otherBitMask  - The bitmask structure to compare with.
    * @returns True if the two bitmasks have the same structure, false otherwise.
    */
-  isCompatible(otherBitMask: BitMask): boolean;
+  isCompatible(otherBitMask: BitMask.Any): boolean;
 
   /**
    * Serializes the bitmask to a JSON string.
@@ -87,7 +89,7 @@ export default class BitMask extends Number {
    * @param jsonString    - The JSON string representing the bitmask.
    * @returns A new BitMask instance created from the JSON string.
    */
-  static fromJSON(jsonString: string): BitMask;
+  static fromJSON(jsonString: string): BitMask.Any;
 
   /**
    * Convert value of this BitMask to object representation according to structure.
@@ -99,7 +101,7 @@ export default class BitMask extends Number {
    * Creates a clone of this BitMask instance.
    * @returns A new BitMask instance with the same value and valid states as this instance.
    */
-  clone(): BitMask;
+  clone(): this;
 
   /**
    * Generates shader constants based on the provided states.
@@ -108,3 +110,13 @@ export default class BitMask extends Number {
    */
   static generateShaderBitMaskConstants(states: string[]): string;
 }
+
+declare namespace BitMask {
+  interface Any extends InternalBitMask<Record<string, boolean>> {}
+  interface AnyConstructor extends Identity<typeof BitMask> {}
+}
+
+declare const BitMask: typeof InternalBitMask & (new (...args: any) => number);
+type BitMask = BitMask.Any & number;
+
+export default BitMask;

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

@@ -1,31 +1,21 @@
-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>;
+// This class exists make it as sound as possible to override these parts of the class and make them
 
-declare namespace PatchedMap {
-  type Any = PatchedMap<any, any>;
-}
+import type { AnyArray, Identity } from "fvtt-types/utils";
 
-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;
+// completely unrelated. It's done this way specifically to avoid situations with broken inheritance.
+declare class Map<K, V> extends globalThis.Map<K, V> {
+  [Symbol.iterator](): any;
+  forEach(...args: AnyArray): any;
+  get(...args: AnyArray): 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);
+declare class Collection<V, Methods extends Collection.Methods.Any = Collection.Methods<V>> extends Map<string, V> {
+  constructor(entries?: Iterable<readonly [string, V]> | null);
 
   /**
    * When iterating over a Collection, we should iterate over its values instead of over its entries
@@ -39,7 +29,7 @@ declare class Collection<V> extends Map<string, V> {
 
   /**
    * Find an entry in the Map using an functional condition.
-   * @see {@link Array#find}
+   * @see {@link Array.find | `Array#find`}
    *
    * @param condition - The functional condition to test. Positional arguments are the value, the index of
    *                    iteration, and the collection being searched.
@@ -51,12 +41,14 @@ declare class Collection<V> extends Map<string, V> {
    * 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;
+  find<S extends V>(
+    /** @immediate */ condition: (e: V, index: number, collection: Collection<V>) => e is S,
+  ): S | undefined;
+  find(/** @immediate */ 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}
+   * @see {@link Array.filter | `Array#filter`}
    *
    * @param condition - The functional condition to test. Positional arguments are the value, the
    *                    index of iteration, and the collection being filtered.
@@ -68,12 +60,12 @@ declare class Collection<V> extends Map<string, V> {
    * 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[];
+  filter<S extends V>(/** @immediate */ condition: (e: V, index: number, collection: Collection<V>) => e is S): S[];
+  filter(/** @immediate */ condition: (e: V, index: number, collection: Collection<V>) => boolean): V[];
 
   /**
    * Apply a function to each element of the collection
-   * @see Array#forEach
+   * @see {@link Array.forEach | `Array#forEach`}
    * @param fn - The function to apply to each element
    *
    * @example Apply a function to each value in the collection
@@ -82,7 +74,7 @@ declare class Collection<V> extends Map<string, V> {
    * c.forEach(e => e.active = true);
    * ```
    */
-  forEach(fn: (e: V) => void): void;
+  forEach(/** @immediate */ fn: (e: V) => void): void;
 
   /**
    * Get an element from the Collection by its key.
@@ -99,8 +91,7 @@ declare class Collection<V> extends Map<string, V> {
    * c.get("d", {strict: true}); // throws Error
    * ```
    */
-  get(key: string, { strict }: { strict: true }): V;
-  get(key: string, { strict }?: { strict?: false }): V | undefined;
+  get: Methods["get"];
 
   /**
    * Get an entry from the Collection by name.
@@ -128,11 +119,11 @@ declare class Collection<V> extends Map<string, V> {
    * @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[];
+  map<M>(/** @immediate */ 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}
+   * @see {@link Array.reduce | `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
@@ -147,30 +138,62 @@ declare class Collection<V> extends Map<string, V> {
    * }, ""); // "ABC"
    * ```
    */
-  reduce<A>(evaluator: (accumulator: A, entity: V, index: number, collection: Collection<V>) => A, initial: A): A;
+  reduce<A>(
+    /** @immediate */ 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
+   * @see {@link Array.some | `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;
+  some(/** @immediate */ 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>;
+  toJSON(): Array<V extends { toJSON: (...args: infer _1) => infer U } ? U : V>;
 }
 
 declare namespace Collection {
-  type AnyConstructor = typeof AnyCollection;
+  interface Any extends AnyCollection {}
+  interface AnyConstructor extends Identity<typeof AnyCollection> {}
+
+  interface GetOptions {
+    /**
+     * Throw an Error if the requested Embedded Document does not exist.
+     * @defaultValue `false`
+     */
+    strict?: boolean | undefined;
+  }
+
+  interface Methods<V> {
+    get<Options extends DocumentCollection.GetOptions>(
+      key: string,
+      { strict }?: Options,
+    ): Collection.GetReturnType<V, Options>;
+  }
+
+  namespace Methods {
+    interface Any {
+      get(key: string, options?: never): unknown;
+    }
+  }
+
+  type GetReturnType<T, Options extends GetOptions> = _ApplyStrict<T, Options["strict"]>;
+
+  /** @internal */
+  type _ApplyStrict<ConcreteDocument, Strict extends boolean | undefined> =
+    | (Strict extends false | undefined ? undefined : never)
+    | ConcreteDocument;
 }
 
-declare abstract class AnyCollection extends Collection<any> {
-  constructor(arg0: never, ...args: never[]);
+declare abstract class AnyCollection extends Collection<unknown, Collection.Methods.Any> {
+  constructor(...args: never);
 }
 
 export default Collection;

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

@@ -1,10 +1,15 @@
 export default Color;
+
+// `Color#fromString` breaks inheritance
+declare class PatchedNumber extends Number {
+  static fromString(color: string): any;
+}
+
 /**
  * A representation of a color in hexadecimal format.
  * This class provides methods for transformations and manipulations of colors.
  */
-// @ts-expect-error 2417: Override of Color.fromString does not match Number.fromString
-declare class Color extends Number {
+declare class InternalColor extends PatchedNumber {
   /**
    * Is this a valid color?
    */
@@ -263,6 +268,15 @@ declare class Color extends Number {
    */
   static fromRGB(rgb: Color.RGBColorVector): Color;
 
+  /**
+   * Create a Color instance from an RGB normalized values.
+   * @param r - The red value
+   * @param g - The green value
+   * @param b - The blue value
+   * @returns The hex color instance
+   */
+  static fromRGBvalues(r: number, g: number, b: number): Color;
+
   /**
    * Create a Color instance from an HSV array.
    * Conversion formula adapted from {@link http://en.wikipedia.org/wiki/HSV_color_space}.
@@ -290,8 +304,12 @@ declare class Color extends Number {
   static fromLinearRGB(linear: Color.RGBColorVector): Color;
 }
 
+declare const Color: typeof InternalColor & (new (...args: any) => number);
+type Color = InternalColor & number;
+
 declare namespace Color {
   type RGBColorVector = [r: number, g: number, b: number];
+  type RGBAColorVector = [r: number, g: number, b: number, a: number];
   type HSVColorVector = [h: number, s: number, v: number];
   type HSLColorVector = [h: number, s: number, l: number];
 

package/src/foundry/common/utils/event-emitter.d.mts

@@ -1,12 +1,14 @@
-import type { InexactPartial, Mixin } from "../../../types/utils.d.mts";
+import type { AnyConstructor, FixedInstanceType, Mixin, NullishProps } from "fvtt-types/utils";
 
 /**
  * A mixin class which implements the behavior of EventTarget.
  * This is useful in cases where a class wants EventTarget-like behavior but needs to extend some other class.
- * @see https://developer.mozilla.org/en-US/docs/Web/API/EventTarget
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget}
  */
+// ESLint doesn't like this class "only being used as a type"
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
 declare class EventEmitter {
-  /** @privateRemarks All mixin classses should accept anything for its constructor. */
+  /** @privateRemarks All mixin classes should accept anything for its constructor. */
   constructor(...args: any[]);
 
   /**
@@ -16,21 +18,16 @@ declare class EventEmitter {
 
   /**
    * Add a new event listener for a certain type of event.
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener}
    * @param type     - The type of event being registered for
    * @param listener - The listener function called when the event occurs
    * @param options  - Options which configure the event listener
    */
+  // options: not null (destructured)
   addEventListener(
     type: string,
-    listener: EventEmitter.EmittedEventListener,
-    options?: InexactPartial<{
-      /**
-       * Should the event only be responded to once and then removed
-       * @defaultValue `false`
-       */
-      once: boolean;
-    }>,
+    listener: EventEmitterMixin.EventListener,
+    options?: EventEmitterMixin.AddListenerOptions,
   ): void;
 
   /**
@@ -38,25 +35,43 @@ declare class EventEmitter {
    * @param type     - The type of event being removed
    * @param listener - The listener function being removed
    */
-  removeEventListener(type: string, listener: EventEmitter.EmittedEventListener): void;
+  removeEventListener(type: string, listener: EventEmitterMixin.EventListener): void;
 
   /**
    * Dispatch an event on this target.
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent}
    * @param event - The Event to dispatch
    * @returns Was default behavior for the event prevented?
    */
   dispatchEvent(event: Event): boolean;
 }
 
-declare namespace EventEmitter {
-  type EmittedEventListener = (event: Event) => void;
+declare namespace EventEmitterMixin {
+  interface AnyMixedConstructor extends ReturnType<typeof EventEmitterMixin<BaseClass>> {}
+  interface AnyMixed extends FixedInstanceType<AnyMixedConstructor> {}
+
+  type BaseClass = AnyConstructor;
+
+  /** @internal */
+  type _AddListenerOptions = NullishProps<{
+    /**
+     * Should the event only be responded to once and then removed
+     * @defaultValue `false`
+     */
+    once: boolean;
+  }>;
+
+  interface AddListenerOptions extends _AddListenerOptions {}
+
+  type EventListener = (event: Event) => void;
 }
 
 /**
  * Augment a base class with EventEmitter behavior.
  * @param BaseClass - Some base class augmented with event emitter functionality
  */
-export default function EventEmitterMixin<ExtendedClass extends abstract new (...args: any[]) => any>(
+declare function EventEmitterMixin<ExtendedClass extends EventEmitterMixin.BaseClass>(
   BaseClass: ExtendedClass,
 ): Mixin<typeof EventEmitter, ExtendedClass>;
+
+export default EventEmitterMixin;

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

@@ -26,7 +26,12 @@ export declare function orient2dFast(a: Canvas.Point, b: Canvas.Point, c: Canvas
  *
  * @returns Do the line segments intersect?
  */
-export declare function lineSegmentIntersects(a: Canvas.Point, b: Canvas.Point, c: Canvas.Point, d: Canvas.Point): boolean;
+export declare function lineSegmentIntersects(
+  a: Canvas.Point,
+  b: Canvas.Point,
+  c: Canvas.Point,
+  d: Canvas.Point,
+): boolean;
 
 export interface LineIntersection {
   /** The x-coordinate of intersection */
@@ -182,7 +187,12 @@ export declare function polygonCentroid(points: Points): Canvas.Point;
  * @param radius    - The radius of the circle
  * @returns         - Whether the circle intersect the path
  */
-export declare function pathCircleIntersects(points: Points, close: boolean, center: Canvas.Point, radius: number): boolean;
+export declare function pathCircleIntersects(
+  points: Points,
+  close: boolean,
+  center: Canvas.Point,
+  radius: number,
+): boolean;
 
 /**
  * Test whether two circles (with position and radius) intersect.