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

package/src/foundry/client/core/packages.d.mts

@@ -0,0 +1,185 @@
+import type { InexactPartial, Mixin } from "../../../types/utils.d.mts";
+import type { CONST } from "../../client-esm/client.d.mts";
+import type BasePackage from "../../common/packages/base-package.d.mts";
+
+declare class ClientPackage {
+  /** @privateRemarks All mixin classses should accept anything for its constructor. */
+  constructor(...args: any[]);
+
+  /**
+   * Is this package marked as a favorite?
+   * This boolean is currently only populated as true in the /setup view of the software.
+   */
+  favorite: false;
+
+  /**
+   * Associate package availability with certain badge for client-side display.
+   */
+  getVersionBadge(): ClientPackage.PackageCompatibilityBadge | null;
+
+  /**
+   * Determine a version badge for the provided compatibility data.
+   * @param availability - The availability level.
+   * @param data         - The compatibility data.
+   * @param options      - (default: `{}`)
+   */
+  static getVersionBadge(
+    availability: CONST.PACKAGE_AVAILABILITY_CODES,
+    data: Partial<PackageManifestData>,
+    options: InexactPartial<{
+      /**
+       * A specific collection of modules to test availability against. Tests against the currently installed modules by default.
+       */
+      modules: Collection<Module>;
+      /**
+       * A specific collection of systems to test availability against. Tests against the currently installed systems by default.
+       */
+      systems: Collection<System>;
+    }>,
+  ): ClientPackage.PackageCompatibilityBadge | null;
+
+  /**
+   * List missing dependencies and format them for display.
+   * @param availability - The availability level.
+   * @param data         - The compatibility data.
+   * @param options      - (default: `{}`)
+   */
+  static _formatBadDependenciesTooltip(
+    availability: CONST.PACKAGE_AVAILABILITY_CODES,
+    data: Partial<PackageManifestData>,
+    options: InexactPartial<{
+      /**
+       * A specific collection of modules to test availability against. Tests against the currently installed modules by default.
+       */
+      modules: Collection<Module>;
+      /**
+       * A specific collection of systems to test availability against. Tests against the currently installed systems by default.
+       */
+      systems: Collection<System>;
+    }>,
+  ): string;
+
+  /**
+   * List missing dependencies and format them for display.
+   * @param availability - The availability level.
+   * @param data         - The compatibility data.
+   * @param options      - (default: `{}`)
+   */
+  static _formatIncompatibleSystemsTooltip(
+    availability: CONST.PACKAGE_AVAILABILITY_CODES,
+    data: Partial<PackageManifestData>,
+    options: InexactPartial<{
+      /**
+       * A specific collection of systems to test availability against. Tests against the currently installed systems by default.
+       */
+      systems: Collection<System>;
+    }>,
+  ): string;
+
+  /**
+   * When a package has been installed, add it to the local game data.
+   */
+  install(): void;
+
+  /**
+   * When a package has been uninstalled, remove it from the local game data.
+   */
+  uninstall(): void;
+
+  /**
+   * Remove a package from the local game data when it has been uninstalled.
+   * @param id - The package ID.
+   */
+  static uninstall(id: string): void;
+
+  /**
+   * Retrieve the latest Package manifest from a provided remote location.
+   * @param manifest - A remote manifest URL to load
+   * @param options  - Additional options which affect package construction
+   * @returns A Promise which resolves to a constructed ServerPackage instance
+   * @throws An error if the retrieved manifest data is invalid
+   */
+  static fromRemoteManifest(
+    manifest: string,
+    options: InexactPartial<{
+      /**
+       *  Whether to construct the remote package strictly
+       * @defaultValue `true`
+       */
+      strict: boolean;
+    }>,
+  ): Promise<ClientPackage | null>;
+}
+
+declare global {
+  namespace ClientPackage {
+    interface PackageCompatibilityBadge {
+      type: "safe" | "unsafe" | "warning" | "neutral" | "error";
+      tooltip: string;
+      label?: string;
+      icon?: string;
+    }
+
+    interface ModuleConstructorData {
+      active: boolean;
+    }
+  }
+
+  /**
+   * A client-side mixin used for all Package types.
+   * @param BasePackage - The parent BasePackage class being mixed
+   * @returns A BasePackage subclass mixed with ClientPackage features
+   */
+  function ClientPackageMixin<BaseClass extends BasePackage.Internal.Constructor>(
+    BasePackage: BaseClass,
+  ): Mixin<typeof ClientPackage, BaseClass>;
+
+  class Module extends ClientPackageMixin(foundry.packages.BaseModule) {
+    constructor(data: ClientPackage.ModuleConstructorData, options: unknown);
+
+    /**
+     * Is this package currently active?
+     */
+    readonly active: boolean;
+  }
+
+  class System extends ClientPackageMixin(foundry.packages.BaseSystem) {}
+
+  class World extends ClientPackageMixin(foundry.packages.BaseWorld) {
+    static override getVersionBadge(
+      availability: CONST.PACKAGE_AVAILABILITY_CODES,
+      data: Partial<PackageManifestData>,
+      options: InexactPartial<{
+        /**
+         * A specific collection of modules to test availability against. Tests against the currently installed modules by default.
+         */
+        modules: Collection<Module>;
+        /**
+         * A specific collection of systems to test availability against. Tests against the currently installed systems by default.
+         */
+        systems: Collection<System>;
+      }>,
+    ): ClientPackage.PackageCompatibilityBadge | null;
+
+    /**
+     * Provide data for a system badge displayed for the world which reflects the system ID and its availability
+     * @param system - A specific system to use, otherwise use the installed system.
+     */
+    getSystemBadge(system?: System): ClientPackage.PackageCompatibilityBadge | null;
+
+    static override _formatBadDependenciesTooltip(
+      availability: CONST.PACKAGE_AVAILABILITY_CODES,
+      data: Partial<PackageManifestData>,
+      options: InexactPartial<{
+        /**
+         * A specific collection of modules to test availability against. Tests against the currently installed modules by default.
+         */
+        modules: Collection<Module>;
+        /**
+         * A specific collection of systems to test availability against. Tests against the currently installed systems by default.
+         */
+        systems: Collection<System>;
+      }>,
+    ): string;
+  }
+}

package/src/foundry/client/core/settings.d.mts

@@ -0,0 +1,260 @@
+import type { ConformRecord } from "../../../types/helperTypes.d.mts";
+import type { AnyArray, AnyObject, InexactPartial } from "../../../types/utils.d.mts";
+import type DataModel from "../../common/abstract/data.d.mts";
+import type Document from "../../common/abstract/document.d.mts";
+import type { DataField } from "../../common/data/fields.d.mts";
+
+declare global {
+  /**
+   * A class responsible for managing defined game settings or settings menus.
+   * Each setting is a string key/value pair belonging to a certain package and a certain store scope.
+   *
+   * When Foundry Virtual Tabletop is initialized, a singleton instance of this class is constructed within the global
+   * Game object as as game.settings.
+   *
+   * @see {@link Game#settings}
+   * @see {@link Settings}
+   * @see {@link SettingsConfig}
+   */
+  class ClientSettings {
+    constructor(worldSettings?: Setting["_source"][]);
+
+    /**
+     * A object of registered game settings for this scope
+     */
+    settings: Map<string, SettingConfig>;
+
+    /**
+     * Registered settings menus which trigger secondary applications
+     */
+    menus: Map<string, SettingSubmenuConfig>;
+
+    /**
+     * The storage interfaces used for persisting settings
+     * Each storage interface shares the same API as window.localStorage
+     * @remarks This is a lie, it doesn't actually have the same interface...
+     */
+    storage: Map<string, Storage | WorldSettings>;
+
+    /**
+     * Return a singleton instance of the Game Settings Configuration app
+     */
+    get sheet(): SettingsConfig;
+
+    /**
+     * Register a new game setting under this setting scope
+     *
+     * @param namespace - The namespace under which the setting is registered
+     * @param key       - The key name for the setting under the namespace
+     * @param data      - Configuration for setting data
+     *
+     * @example Register a client setting
+     * ```typescript
+     * game.settings.register("myModule", "myClientSetting", {
+     *   name: "Register a Module Setting with Choices",
+     *   hint: "A description of the registered setting and its behavior.",
+     *   scope: "client",     // This specifies a client-stored setting
+     *   config: true,        // This specifies that the setting appears in the configuration view
+     *   requiresReload: true // This will prompt the user to reload the application for the setting to take effect.
+     *   type: String,
+     *   choices: {           // If choices are defined, the resulting setting will be a select menu
+     *     "a": "Option A",
+     *     "b": "Option B"
+     *   },
+     *   default: "a",        // The default value for the setting
+     *   onChange: value => { // A callback function which triggers when the setting is changed
+     *     console.log(value)
+     *   }
+     * });
+     * ```
+     *
+     * @example Register a world setting
+     * ```typescript
+     * game.settings.register("myModule", "myWorldSetting", {
+     *   name: "Register a Module Setting with a Range slider",
+     *   hint: "A description of the registered setting and its behavior.",
+     *   scope: "world",      // This specifies a world-level setting
+     *   config: true,        // This specifies that the setting appears in the configuration view
+     *   requiresReload: true // This will prompt the GM to have all clients reload the application for the setting to
+     *                        // take effect.
+     *   type: new foundry.fields.NumberField({nullable: false, min: 0, max: 100, step: 10}),
+     *   default: 50,         // The default value for the setting
+     *   onChange: value => { // A callback function which triggers when the setting is changed
+     *     console.log(value)
+     *   }
+     * });
+     * ```
+     */
+    register<N extends ClientSettings.Namespace, K extends ClientSettings.Key, T extends ClientSettings.Type>(
+      namespace: N,
+      key: K,
+      data: ClientSettings.Type extends T
+        ? ClientSettings.RegisterOptions<_SettingConfig[`${N}.${K}`]>
+        : ClientSettings.RegisterOptions<NoInfer<T>>,
+    ): void;
+
+    /**
+     * Register a new sub-settings menu
+     *
+     * @param namespace - The namespace under which the menu is registered
+     * @param key       - The key name for the setting under the namespace module
+     * @param data      - Configuration for setting data
+     * @typeParam N     - The namespace under which the menu is registered, as a type
+     * @typeParam K     - The key name for the setting under the namespace module, as a type
+     *
+     * @example Define a settings submenu which handles advanced configuration needs
+     * ```typescript
+     * game.settings.registerMenu("myModule", "mySettingsMenu", {
+     *   name: "My Settings Submenu",
+     *   label: "Settings Menu Label",      // The text label used in the button
+     *   hint: "A description of what will occur in the submenu dialog.",
+     *   icon: "fas fa-bars",               // A Font Awesome icon used in the submenu button
+     *   type: MySubmenuApplicationClass,   // A FormApplication subclass which should be created
+     *   restricted: true                   // Restrict this submenu to gamemaster only?
+     * });
+     * ```
+     */
+    registerMenu<N extends string, K extends string>(namespace: N, key: K, data: ClientSettings.RegisterSubmenu): void;
+
+    /**
+     * Get the value of a game setting for a certain namespace and setting key
+     *
+     * @param namespace - The namespace under which the setting is registered
+     * @param key       - The setting key to retrieve
+     * @typeParam N     - The namespace under which the setting is registered, as a type
+     * @typeParam K     - The setting key to retrieve, as a type
+     *
+     * @example Retrieve the current setting value
+     * ```typescript
+     * game.settings.get("myModule", "myClientSetting");
+     * ```
+     */
+    get<N extends ClientSettings.Namespace, K extends ClientSettings.Key>(
+      namespace: N,
+      key: K,
+    ): ClientSettings.SettingInitializedType<N, K>;
+
+    /**
+     * Set the value of a game setting for a certain namespace and setting key
+     *
+     * @param namespace - The namespace under which the setting is registered
+     * @param key       - The setting key to retrieve
+     * @param value     - The data to assign to the setting key
+     * @param options   - Additional options passed to the server when updating world-scope settings
+     * @typeParam N     - The namespace under which the setting is registered, as a type
+     * @typeParam K     - The setting key to retrieve, as a type
+     * @typeParam V     - The type of the value being set
+     * @returns         - The assigned setting value
+     *
+     * @example
+     * ```typescript
+     * // Update the current value of a setting
+     * game.settings.set("myModule", "myClientSetting", "b");
+     * ```
+     */
+    set<N extends ClientSettings.Namespace, K extends ClientSettings.Key>(
+      namespace: N,
+      key: K,
+      value: ClientSettings.SettingAssignmentType<N, K>,
+      options?: Document.OnUpsertOptions<"Setting">,
+    ): Promise<ClientSettings.SettingInitializedType<N, K>>;
+  }
+
+  namespace ClientSettings {
+    type Namespace = GetNamespaces<keyof _SettingConfig>;
+    type Key = GetKeys<keyof _SettingConfig>;
+
+    /**
+     * A compile type is a type for a setting that only exists at compile time.
+     * For example `string` does not correspond to a real runtime value like `String` does.
+     */
+    type TypeScriptType = string | number | boolean | symbol | bigint | AnyArray | AnyObject;
+
+    // The type `typeof DataModel<any, any>` is used because Foundry actually constructs with its regular constructor parameters in this case.
+    type RuntimeType = DataField.Any | typeof DataModel<any, any> | SettingFunction | SettingConstructor;
+
+    type Type = TypeScriptType | RuntimeType;
+
+    type ToRuntimeType<T extends Type> =
+      | (T extends RuntimeType ? T : never)
+      | (T extends string ? typeof String : never)
+      | (T extends number ? typeof Number : never)
+      | (T extends boolean ? typeof Boolean : never)
+      | (T extends symbol ? typeof Symbol : never)
+      | (T extends bigint ? typeof BigInt : never)
+      | (T extends readonly (infer V)[] ? typeof Array<V> : never)
+      | (T extends AnyObject ? typeof Object : never);
+
+    type SettingAssignmentType<N extends Namespace, K extends Key> = ToSettingAssignmentType<ConfiguredType<N, K>>;
+    type ToSettingAssignmentType<T extends Type> = ReplaceUndefinedWithNull<
+      | SettingType<T>
+      // TODO(LukeAbby): The `fromSource` function is called with `strict` which changes how fallback behaviour works. See `ClientSettings#set`
+      | (T extends DataModel.AnyConstructor ? DataModel.ConstructorDataFor<InstanceType<T>> : never)
+    >;
+
+    type SettingInitializedType<N extends Namespace, K extends Key> = ToSettingInitializedType<ConfiguredType<N, K>>;
+    type ToSettingInitializedType<T extends Type> = ReplaceUndefinedWithNull<
+      SettingType<T> | (T extends DataModel.Any ? T : never)
+    >;
+
+    interface RegisterOptions<T extends Type>
+      extends InexactPartial<Omit<SettingOptions<T>, "key" | "namespace">> {}
+
+    type RegisterSubmenu = Omit<SettingSubmenuConfig, "key" | "namespace">;
+
+    /**
+     * @deprecated - {@link SettingConfig | `SettingConfig`}
+     */
+    interface Values extends SettingConfig {}
+  }
+}
+
+type SettingFunction = (value: never) => unknown;
+type SettingConstructor = new (value: never) => unknown;
+
+// Matches what's in `Setting#PRIMITIVE_TYPES`.
+// Foundry itself uses this nomenclature despite the fact that it's a misnomer.
+type PRIMITIVE_TYPES = readonly [
+  typeof String,
+  typeof Number,
+  typeof Boolean,
+  typeof Array,
+  typeof Symbol,
+  typeof BigInt,
+];
+
+// A type can be both a constructor and a function at once.
+// Foundry prioritizes the constructor over the function unless it's in `Setting#PRIMITIVE_TYPES`.
+type ConstructorToSettingType<T extends SettingConstructor> = T extends PRIMITIVE_TYPES[number]
+  ? PrimitiveConstructorToSettingType<T>
+  : InstanceType<T>;
+
+// In theory this is just the `ReturnType<T>`.
+// However the function end of `Array` returns `any[]` while `Object` returns `any`.
+// To increase safety they're special cased here.
+type PrimitiveConstructorToSettingType<T extends PRIMITIVE_TYPES[number]> = T extends typeof Array
+  ? AnyArray
+  : T extends typeof Object
+    ? AnyObject
+    : ReturnType<T>;
+
+type ConfiguredType<N extends ClientSettings.Namespace, K extends ClientSettings.Key> = _SettingConfig[`${N}.${K}`];
+
+type SettingType<T extends ClientSettings.Type> =
+  // Note(LukeAbby): This isn't written as `T extends ClientSettings.TypeScriptType ? T : never` because then types like `DataField.Any` would be matched.
+  | (T extends ClientSettings.RuntimeType ? never : T)
+  // TODO(LukeAbby): The `validate` function is called with `strict` which changes how fallback behaviour works. See `ClientSettings#set`
+  | (T extends DataField.Any ? DataField.AssignmentTypeFor<T> : never)
+  | (T extends SettingConstructor ? ConstructorToSettingType<T> : T extends SettingFunction ? ReturnType<T> : never);
+
+// TODO(LukeAbby): The exact semantics for when `undefined` is replaced with `null` are unclear.
+type ReplaceUndefinedWithNull<T> = T extends undefined ? null : T;
+
+type GetNamespaces<SettingPath extends PropertyKey> = SettingPath extends `${infer Scope}.${string}` ? Scope : never;
+type GetKeys<SettingPath extends PropertyKey> = SettingPath extends `${string}.${infer Name}` ? Name : never;
+
+type _SettingConfig = ConformRecord<
+  // Refers to the deprecated interface so that merging works both ways.
+  ClientSettings.Values,
+  ClientSettings.Type
+>;

package/src/foundry/client/core/socket.d.mts

@@ -0,0 +1,16 @@
+import type { DatabaseOperationMap, DocumentSocketRequest } from "../../common/abstract/_types.d.mts";
+
+declare global {
+  class SocketInterface {
+    /**
+     * Standardize the way that socket messages are dispatched and their results are handled
+     * @param eventName - The socket event name being handled
+     * @param request   - Request data provided to the Socket event
+     * @returns A Promise which resolves to the SocketResponse
+     */
+    static dispatch<DatabaseAction extends keyof DatabaseOperationMap>(
+      eventName: string,
+      request: DocumentSocketRequest<DatabaseAction> | ManageCompendiumRequest,
+    ): Promise<SocketResponse>;
+  }
+}

package/src/foundry/client/core/sorting.d.mts

@@ -0,0 +1,76 @@
+import type { InexactPartial } from "../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * A collection of functions related to sorting objects within a parent container.
+   */
+  class SortingHelpers {
+    /**
+     * Given a source object to sort, a target to sort relative to, and an Array of siblings in the container:
+     * Determine the updated sort keys for the source object, or all siblings if a reindex is required.
+     * Return an Array of updates to perform, it is up to the caller to dispatch these updates.
+     * Each update is structured as:
+     * ```typescript
+     * {
+     *   target: object,
+     *   update: {sortKey: sortValue}
+     * }
+     * ```
+     *
+     * @param source  - source object being sorted
+     * @param options - Options which modify the sort behavior
+     * @typeParam T   - the type of the source and target object
+     *
+     * @returns An Array of updates for the caller of the helper function to perform
+     */
+    static performIntegerSort<T, SortKey extends string = "sort">(
+      source: T,
+      options?: InexactPartial<SortingHelpers.SortOptions<T, SortKey>>,
+    ): Array<{
+      target: T;
+      update: {
+        [Key in SortKey]: number;
+      };
+    }>;
+
+    /**
+     * Given an ordered Array of siblings and a target position, return the [min,max] indices to sort before the target
+     */
+    protected static _sortBefore<T>(siblings: T[], idx: number, sortKey: string): [T, T];
+
+    /**
+     * Given an ordered Array of siblings and a target position, return the [min,max] indices to sort after the target
+     */
+    protected static _sortAfter<T>(siblings: T[], idx: number, sortKey: string): [T, T];
+  }
+
+  namespace SortingHelpers {
+    interface SortOptions<T, SortKey extends string = "sort"> {
+      /**
+       * The target object relative which to sort
+       * @defaultValue `null`
+       */
+      target: T | null;
+
+      /**
+       * The sorted Array of siblings which share the same sorted container
+       * @defaultValue `[]`
+       */
+      siblings: T[];
+
+      /**
+       * The name of the data property within the source object which defines the sort key
+       * @defaultValue `"sort"`
+       */
+      sortKey: SortKey;
+
+      /**
+       * Whether to explicitly sort before (true) or sort after (false). If nothing is passed
+       * the sort order will be automatically determined, preferring before.
+       *
+       * @defaultValue `true`
+       */
+      sortBefore: boolean;
+    }
+  }
+}

package/src/foundry/client/core/time.d.mts

@@ -0,0 +1,73 @@
+import type Document from "../../common/abstract/document.d.mts";
+
+declare global {
+  /**
+   * A singleton class {@link game#time} which keeps the official Server and World time stamps.
+   * Uses a basic implementation of https://www.geeksforgeeks.org/cristians-algorithm/ for synchronization.
+   */
+  class GameTime {
+    constructor(socket?: io.Socket | null);
+
+    /**
+     * The most recently synchronized timestamps retrieved from the server.
+     * @defaultValue `{}`
+     */
+    protected _time: GameTime.Timestamps;
+
+    /**
+     * The average one-way latency across the most recent 5 trips
+     * @defaultValue `0`
+     */
+    protected _dt: number;
+
+    /**
+     * The most recent five synchronization durations
+     * @defaultValue `[]`
+     */
+    protected _dts: number[];
+
+    /**
+     * The amount of time to delay before re-syncing the official server time.
+     * @defaultValue `1000 * 60 * 5`
+     */
+    static SYNC_INTERVAL_MS: number;
+
+    /**
+     * The current server time based on the last synchronization point and the approximated one-way latency.
+     */
+    get serverTime(): number;
+
+    /**
+     * The current World time based on the last recorded value of the core.time setting
+     */
+    get worldTime(): number;
+
+    /**
+     * Advance the game time by a certain number of seconds
+     * @param seconds - The number of seconds to advance (or rewind if negative) by
+     * @param options - Additional options passed to game.settings.set
+     * @returns The new game time
+     */
+    advance(seconds: number, options?: Document.OnUpsertOptions<"Setting">): Promise<number>;
+
+    /**
+     * Synchronize the local client game time with the official time kept by the server
+     * @param socket - The connected server Socket instance
+     */
+    sync(socket?: io.Socket | null): Promise<this>;
+
+    /**
+     * Handle follow-up actions when the official World time is changed
+     * @param worldTime - The new canonical World time.
+     */
+    onUpdateWorldTime(worldTime: number): void;
+  }
+
+  namespace GameTime {
+    interface Timestamps {
+      clientTime: number;
+      serverTime: number;
+      worldTime: number;
+    }
+  }
+}