Merge pull request League-of-Foundry-Developers#2192 from Spice-King/v10/common-utils

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

Author: ghost91-

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

@@ -1,5 +1,5 @@
 import './types.mjs';
-import './utils/primitives.mjs';
+import './primitives/module.mjs';
 import * as _CONST from './constants.mjs';
 import * as _abstract from './abstract/module.mjs';
 import * as _data from './data/module.mjs';

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

@@ -0,0 +1,52 @@
+declare namespace Array {
+  type Flattened<T> = T extends Array<infer U> ? Flattened<U> : T;
+}
+
+interface Array<T> {
+  /**
+   * Flatten nested arrays by concatenating their contents
+   * @returns An array containing the concatenated inner values
+   */
+  deepFlatten(): Array<Array.Flattened<T>>;
+
+  /**
+   * 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;
+
+  /**
+   * Partition an original array into two children array based on a logical test
+   * Elements which test as false go into the first result while elements testing as true appear in the second
+   * @param rule - The rule to partition by
+   * @returns An Array of length two whose elements are the partitioned pieces of the original
+   */
+  partition<S extends T>(rule: (val: T) => val is S): [Exclude<T, S>[], S[]];
+  partition(rule: (val: T) => boolean): [T[], T[]];
+
+  /**
+   * Join an Array using a string separator, first filtering out any parts which return a false-y value
+   * @param sep - The separator string
+   * @returns The joined string, filtered of any false values
+   */
+  filterJoin(sep: string): string;
+
+  /**
+   * Find an element within the Array and remove it from the array
+   * @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.
+   */
+  findSplice(find: (value: T, index: number, obj: T[]) => boolean, replace?: T): T | null;
+}
+
+interface ArrayConstructor {
+  /**
+   * Create and initialize an array of length n with integers from 0 to n-1
+   * @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, min?: number): number[];
+}

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

@@ -0,0 +1,20 @@
+interface Date {
+  /**
+   * Test whether a Date instance is valid.
+   * A valid date returns a number for its timestamp, and NaN otherwise.
+   * NaN is never equal to itself.
+   */
+  isValid(): boolean;
+
+  /**
+   * Return a standard YYYY-MM-DD string for the Date instance.
+   * @returns The date in YYYY-MM-DD format
+   */
+  toDateInputString(): string;
+
+  /**
+   * Return a standard H:M:S.Z string for the Date instance.
+   * @returns The time in H:M:S format
+   */
+  toTimeInputString(): string;
+}

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

@@ -0,0 +1,64 @@
+interface Math {
+  /**
+   * Bound a number between some minimum and maximum value, inclusively
+   * @param num - The current value
+   * @param min - The minimum allowed value
+   * @param max - The maximum allowed value
+   * @returns The clamped number
+   */
+  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
+   * @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, base?: number): number;
+
+  /**
+   * Transform an angle in radians to be bounded within the domain [-PI, PI]
+   * @param radians - An angle in degrees
+   * @returns The same angle on the range [-PI, PI]
+   */
+  normalizeRadians(radians: number): number;
+
+  /**
+   * 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
+   */
+  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
+   * @returns An angle in degrees
+   */
+  toDegrees(angle: number): number;
+
+  /**
+   * Transform an angle in degrees to an angle in radians
+   * @param angle - An angle in degrees
+   * @returns An angle in radians
+   */
+  toRadians(angle: number): number;
+}

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

@@ -0,0 +1,8 @@
+import './array.mjs';
+import './date.mjs';
+import './math.mjs';
+import './number.mjs';
+import './regex.mjs';
+import './set.mjs';
+import './string.mjs';
+import './url.mjs';

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

@@ -0,0 +1,85 @@
+interface Number {
+  /**
+     * 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`)
+     * @returns Are the numbers almost equal?
+     */
+  almostEqual(n: number, e?: number): boolean;
+
+  /**
+   * Transform a number to an ordinal string representation. i.e.
+   * ```
+   * 1 => 1st
+   * 2 => 2nd
+   * 3 => 3rd
+   * ```
+   */
+  ordinalString(): string;
+
+  /**
+   * Return a string front-padded by zeroes to reach a certain number of numeral characters
+   * @param digits - The number of characters desired
+   * @returns The zero-padded number
+   */
+  paddedString(digits: number): string;
+
+  /**
+   * Return a string prefaced by the sign of the number (+) or (-)
+   * @returns The signed number as a string
+   */
+  signedString(): string;
+
+  /**
+   * Round a number to the nearest number which is a multiple of a given interval
+   * @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'`)
+   * @returns The rounded number
+   *
+   * @example Round a number to the nearest step interval
+   * ```typescript
+   * 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
+   * ```
+   */
+  toNearest(interval?: number, method?: 'round' | 'ceil' | 'floor'): 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?
+   * @returns Is the number between the two bounds?
+   */
+  between(a: number, b: number, inclusive?: boolean): boolean;
+}
+
+interface NumberConstructor {
+  /**
+   * @see {@link Number#between}
+   */
+  between(num: number, a: number, b: number, inclusive?: boolean): boolean;
+
+  /**
+   * Test whether a value is numeric
+   * This is the highest performing algorithm currently available, per https://jsperf.com/isnan-vs-typeof/5
+   * @param n - A value to test
+   * @returns Is it a number?
+   */
+  isNumeric(n: unknown): boolean;
+
+  /**
+   * Attempt to create a number from a user-provided string.
+   * @param n - The value to convert; typically a string, but may already be a number.
+   * @returns The number that the string represents, or NaN if no number could be determined.
+   */
+  fromString(str: string | number): number;
+}

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

@@ -0,0 +1,8 @@
+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
+   */
+  escape(string: string): string;
+}

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

@@ -0,0 +1,101 @@
+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;
+
+  /**
+   * Return the first value from the set.
+   * @returns The first element in the set, or undefined
+   */
+  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?
+   */
+  intersects(other: Set<T>): 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?
+   */
+  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<F extends T>(test: (value: T, index: number, set: Set<T>) => value is F): Set<F>;
+  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<F extends T>(test: (value: T, index: number, set: Set<T>) => value is F): F | 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

@@ -0,0 +1,39 @@
+interface String {
+  /**
+   * Capitalize a string, transforming it's first character to a capital letter
+   */
+  capitalize<S extends string>(this: S): Capitalize<S>;
+
+  /**
+   * Convert a string to Title Case where the first letter of each word is capitalized
+   */
+  titleCase<S extends string>(this: S): Titlecase<S>;
+
+  /**
+   * Strip any <script> tags which were included within a provided string
+   */
+  stripScripts(): string;
+
+  /**
+   * Transform any string into a url-viable slug string
+   * @param options - Optional arguments which customize how the slugify operation is performed
+   * @returns The slugified input string
+   */
+  slugify(options?: String.SlugifyOptions): string;
+}
+
+declare namespace String {
+  interface SlugifyOptions {
+    /**
+     * The replacement character to separate terms
+     * @defaultValue `'-'`
+     */
+    replacement?: string;
+
+    /**
+     * Replace all non-alphanumeric characters, or allow them?
+     * @defaultValue `false`
+     */
+    strict?: boolean;
+  }
+}