@league-of-foundry-developers/foundry-vtt-types 13.346.0-beta.20250825020008 → 13.346.0-beta.20250825021358

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@league-of-foundry-developers/foundry-vtt-types",
-  "version": "13.346.0-beta.20250825020008",
+  "version": "13.346.0-beta.20250825021358",
   "description": "TypeScript type definitions for Foundry VTT",
   "type": "module",
   "types": "./src/index.d.mts",

package/src/foundry/common/primitives/math.d.mts

@@ -4,13 +4,17 @@ declare global {
   interface Math {
     /**
      * √3
+     * @remarks Created with `defineProperties` with no options other than `value` specified, making it
+     * `writeable: false, enumerable: false, configurable: false` by default
      */
-    SQRT3: 1.7320508075688772;
+    readonly SQRT3: 1.7320508075688772;
 
     /**
      * √⅓
+     * @remarks Created with `defineProperties` with no options other than `value` specified, making it
+     * `writeable: false, enumerable: false, configurable: false` by default
      */
-    SQRT1_3: 0.5773502691896257;
+    readonly SQRT1_3: 0.5773502691896257;
 
     /**
      * Bound a number between some minimum and maximum value, inclusively.
@@ -27,7 +31,7 @@ declare global {
      * @param min - The minimum allowed value
      * @param max - The maximum allowed value
      * @returns The clamped number
-     * @deprecated since v12 till v14
+     * @deprecated "Math.clamped is deprecated in favor of {@linkcode Math.clamp}." (since v12, until v14)
      */
     clamped(num: number, min: number, max: number): number;
 
@@ -41,21 +45,22 @@ declare global {
     mix(a: number, b: number, w: number): number;
 
     /**
-     * Transform an angle in degrees to be bounded within the domain [0, 360]
+     * Transform an angle in degrees to be bounded within the domain [0, 360)
      * @param degrees - An angle in degrees
-     * @returns The same angle on the range [0, 360) or (0, 360]
+     * @returns The same angle on the range [0, 360)
      */
     normalizeDegrees(degrees: number): number;
 
     /**
      * Transform an angle in degrees to be bounded within the domain [0, 360]
      * @param degrees - An angle in degrees
-     * @param base    - The base angle to normalize to, either 0 for [0, 360) or 360 for (0, 360] (default: `0`)
+     * @param base    - The base angle to normalize to, either 0 for [0, 360) or 360 for (0, 360]
      * @returns The same angle on the range [0, 360) or (0, 360]
-     * @deprecated since v12, until v14.
-     * @remarks Use Math.normalizeDegrees(degrees: number): number.
+     * @deprecated "`Math.normalizeDegrees(degrees, base)` is deprecated." (since v12, until v14)
+     * @remarks Despite the parameter description, passing *any* non-`undefined` value for `base` changes behaviour.
+     * This is accurate to the behaviour in v11 and earlier, it's unclear why this wasn't originally a boolean.
      */
-    normalizeDegrees(degrees: number, base?: number): number;
+    normalizeDegrees(degrees: number, base: number): number;
 
     /**
      * Transform an angle in radians to be bounded within the domain [-PI, PI]
@@ -68,7 +73,7 @@ declare global {
      * Round a floating point number to a certain number of decimal places
      * @param number - A floating point number
      * @param places - An integer number of decimal places
-     * @deprecated since v12, until v14
+     * @deprecated "`Math.roundDecimals` is deprecated." (since v12, until v14)
      */
     roundDecimals(number: number, places: number): number;
 
@@ -91,12 +96,9 @@ declare global {
      * @param  minVal - The minimal value of the oscillation.
      * @param  maxVal - The maximum value of the oscillation.
      * @param  t      - The time value.
-     * @param  p      - The period (must be nonzero).
-     *                  (default: `1`)
-     * @param  func   - The optional math function to use for oscillation.
-     *                  (default: `Math.cos`)
-     *                  Its period must be 2π
-     * @returns The oscillation according to t. `((maxValue - minValue) * (f(2π * t / p) + 1) / 2) + minValue`
+     * @param  p      - The period (must be nonzero). (default: `1`)
+     * @param  fn     - The optional math function to use for oscillation.  Its period must be 2π (default: `Math.cos`)
+     * @returns The oscillation according to t. `((maxVal - minVal) * (fn(2π * t / p) + 1) / 2) + minVal`
      */
     oscillation(
       minVal: number,
@@ -105,7 +107,7 @@ declare global {
       p?: number,
 
       /** @immediate */
-      func?: (radians: number) => number,
+      fn?: (radians: number) => number,
     ): number;
   }
 }

package/src/foundry/common/primitives/number.d.mts

@@ -5,8 +5,7 @@ declare global {
     /**
      * Test for near-equivalence of two numbers within some permitted epsilon
      * @param n - Some other number
-     * @param e - Some permitted epsilon, by default 1e-8
-                  (default: `1e-8`)
+     * @param e - Some permitted epsilon, by default 1e-8 (default: `1e-8`)
      * @returns Are the numbers almost equal?
      */
     almostEqual(n: number, e?: number): boolean;
@@ -29,39 +28,44 @@ declare global {
     paddedString(digits: number): string;
 
     /**
-     * Return a string prefaced by the sign of the number (+) or (-)
-     * @returns The signed number as a string
+     * Return a locally formatted string prefaced by the explicit sign of the number (+) or (-). Use of this method is
+     * intended for display purposes only.
+     * @returns The signed number as a locally formatted string
+     * @remarks Uses `−` (`U+2212 Minus Sign`) instead of a regular ASCII `-`
      */
     signedString(): string;
 
     /**
-     * Round a number to the nearest number which is a multiple of a given interval
+     * Round a number to the closest number which subtracted from the base is a multiple of the provided interval.
      * This is a convenience function intended to humanize issues of floating point precision.
      * The interval is treated as a standard string representation to determine the amount of decimal truncation applied.
-     * @param interval - The interval to round the number to the nearest multiple of
-     *                   (default: `1`)
-     * @param method   - The rounding method in: round, ceil, floor
-     *                   (default: `"round"`)
+     * @param interval - The step interval (default: `1`)
+     * @param method   - The rounding method (default: `"round"`)
+     * @param base     - The step base (default: `0`)
      * @returns The rounded number
      *
      * @example Round a number to the nearest step interval
-     * ```typescript
+     * ```js
      * let n = 17.18;
      * n.toNearest(5); // 15
      * n.toNearest(10); // 20
      * n.toNearest(10, "floor"); // 10
      * n.toNearest(10, "ceil"); // 20
      * n.toNearest(0.25); // 17.25
+     * n.toNearest(2, "round", 1); // 17
      * ```
+     *
+     * @remarks
+     * @throws If `interval` is negative
      */
-    toNearest(interval?: number, method?: "round" | "ceil" | "floor"): number;
+    toNearest(interval?: number, method?: "round" | "ceil" | "floor", base?: number): number;
 
     /**
      * A faster numeric between check which avoids type coercion to the Number object.
      * Since this avoids coercion, if non-numbers are passed in unpredictable results will occur. Use with caution.
      * @param a         - The lower-bound
      * @param b         - The upper-bound
-     * @param inclusive - Include the bounding values as a true result?
+     * @param inclusive - Include the bounding values as a true result? (default: `true`)
      * @returns Is the number between the two bounds?
      */
     between(a: number, b: number, inclusive?: boolean): boolean;
@@ -69,7 +73,7 @@ declare global {
 
   interface NumberConstructor {
     /**
-     * @see {@link NumberInstance.between | `Number#between`}
+     * @see {@linkcode Number#between}
      */
     between(num: number, a: number, b: number, inclusive?: boolean): boolean;
 

package/src/foundry/common/primitives/set.d.mts

@@ -2,20 +2,13 @@ export {};
 
 declare global {
   interface Set<T> {
-    /**
-     * Return the difference of two sets.
-     * @param other - Some other set to compare against
-     * @returns The difference defined as objects in this which are not present in other
-     */
-    difference(other: Set<T>): Set<T>;
-
     /**
      * Test whether this set is equal to some other set.
      * Sets are equal if they share the same members, independent of order
      * @param other - Some other set to compare against
      * @returns Are the sets equal?
      */
-    equals(other: Set<T>): boolean;
+    equals(other: ReadonlySetLike<unknown>): boolean;
 
     /**
      * Return the first value from the set.
@@ -23,27 +16,22 @@ declare global {
      */
     first(): T | undefined;
 
-    /**
-     * Return the intersection of two sets.
-     * @param other - Some other set to compare against
-     * @returns The intersection of both sets
-     */
-    intersection(other: Set<T>): Set<T>;
-
     /**
      * Test whether this set has an intersection with another set.
      * @param other - Another set to compare against
      * @returns Do the sets intersect?
+     * @remarks Just returns {@linkcode Set.isDisjointFrom | !this.isDisjointFrom(other)}
      */
-    intersects(other: Set<T>): boolean;
+    intersects(other: ReadonlySetLike<unknown>): boolean;
 
     /**
      * Test whether this set is a subset of some other set.
      * A set is a subset if all its members are also present in the other set.
      * @param other - Some other set that may be a subset of this one
      * @returns Is the other set a subset of this one?
+     * @deprecated "`Set#isSubset` is deprecated in favor of the native {@linkcode Set.isSubsetOf | Set#isSubsetOf}." (since v13, until v15)
      */
-    isSubset(other: Set<T>): boolean;
+    isSubset(other: ReadonlySetLike<unknown>): boolean;
 
     /**
      * Convert a set to a JSON object by mapping its contents to an array
@@ -53,15 +41,16 @@ declare global {
 
     /**
      * Test whether every element in this Set satisfies a certain test criterion.
-     * @see {@link Array.every | `Array#every`}
+     * @see {@linkcode Array.every | Array#every}
      * @param test - The test criterion to apply. Positional arguments are the value, the index of iteration, and the set being tested.
      * @returns Does every element in the set satisfy the test criterion?
      */
+    every<S extends T>(/** @immediate */ test: (value: T, index: number, set: Set<T>) => value is S): this is Set<S>;
     every(/** @immediate */ test: (value: T, index: number, set: Set<T>) => boolean): boolean;
 
     /**
      * Filter this set to create a subset of elements which satisfy a certain test criterion.
-     * @see {@link Array.filter | `Array#filter`}
+     * @see {@linkcode Array.filter | Array#filter}
      * @param test - The test criterion to apply. Positional arguments are the value, the index of iteration, and the set being filtered.
      * @returns A new Set containing only elements which satisfy the test criterion.
      */
@@ -70,7 +59,7 @@ declare global {
 
     /**
      * Find the first element in this set which satisfies a certain test criterion.
-     * @see {@link Array.find | `Array#find`}
+     * @see {@linkcode Array.find | Array#find}
      * @param test - The test criterion to apply. Positional arguments are the value, the index of iteration, and the set being searched.
      * @returns The first element in the set which satisfies the test criterion, or undefined.
      */
@@ -79,7 +68,7 @@ declare global {
 
     /**
      * Create a new Set where every element is modified by a provided transformation function.
-     * @see {@link Array.map | `Array#map`}
+     * @see {@linkcode Array.map | Array#map}
      * @param transform - The transformation function to apply.Positional arguments are the value, the index of iteration, and the set being transformed.
      * @returns A new Set of equal size containing transformed elements.
      */
@@ -87,19 +76,16 @@ declare global {
 
     /**
      * Create a new Set with elements that are filtered and transformed by a provided reducer function.
-     * @see {@link Array.reduce | `Array#reduce`}
+     * @see {@linkcode Array.reduce | Array#reduce}
      * @param reducer - A reducer function applied to each value. Positional arguments are the accumulator, the value, the index of iteration, and the set being reduced.
-     * @param accumulator - The initial value of the returned accumulator.
+     * @param initial - The initial value of the returned accumulator.
      * @returns The final value of the accumulator.
      */
-    reduce<V>(
-      /** @immediate */ reducer: (accumulator: V, value: T, index: number, set: Set<T>) => V,
-      accumulator: V,
-    ): V;
+    reduce<V>(/** @immediate */ reducer: (accumulator: V, value: T, index: number, set: Set<T>) => V, initial: V): V;
 
     /**
      * Test whether any element in this Set satisfies a certain test criterion.
-     * @see {@link Array.some | `Array#some`}
+     * @see {@linkcode Array.some | Array#some}
      * @param test - The test criterion to apply. Positional arguments are the value, the index of iteration, and the set being tested.
      * @returns Does any element in the set satisfy the test criterion?
      */

package/src/foundry/common/primitives/string.d.mts

@@ -9,12 +9,13 @@ declare global {
 
     /**
      * Compare this string (x) with the other string (y) by comparing each character's Unicode code point value.
+     * Returns a negative Number if x \< y, a positive Number if x\> y, or a zero otherwise.
      * This is the same comparison function that used by Array#sort if the compare function argument is omitted.
      * The result is host/locale-independent.
      * @param other - The other string to compare this string to.
      * @returns A negative Number if x \< y, a positive Number if x \> y, or a zero otherwise.
      */
-    compare<S extends string>(this: S, other: string): number;
+    compare<S extends string>(this: S, other: string): -1 | 0 | 1;
 
     /**
      * Convert a string to Title Case where the first letter of each word is capitalized

package/src/foundry/common/primitives/url.d.mts

@@ -3,11 +3,15 @@ export {};
 declare global {
   // Non-functional due to upstream
   // https://github.com/microsoft/TypeScript-DOM-lib-generator/pull/1379
-  // declare const URL: {
+  // Foundry's override is redundant in 2025, as the native `URL.parse` (https://developer.mozilla.org/en-US/docs/Web/API/URL/parse_static)
+  // is a drop-in replacement
+  // const URL: {
   //   prototype: URL;
   //   new (url: string | URL, base?: string | URL): URL;
   //   createObjectURL(obj: Blob | MediaSource): string;
   //   revokeObjectURL(url: string): void;
+  //   canParse(url: string | URL, base?: string | URL): boolean;
+  //   parse(url: string | URL, base?: string | URL): URL | null;
   //   /**
   //    * Attempt to parse a URL without throwing an error.
   //    * @param url - The string to parse.

package/src/utils/index.d.mts

@@ -82,7 +82,7 @@ export type IntentionalPartial<T extends object> = Partial<T>;
  *
  * @example
  * ```ts
- * // The `const T` allows inference to be a bit more specific. This is useful for a utility type like this.`
+ * // The `const T` allows inference to be a bit more specific. This is useful for a utility type like this.
  * function takesNumber<const T>(input: OverlapsWith<T, number>): void {
  *   // This function body is an example of a method this might be useful for.
  *   // If the input isn't an number it simply returns in this case.