roll-parser 3.0.0-beta.0 → 3.1.0

package/src/evaluator/env.ts

@@ -0,0 +1,105 @@
+/**
+ * Per-evaluation shared environment.
+ *
+ * Lives in its own module so the modifier implementations under
+ * `./modifiers/*` can type their `env` parameter without importing
+ * `./evaluator.js`, which imports them back.
+ *
+ * @module evaluator/env
+ */
+
+import { EvaluatorError } from '../errors.js';
+import type { ASTNode } from '../parser/ast.js';
+import type { DieResult, ResolvedCritThreshold } from '../types.js';
+
+/**
+ * A resolved `cs`/`cf` pair, recorded per die so that dice minted later by
+ * explode or reroll can be judged by the rule the user declared instead of
+ * the built-in default.
+ */
+export type CritRule = {
+  readonly success: readonly ResolvedCritThreshold[];
+  readonly fail: readonly ResolvedCritThreshold[];
+};
+
+/**
+ * Per-evaluation shared environment (created once, shared across all branches).
+ *
+ * Exported for use by modifier implementations under `./modifiers/*`. Not part
+ * of the public library API.
+ */
+export type EvalEnv = {
+  readonly maxDice: number;
+  readonly maxExplodeIterations: number;
+  readonly maxRerollIterations: number;
+  totalDiceRolled: number;
+  /**
+   * Set to `true` by `evalSuccessCount`. Propagates through the shared env
+   * so `evaluate()` can include `successes`/`failures` fields even when no
+   * die was tagged (impossible threshold).
+   */
+  hasSuccessCount: boolean;
+  /**
+   * `true` while the evaluator is inside a `VersusNode`'s roll or DC
+   * sub-evaluation. `evalVersus` rejects nesting via this flag — catches
+   * paren-nested versus (`1d20 vs (5 vs 3)`) that slip past the parser's
+   * left-chain check.
+   */
+  insideVersus: boolean;
+  /**
+   * `true` once a `vs` has tagged its DC dice `'dc'`. Lets every pool
+   * operation skip its per-die `isVersusDc` check outright — the tag exists in
+   * a small minority of notation, and the call inside the loop cost 11-38% on
+   * keep/drop, success, and sort notation that can never carry one (#281).
+   *
+   * ! Monotonic: set by `evalVersus`, never cleared. `insideVersus` is not a
+   * ! model for it — that flag resets in a `finally`, and it is false exactly
+   * ! when the tagged DC dice become visible to the enclosing pool.
+   */
+  hasVersusDc: boolean;
+  /**
+   * Crit rule per die, keyed on the `DieResult` object itself. Populated by
+   * `applyCritThresholds`; read by explode and reroll so a die they mint
+   * inherits the rule of the die it descended from.
+   *
+   * Out of band rather than a `DieResult` field because `DieResult` is public
+   * and serialized. `undefined` until the first `cs`/`cf` node — declared here
+   * so the shape stays stable for notation that has none.
+   */
+  critRules: WeakMap<DieResult, CritRule> | undefined;
+  /**
+   * User-supplied variable map for `@name` / `@{name}` references. Always
+   * defined — `evaluate()` defaults to an empty object so lookups can be
+   * branch-free on presence.
+   */
+  readonly context: Readonly<Record<string, number>>;
+  /**
+   * Behavior when a referenced variable is missing from `context`. Always
+   * defined — `evaluate()` defaults to `'throw'`.
+   */
+  readonly onMissingVariable: 'throw' | 'zero';
+};
+
+/**
+ * Reserves `count` dice against the global `maxDice` budget, throwing
+ * `DICE_LIMIT_EXCEEDED` when the reservation would overshoot.
+ *
+ * Every path that consumes RNG draws for dice charges through here — initial
+ * pools (`evalDice` / `evalFateDice`), explosion continuations, and reroll
+ * replacements — so the limit and its message have one definition.
+ */
+export function chargeDice(env: EvalEnv, count: number, nodeType: ASTNode['type']): void {
+  if (env.totalDiceRolled + count > env.maxDice) {
+    throw new EvaluatorError(
+      `Total dice count ${env.totalDiceRolled + count} exceeds limit of ${env.maxDice}`,
+      'DICE_LIMIT_EXCEEDED',
+      nodeType,
+    );
+  }
+  env.totalDiceRolled += count;
+}
+
+/** Single-die shorthand for {@link chargeDice}. */
+export function chargeDie(env: EvalEnv, nodeType: ASTNode['type']): void {
+  chargeDice(env, 1, nodeType);
+}