Update common/utils and common/primitives to v10.277

Author: Spice-King

src/foundry/common/primitives/array.mjs.d.ts

@@ -10,7 +10,9 @@ interface Array<T> {
   deepFlatten(): Array<Array.Flattened<T>>;
 
   /**
-   * Test equality of the values of this array against the values of some other Array
+   * Test element-wise equality of the values of this array against the values of another array
+   * @param other - Some other array against which to test equality
+   * @returns Are the two arrays element-wise equal?
    */
   equals(other: T[]): boolean;
 
@@ -31,7 +33,7 @@ interface Array<T> {
 
   /**
    * Find an element within the Array and remove it from the array
-   * @param find - A function to use as input to findIndex
+   * @param find    - A function to use as input to findIndex
    * @param replace - A replacement for the spliced element
    * @returns The replacement element, the removed element, or null if no element was found.
    */
@@ -41,8 +43,9 @@ interface Array<T> {
 interface ArrayConstructor {
   /**
    * Create and initialize an array of length n with integers from 0 to n-1
-   * @param n - The desired array length
-   * @returns An array of integers from 0 to n
+   * @param n   - The desired array length
+   * @param min - A desired minimum number from which the created array starts (default: `0`)
+   * @returns An array of integers from min to min+n
    */
-  fromRange(n: number): number[];
+  fromRange(n: number, min?: number): number[];
 }

src/foundry/common/primitives/math.mjs.d.ts

@@ -8,12 +8,22 @@ interface Math {
    */
   clamped(num: number, min: number, max: number): number;
 
+  /**
+   * Linear interpolation function
+   * @param a - An initial value when weight is 0.
+   * @param b - A terminal value when weight is 1.
+   * @param w - A weight between 0 and 1.
+   * @returns The interpolated value between a and b with weight w.
+   */
+  mix(a: number, b: number, w: number): number;
+
   /**
    * 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]
+   * @param base    - The base angle to normalize to, either 0 for [0, 360) or 360 for (0, 360] (default: `0`)
+   * @returns The same angle on the range [0, 360) or (0, 360]
    */
-  normalizeDegrees(degrees: number): number;
+  normalizeDegrees(degrees: number, base?: number): number;
 
   /**
    * Transform an angle in radians to be bounded within the domain [-PI, PI]
@@ -29,6 +39,15 @@ interface Math {
    */
   roundDecimals(number: number, places: number): number;
 
+  /**
+   * Round a floating-point number using the fastest available method.
+   * This should be used instead of Math.round in cases where performance matters.
+   * A key limitation is this method returns zero if the input is NaN or undefined.
+   * @param number - A finite number
+   * @returns The rounded number
+   */
+  roundFast(number: number): number;
+
   /**
    * Transform an angle in radians to a number in degrees
    * @param angle - An angle in radians

src/foundry/common/primitives/module.mjs.d.ts

@@ -5,3 +5,4 @@ import './number.mjs';
 import './regex.mjs';
 import './set.mjs';
 import './string.mjs';
+import './url.mjs';

src/foundry/common/primitives/number.mjs.d.ts

@@ -39,7 +39,7 @@ interface Number {
    *                   (default: `'round'`)
    * @returns The rounded number
    *
-   * @example
+   * @example Round a number to the nearest step interval
    * ```typescript
    * let n = 17.18;
    * n.toNearest(5); // 15
@@ -52,18 +52,19 @@ interface Number {
   toNearest(interval?: number, method?: 'round' | 'ceil' | 'floor'): number;
 
   /**
-   * A faster numeric between check which avoids type coercion to the Number object
+   * 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 inclusive - (default: `true`)
+   * @param a         - The lower-bound
+   * @param b         - The upper-bound
+   * @param inclusive - Include the bounding values as a true result?
+   * @returns Is the number between the two bounds?
    */
   between(a: number, b: number, inclusive?: boolean): boolean;
 }
 
 interface NumberConstructor {
   /**
-   * 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 inclusive - (default: `true`)
+   * @see {@link Number#between}
    */
   between(num: number, a: number, b: number, inclusive?: boolean): boolean;
 

src/foundry/common/primitives/regex.mjs.d.ts

@@ -2,7 +2,7 @@ interface RegExpConstructor {
   /**
    * Escape a given input string, prefacing special characters with backslashes for use in a regular expression
    * @param string - The un-escaped input string
-   * @returns  The escaped string, suitable for use in regular expression
+   * @returns The escaped string, suitable for use in regular expression
    */
   escape(string: string): string;
 }

src/foundry/common/primitives/set.mjs.d.ts

@@ -1,4 +1,11 @@
 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
@@ -34,4 +41,59 @@ interface Set<T> {
    * @returns Is the other set a subset of this one?
    */
   isSubset(other: Set<T>): boolean;
+
+  /**
+   * Convert a set to a JSON object by mapping its contents to an array
+   * @returns The set elements as an array.
+   */
+  toObject(): T[];
+
+  /**
+   * Test whether every element in this Set satisfies a certain test criterion.
+   * @see {@link 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(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}
+   * @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.
+   */
+  filter(test: (value: T, index: number, set: Set<T>) => boolean): Set<T>;
+
+  /**
+   * Find the first element in this set which satisfies a certain test criterion.
+   * @see {@link 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.
+   */
+  find(test: (value: T, index: number, set: Set<T>) => boolean): T | undefined;
+
+  /**
+   * Create a new Set where every element is modified by a provided transformation function.
+   * @see {@link 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.
+   */
+  map<V>(transform: (value: T, index: number, set: Set<T>) => V): Set<V>;
+
+  /**
+   * Create a new Set with elements that are filtered and transformed by a provided reducer function.
+   * @see {@link 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.
+   * @returns The final value of the accumulator.
+   */
+  reduce<V>(reducer: (accumulator: V, value: T, index: number, set: Set<T>) => V, accumulator: V): V;
+
+  /**
+   * Test whether any element in this Set satisfies a certain test criterion.
+   * @see {@link 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?
+   */
+  some(test: (value: T, index: number, set: Set<T>) => boolean): boolean;
 }

src/foundry/common/primitives/string.mjs.d.ts

@@ -17,7 +17,7 @@ interface String {
   /**
    * Transform any string into a url-viable slug string
    * @param options - Optional arguments which customize how the slugify operation is performed
-   * @returns The cleaned slug string
+   * @returns The slugified input string
    */
   slugify(options?: String.SlugifyOptions): string;
 }

src/foundry/common/primitives/url.mjs.d.ts

@@ -0,0 +1,15 @@
+// Non-functional due to upstream
+// https://github.com/microsoft/TypeScript-DOM-lib-generator/pull/1379
+// declare const URL: {
+//   prototype: URL;
+//   new (url: string | URL, base?: string | URL): URL;
+//   createObjectURL(obj: Blob | MediaSource): string;
+//   revokeObjectURL(url: string): void;
+
+//   /**
+//    * Attempt to parse a URL without throwing an error.
+//    * @param url - The string to parse.
+//    * @returns The parsed URL if successful, otherwise null.
+//    */
+//   parseSafe(url: string): URL | null;
+// };

src/foundry/common/utils/color.mjs.d.ts

@@ -0,0 +1,152 @@
+type RGBColorVector = [r: number, g: number, b: number];
+type HSVColorVector = [h: number, s: number, v: number];
+
+/**
+ * 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
+export default class Color extends Number {
+  /**
+   * A CSS-compatible color string.
+   * An alias for Color#toString.
+   */
+  get css(): string;
+
+  /**
+   * The color represented as an RGB array.
+   */
+  get rgb(): RGBColorVector;
+
+  /**
+   * The numeric value of the red channel between [0, 1].
+   */
+  get r(): number;
+
+  /**
+   * The numeric value of the green channel between [0, 1].
+   */
+  get g(): number;
+
+  /**
+   * The numeric value of the blue channel between [0, 1].
+   */
+  get b(): number;
+
+  /**
+   * The maximum value of all channels.
+   */
+  get maximum(): number;
+
+  /**
+   * The minimum value of all channels.
+   */
+  get minimum(): number;
+
+  /**
+   * Get the value of this color in little endian format.
+   */
+  get littleEndian(): number;
+
+  /**
+   * The color represented as an HSV array.
+   * Conversion formula adapted from http://en.wikipedia.org/wiki/HSV_color_space.
+   * Assumes r, g, and b are contained in the set [0, 1] and returns h, s, and v in the set [0, 1].
+   */
+  get hsv(): HSVColorVector;
+
+  /** @override */
+  toString(): string;
+
+  /**
+   * Test whether this color equals some other color
+   * @param other - Some other color or hex number
+   * @returns Are the colors equal?
+   */
+  equals(other: Color | number): string;
+
+  /**
+   * Get a CSS-compatible RGBA color string.
+   * @param alpha - The desired alpha in the range [0, 1]
+   * @returns A CSS-compatible RGBA string
+   */
+  toRGBA(alpha: number): string;
+
+  /**
+   * Mix this Color with some other Color using a provided interpolation weight.
+   * @param other - Some other Color to mix with
+   * @param weight - The mixing weight placed on this color where weight is placed on the other color
+   * @returns The resulting mixed Color
+   */
+  mix(other: Color, weight: number): Color;
+
+  /**
+   * Multiply this Color by another Color or a static scalar.
+   * @param other - Some other Color or a static scalar.
+   * @returns The resulting Color.
+   */
+  multiply(other: Color | number): Color;
+
+  /**
+   * Add this Color by another Color or a static scalar.
+   * @param other - Some other Color or a static scalar.
+   * @returns The resulting Color.
+   */
+  add(other: Color | number): Color;
+
+  /**
+   * Subtract this Color by another Color or a static scalar.
+   * @param other - Some other Color or a static scalar.
+   * @returns The resulting Color.
+   */
+  subtract(other: Color | number): Color;
+
+  /**
+   * Max this color by another Color or a static scalar.
+   * @param other - Some other Color or a static scalar.
+   * @returns The resulting Color.
+   */
+  maximize(other: Color | number): Color;
+
+  /**
+   * Min this color by another Color or a static scalar.
+   * @param other - Some other Color or a static scalar.
+   * @returns The resulting Color.
+   */
+  minimize(other: Color | number): Color;
+
+  /**
+   * Iterating over a Color is equivalent to iterating over its [r,g,b] color channels.
+   */
+  [Symbol.iterator](): Generator<number>;
+
+  /**
+   * Create a Color instance from an RGB array.
+   * @param color - A color input
+   * @returns The hex color instance or NaN
+   */
+  static from(color: null | string | number | RGBColorVector | Color): Color | typeof NaN;
+
+  /**
+   * Create a Color instance from a color string which either includes or does not include a leading #.
+   * @param color - A color string
+   * @returns The hex color instance
+   */
+  static fromString(color: string): Color;
+
+  /**
+   * Create a Color instance from an RGB array.
+   * @param rgb - An RGB tuple
+   * @returns The hex color instance
+   */
+  static fromRGB(rgb: RGBColorVector): Color;
+
+  /**
+   * Create a Color instance from an HSV array.
+   * Conversion formula adapted from http://en.wikipedia.org/wiki/HSV_color_space.
+   * Assumes h, s, and v are contained in the set [0, 1].
+   * @param hsv - An HSV tuple
+   * @returns The hex color instance
+   */
+  static fromHSV(hsv: HSVColorVector): Color;
+}