roll-parser 3.0.0-alpha.0 → 3.0.0

package/dist/evaluator/evaluator.d.ts

@@ -3,63 +3,85 @@
  *
  * @module evaluator/evaluator
  */
-import type { RollParserErrorCode } from '../errors';
-import { RollParserError } from '../errors';
-import type { ASTNode } from '../parser/ast';
-import type { RNG } from '../rng/types';
-import type { EvaluateOptions, RollResult } from '../types';
-import { DEFAULT_MAX_EXPLODE_ITERATIONS } from './modifiers/explode';
-import { DEFAULT_MAX_REROLL_ITERATIONS } from './modifiers/reroll';
+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;
-    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).
+ * Per-branch mutable accumulator for tracking rolls and output during recursion.
  *
- * Exported for use by modifier implementations under `./modifiers/*`. Not part
- * of the public library 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 EvalEnv = {
-    readonly maxDice: number;
-    readonly maxExplodeIterations: number;
-    readonly maxRerollIterations: number;
-    totalDiceRolled: number;
+export type EvalContext = {
+    rolls: DieResult[];
+    expressionParts: string[];
+    renderedParts: string[];
     /**
-     * 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).
+     * Populated by `evalVersus` with the resolved degree and natural value.
+     * `evaluate()` reads this from the top-level ctx to surface `degree` and
+     * `natural` on the final `RollResult`. Only populated when `vs` is the
+     * root of the expression.
      */
-    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;
+    versusMetadata?: {
+        degree: DegreeOfSuccess;
+        natural: number | undefined;
+        dcTotal: number;
+    };
 };
 /**
- * Evaluates a parsed AST and returns the roll result.
+ * Evaluates a parsed AST against an {@link RNG} 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.
  *
- * @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
+ * 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 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,WAAW,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EACV,OAAO,EAWR,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,EAA2B,eAAe,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAErF,OAAO,EAKL,8BAA8B,EAC/B,MAAM,qBAAqB,CAAC;AAS7B,OAAO,EAGL,6BAA6B,EAC9B,MAAM,oBAAoB,CAAC;AAG5B;;GAEG;AACH,qBAAa,cAAe,SAAQ,eAAe;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE1B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,QAAQ,CAAC,EAAE,MAAM;CAK1E;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;CACvB,CAAC;AAspBF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,GAAE,eAAoB,GAAG,UAAU,CAqE1F"}
+{"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"}