@league-of-foundry-developers/foundry-vtt-types 13.340.1 → 13.345.1

package/src/foundry/client/dice/terms/pool.d.mts

@@ -0,0 +1,272 @@
+import type { InexactPartial, FixedInstanceType, Identity } from "#utils";
+import type { PoolRollParseNode } from "../_types.d.mts";
+
+import type RollTerm from "./term.d.mts";
+import type DiceTerm from "./dice.d.mts";
+import type Die from "./die.d.mts";
+
+/**
+ * A type of RollTerm which encloses a pool of multiple inner Rolls which are evaluated jointly.
+ *
+ * A dice pool represents a set of Roll expressions which are collectively modified to compute an effective total
+ * across all Rolls in the pool. The final total for the pool is defined as the sum over kept rolls, relative to any
+ * success count or margin.
+ *
+ * @example Keep the highest of the 3 roll expressions
+ * ```typescript
+ * let pool = new PoolTerm({
+ *   terms: ["4d6", "3d8 - 1", "2d10 + 3"],
+ *   modifiers: ["kh"]
+ * });
+ * pool.evaluate();
+ * ```
+ */
+declare class PoolTerm extends RollTerm {
+  constructor(terms?: PoolTerm.PoolTermConstructorData);
+
+  /**
+   * The original provided terms to the Dice Pool
+   */
+  terms: string[];
+
+  /**
+   * The string modifiers applied to resolve the pool
+   */
+  modifiers: (keyof PoolTerm.Modifiers)[];
+
+  /**
+   * Each component term of a dice pool is evaluated as a Roll instance
+   */
+  rolls: Roll[];
+
+  /**
+   * The array of dice pool results which have been rolled
+   */
+  results: DiceTerm.Result[];
+
+  /**
+   * Define the modifiers that can be used for this particular DiceTerm type.
+   */
+  static MODIFIERS: PoolTerm.Modifiers;
+
+  /**
+   * The regular expression pattern used to identify the opening of a dice pool expression.
+   * @defaultValue `/{/g`
+   */
+  static OPEN_REGEXP: RegExp;
+
+  /**
+   * A regular expression pattern used to identify the closing of a dice pool expression
+   * @defaultValue
+   * ```typescript
+   * new RegExp(`}${DiceTerm.MODIFIERS_REGEXP_STRING}?(?:\\$\\$F[0-9]+\\$\\$)?`, "g");
+   * ```
+   */
+  static CLOSE_REGEXP: RegExp;
+
+  /**
+   * A regular expression pattern used to match the entirety of a DicePool expression.
+   * @defaultValue
+   * ```typescript
+   * new RegExp(`{([^}]+)}${DiceTerm.MODIFIERS_REGEXP_STRING}?(?:\\$\\$F[0-9]+\\$\\$)?`);
+   * ```
+   */
+  static REGEXP: RegExp;
+
+  /**
+   * @defaultValue `["terms", "modifiers", "rolls", "results"]`
+   */
+  static SERIALIZE_ATTRIBUTES: string[];
+
+  /* -------------------------------------------- */
+  /*  Dice Pool Attributes                        */
+  /* -------------------------------------------- */
+
+  /**
+   * Return an Array of each individual DiceTerm instances contained within the PoolTerm.
+   */
+  get dice(): DiceTerm[];
+
+  override get expression(): string;
+
+  override get total(): undefined | number;
+
+  /**
+   * Return an array of rolled values which are still active within the PoolTerm
+   */
+  get values(): number[];
+
+  override get isDeterministic(): boolean;
+
+  /**
+   * Alter the DiceTerm by adding or multiplying the number of dice which are rolled
+   * @param args - Arguments passed to each contained Roll#alter method.
+   * @returns The altered pool
+   */
+  alter(...args: Parameters<Roll["alter"]>): this;
+
+  protected override _evaluate(options?: InexactPartial<RollTerm.EvaluationOptions>): this | Promise<this>;
+
+  protected _evaluateAsync(options?: InexactPartial<RollTerm.EvaluationOptions>): Promise<this>;
+
+  protected _evaluateSync(options?: InexactPartial<RollTerm.EvaluationOptions>): this;
+
+  /**
+   * Use the same logic as for the DiceTerm to avoid duplication
+   * @see {@link DiceTerm._evaluateModifiers | `DiceTerm#_evaluateModifiers`}
+   */
+  protected _evaluateModifiers(): void;
+
+  /**
+   * Use the same logic as for the DiceTerm to avoid duplication
+   * @see {@link DiceTerm._evaluateModifier | `DiceTerm#_evaluateModifier`}
+   */
+  protected _evaluateModifier(command: string, modifier: string): void;
+
+  /* -------------------------------------------- */
+  /*  Saving and Loading                          */
+  /* -------------------------------------------- */
+
+  protected static override _fromData<T extends RollTerm.AnyConstructor>(
+    this: T,
+    data: Record<string, unknown>,
+  ): FixedInstanceType<T>;
+
+  toJSON(): Record<string, unknown>;
+
+  /**
+   * Given a string formula, create and return an evaluated PoolTerm object
+   * @param formula - The string formula to parse
+   * @param options - Additional options applied to the PoolTerm
+   * @returns The evaluated PoolTerm object or null if the formula is invalid
+   */
+  static fromExpression<T extends RollTerm.AnyConstructor>(
+    this: T,
+    formula: string,
+    options?: RollTerm.Options,
+  ): FixedInstanceType<T> | null;
+
+  /**
+   * Create a PoolTerm by providing an array of existing Roll objects
+   * @param rolls - An array of Roll objects from which to create the pool
+   * @returns The constructed PoolTerm comprised of the provided rolls
+   */
+  static fromRolls<T extends PoolTerm.AnyConstructor>(this: T, rolls?: Roll[]): FixedInstanceType<T>;
+
+  /** Construct a PoolTerm from parser information. */
+  static fromParseNode(node: PoolRollParseNode): PoolTerm;
+
+  /* -------------------------------------------- */
+  /*  Modifiers                                   */
+  /* -------------------------------------------- */
+
+  /**
+   * Keep a certain number of highest or lowest dice rolls from the result set.
+   * @example
+   * `{1d6,1d8,1d10,1d12}kh2` Keep the 2 best rolls from the pool
+   * @example
+   * `{1d12,6}kl` Keep the lowest result in the pool
+   *
+   * @param modifier - The matched modifier query
+   */
+  keep(modifier: string): ReturnType<Die["keep"]>;
+
+  /**
+   * Keep a certain number of highest or lowest dice rolls from the result set.
+   * @example
+   * `{1d6,1d8,1d10,1d12}dl3` Drop the 3 worst results in the pool
+   * @example
+   * `{1d12,6}dh` Drop the highest result in the pool
+   *
+   * @param modifier - The matched modifier query
+   */
+  drop(modifier: string): ReturnType<Die["drop"]>;
+
+  /**
+   * Count the number of successful results which occurred in the pool.
+   * Successes are counted relative to some target, or relative to the maximum possible value if no target is given.
+   * Applying a count-success modifier to the results re-casts all results to 1 (success) or 0 (failure)
+   * @example
+   * `20d20cs` Count the number of dice which rolled a 20
+   * @example
+   * `20d20cs>10` Count the number of dice which rolled higher than 10
+   * @example
+   * `20d20cs<10` Count the number of dice which rolled less than 10
+   *
+   * @param modifier - The matched modifier query
+   */
+  countSuccess(modifier: string): ReturnType<Die["countSuccess"]>;
+
+  /**
+   * Count the number of failed results which occurred in a given result set.
+   * Failures are counted relative to some target, or relative to the lowest possible value if no target is given.
+   * Applying a count-failures modifier to the results re-casts all results to 1 (failure) or 0 (non-failure)
+   * @example
+   * `6d6cf` Count the number of dice which rolled a 1 as failures
+   * @example
+   * `6d6cf<=3` Count the number of dice which rolled less than 3 as failures
+   * @example
+   * `6d6cf>4` Count the number of dice which rolled greater than 4 as failures
+   *
+   * @param modifier - The matched modifier query
+   */
+  countFailures(modifier: string): ReturnType<Die["countFailures"]>;
+}
+
+declare namespace PoolTerm {
+  interface Any extends AnyPoolTerm {}
+  interface AnyConstructor extends Identity<typeof AnyPoolTerm> {}
+
+  /**
+   * @remarks This interface is not defined by foundry itself. It only exists
+   * to allow module and system authors to use it for declaration merging,
+   * enabling them to add additional modifiers for {@linkcode PoolTerm}s.
+   */
+  interface Modifiers {
+    k: "keep";
+    kh: "keep";
+    kl: "keep";
+    d: "drop";
+    dh: "drop";
+    dl: "drop";
+    cs: "countSuccess";
+    cf: "countFailures";
+  }
+
+  interface TermData extends Required<PoolTermConstructorData> {}
+
+  interface PoolTermConstructorData {
+    /**
+     * @defaultValue `[]`
+     */
+    terms?: string[] | undefined;
+
+    get isDeterministic(): boolean;
+
+    /**
+     * @defaultValue `[]`
+     */
+    modifiers?: Array<keyof Modifiers> | undefined;
+
+    /**
+     * @defaultValue `[]`
+     */
+    rolls?: Roll[] | undefined;
+
+    /**
+     * @defaultValue `[]`
+     */
+    results?: DiceTerm.Result[] | undefined;
+
+    /**
+     * @defaultValue `{}`
+     */
+    options?: RollTerm.Options | undefined;
+  }
+}
+
+declare abstract class AnyPoolTerm extends PoolTerm {
+  constructor(...args: never);
+}
+
+export default PoolTerm;

package/src/foundry/client/dice/terms/string.d.mts

@@ -0,0 +1,34 @@
+import type { InexactPartial } from "#utils";
+import type RollTerm from "./term.d.mts";
+
+/**
+ * A type of RollTerm used to represent strings which have not yet been matched.
+ */
+declare class StringTerm extends RollTerm {
+  constructor({ term, options }: StringTerm.TermData);
+
+  term: string;
+
+  /**
+   * @defaultValue `["term"]`
+   */
+  static SERIALIZE_ATTRIBUTES: string[];
+
+  override get expression(): string;
+
+  override get total(): string;
+
+  override get isDeterministic(): boolean;
+
+  evaluate(options?: InexactPartial<RollTerm.EvaluationOptions>): never;
+}
+
+declare namespace StringTerm {
+  interface TermData {
+    term: string;
+
+    options?: RollTerm.Options | undefined;
+  }
+}
+
+export default StringTerm;

package/src/foundry/client/dice/terms/term.d.mts

@@ -0,0 +1,178 @@
+import type { InexactPartial, FixedInstanceType, Identity } from "#utils";
+import type { RollParseNode } from "../_types.mts";
+
+import type RollResolver from "../../applications/dice/roll-resolver.d.mts";
+
+declare abstract class RollTerm {
+  constructor({ options }?: RollTerm.TermData);
+
+  /** An object of additional options which describes and modifies the term. */
+  options: RollTerm.Options;
+
+  /** An internal flag for whether the term has been evaluated. */
+  protected _evaluated: boolean;
+
+  /** A reference to the Roll at the root of the evaluation tree. */
+  protected _root: Roll;
+
+  /**
+   * Is this term intermediate, and should be evaluated first as part of the simplification process?
+   * @defaultValue `false`
+   */
+  isIntermediate: boolean;
+
+  /* eslint-disable jsdoc/valid-types */
+
+  /**
+   * A regular expression pattern which identifies optional term-level flavor text
+   * @defaultValue `/(?:\[([^\]]+)\])/`
+   */
+  static FLAVOR_REGEXP_STRING: string;
+
+  /* eslint-enable jsdoc/valid-types */
+
+  /**
+   * A regular expression which identifies term-level flavor text
+   * @defaultValue `new RegExp(RollTerm.FLAVOR_REGEXP_STRING, "G")`
+   */
+  static FLAVOR_REGEXP: RegExp;
+
+  /**
+   * A regular expression used to match a term of this type
+   * @defaultValue `undefined`
+   */
+  static REGEXP: RegExp;
+
+  /* -------------------------------------------- */
+  /*  RollTerm Attributes                         */
+  /* -------------------------------------------- */
+
+  /** An array of additional attributes which should be retained when the term is serialized */
+  static SERIALIZE_ATTRIBUTES: string[];
+
+  /** A string representation of the formula expression for this RollTerm, prior to evaluation */
+  get expression(): string;
+
+  /** A string representation of the formula, including optional flavor text. */
+  get formula(): string;
+
+  /** A string or numeric representation of the final output for this term, after evaluation. */
+  get total(): number | string | null | undefined;
+
+  /** Optional flavor text which modifies and describes this term. */
+  get flavor(): string;
+
+  /** Whether this term is entirely deterministic or contains some randomness. */
+  get isDeterministic(): boolean;
+
+  /** A reference to the RollResolver app being used to externally resolve this term. */
+  get resolver(): RollResolver; // TODO: Implement this
+
+  /* -------------------------------------------- */
+  /*  RollTerm Methods                            */
+  /* -------------------------------------------- */
+
+  /**
+   * Evaluate the term, processing its inputs and finalizing its total.
+   * @param options - (default: `{}`)
+   * @returns A Promise if the term is non-deterministic.
+   */
+  evaluate(options?: InexactPartial<RollTerm.EvaluationOptions>): this | Promise<this>;
+
+  /**
+   * Evaluate the term.
+   * @param options - (default: `{}`)
+   * @returns A Promise if the term is non-deterministic.
+   */
+  protected _evaluate(options?: InexactPartial<RollTerm.EvaluationOptions>): this | Promise<this>;
+
+  /**
+   * Determine if evaluating a given RollTerm with certain evaluation options can be done so deterministically.
+   */
+  static isDeterministic(
+    term: RollTerm,
+    { minimize, maximize }?: InexactPartial<{ minimize: boolean; maximize: boolean }>,
+  ): boolean;
+
+  /* -------------------------------------------- */
+  /*  Serialization and Loading                   */
+  /* -------------------------------------------- */
+
+  /**
+   * Construct a RollTerm from a provided data object
+   * @param data - Provided data from an un-serialized term
+   * @returns The constructed RollTerm
+   */
+  static fromData(data: Record<string, unknown>): RollTerm;
+
+  /** Construct a RollTerm from parser information. */
+  static fromParseNode(node: RollParseNode): RollTerm;
+
+  /**
+   * Define term-specific logic for how a de-serialized data object is restored as a functional RollTerm
+   * @param data - The de-serialized term data
+   * @returns The re-constructed RollTerm object
+   */
+  protected static _fromData<T extends RollTerm.AnyConstructor>(
+    this: T,
+    data: Record<string, unknown>,
+  ): FixedInstanceType<T>;
+
+  /**
+   * Reconstruct a RollTerm instance from a provided JSON string
+   * @param json - A serialized JSON representation of a DiceTerm
+   * @returns A reconstructed RollTerm from the provided JSON
+   */
+  static fromJSON(json: string): RollTerm;
+
+  /**
+   * Serialize the RollTerm to a JSON string which allows it to be saved in the database or embedded in text.
+   * This method should return an object suitable for passing to the JSON.stringify function.
+   */
+  toJSON(): Record<string, unknown>;
+}
+
+declare namespace RollTerm {
+  interface Any extends AnyRollTerm {}
+  interface AnyConstructor extends Identity<typeof AnyRollTerm> {}
+
+  interface Options {
+    flavor?: string | undefined | null;
+  }
+
+  interface EvaluationOptions {
+    /**
+     * Maximize the result, obtaining the largest possible value.
+     * @defaultValue `false`
+     */
+    maximize: boolean;
+
+    /**
+     * Minimize the result, obtaining the smallest possible value
+     * @defaultValue `false`
+     */
+    minimize: boolean;
+
+    /**
+     * If true, string terms will not throw an error when evaluated.
+     * @defaultValue `false`
+     */
+    allowStrings: boolean;
+  }
+
+  interface Data {
+    class: string;
+    evaluated: boolean;
+    options: Options;
+  }
+
+  interface TermData {
+    options?: RollTerm.Options | undefined;
+  }
+}
+
+declare abstract class AnyRollTerm extends RollTerm {
+  constructor(...args: never);
+}
+
+export default RollTerm;

package/src/foundry/client/documents/_module.d.mts

@@ -0,0 +1,51 @@
+// 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-x/no-unresolved` from erroring `.mjs` is used.
+/* eslint-disable import-x/extensions */
+
+export * from "#common/documents/_module.mjs";
+export * as types from "./_types.mjs";
+
+// Abstract Classes
+export * as abstract from "./abstract/_module.mjs";
+export * as collections from "./collections/_module.mjs";
+
+// Primary Documents
+export { default as Actor } from "./actor.mjs";
+export { default as Adventure } from "./adventure.mjs";
+export { default as Cards } from "./cards.mjs";
+export { default as ChatMessage } from "./chat-message.mjs";
+export { default as Combat } from "./combat.mjs";
+export { default as FogExploration } from "./fog-exploration.mjs";
+export { default as Folder } from "./folder.mjs";
+export { default as Item } from "./item.mjs";
+export { default as JournalEntry } from "./journal-entry.mjs";
+export { default as Macro } from "./macro.mjs";
+export { default as Playlist } from "./playlist.mjs";
+export { default as Scene } from "./scene.mjs";
+export { default as Setting } from "./setting.mjs";
+export { default as RollTable } from "./roll-table.mjs";
+export { default as User } from "./user.mjs";
+
+// Embedded Documents
+export { default as ActiveEffect } from "./active-effect.mjs";
+export { default as ActorDelta } from "./actor-delta.mjs";
+export { default as Card } from "./card.mjs";
+export { default as Combatant } from "./combatant.mjs";
+export { default as CombatantGroup } from "./combatant-group.mjs";
+export { default as JournalEntryCategory } from "./journal-entry-category.mjs";
+export { default as JournalEntryPage } from "./journal-entry-page.mjs";
+export { default as PlaylistSound } from "./playlist-sound.mjs";
+export { default as RegionBehavior } from "./region-behavior.mjs";
+export { default as TableResult } from "./table-result.mjs";
+
+// Canvas Documents
+export { default as AmbientLightDocument } from "./ambient-light.mjs";
+export { default as AmbientSoundDocument } from "./ambient-sound.mjs";
+export { default as DrawingDocument } from "./drawing.mjs";
+export { default as MeasuredTemplateDocument } from "./measured-template.mjs";
+export { default as NoteDocument } from "./note.mjs";
+export { default as RegionDocument } from "./region.mjs";
+export { default as TileDocument } from "./tile.mjs";
+export { default as TokenDocument } from "./token.mjs";
+export { default as WallDocument } from "./wall.mjs";

package/src/foundry/client/documents/_types.d.mts

@@ -0,0 +1,134 @@
+export {};
+
+// After seeing that none of these types add anything or are even exported a
+// very reasonable question may be: Why on earth does this file exist?
+//
+// Well this is the file in which Foundry defines these types. We don't house
+// them here because it has poor discoverability. It's also just nice to
+// have as reference to keep us synced with the latest version of Foundry.
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+
+type AdventureImportData = Adventure.ImportData;
+
+type AdventureImportOptions = Adventure.ImportOptions;
+
+type AdventureImportResult = Adventure.ImportResult;
+
+type _ActiveEffectDuration = ActiveEffect.Duration;
+
+type ActiveEffectDuration = ActiveEffect.DurationData & _ActiveEffectDuration;
+
+type FolderChildNode = Folder.ChildNode;
+
+type CombatHistoryData = Combat.HistoryData;
+
+type CombatTurnEventContext = Combat.TurnEventContext;
+
+type CombatRoundEventContext = Combat.RoundEventContext;
+
+// TODO: Data extends object, pass generic to RegionDocument.RegionEvent once set up
+type RegionEvent<Data> = RegionDocument.RegionEvent;
+
+type RegionRegionBoundaryEvent = RegionEvent<{}>;
+
+type RegionBehaviorActivatedEvent = RegionEvent<{}>;
+
+type RegionBehaviorDeactivatedEvent = RegionEvent<{}>;
+
+type RegionBehaviorViewedEvent = RegionEvent<{}>;
+
+type RegionBehaviorUnviewedEvent = RegionEvent<{}>;
+
+type RegionTokenEnterExitEventData = unknown;
+
+type RegionTokenEnterExitEvent = RegionEvent<RegionTokenEnterExitEventData>;
+
+type RegionTokenEnterEvent = RegionTokenEnterExitEvent;
+
+type RegionTokenExitEvent = RegionTokenEnterExitEvent;
+
+type RegionTokenMoveEventData = unknown;
+
+type RegionTokenMoveEvent = RegionEvent<RegionTokenMoveEventData>;
+
+type RegionTokenMoveInEvent = RegionTokenMoveEvent;
+
+type RegionTokenMoveOutEvent = RegionTokenMoveEvent;
+
+type RegionTokenMoveWithinEvent = RegionTokenMoveEvent;
+
+type RegionTokenAnimateEventData = unknown;
+
+type RegionTokenAnimateEvent = RegionEvent<RegionTokenAnimateEventData>;
+
+type RegionTokenAnimateInEvent = RegionTokenAnimateEvent;
+
+type RegionTokenAnimateOutEvent = RegionTokenAnimateEvent;
+
+type RegionTokenTurnEventData = unknown;
+
+type RegionTokenTurnEvent = RegionEvent<RegionTokenTurnEventData>;
+
+type RegionTokenTurnStartEvent = RegionTokenTurnEvent;
+
+type RegionTokenTurnEndEvent = RegionTokenTurnEvent;
+
+type RegionTokenRoundEventData = unknown;
+
+type RegionTokenRoundEvent = RegionEvent<RegionTokenRoundEventData>;
+
+type RegionTokenRoundStartEvent = RegionTokenRoundEvent;
+
+type RegionTokenRoundEndEvent = RegionTokenRoundEvent;
+
+type RegionMovementSegment = foundry.canvas.placeables.Region.MovementSegment;
+
+type RegionSegmentizeMovementPathWaypoint = RegionDocument.SegmentizeMovementPathWaypoint;
+
+type RollTableDraw = RollTable.Draw;
+
+type SceneDimensions = Scene.Dimensions;
+
+type TrackedAttributesDescription = TokenDocument.TrackedAttributesDescription;
+
+type TokenMeasuredMovementWaypoint = TokenDocument.MeasuredMovementWaypoint;
+
+type TokenMovementWaypoint = TokenDocument.MovementWaypoint;
+
+type TokenMovementSegmentData = TokenDocument.MovementSegmentData;
+
+type TokenMeasureMovementPathWaypoint = unknown;
+
+type TokenMeasureMovementPathOptions = foundry.canvas.placeables.Token.MeasureMovementPathOptions;
+
+type TokenMovementCostFunction = TokenDocument.MovementCostFunction;
+
+type TokenMovementCostAggregator = TokenDocument.MovementCostAggregator;
+
+type TokenGetCompleteMovementPathWaypoint = TokenDocument.GetCompleteMovementPathWaypoint;
+
+type TokenCompleteMovementWaypoint = TokenDocument.CompleteMovementWaypoint;
+
+type TokenSegmentizeMovementWaypoint = TokenDocument.SegmentizeMovementWaypoint;
+
+type TokenRegionMovementWaypoint = unknown;
+
+type TokenRegionMovementSegment = unknown;
+
+type TokenMovementSectionData = TokenDocument.MovementSectionData;
+
+type TokenMovementHistoryData = TokenDocument.MovementHistoryData;
+
+type TokenMovementMethod = TokenDocument.MovementMethod;
+
+type TokenMovementState = TokenDocument.MovementState;
+
+type TokenMovementData = TokenDocument.MovementData;
+
+type TokenMovementOperation = TokenDocument.MovementOperation;
+
+type TokenMovementContinuationData = TokenDocument.MovementContinuationData;
+
+type TokenMovementContinuationHandle = TokenDocument.MovementContinuationHandle;

package/src/foundry/client/documents/abstract/_module.d.mts

@@ -0,0 +1,10 @@
+// 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-x/no-unresolved` from erroring `.mjs` is used.
+/* eslint-disable import-x/extensions */
+
+export { default as CanvasDocumentMixin } from "./canvas-document.mjs";
+export { default as ClientDocumentMixin } from "./client-document.mjs";
+export { default as DirectoryCollectionMixin } from "./directory-collection-mixin.mjs";
+export { default as DocumentCollection } from "./document-collection.mjs";
+export { default as WorldCollection } from "./world-collection.mjs";