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

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

@@ -0,0 +1,68 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+import type DiceTerm from "./dice.d.mts";
+
+/**
+ * A type of DiceTerm used to represent flipping a two-sided coin.
+ */
+declare class Coin extends DiceTerm {
+  constructor(termData?: InexactPartial<Coin.TermData>);
+
+  _faces: 2;
+
+  /**
+   * @defaultValue `c`
+   */
+  static DENOMINATION: string;
+
+  /**
+   * @defaultValue
+   * ```typescript
+   *  {
+   *    c: "call"
+   *  }
+   * ```
+   */
+  static MODIFIERS: Coin.Modifiers;
+
+  /* -------------------------------------------- */
+
+  override roll({
+    minimize,
+    maximize,
+    ...options
+  }?: InexactPartial<DiceTerm.EvaluationOptions>): Promise<DiceTerm.Result>;
+
+  override getResultLabel(result: DiceTerm.Result): string;
+
+  override getResultCSS(result: DiceTerm.Result): (string | null)[];
+
+  /* -------------------------------------------- */
+
+  override mapRandomFace(randomUniform: number): number;
+
+  /* -------------------------------------------- */
+  /*  Term Modifiers                              */
+  /* -------------------------------------------- */
+
+  /**
+   * Call the result of the coin flip, marking any coins that matched the called target as a success
+   *
+   * 3dcc1      Flip 3 coins and treat "heads" as successes
+   * 2dcc0      Flip 2 coins and treat "tails" as successes
+   *
+   * @param modifier - The matched modifier query
+   */
+  call(modifier: string): void;
+}
+
+declare namespace Coin {
+  interface TermData extends DiceTerm.TermData {
+    modifiers: Array<keyof Modifiers>;
+  }
+
+  interface Modifiers {
+    c: "call";
+  }
+}
+
+export default Coin;

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

@@ -0,0 +1,381 @@
+import type { ConstructorOf, InexactPartial } from "../../../../types/utils.d.mts";
+import type { DiceRollParseNode } from "../_types.d.mts";
+
+import type RollTerm from "./term.d.mts";
+import type Roll from "../roll.d.mts";
+
+/**
+ * An abstract base class for any type of RollTerm which involves randomized input from dice, coins, or other devices.
+ */
+declare abstract class DiceTerm extends RollTerm {
+  /**
+   * @param termData  - Data used to create the Dice Term, including the following:
+   *                    (default: `{}`)
+   * @param number    - The number of dice of this term to roll, before modifiers are applied
+   *                    (default: `1`)
+   * @param faces     - The number of faces on each die of this type
+   *                    (default: `6`)
+   * @param modifiers - An array of modifiers applied to the results
+   *                    (default: `[]`)
+   * @param results   - An optional array of pre-cast results for the term
+   *                    (default: `[]`)
+   * @param options   - Additional options that modify the term
+   *                    (default: `{}`)
+   */
+  constructor(termData?: InexactPartial<DiceTerm.TermData>);
+
+  get method(): string; // TODO: Convert to CONFIG.Dice.fulfillment.methods
+
+  set method(method: string); // TODO: Convert to CONFIG.Dice.fulfillment.methods
+
+  #method: string; // TODO: Convert to CONFIG.Dice.fulfillment.methods
+
+  /**  An Array of dice term modifiers which are applied. */
+  modifiers: DiceTerm.TermData["modifiers"];
+
+  /** The array of dice term results which have been rolled. */
+  results: DiceTerm.Result[];
+
+  /* -------------------------------------------- */
+
+  /**
+   * Define the denomination string used to register this DiceTerm type in CONFIG.Dice.terms
+   * @defaultValue ""
+   */
+  static DENOMINATION: string;
+
+  /**
+   * Define the named modifiers that can be applied for this particular DiceTerm type.
+   * @defaultValue `{}`
+   */
+  static MODIFIERS: DiceTerm.Modifiers;
+
+  /**
+   * A regular expression pattern which captures the full set of term modifiers
+   * Anything until a space, group symbol, or arithmetic operator
+   */
+  static MODIFIERS_REGEXP_STRING: string;
+
+  /** A regular expression used to separate individual modifiers */
+  static MODIFIER_REGEXP: RegExp;
+
+  static REGEXP: RegExp;
+
+  /**
+   * @defaultValue `["number", "faces", "modifiers", "results", "method"]`
+   */
+  static SERIALIZE_ATTRIBUTES: string[];
+
+  /* -------------------------------------------- */
+  /*  Dice Term Attributes                        */
+  /* -------------------------------------------- */
+
+  /** The number of dice of this term to roll. Returns undefined if the number is a
+   * complex term that has not yet been evaluated.
+   */
+  get number(): DiceTerm.TermData["number"] | undefined;
+  /** The number of dice of this term to roll. */
+  set number(value: DiceTerm.TermData["number"]);
+
+  /**
+   * The number of dice of this term to roll, before modifiers are applied, or a Roll instance that will be evaluated to
+   * a number.
+   */
+  _number: DiceTerm.TermData["number"] | Roll;
+
+  /**
+   * The number of faces on the die. Returns undefined if the faces are represented as a complex term that has not yet
+   * been evaluated.
+   */
+  get faces(): DiceTerm.TermData["faces"] | undefined;
+  set faces(value: DiceTerm.TermData["faces"]);
+
+  /** The number of faces on the die, or a Roll instance that will be evaluated to a number. */
+  _faces: DiceTerm.TermData["faces"] | Roll;
+
+  /* -------------------------------------------- */
+  /**  The denomination of this DiceTerm instance. */
+  get denomination(): string;
+
+  /** An array of additional DiceTerm instances involved in resolving this DiceTerm. */
+  get dice(): DiceTerm[];
+
+  override get total(): number | undefined;
+
+  /** Return an array of rolled values which are still active within this term */
+  get values(): number[];
+
+  override get isDeterministic(): boolean;
+
+  /* -------------------------------------------- */
+  /*  Dice Term Methods                           */
+  /* -------------------------------------------- */
+
+  /**
+   * Alter the DiceTerm by adding or multiplying the number of dice which are rolled
+   * @param multiply - A factor to multiply. Dice are multiplied before any additions.
+   * @param add      - A number of dice to add. Dice are added after multiplication.
+   * @returns The altered term
+   */
+  alter(multiply: number, add: number): this;
+
+  /* -------------------------------------------- */
+
+  protected _evaluate(options?: InexactPartial<DiceTerm.EvaluationOptions>): this | Promise<this>;
+
+  /* -------------------------------------------- */
+
+  /**
+   * Evaluate this dice term asynchronously.
+   * @param options - Options forwarded to inner Roll evaluation. (Default: `{}`)
+   */
+  _evaluateAsync(options?: InexactPartial<DiceTerm.EvaluationOptions>): Promise<this>;
+
+  /* -------------------------------------------- */
+  /**
+   * Evaluate deterministic values of this term synchronously.
+   * @param options - Options forwarded to inner Roll evaluation. (Default: `{}`)
+   */
+  _evaluateSync(options?: InexactPartial<DiceTerm.EvaluationOptions>): this;
+
+  /* -------------------------------------------- */
+
+  /**
+   * Roll the DiceTerm by mapping a random uniform draw against the faces of the dice term.
+   * @param minimize - Minimize the result, obtaining the smallest possible value.
+   * @param maximize - Maximize the result, obtaining the largest possible value.
+   * @returns The produced result
+   */
+  roll({ minimize, maximize, ...options }?: InexactPartial<DiceTerm.EvaluationOptions>): Promise<DiceTerm.Result>;
+
+  /* -------------------------------------------- */
+
+  /**
+   * Generate a roll result value for this DiceTerm based on its fulfillment method.
+   * @param  options - Options forwarded to the fulfillment method handler.
+   * @returns Returns a Promise that resolves to the fulfilled number, or undefined if it could
+   *          not be fulfilled.
+   */
+  protected _roll(options?: InexactPartial<DiceTerm.EvaluationOptions>): Promise<number | undefined>;
+
+  /* -------------------------------------------- */
+
+  /**
+   * Invoke the configured fulfillment handler for this term to produce a result value.
+   * @param options -Options forwarded to the fulfillment method handler.
+   * @returns Returns a Promise that resolves to the fulfilled number, or undefined if it could
+   *          not be fulfilled.
+   */
+  #invokeFulfillmentHandler(options?: InexactPartial<DiceTerm.EvaluationOptions>): Promise<number | undefined>;
+
+  /* -------------------------------------------- */
+
+  /**
+   * Maps a randomly-generated value in the interval [0, 1) to a face value on the die.
+   * @param randomUniform - A value to map. Must be in the interval [0, 1).
+   * @returns The face value.
+   */
+  mapRandomFace(randomUniform: number): number;
+
+  /* -------------------------------------------- */
+
+  /** Generate a random face value for this die using the configured PRNG. */
+  randomFace(): number;
+
+  /**
+   * Return a string used as the label for each rolled result
+   * @param result - The rolled result
+   * @returns The result label
+   */
+  getResultLabel(result: DiceTerm.Result): string;
+
+  /* -------------------------------------------- */
+
+  /**
+   * Get the CSS classes that should be used to display each rolled result
+   * @param result - The rolled result
+   * @returns The desired classes
+   */
+  getResultCSS(result: DiceTerm.Result): (string | null)[];
+
+  /* -------------------------------------------- */
+
+  /**
+   * Render the tooltip HTML for a Roll instance
+   * @returns The data object used to render the default tooltip template for this DiceTerm
+   */
+  getTooltipData(): DiceTerm.ToolTipData;
+
+  /* -------------------------------------------- */
+  /*  Modifier Helpers                            */
+  /* -------------------------------------------- */
+
+  /**
+   * Sequentially evaluate each dice roll modifier by passing the term to its evaluation function
+   * Augment or modify the results array.
+   */
+  protected _evaluateModifiers(): void;
+
+  /* -------------------------------------------- */
+
+  /**
+   * Evaluate a single modifier command, recording it in the array of evaluated modifiers
+   * @param command - The parsed modifier command
+   * @param modifier -  The full modifier request
+   */
+  protected _evaluateModifier(command: string, modifier: string): void;
+  /* -------------------------------------------- */
+
+  /**
+   * A helper comparison function.
+   * Returns a boolean depending on whether the result compares favorably against the target.
+   * @param result     - The result being compared
+   * @param comparison - The comparison operator in [=,&lt;,&lt;=,\>,\>=]
+   * @param target     - The target value
+   * @returns Is the comparison true?
+   */
+  static compareResult(result: number, comparison: string, target: number): boolean;
+
+  /* -------------------------------------------- */
+
+  /**
+   * A helper method to modify the results array of a dice term by flagging certain results are kept or dropped.
+   * @param results - The results array
+   * @param number  - The number to keep or drop
+   * @param keep    - Keep results?
+   *                  (default: `true`)
+   * @param highest - Keep the highest?
+   *                  (default: `true`)
+   * @returns The modified results array
+   */
+  protected static _keepOrDrop(
+    results: DiceTerm.Result[],
+    number: number,
+    { keep, highest }?: InexactPartial<{ keep: boolean; highest: boolean }>,
+  ): DiceTerm.Result;
+
+  /* -------------------------------------------- */
+
+  /**
+   * A reusable helper function to handle the identification and deduction of failures
+   * @param flagFailure - (default: `false`)
+   * @param flagSuccess - (default: `false`)
+   */
+  protected static _applyCount(
+    results: DiceTerm.Result[],
+    comparison: string,
+    target: number,
+    { flagSuccess, flagFailure }?: InexactPartial<{ flagSuccess: boolean; flagFailure: boolean }>,
+  ): void;
+
+  /* -------------------------------------------- */
+
+  /**
+   * A reusable helper function to handle the identification and deduction of failures
+   * @param deductFailure - (default: `false`)
+   * @param invertFailure - (default: `false`)
+   */
+  protected static _applyDeduct(
+    results: DiceTerm.Result[],
+    comparison: string,
+    target: number,
+    { deductFailure, invertFailure }?: InexactPartial<{ deductFailure: boolean; invertFailure: boolean }>,
+  ): void;
+
+  /* -------------------------------------------- */
+  /*  Factory Methods                             */
+  /* -------------------------------------------- */
+
+  /**
+   * Determine whether a string expression matches this type of term
+   * @param expression - The expression to parse
+   * @param options - Additional options which customize the match
+   * @param imputeNumber - Allow the number of dice to be optional, i.e. "d6"
+   *                       (default: `true`)
+   */
+  static matchTerm(
+    expression: string,
+    { imputeNumber }?: InexactPartial<{ imputeNumber: boolean }>,
+  ): 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): DiceTerm;
+
+  /* -------------------------------------------- */
+  /** Construct a DiceTerm from parser information. */
+  static override fromParseNode(node: DiceRollParseNode): DiceTerm;
+
+  /* -------------------------------------------- */
+  /*  Serialization & Loading                     */
+  /* -------------------------------------------- */
+
+  protected static _fromData<T extends RollTerm>(this: ConstructorOf<T>, data: Record<string, unknown>): T;
+
+  override toJSON(): Record<string, unknown>;
+}
+
+declare namespace DiceTerm {
+  interface Data extends InexactPartial<TermData> {
+    class?: string | undefined;
+    results: DiceTerm.Result[];
+  }
+
+  interface TermData {
+    number: number;
+    faces: number;
+    modifiers: string[];
+    results: Result[];
+    options: DiceTerm.Options;
+  }
+
+  interface Options extends RollTerm.Options {}
+
+  interface Result {
+    /** The numeric result. */
+    result: number;
+    /** Is this result active, contributing to the total? */
+    active?: boolean | undefined;
+    /** A value that the result counts as, otherwise the result is not used directly as. */
+    count?: number | undefined;
+    /** Does this result denote a success? */
+    success?: boolean | undefined;
+    /** Does this result denote a failure? */
+    failure?: boolean | undefined;
+    /** Was this result discarded? */
+    discarded?: boolean | undefined;
+    /** Was this result rerolled? */
+    rerolled?: boolean | undefined;
+    /** Was this result exploded? */
+    exploded?: boolean | undefined;
+  }
+
+  interface ToolTipData {
+    total: number;
+    faces: number;
+    flavor: string;
+    icon: string;
+    method: string;
+    formula: string;
+    rolls: { result: string; classes: string }[];
+  }
+
+  interface EvaluationOptions extends RollTerm.EvaluationOptions {
+    /**
+     * Throw an error if attempting to evaluate a die term in a way that cannot be done
+     *  synchronously.
+     * @defaultValue `true`
+     */
+    strict: boolean;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface Modifiers {}
+}
+
+export default DiceTerm;

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

@@ -0,0 +1,241 @@
+import type { InexactPartial } from "../../../../types/utils.d.mts";
+
+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}
+   */
+  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}
+   */
+  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 TermData extends DiceTerm.TermData {
+    modifiers: Array<keyof (typeof Die)["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";
+  }
+}
+
+export default Die;