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

package/src/foundry/client-esm/dice/terms/fate.d.mts

@@ -0,0 +1,50 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+
+import type DiceTerm from "./dice.d.mts";
+import type Die from "./die.d.mts";
+
+/**
+ * A type of DiceTerm used to represent a three-sided Fate/Fudge die.
+ * Mathematically behaves like 1d3-2
+ */
+declare class FateDie extends DiceTerm {
+  constructor(termData?: InexactPartial<FateDie.TermData>);
+
+  _faces: 3;
+
+  /**
+   * @defaultValue `"f"`
+   */
+  static DENOMINATION: string;
+
+  static override MODIFIERS: FateDie.Modifiers;
+
+  override roll({
+    minimize,
+    maximize,
+    ...options
+  }?: InexactPartial<DiceTerm.EvaluationOptions>): Promise<DiceTerm.Result>;
+
+  override mapRandomFace(randomUniform: number): number;
+
+  override getResultLabel(result: DiceTerm.Result): string;
+}
+
+declare namespace FateDie {
+  interface TermData extends DiceTerm.TermData {
+    modifiers: Array<keyof (typeof FateDie)["MODIFIERS"]>;
+  }
+
+  interface Modifiers {
+    r: Die["reroll"];
+    rr: Die["rerollRecursive"];
+    k: Die["keep"];
+    kh: Die["keep"];
+    kl: Die["keep"];
+    d: Die["drop"];
+    dh: Die["drop"];
+    dl: Die["drop"];
+  }
+}
+
+export default FateDie;

package/src/foundry/client-esm/dice/terms/function.d.mts

@@ -0,0 +1,104 @@
+import type { ConstructorOf, InexactPartial } from "../../../../types/utils.d.mts";
+import type { FunctionRollParseNode } from "../_types.d.mts";
+
+import type RollTerm from "./term.d.mts";
+import type DiceTerm from "./dice.d.mts";
+import type { RollFunction } from "../../../client/config.d.mts";
+
+/**
+ * A type of RollTerm used to apply a function.
+ */
+declare class FunctionTerm extends RollTerm {
+  constructor(termData?: InexactPartial<FunctionTerm.TermData>);
+
+  /* The name of the configured function, or one in the Math environment, which should be applied to the term. */
+  fn: string;
+
+  /** An array of string argument terms for the function. */
+  terms: string[];
+
+  /* The cached Roll instances for each function argument. */
+  rolls: Roll[];
+
+  /* The cached result of evaluating the method arguments. */
+  result: string | number;
+
+  /** Is this term intermediate, and should be evaluated first as part of the simplification process? */
+  override isIntermediate: true;
+
+  static override SERIALIZE_ATTRIBUTES: ["fn", "terms", "rolls", "result"];
+
+  /* -------------------------------------------- */
+  /*  Function Term Attributes                    */
+  /* -------------------------------------------- */
+
+  /** An array of evaluated DiceTerm instances that should be bubbled up to the parent Roll. */
+  get dice(): DiceTerm[];
+
+  override get total(): string | number;
+
+  override get expression(): string;
+
+  get function(): RollFunction; // TODO: Implement this
+
+  override get isDeterministic(): boolean;
+
+  /* -------------------------------------------- */
+  /*  Math Term Methods                           */
+  /* -------------------------------------------- */
+  protected override _evaluate(options?: InexactPartial<RollTerm.EvaluationOptions>): this | Promise<this>;
+
+  /**
+   * Evaluate this function when it contains any non-deterministic sub-terms.
+   * @param options - Options forwarded to inner Roll evaluation. (Default: `{}`)
+   */
+  protected _evaluateASync(options?: InexactPartial<RollTerm.EvaluationOptions>): Promise<this>;
+
+  /**
+   * Evaluate deterministic values of this term synchronously.
+   * @param options - Options forwarded to inner Roll evaluation. (Default: `{}`)
+   */
+  protected _evaluateSync(options?: InexactPartial<DiceTerm.EvaluationOptions>): this;
+
+  /* -------------------------------------------- */
+
+  /**
+   * Parse a function argument from its evaluated Roll instance.
+   * @param roll - The evaluated Roll instance that wraps the argument.
+   */
+  #parseArgument(roll: Roll): string | number;
+
+  /* -------------------------------------------- */
+  /*  Saving and Loading                          */
+  /* -------------------------------------------- */
+  protected static override _fromData<T extends RollTerm>(this: ConstructorOf<T>, data: Record<string, unknown>): T;
+
+  /* -------------------------------------------- */
+  override toJSON(): Record<string, unknown>;
+
+  /* -------------------------------------------- */
+  static override fromParseNode(node: FunctionRollParseNode): RollTerm;
+}
+
+declare namespace FunctionTerm {
+  interface Data extends InexactPartial<TermData> {
+    class: string | undefined;
+    evaluated: boolean;
+  }
+
+  interface TermData {
+    /* The name of the configured function, or one in the Math environment, which should be applied to the term. */
+    fn: string;
+    /** An array of string argument terms for the function. */
+    terms: string[];
+    /* The cached Roll instances for each function argument. */
+    rolls: Roll[];
+    /* The cached result of evaluating the method arguments. */
+    result: string | number;
+    options?: InexactPartial<FunctionTerm.Options>;
+  }
+
+  interface Options extends RollTerm.Options {}
+}
+
+export default FunctionTerm;

package/src/foundry/client-esm/dice/terms/numeric.d.mts

@@ -0,0 +1,56 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+import type RollTerm from "./term.d.mts";
+
+/**
+ * A type of RollTerm used to represent static numbers.
+ */
+declare class NumericTerm extends RollTerm {
+  constructor({ number, options }: NumericTerm.TermData);
+
+  number: NumericTerm.TermData["number"];
+
+  /**
+   * @defaultValue
+   * ```typescript
+   * new RegExp(`^([0-9]+(?:\\.[0-9]+)?)${RollTerm.FLAVOR_REGEXP_STRING}?$`)
+   * ```
+   */
+  static REGEXP: RegExp;
+
+  /**
+   * @defaultValue `["number"]`
+   */
+  static override SERIALIZE_ATTRIBUTES: string[];
+
+  override get expression(): string;
+
+  override get total(): number;
+
+  /**
+   * Determine whether a string expression matches a NumericTerm
+   * @param expression - The expression to parse
+   */
+  static matchTerm(expression: string): RegExpMatchArray | null;
+
+  /* -------------------------------------------- */
+
+  /**
+   * Construct a term of this type given a matched regular expression array.
+   * @param match -  The matched regular expression array
+   * @returns The constructed term
+   */
+  static fromMatch(match: RegExpMatchArray): NumericTerm;
+}
+
+declare namespace NumericTerm {
+  interface TermData {
+    number: number;
+
+    /**
+     * @defaultValue `{}`
+     */
+    options?: InexactPartial<RollTerm.Options>;
+  }
+}
+
+export default NumericTerm;

package/src/foundry/client-esm/dice/terms/operator.d.mts

@@ -0,0 +1,55 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+
+import type RollTerm from "./term.d.mts";
+
+/**
+ * A type of RollTerm used to denote and perform an arithmetic operation.
+ */
+declare class OperatorTerm extends RollTerm {
+  constructor({ operator, options }?: InexactPartial<OperatorTerm.TermData>);
+
+  /** The term's operator value. */
+  operator: OperatorTerm.TermData["operator"];
+
+  /** An object of operators with their precedence values. */
+  static PRECEDENCE: {
+    "+": 10;
+    "-": 10;
+    "*": 20;
+    "/": 20;
+    "%": 20;
+  };
+
+  /**
+   * An array of operators which represent arithmetic operations.
+   * @defaultValue `["+", "-", "*", "/", "%"]`
+   */
+  static OPERATORS: string[];
+
+  static override REGEXP: RegExp;
+
+  /**
+   * An array of additional attributes which should be retained when the term is serialized.
+   * @defaultValue `["operator"]`
+   */
+  static override SERIALIZE_ATTRIBUTES: string[];
+
+  /**
+   * Optional flavor text which modifies and describes this term.
+   * @remarks Operator terms cannot have flavor text
+   */
+  override get flavor(): string;
+
+  override get expression(): string;
+
+  override get total(): string;
+}
+
+declare namespace OperatorTerm {
+  interface TermData {
+    operator: string;
+    options?: InexactPartial<RollTerm.Options>;
+  }
+}
+
+export default OperatorTerm;

package/src/foundry/client-esm/dice/terms/parenthetical.d.mts

@@ -0,0 +1,105 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+import type { ParentheticalRollParseNode } from "../_types.d.mts";
+
+import type RollTerm from "./term.d.mts";
+import type DiceTerm from "./dice.d.mts";
+
+/**
+ * A type of RollTerm used to enclose a parenthetical expression to be recursively evaluated.
+ */
+declare class ParentheticalTerm extends RollTerm {
+  constructor({ term, roll, options }: ParentheticalTerm.TermData);
+
+  /** The original provided string term used to construct the parenthetical */
+  term: ParentheticalTerm.TermData["term"];
+
+  /** Alternatively, an already-evaluated Roll instance may be passed directly */
+  roll: ParentheticalTerm.TermData["roll"];
+
+  /**
+   * Is this term intermediate, and should be evaluated first as part of the simplification process?
+   * @defaultValue `true`
+   */
+  override isIntermediate: boolean;
+
+  /**
+   * The regular expression pattern used to identify the opening of a parenthetical expression.
+   * This could also identify the opening of a math function.
+   * @defaultValue
+   * ```typescript
+   * /([A-z][A-z0-9]+)?\(/g;
+   * ```
+   */
+  static OPEN_REGEXP: RegExp;
+
+  /**
+   * A regular expression pattern used to identify the closing of a parenthetical expression.
+   * @defaultValue
+   * ```typescript
+   * new RegExp("\\)(?:\\$\\$F[0-9]+\\$\\$)?", "g");
+   * ```
+   */
+  static CLOSE_REGEXP: RegExp;
+
+  /**
+   * An array of additional attributes which should be retained when the term is serialized.
+   * @defaultValue `["term", "roll"]`
+   */
+  static override SERIALIZE_ATTRIBUTES: string[];
+
+  /* -------------------------------------------- */
+  /*  Parenthetical Term Attributes               */
+  /* -------------------------------------------- */
+
+  /** An array of evaluated DiceTerm instances that should be bubbled up to the parent Roll */
+  get dice(): DiceTerm[];
+
+  override get total(): string | number | null | undefined;
+
+  override get expression(): string;
+
+  override get isDeterministic(): boolean;
+
+  /* -------------------------------------------- */
+  /*  Parenthetical Term Methods                  */
+  /* -------------------------------------------- */
+  protected override _evaluate(options?: InexactPartial<RollTerm.EvaluationOptions>): this | Promise<this>;
+
+  protected _evaluateAsync(roll: Roll, options?: InexactPartial<RollTerm.EvaluationOptions>): Promise<this>;
+
+  protected _evaluateSync(roll: Roll, options?: InexactPartial<RollTerm.EvaluationOptions>): this;
+
+  /* -------------------------------------------- */
+
+  /**
+   * Construct a ParentheticalTerm from an Array of component terms which should be wrapped inside the parentheses.
+   * @param terms - The array of terms to use as internal parts of the parenthetical
+   * @param options - Additional options passed to the ParentheticalTerm constructor
+   * @returns  The constructed ParentheticalTerm instance
+   *
+   * @example Create a Parenthetical Term from an array of component RollTerm instances
+   * ```typescript
+   * const d6 = new Die({number: 4, faces: 6});
+   * const plus = new OperatorTerm({operator: "+"});
+   * const bonus = new NumericTerm({number: 4});
+   * t = ParentheticalTerm.fromTerms([d6, plus, bonus]);
+   * t.formula; // (4d6 + 4)
+   * ```
+   */
+  static fromTerms(terms: RollTerm[], options?: InexactPartial<RollTerm.Options>): ParentheticalTerm;
+
+  /* -------------------------------------------- */
+
+  /** Construct a Parenthetical from parser information. */
+  static override fromParseNode(node: ParentheticalRollParseNode): ParentheticalTerm;
+}
+
+declare namespace ParentheticalTerm {
+  interface TermData {
+    term: string;
+    roll: Roll;
+    options?: InexactPartial<RollTerm.Options>;
+  }
+}
+
+export default ParentheticalTerm;

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

@@ -0,0 +1,278 @@
+import type { ConstructorOf, InexactPartial } from "../../../../types/utils.d.mts";
+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, modifiers, rolls, results, options }?: InexactPartial<PoolTerm.PoolTermConstructorData>);
+
+  /**
+   * The original provided terms to the Dice Pool
+   */
+  terms: PoolTerm.TermData["terms"];
+
+  /**
+   * The string modifiers applied to resolve the pool
+   */
+  modifiers: PoolTerm.TermData["modifiers"];
+
+  /**
+   * Each component term of a dice pool is evaluated as a Roll instance
+   */
+  rolls: PoolTerm.TermData["rolls"];
+
+  /**
+   * The array of dice pool results which have been rolled
+   */
+  results: PoolTerm.TermData["results"];
+
+  /**
+   * 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 DiceTerm#_evaluateModifiers
+   */
+  protected _evaluateModifiers(): void;
+
+  /* -------------------------------------------- */
+
+  /**
+   * Use the same logic as for the DiceTerm to avoid duplication
+   * @see DiceTerm#_evaluateModifier
+   */
+  protected _evaluateModifier(command: string, modifier: string): void;
+
+  /* -------------------------------------------- */
+  /*  Saving and Loading                          */
+  /* -------------------------------------------- */
+
+  protected static override _fromData<T extends RollTerm>(this: ConstructorOf<T>, data: Record<string, unknown>): 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>(
+    this: ConstructorOf<T>,
+    formula: string,
+    options?: RollTerm.Options,
+  ): 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>(this: ConstructorOf<T>, rolls?: Roll[]): 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 {
+  /**
+   * @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 {@link 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?: string[] | undefined;
+
+    /**
+     * @defaultValue `[]`
+     */
+    rolls?: Roll[] | undefined;
+
+    /**
+     * @defaultValue `[]`
+     */
+    results?: DiceTerm.Result[] | undefined;
+
+    /**
+     * @defaultValue `{}`
+     */
+    options?: RollTerm.Options | undefined;
+  }
+}
+
+export default PoolTerm;

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

@@ -0,0 +1,34 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+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.ConstructorData);
+
+  term: StringTerm.ConstructorData["term"];
+
+  /**
+   * @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 ConstructorData {
+    term: string;
+
+    options?: RollTerm.Options | undefined;
+  }
+}
+
+export default StringTerm;