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

package/src/foundry/common/packages/base-system.d.mts

@@ -0,0 +1,90 @@
+import type BasePackage from "./base-package.d.mts";
+import type * as fields from "../data/fields.d.mts";
+import type AdditionalTypesField from "./sub-types.d.mts";
+
+declare namespace BaseSystem {
+  interface Schema extends ReturnType<typeof BasePackage.defineSchema> {
+    /**
+     * The current package version
+     * @remarks Actually defined in BasePackage but defined here to avoid conflict with BaseWorld
+     */
+    version: fields.StringField<{ required: true; blank: false; initial: "0" }>;
+
+    /**
+     * Additional document subtypes provided by this system.
+     */
+    documentTypes: AdditionalTypesField;
+
+    /**
+     * A web URL or local file path which provides a default background banner for worlds which are created using this system
+     */
+    background: fields.StringField<{ required: false; blank: false }>;
+
+    /**
+     * A default initiative formula used for this system
+     */
+    initiative: fields.StringField;
+
+    /**
+     * The default grid settings to use for Scenes in this system
+     */
+    grid: fields.SchemaField<{
+      /** A default grid type to use for Scenes in this system */
+      type: fields.NumberField;
+
+      /** A default distance measurement to use for Scenes in this system */
+      distance: fields.NumberField;
+
+      /** A default unit of measure to use for distance measurement in this system */
+      units: fields.StringField;
+
+      /** The default rule used by this system for diagonal measurement on square grids */
+      diagonals: fields.NumberField;
+    }>;
+
+    /**
+     * An Actor data attribute path to use for Token primary resource bars
+     */
+    primaryTokenAttribute: fields.StringField;
+
+    /**
+     * An Actor data attribute path to use for Token secondary resource bars
+     */
+    secondaryTokenAttribute: fields.StringField;
+
+    /**
+     * A default distance measurement to use for Scenes in this system
+     * @deprecated since v12
+     */
+    gridDistance: fields.NumberField;
+
+    /**
+     * A default unit of measure to use for distance measurement in this system
+     * @deprecated since v12
+     */
+    gridUnits: fields.NumberField;
+  }
+}
+
+/**
+ * The data schema used to define System manifest files.
+ * Extends the basic PackageData schema with some additional system-specific fields.
+ */
+declare class BaseSystem extends BasePackage<BaseSystem.Schema> {
+  static defineSchema(): BaseSystem.Schema;
+
+  static type: "system";
+
+  /**
+   * The default icon used for this type of Package.
+   * @defaultValue `"fa-dice"`
+   */
+  static icon: string;
+
+  /**
+   * Does the system template request strict type checking of data compared to template.json inferred types.
+   */
+  strictDataCleaning: boolean;
+}
+
+export default BaseSystem;

package/src/foundry/common/packages/base-world.d.mts

@@ -0,0 +1,116 @@
+import type BasePackage from "./base-package.d.mts";
+import type * as fields from "../data/fields.d.mts";
+import type { AnyObject, InexactPartial, Merge } from "../../../types/utils.d.mts";
+import type { ReleaseData } from "../config.d.mts";
+
+type BaseWorldSchema = Merge<
+  ReturnType<typeof BasePackage.defineSchema>,
+  {
+    /**
+     * The game system name which this world relies upon
+     */
+    system: fields.StringField<{ required: true; blank: false }>;
+
+    /**
+     * A web URL or local file path which provides a background banner image
+     */
+    background: fields.StringField<{ required: false; blank: false }>;
+
+    /**
+     * The theme to use for this world's join page.
+     */
+    joinTheme: fields.StringField<{
+      required: false;
+      initial: undefined;
+      nullable: false;
+      blank: false;
+      choices: typeof foundry.CONST.WORLD_JOIN_THEMES;
+    }>;
+
+    /**
+     * The version of the core software for which this world has been migrated
+     */
+    coreVersion: fields.StringField<{ required: true; blank: false }>;
+
+    /**
+     * The version of the game system for which this world has been migrated
+     */
+    systemVersion: fields.StringField<{ required: true; blank: false; initial: "0" }>;
+
+    lastPlayed: fields.StringField;
+
+    playtime: fields.NumberField<{ integer: true; min: 0; initial: 0 }>;
+
+    /**
+     * An ISO datetime string when the next game session is scheduled to occur
+     */
+    nextSession: fields.StringField<{ blank: false; nullable: true; initial: null }>;
+
+    /**
+     * Should user access keys be reset as part of the next launch?
+     */
+    resetKeys: fields.BooleanField<{ required: false; initial: undefined }>;
+
+    /**
+     * Should the world launch in safe mode?
+     */
+    safeMode: fields.BooleanField<{ required: false; initial: undefined }>;
+
+    version: fields.StringField<{ required: true; blank: false; nullable: true; initial: null }>;
+  }
+>;
+
+declare namespace BaseWorld {
+  interface Schema extends BaseWorldSchema {}
+}
+
+/**
+ * The data schema used to define World manifest files.
+ * Extends the basic PackageData schema with some additional world-specific fields.
+ */
+declare class BaseWorld extends BasePackage<BaseWorld.Schema> {
+  // TODO(LukeAbby): This override is unsound. Revisit.
+  // static defineSchema(): BaseWorld.Schema;
+
+  static type: "world";
+
+  /**
+   * The default icon used for this type of Package.
+   * @defaultValue `"fa-globe-asia"`
+   */
+  static icon: string;
+
+  static migrateData(data: AnyObject): AnyObject;
+
+  static testAvailability(
+    data: InexactPartial<PackageManifestData>,
+    options: InexactPartial<{
+      /**
+       * A specific software release for which to test availability.
+       * Tests against the current release by default.
+       */
+      release: ReleaseData;
+      /**
+       * A specific collection of modules to test availability
+       * against. Tests against the currently installed modules by
+       * default.
+       */
+      modules: Collection<Module>;
+      /**
+       * A specific collection of modules to test availability
+       * against. Tests against the currently installed modules by
+       * default.
+       */
+      systems: Collection<System>;
+      /**
+       * Ignore the world's own core software compatibility and
+       * instead defer entirely to the system's core software
+       * compatibility, if the world's availability is less than
+       * this.
+       */
+      systemAvailabilityThreshold: foundry.CONST.PACKAGE_AVAILABILITY_CODES;
+    }>,
+  ): foundry.CONST.PACKAGE_AVAILABILITY_CODES;
+}
+
+export default BaseWorld;

package/src/foundry/common/packages/module.d.mts

@@ -0,0 +1,28 @@
+// In Foundry itself this file contains re-exports of these other modules.
+// Therefore it has a runtime effect and uses `.mjs` instead of `.d.mts`.
+// While `.mts` could work, to avoid `import/no-unresolved` from erroring `.mjs` is used.
+/* eslint-disable import/extensions */
+
+import type { SchemaField } from "../data/fields.d.mts";
+
+export { default as BasePackage } from "./base-package.mjs";
+export { default as BaseWorld } from "./base-world.mjs";
+export { default as BaseSystem } from "./base-system.mjs";
+export { default as BaseModule } from "./base-module.mjs";
+export { PackageCompatibility, RelatedPackage } from "./base-package.mjs";
+
+declare global {
+  type PackageAuthorData = SchemaField.InnerAssignmentType<foundry.packages.BasePackage.PackageAuthorSchema>;
+
+  type PackageCompendiumData = SchemaField.InnerAssignmentType<foundry.packages.BasePackage.PackageCompendiumSchema>;
+
+  type PackageLanguageData = SchemaField.InnerAssignmentType<foundry.packages.BasePackage.PackageLanguageSchema>;
+
+  type RelatedPackage = SchemaField.InnerAssignmentType<foundry.packages.BasePackage.RelatedPackageSchema>;
+
+  /*
+   * The data structure of a package manifest. This data structure is extended by BasePackage subclasses to add additional
+   * type-specific fields.
+   */
+  interface PackageManifestData extends SchemaField.InnerAssignmentType<foundry.packages.BasePackage.Schema> {}
+}

package/src/foundry/common/packages/sub-types.d.mts

@@ -0,0 +1,42 @@
+import type { AnyObject, Merge } from "../../../types/utils.d.mts";
+import type Document from "../abstract/document.d.mts";
+import type { DataField, ObjectField } from "../data/fields.d.mts";
+
+export type DocumentTypesConfiguration = Record<string, Record<string, AnyObject>>;
+
+/**
+ * A special [ObjectField]{@link ObjectField} available to packages which configures any additional Document subtypes
+ * provided by the package.
+ */
+declare class AdditionalTypesField<
+  Options extends AdditionalTypesField.DefaultOptions = AdditionalTypesField.DefaultOptions,
+> extends ObjectField<
+  Options,
+  AdditionalTypesField.ServerTypeDeclarations,
+  AdditionalTypesField.ServerTypeDeclarations,
+  AdditionalTypesField.ServerTypeDeclarations
+> {
+  static get _defaults(): AdditionalTypesField.DefaultOptions;
+
+  protected _validateType(
+    value: ObjectField.InitializedType<Options>,
+    options?: DataField.ValidationOptions<DataField.Any>,
+  ): boolean | void;
+}
+
+export default AdditionalTypesField;
+
+declare namespace AdditionalTypesField {
+  type DefaultOptions = Merge<
+    ObjectField.DefaultOptions,
+    {
+      // Required is set as false BUT this doesn't work correctly in v11
+      // TODO: Re-enable in v12
+      // required: false;
+      readonly: true;
+      validationError: "is not a valid sub-types configuration";
+    }
+  >;
+
+  type ServerTypeDeclarations = Record<Document.SystemType, Record<string, Record<string, unknown>>>;
+}

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

@@ -0,0 +1,56 @@
+import type { OverlapsWith } from "../../../types/helperTypes.d.mts";
+
+declare global {
+  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<const O>(other: OverlapsWith<O, 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[];
+  }
+}

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

@@ -0,0 +1,24 @@
+export {};
+
+declare global {
+  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;
+  }
+}

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

@@ -0,0 +1,103 @@
+export {};
+
+declare global {
+  interface Math {
+    /**
+     * √3
+     */
+    SQRT3: 1.7320508075688772;
+
+    /**
+     * √⅓
+     */
+    SQRT1_3: 0.5773502691896257;
+
+    /**
+     * 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
+     */
+    clamp(num: number, min: number, max: number): number;
+
+    /**
+     * 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
+     * @deprecated since v12 till v14
+     */
+    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) or (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`)
+     * @returns The same angle on the range [0, 360) or (0, 360]
+     * @deprecated since v12, until v14.
+     * @remarks Use Math.normalizeDegrees(degrees: number): number.
+     */
+    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
+     * @deprecated since v12, until v14
+     */
+    roundDecimals(number: number, places: 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;
+
+    /**
+     * Get an oscillation between lVal and hVal according to t
+     * @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`
+     */
+    oscillation(minVal: number, maxVal: number, t: number, p?: number, func?: (radians: number) => number): number;
+  }
+}

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

@@ -0,0 +1,8 @@
+import "./array.d.mts";
+import "./date.d.mts";
+import "./math.d.mts";
+import "./number.d.mts";
+import "./regexp.d.mts";
+import "./set.d.mts";
+import "./string.d.mts";
+import "./url.d.mts";

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

@@ -0,0 +1,91 @@
+export {};
+
+declare global {
+  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
+     * 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"`)
+     * @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;
+  }
+}

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

@@ -0,0 +1,12 @@
+export {};
+
+declare global {
+  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;
+  }
+}

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

@@ -0,0 +1,12 @@
+export {};
+
+declare global {
+  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;
+  }
+}