roll-parser 3.0.0-beta.0 → 3.0.0

package/dist/evaluator/evaluator.d.ts

@@ -3,71 +3,32 @@
  *
  * @module evaluator/evaluator
  */
-import type { RollParserErrorCode } from '../errors.js';
-import { RollParserError } from '../errors.js';
+import { EvaluatorError } from '../errors.js';
 import type { ASTNode } from '../parser/ast.js';
 import type { RNG } from '../rng/types.js';
 import type { DieResult, EvaluateOptions, RollResult } from '../types.js';
 import { DegreeOfSuccess } from '../types.js';
 import { DEFAULT_MAX_EXPLODE_ITERATIONS } from './modifiers/explode.js';
 import { DEFAULT_MAX_REROLL_ITERATIONS } from './modifiers/reroll.js';
+export { EvaluatorError };
 /**
- * Error thrown during AST evaluation.
+ * Default value of `EvaluationOptions.maxDice`: the number of dice a single
+ * evaluation may roll before `DICE_LIMIT_EXCEEDED` is thrown.
+ *
+ * Counted across the whole expression, not per pool, so `6000d6+6000d6`
+ * breaches it. Includes dice rolled by explosions, rerolls, and
+ * meta-expressions.
+ *
+ * @category Limits
  */
-export declare class EvaluatorError extends RollParserError {
-    readonly nodeType: string | undefined;
-    /**
-     * Source span of the tightest AST node that was being evaluated when the
-     * error was thrown — stamped by `evalNode` on the way up, so the innermost
-     * node wins. `undefined` when the AST was built without parser spans.
-     */
-    start: number | undefined;
-    end: number | undefined;
-    constructor(message: string, code: RollParserErrorCode, nodeType?: string);
-}
-/** Default maximum total dice allowed per evaluation. */
 export declare const DEFAULT_MAX_DICE = 10000;
 export { DEFAULT_MAX_EXPLODE_ITERATIONS, DEFAULT_MAX_REROLL_ITERATIONS };
-/**
- * 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;
-    /**
-     * 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';
-};
 /**
  * Per-branch mutable accumulator for tracking rolls and output during recursion.
  *
- * @internal exported for targeted `mergeMetaRolls` tests only; not a public API.
+ * Module-level export, deliberately absent from `src/index.ts` — the package
+ * surface never mentions it. See {@link mergeMetaRolls} for why the export
+ * exists at all.
  */
 export type EvalContext = {
     rolls: DieResult[];
@@ -86,36 +47,41 @@ export type EvalContext = {
     };
 };
 /**
- * Forwards rolls from a throwaway sub-expression context into the parent
- * audit trail, tagging them as `'meta'` + `'dropped'`. Meta dice are dice
- * rolled to compute parameters (dice count, sides, threshold, modifier
- * count) — they consume RNG and count against `maxDice`, so they must be
- * inspectable. Tagging them `'dropped'` keeps totals correct via
- * `sumKeptDice`; `'meta'` lets renderers hide them and lets callers
- * distinguish them from ordinary pool dice.
+ * Evaluates a parsed AST against an {@link RNG} and returns the roll result.
  *
- * `'success'`/`'failure'` tags are stripped here as defense-in-depth against
- * a SuccessCount leaking into a meta sub-expression (parser rejects all such
- * wrappings; this strip ensures a future parse regression cannot leak tags
- * into the top-level `successes`/`failures` scan).
- */
-/** @internal exported for targeted defense-in-depth tests only. */
-export declare function mergeMetaRolls(parent: EvalContext, source: EvalContext): void;
-/**
- * Evaluates a parsed AST and returns the roll result.
+ * The second half of the pipeline — {@link roll} is `evaluate(parse(...))`.
+ * Call it directly to reuse one AST across many rolls, or to drive a
+ * hand-built AST.
+ *
+ * Unlike `roll`, the RNG is required: `evaluate` never invents a randomness
+ * source, so a caller can never accidentally get an unseeded roll.
  *
- * @param ast - The parsed AST node
- * @param rng - Random number generator to use for dice rolls
- * @param options - Optional evaluation options
- * @returns Complete roll result with total and metadata
+ * @param ast - The AST to evaluate, from {@link parse} or hand-built
+ * @param rng - Randomness source; one `nextInt` call per die
+ * @param options - Evaluation limits plus the original `notation` string,
+ *   which the AST cannot supply
+ * @returns Complete {@link RollResult}
+ * @throws {EvaluatorError} On a limit breach, division by zero, an undefined
+ *   variable, or a non-finite total
+ * @throws {RollParserError} `INVALID_EVALUATION_LIMIT` when a supplied limit is
+ *   not an integer in range — raised before any die is rolled
  *
  * @example
  * ```typescript
+ * import { evaluate, parse } from 'roll-parser';
+ * import { createMockRng } from 'roll-parser/testing';
+ *
  * const ast = parse('2d6+3');
- * const rng = new SeededRNG('test');
- * const result = evaluate(ast, rng);
- * console.log(result.total); // Sum of dice plus 3
+ * const result = evaluate(ast, createMockRng([4, 2]), { notation: '2d6+3' });
+ * result.total; // 9
+ * result.rendered; // '2d6[4, 2] + 3 = 9'
  * ```
+ *
+ * Omitting `notation` falls back to the normalized `expression`, which is
+ * reconstructed from the AST — so `RollResult.notation` is always a string,
+ * just not necessarily the one the user typed.
+ *
+ * @category Core
  */
 export declare function evaluate(ast: ASTNode, rng: RNG, options?: EvaluateOptions): RollResult;
 //# sourceMappingURL=evaluator.d.ts.map

package/dist/evaluator/evaluator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluator/evaluator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EACV,OAAO,EAkBR,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,KAAK,EAEV,SAAS,EACT,eAAe,EAGf,UAAU,EACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAKL,8BAA8B,EAC/B,MAAM,wBAAwB,CAAC;AAShC,OAAO,EAGL,6BAA6B,EAC9B,MAAM,uBAAuB,CAAC;AAI/B;;GAEG;AACH,qBAAa,cAAe,SAAQ,eAAe;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,QAAQ,CAAC,EAAE,MAAM;CAO1E;AAED,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC,OAAO,EAAE,8BAA8B,EAAE,6BAA6B,EAAE,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,eAAe,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,YAAY,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,GAAG,MAAM,CAAC;CAC9C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;OAKG;IACH,cAAc,CAAC,EAAE;QACf,MAAM,EAAE,eAAe,CAAC;QACxB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,CAAC;AA+FF;;;;;;;;;;;;;GAaG;AACH,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAa7E;AA8pCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,GAAE,eAAoB,GAAG,UAAU,CAmF1F"}
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluator/evaluator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAiB,cAAc,EAAuC,MAAM,cAAc,CAAC;AAClG,OAAO,KAAK,EACV,OAAO,EAmBR,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,KAAK,EAIV,SAAS,EACT,eAAe,EAKf,UAAU,EACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAK9C,OAAO,EAKL,8BAA8B,EAC/B,MAAM,wBAAwB,CAAC;AAQhC,OAAO,EAGL,6BAA6B,EAC9B,MAAM,uBAAuB,CAAC;AAM/B,OAAO,EAAE,cAAc,EAAE,CAAC;AAM1B;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAmCvC,OAAO,EAAE,8BAA8B,EAAE,6BAA6B,EAAE,CAAC;AAMzE;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB;;;;;OAKG;IACH,cAAc,CAAC,EAAE;QACf,MAAM,EAAE,eAAe,CAAC;QACxB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,CAAC;AA++CF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,GAAE,eAAoB,GAAG,UAAU,CA4D1F"}