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

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

@@ -0,0 +1,248 @@
+import type { Identity, InexactPartial } from "#utils";
+
+import type DiceTerm from "./dice.d.mts";
+
+/**
+ * A type of DiceTerm used to represent rolling a fair n-sided die.
+ *
+ * @example Roll 4 six-sided dice
+ * ```typescript
+ * let die = new Die({faces: 6, number: 4}).evaluate();
+ * ```
+ */
+declare class Die extends DiceTerm {
+  constructor(termData?: InexactPartial<Die.TermData>);
+
+  /**
+   * @defaultValue `"d"`
+   */
+  static override DENOMINATION: string;
+
+  /**
+   * @defaultValue
+   * ```typescript
+   * {
+   *   r: "reroll";
+   *   rr: "rerollRecursive";
+   *   x: "explode";
+   *   xo: "explodeOnce";
+   *   k: "keep";
+   *   kh: "keep";
+   *   kl: "keep";
+   *   d: "drop";
+   *   dh: "drop";
+   *   dl: "drop";
+   *   min: "minimum";
+   *   max: "maximum";
+   *   even: "countEven";
+   *   odd: "countOdd";
+   *   cs: "countSuccess";
+   *   cf: "countFailures";
+   *   df: "deductFailures";
+   *   sf: "subtractFailures";
+   *   ms: "marginSuccess";
+   * }
+   * ```
+   */
+  static override MODIFIERS: Die.Modifiers;
+
+  override get total(): number | undefined;
+
+  override get denomination(): string;
+
+  /* -------------------------------------------- */
+  /*  Term Modifiers                              */
+  /* -------------------------------------------- */
+
+  /**
+   * Re-roll the Die, rolling additional results for any values which fall within a target set.
+   * If no target number is specified, re-roll the lowest possible result.
+   *
+   * 20d20r         reroll all 1s
+   * 20d20r1        reroll all 1s
+   * 20d20r=1       reroll all 1s
+   * 20d20r1=1      reroll a single 1
+   *
+   * @param modifier - The matched modifier query
+   * @param recursive - Reroll recursively, continuing to reroll until the condition is no longer met
+   * @returns False if the modifier was unmatched
+   */
+  reroll(modifier: string, { recursive }?: InexactPartial<{ recursive: boolean }>): Promise<boolean | void>;
+
+  /**
+   * @see {@link Die.reroll | `Die#reroll`}
+   */
+  rerollRecursive(modifier: string): Promise<boolean | void>;
+
+  /**
+   * Explode the Die, rolling additional results for any values which match the target set.
+   * If no target number is specified, explode the highest possible result.
+   * Explosion can be a "small explode" using a lower-case x or a "big explode" using an upper-case "X"
+   *
+   * @param modifier  - The matched modifier query
+   * @param recursive - Explode recursively, such that new rolls can also explode?
+   *                    (default: `true`)
+   */
+  explode(modifier: string, { recursive }?: InexactPartial<{ recursive: boolean }>): Promise<boolean | void>;
+
+  /**
+   * @see {@link Die.explode | `Die#explode`}
+   */
+  explodeOnce(modifier: string): Promise<boolean | void>;
+
+  /**
+   * Keep a certain number of highest or lowest dice rolls from the result set.
+   *
+   * 20d20k       Keep the 1 highest die
+   * 20d20kh      Keep the 1 highest die
+   * 20d20kh10    Keep the 10 highest die
+   * 20d20kl      Keep the 1 lowest die
+   * 20d20kl10    Keep the 10 lowest die
+   *
+   * @param modifier - The matched modifier query
+   */
+  keep(modifier: string): boolean | void;
+
+  /**
+   * Drop a certain number of highest or lowest dice rolls from the result set.
+   *
+   * 20d20d       Drop the 1 lowest die
+   * 20d20dh      Drop the 1 highest die
+   * 20d20dl      Drop the 1 lowest die
+   * 20d20dh10    Drop the 10 highest die
+   * 20d20dl10    Drop the 10 lowest die
+   *
+   * @param modifier - The matched modifier query
+   */
+  drop(modifier: string): boolean | void;
+
+  /**
+   * Count the number of successful results which occurred in a given result set.
+   * 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)
+   *
+   * 20d20cs      Count the number of dice which rolled a 20
+   * 20d20cs\>10   Count the number of dice which rolled higher than 10
+   * 20d20cs\<10   Count the number of dice which rolled less than 10
+   *
+   * @param modifier - The matched modifier query
+   */
+  countSuccess(modifier: string): boolean | void;
+
+  /**
+   * 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)
+   *
+   * 6d6cf      Count the number of dice which rolled a 1 as failures
+   * 6d6cf\<=3   Count the number of dice which rolled less than 3 as failures
+   * 6d6cf\>4    Count the number of dice which rolled greater than 4 as failures
+   *
+   * @param modifier - The matched modifier query
+   */
+  countFailures(modifier: string): boolean | void;
+
+  /**
+   * Count the number of even results which occurred in a given result set.
+   * Even numbers are marked as a success and counted as 1
+   * Odd numbers are marked as a non-success and counted as 0.
+   *
+   * 6d6even    Count the number of even numbers rolled
+   *
+   * @param modifier - The matched modifier query
+   */
+  countEven(modifier: string): boolean | void; // FIXME:  Modifiers is also unused.
+
+  /**
+   * Count the number of odd results which occurred in a given result set.
+   * Odd numbers are marked as a success and counted as 1
+   * Even numbers are marked as a non-success and counted as 0.
+   *
+   * 6d6odd    Count the number of odd numbers rolled
+   *
+   * @param modifier - The matched modifier query
+   */
+  countOdd(modifier: string): boolean | void; // FIXME: Modifiers is also unused.
+
+  /**
+   * Deduct the number of failures from the dice result, counting each failure as -1
+   * Failures are identified relative to some target, or relative to the lowest possible value if no target is given.
+   * Applying a deduct-failures modifier to the results counts all failed results as -1.
+   *
+   * 6d6df      Subtract the number of dice which rolled a 1 from the non-failed total.
+   * 6d6cs\>3df  Subtract the number of dice which rolled a 3 or less from the non-failed count.
+   * 6d6cf\<3df  Subtract the number of dice which rolled less than 3 from the non-failed count.
+   *
+   * @param modifier - The matched modifier query
+   */
+  deductFailures(modifier: string): boolean | void;
+
+  /**
+   * Subtract the value of failed dice from the non-failed total, where each failure counts as its negative value.
+   * Failures are identified relative to some target, or relative to the lowest possible value if no target is given.
+   * Applying a deduct-failures modifier to the results counts all failed results as -1.
+   *
+   * 6d6df\<3    Subtract the value of results which rolled less than 3 from the non-failed total.
+   *
+   * @param modifier - The matched modifier query
+   */
+  subtractFailures(modifier: string): boolean | void;
+
+  /**
+   * Subtract the total value of the DiceTerm from a target value, treating the difference as the final total.
+   * Example: 6d6ms\>12    Roll 6d6 and subtract 12 from the resulting total.
+   * @param modifier - The matched modifier query
+   */
+  marginSuccess(modifier: string): boolean | void;
+
+  /**
+   * Constrain each rolled result to be at least some minimum value.
+   * Example: 6d6min2    Roll 6d6, each result must be at least 2
+   * @param modifier - The matched modifier query
+   */
+  minimum(modifier: string): boolean | void;
+
+  /**
+   * Constrain each rolled result to be at most some maximum value.
+   * Example: 6d6max5    Roll 6d6, each result must be at most 5
+   * @param modifier - The matched modifier query
+   */
+  maximum(modifier: string): boolean | void;
+}
+
+declare namespace Die {
+  interface Any extends AnyDie {}
+  interface AnyConstructor extends Identity<typeof AnyDie> {}
+
+  interface TermData extends DiceTerm.TermData {
+    modifiers: Array<keyof Modifiers>;
+  }
+
+  interface Modifiers {
+    r: "reroll";
+    rr: "rerollRecursive";
+    x: "explode";
+    xo: "explodeOnce";
+    k: "keep";
+    kh: "keep";
+    kl: "keep";
+    d: "drop";
+    dh: "drop";
+    dl: "drop";
+    min: "minimum";
+    max: "maximum";
+    even: "countEven";
+    odd: "countOdd";
+    cs: "countSuccess";
+    cf: "countFailures";
+    df: "deductFailures";
+    sf: "subtractFailures";
+    ms: "marginSuccess";
+  }
+}
+
+declare abstract class AnyDie extends Die {
+  constructor(...args: never);
+}
+
+export default Die;

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

@@ -0,0 +1,57 @@
+import type { Identity, InexactPartial } from "#utils";
+
+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 Any extends AnyFateDie {}
+  interface AnyConstructor extends Identity<typeof AnyFateDie> {}
+
+  interface TermData extends DiceTerm.TermData {
+    modifiers: Array<keyof 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"];
+  }
+}
+
+declare abstract class AnyFateDie extends FateDie {
+  constructor(...args: never);
+}
+
+export default FateDie;

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

@@ -0,0 +1,106 @@
+import type { InexactPartial, FixedInstanceType } from "#utils";
+import type { FunctionRollParseNode } from "../_types.d.mts";
+
+import type RollTerm from "./term.d.mts";
+import type DiceTerm from "./dice.d.mts";
+
+/**
+ * A type of RollTerm used to apply a function.
+ */
+declare class FunctionTerm extends RollTerm {
+  constructor(termData: 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 | undefined; // note: it will be undefined if the function has not yet been evaluated
+
+  /** 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(): CONFIG.Dice.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.AnyConstructor>(
+    this: T,
+    data: Record<string, unknown>,
+  ): FixedInstanceType<T>;
+
+  override toJSON(): Record<string, unknown>;
+
+  static override fromParseNode(node: FunctionRollParseNode): RollTerm;
+}
+
+declare namespace FunctionTerm {
+  interface Data extends TermData {
+    fn: string;
+    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[] | undefined;
+
+    /** The cached Roll instances for each function argument. */
+    rolls?: Roll[] | undefined;
+
+    /** The cached result of evaluating the method arguments. */
+    result?: string | number | undefined;
+    options?: InexactPartial<FunctionTerm.Options>;
+  }
+
+  interface Options extends RollTerm.Options {}
+}
+
+export default FunctionTerm;

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

@@ -0,0 +1,54 @@
+import type { InexactPartial } from "#utils";
+import type RollTerm from "./term.d.mts";
+
+/**
+ * A type of RollTerm used to represent static numbers.
+ */
+declare class NumericTerm extends RollTerm {
+  constructor(termData: 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 `undefined`
+     */
+    options?: InexactPartial<RollTerm.Options>;
+  }
+}
+
+export default NumericTerm;

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

@@ -0,0 +1,55 @@
+import type { InexactPartial } from "#utils";
+
+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(termData: 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/dice/terms/parenthetical.d.mts

@@ -0,0 +1,104 @@
+import type { InexactPartial } from "#utils";
+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: string | undefined; // only one of term or roll is expected
+
+  /** Alternatively, an already-evaluated Roll instance may be passed directly */
+  roll: Roll | undefined; // only one of term or roll is expected
+
+  /**
+   * 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(): number | 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 {
+  /** @internal */
+  interface _TermData {
+    term: string;
+    roll: Roll;
+    options?: InexactPartial<RollTerm.Options>;
+  }
+
+  interface TermData extends InexactPartial<ParentheticalTerm._TermData> {}
+}
+
+export default ParentheticalTerm;