roll-parser 3.0.0-alpha.0 → 3.0.0

package/src/roll.ts

@@ -4,63 +4,88 @@
  * @module roll
  */
 
-import type { RNG } from './rng/types';
-import type { EvaluateOptions, RollResult } from './types';
-import { evaluate } from './evaluator/evaluator';
-import { lex } from './lexer/lexer';
-import { Parser } from './parser/parser';
-import { SeededRNG } from './rng/seeded';
+import { evaluate } from './evaluator/evaluator.js';
+import { parse } from './parser/parser.js';
+import { SeededRNG } from './rng/seeded.js';
+import type { RNG } from './rng/types.js';
+import type { EvaluationOptions, RollResult } from './types.js';
 
 /**
- * Options for the roll function.
+ * Everything {@link roll} accepts on top of the shared {@link EvaluationOptions}:
+ * a randomness source, given either as a ready-made {@link RNG} or as a seed.
+ *
+ * @category Core
+ *
+ * @example
+ * ```typescript
+ * import { roll, SeededRNG } from 'roll-parser';
+ *
+ * roll('4d6', { seed: 'character-1' });     // reproducible
+ * roll('4d6', { rng: new SeededRNG(42) });  // rng wins over seed
+ * roll('1d20+@str', { context: { str: 4 } });
+ * ```
  */
-export type RollOptions = {
-  /** Custom RNG instance (takes precedence over seed) */
+export type RollOptions = EvaluationOptions & {
+  /**
+   * Randomness source. Takes precedence over `seed` — when both are given,
+   * `seed` is ignored.
+   */
   rng?: RNG;
-  /** Seed for deterministic rolls (ignored if rng provided) */
+  /**
+   * Seed for a fresh `SeededRNG`. Equal seeds replay the same die sequence for
+   * the same notation. Ignored when `rng` is set.
+   */
   seed?: string | number;
-  /** Maximum total dice allowed per evaluation (default: 10,000) */
-  maxDice?: number;
-  /** Maximum explosion iterations allowed per die (default: 1,000) */
-  maxExplodeIterations?: number;
-  /** Maximum reroll iterations allowed per die (default: 1,000) */
-  maxRerollIterations?: number;
 };
 
 /**
- * Parses and evaluates a dice notation string.
+ * Parses and evaluates a dice notation string in one call — the main entry
+ * point of the library.
+ *
+ * Equivalent to `evaluate(parse(notation), rng, { notation })`. Each call
+ * builds a fresh `SeededRNG` unless `options.rng` is supplied, so reuse
+ * {@link parse} + {@link evaluate} directly when rolling the same notation in
+ * a loop.
  *
- * @param notation - Dice notation (e.g., "2d6+3", "4d6kh3")
- * @param options - Optional configuration (RNG or seed)
- * @returns Complete roll result with total and metadata
+ * @param notation - Dice notation, e.g. `'2d6+3'` or `'4d6kh3'`
+ * @param options - RNG or seed, plus the shared {@link EvaluationOptions}
+ * @returns Complete {@link RollResult} with total, per-die results and the
+ *   structured `parts` tree
+ * @throws {LexerError} On an invalid character
+ * @throws {ParseError} On invalid syntax
+ * @throws {EvaluatorError} On a limit breach or an impossible expression
+ * @throws {RollParserError} `INVALID_EVALUATION_LIMIT` when a supplied limit is
+ *   not an integer in range — raised before any die is rolled
+ * @throws {RollParserError} `INVALID_NOTATION_TYPE` when `notation` is not a
+ *   string, so `isRollParserError` still filters untrusted input completely
  *
  * @example
  * ```typescript
+ * import { roll } from 'roll-parser';
+ *
  * // Random roll
- * const result = roll('2d6+3');
- * console.log(result.total); // 5-15
+ * roll('2d6+3').total; // 5..15
+ *
+ * // Seeded — same seed, same sequence
+ * roll('2d6+3', { seed: 'demo' }).rendered; // '2d6[1, 6] + 3 = 10'
+ * roll('2d6+3', { seed: 'demo' }).total; // 10
+ * ```
  *
- * // Seeded for reproducibility
- * const r1 = roll('4d6', { seed: 'test' });
- * const r2 = roll('4d6', { seed: 'test' });
- * r1.total === r2.total; // true
+ * @example Deterministic tests with the testing mock
+ * ```typescript
+ * import { roll } from 'roll-parser';
+ * import { createMockRng } from 'roll-parser/testing';
  *
- * // Custom RNG for testing
- * const result = roll('1d20', { rng: createMockRng([15]) });
- * result.total; // 15
+ * const result = roll('4d6kh3', { rng: createMockRng([3, 6, 2, 5]) });
+ * result.total; // 14
+ * result.rendered; // '4d6[3, 6, ~~2~~, 5] = 14'
  * ```
+ *
+ * @category Core
  */
 export function roll(notation: string, options: RollOptions = {}): RollResult {
-  const rng = options.rng ?? new SeededRNG(options.seed);
-  const tokens = lex(notation);
-  const ast = new Parser(tokens).parse();
-  const evalOptions: EvaluateOptions = { notation };
-  if (options.maxDice != null) evalOptions.maxDice = options.maxDice;
-  if (options.maxExplodeIterations != null) {
-    evalOptions.maxExplodeIterations = options.maxExplodeIterations;
-  }
-  if (options.maxRerollIterations != null) {
-    evalOptions.maxRerollIterations = options.maxRerollIterations;
-  }
-  return evaluate(ast, rng, evalOptions);
+  // Explicitly-undefined limit keys forward harmlessly — `evaluate` nullish-checks each.
+  const { rng, seed, ...limits } = options;
+
+  return evaluate(parse(notation), rng ?? new SeededRNG(seed), { ...limits, notation });
 }

package/src/testing.ts

@@ -1,16 +1,12 @@
 /**
  * Test utilities for roll-parser consumers.
  *
- * Import from `roll-parser/testing` for deterministic dice testing.
+ * Import from `roll-parser/testing` for deterministic dice testing. The full
+ * TSDoc lives on the implementations in `./rng/mock.ts`; this entry point is
+ * a plain re-export barrel.
  *
  * @module testing
  */
 
-// Direct value exports force the bundler to inline the code
-import {
-  MockRNGExhaustedError as _MockRNGExhaustedError,
-  createMockRng as _createMockRng,
-} from './rng/mock';
-
-export const createMockRng = _createMockRng;
-export const MockRNGExhaustedError = _MockRNGExhaustedError;
+export { createMockRng, MockRNGExhaustedError } from './rng/mock.js';
+export type { RNG } from './rng/types.js';

package/src/types.ts

@@ -4,33 +4,121 @@
  * @module types
  */
 
-import type { ASTNode } from './parser/ast';
+import type { ASTNode } from './parser/ast.js';
 
 /**
- * Comparison operator for compare points.
+ * Comparison operator for compare points. Spelled exactly as it appears in
+ * notation — `4d6!>=5` carries `'>='`, bare `f1` normalizes to `'='`.
+ *
+ * @category AST
  */
 export type CompareOp = '>' | '>=' | '<' | '<=' | '=';
 
 /**
- * A comparison threshold used by exploding dice, reroll, and success counting.
+ * A comparison threshold used by exploding dice, reroll, success counting, and
+ * crit-threshold overrides.
+ *
+ * The value is an {@link ASTNode} to support computed thresholds
+ * (`1d6!>(1d2+3)`), matching the pattern used by `DiceNode.count` and
+ * `DiceNode.sides`. The evaluated counterpart is {@link ResolvedComparePoint}.
  *
- * The value is an ASTNode to support computed thresholds (e.g., `>=ceil(5)`),
- * matching the pattern used by DiceNode.count and DiceNode.sides.
+ * @category AST
  */
 export type ComparePoint = {
-  operator: CompareOp;
-  value: ASTNode;
+  readonly operator: CompareOp;
+  readonly value: ASTNode;
+};
+
+/**
+ * A {@link ComparePoint} whose value has been evaluated to a number. Used
+ * throughout {@link RollPart}, where meta-expressions are already resolved —
+ * `1d6!>(1d2+3)` surfaces as `{ operator: '>', value: 5 }`.
+ *
+ * @category Results
+ */
+export type ResolvedComparePoint = {
+  readonly operator: CompareOp;
+  readonly value: number;
 };
 
 /**
- * Modifier flags applied to individual die results.
+ * A resolved crit threshold — `'default'` means the per-die default rule
+ * (`result === sides` for critical, `result === 1` for fumble), which is what
+ * bare `cs` / `cf` produce.
+ *
+ * @category Results
+ */
+export type ResolvedCritThreshold = ResolvedComparePoint | 'default';
+
+/**
+ * Tags attached to a {@link DieResult} by the evaluator. A die can carry more
+ * than one (an exploded die that was later dropped is `['dropped',
+ * 'exploded']`), and the set drives the markers in `RollResult.rendered`.
+ *
+ * | Tag | Meaning | Rendered as |
+ * |-----|---------|-------------|
+ * | `'kept'` | Counted toward the total. Every non-dropped die carries it. | plain |
+ * | `'dropped'` | Excluded from the total by `kh`/`kl`/`dh`/`dl` or group selection. | `~~n~~` |
+ * | `'exploded'` | Produced by, or the trigger of, an explosion (`!`, `!!`, `!p`). | plain |
+ * | `'rerolled'` | A discarded intermediate from `r` / `ro`, always paired with `'dropped'` — the replacement die carries no tag. | `~~n~~` (via `'dropped'`) |
+ * | `'min'` | Raised to a `minN` bound; `initialResult` keeps the raw face. | plain |
+ * | `'max'` | Lowered to a `maxN` bound; `initialResult` keeps the raw face. | plain |
+ * | `'success'` | Met a success-count threshold (`>=6`). | `**n**` |
+ * | `'failure'` | Met a failure threshold (`f1`). | `__n__` |
+ * | `'meta'` | Rolled by a meta-expression rather than by the visible pool. | not shown |
+ * | `'dc'` | The DC side of a `vs` comparison. Never part of the roll-side pool. | plain |
+ *
+ * `'meta'` is the one tag with no counterpart in the notation. Dice counts,
+ * sides, modifier counts and computed thresholds may themselves be dice
+ * (`(1d4)d6`, `4d6kh(1d2)`, `1d6!>(1d2+3)`). Those inner dice are not part of
+ * any pool, so they never appear in a {@link RollPart}; they are appended to
+ * `RollResult.rolls` tagged `'meta'` so an audit log can still show what the
+ * meta-expression rolled. Filter them out when summing or displaying a pool.
+ *
+ * `'dc'` marks the DC side of a `vs` comparison. Unlike `'meta'` these dice do
+ * render — `1d20[3] vs 2d10[5, 6]` shows both sides — but they are not part of
+ * the roll-side pool, so no modifier may sum, select, clamp, reroll, explode,
+ * or tally them. Filter them out when summing a pool, exactly as with `'meta'`.
+ *
+ * @category Results
  */
-export type DieModifier = 'dropped' | 'kept' | 'exploded' | 'rerolled' | 'success' | 'failure';
+export type DieModifier =
+  | 'dropped'
+  | 'kept'
+  | 'exploded'
+  | 'rerolled'
+  | 'min'
+  | 'max'
+  | 'success'
+  | 'failure'
+  | 'meta'
+  | 'dc';
 
 /**
  * PF2e Degree of Success. Produced by the `vs` operator when comparing a
  * roll against a Difficulty Class. Ordering is significant — natural 20
  * upgrades one step and natural 1 downgrades one step.
+ *
+ * Numeric by design: the enum members are plain numbers, so `--json` CLI
+ * output and `JSON.stringify` emit `0`–`3` and comparisons like
+ * `degree >= DegreeOfSuccess.Success` work.
+ *
+ * @example
+ * ```typescript
+ * import { DegreeOfSuccess, roll } from 'roll-parser';
+ * import { createMockRng } from 'roll-parser/testing';
+ *
+ * const result = roll('1d20+7 vs 15', { rng: createMockRng([12]) });
+ * result.degree; // DegreeOfSuccess.Success (2)
+ * result.natural; // 12 — the raw d20 face, used for the ±1 step
+ * result.rendered; // '1d20[12] + 7 vs 15 = Success'
+ *
+ * if (result.degree != null && result.degree >= DegreeOfSuccess.Success) {
+ *   // hit
+ * }
+ * ```
+ *
+ * @category Results
  */
 export enum DegreeOfSuccess {
   CriticalFailure = 0,
@@ -40,7 +128,25 @@ export enum DegreeOfSuccess {
 }
 
 /**
- * Individual die roll result with metadata.
+ * One physical die and everything the evaluator learned about it.
+ *
+ * The same object is shared between `RollResult.rolls` and the `rolls[]` of
+ * the {@link RollPart} that produced it — there is no deep clone, so mutating
+ * a die is visible through both views.
+ *
+ * @example
+ * ```typescript
+ * import { roll } from 'roll-parser';
+ * import { createMockRng } from 'roll-parser/testing';
+ *
+ * const result = roll('4d6kh3', { rng: createMockRng([3, 6, 2, 5]) });
+ * result.rolls[1];
+ * // { sides: 6, result: 6, modifiers: ['kept'], critical: true, fumble: false }
+ * result.rolls[2];
+ * // { sides: 6, result: 2, modifiers: ['dropped'], critical: false, fumble: false }
+ * ```
+ *
+ * @category Results
  */
 export type DieResult = {
   /**
@@ -51,6 +157,13 @@ export type DieResult = {
   sides: number;
   /** The rolled value */
   result: number;
+  /**
+   * Raw first roll before any mutation (e.g., compound-explode accumulation).
+   * Only populated when `result` has been overwritten with a computed value.
+   * Consumers that need the original face (nat-20 / nat-1 detection) should
+   * read `initialResult ?? result`.
+   */
+  initialResult?: number;
   /** Modifiers applied to this die */
   modifiers: DieModifier[];
   /** True if rolled the maximum value (always false for Fate dice) */
@@ -60,9 +173,218 @@ export type DieResult = {
 };
 
 /**
- * Complete roll result with all metadata.
+ * One entry inside a flattened keep/drop chain. Counts are resolved at
+ * evaluation time (meta-expressions like `kh(1d2)` become the rolled number).
+ *
+ * Chained keep/drop modifiers flatten into one list — `4d6kh3dl1` yields two
+ * specs against a single pool, each applied independently, with drop sets
+ * unioned (Roll20 semantics).
+ *
+ * @category Results
+ */
+export type KeepDropSpec = {
+  readonly kind: 'keep' | 'drop';
+  readonly selector: 'highest' | 'lowest';
+  readonly count: number;
+};
+
+/**
+ * Fields shared by every {@link RollPart} variant. `start`/`end` mirror the
+ * source span of the AST node the part was evaluated from — present whenever
+ * the AST came from `parse()`, absent on hand-built ASTs.
+ *
+ * Useful for code that walks the parts tree generically: any part can be
+ * narrowed to this shape without switching on `type` first.
+ *
+ * @category Results
  */
-export type RollResult = {
+export type RollPartBase = {
+  /** Sub-total this part contributed to its parent. */
+  total: number;
+  start?: number;
+  end?: number;
+};
+
+/**
+ * Structured breakdown of an evaluated expression, mirroring the AST 1:1 —
+ * every ASTNode produces exactly one RollPart. Discriminants are lowercase
+ * camelCase to distinguish evaluation-tree types from `ASTNode.type`
+ * (PascalCase) at a glance.
+ *
+ * Invariants:
+ * - `RollResult.parts.total === RollResult.total`.
+ * - `successCount.total === successes - failures`.
+ * - `literal.total === value` and `variable.total === value`.
+ * - Each part's `rolls[]` shares `DieResult` references with
+ *   `RollResult.rolls[]`; both reflect post-evaluation state (explode
+ *   accumulation, reroll flags, keep/drop flags). No deep clone.
+ *
+ * Meta-expression sub-trees (`4d6kh(1d2)`, `(1+1)d6` counts/sides, computed
+ * thresholds) are not surfaced as nested parts — their resolved numbers
+ * appear in the owning part, and their dice are inspectable in
+ * `RollResult.rolls` via the `'meta'` modifier tag.
+ *
+ * @example Walking the tree with an exhaustive switch
+ * ```typescript
+ * import type { RollPart } from 'roll-parser';
+ *
+ * function describe(part: RollPart): string {
+ *   switch (part.type) {
+ *     case 'literal':
+ *       return String(part.value);
+ *     case 'variable':
+ *       return `@${part.name}`;
+ *     case 'dice':
+ *       return `${part.count}d${part.sides}[${part.rolls.map((d) => d.result).join(', ')}]`;
+ *     case 'fateDice':
+ *       return `${part.count}dF`;
+ *     case 'grouped':
+ *       return `(${describe(part.inner)})`;
+ *     case 'binaryOp':
+ *       return `${describe(part.left)} ${part.operator} ${describe(part.right)}`;
+ *     case 'unaryOp':
+ *       return `-${describe(part.operand)}`;
+ *     case 'keepDrop':
+ *       return `${describe(part.target)} [${part.specs.length} keep/drop]`;
+ *     case 'explode':
+ *       return `${describe(part.target)} (${part.variant} explode)`;
+ *     case 'reroll':
+ *       return `${describe(part.target)} (reroll${part.once ? ' once' : ''})`;
+ *     case 'dieBound':
+ *       return `${describe(part.target)} (${part.bound} ${part.value})`;
+ *     case 'successCount':
+ *       return `${describe(part.target)} => ${part.successes}-${part.failures}`;
+ *     case 'versus':
+ *       return `${describe(part.roll)} vs ${describe(part.dc)}`;
+ *     case 'functionCall':
+ *       return `${part.name}(${part.args.map(describe).join(', ')})`;
+ *     case 'group':
+ *       return `{${part.parts.map(describe).join(', ')}}`;
+ *     case 'sort':
+ *       return `${describe(part.target)} (${part.order})`;
+ *     case 'critThreshold':
+ *       return `${describe(part.target)} (crit override)`;
+ *   }
+ * }
+ * ```
+ *
+ * @example Reading a concrete tree
+ * ```typescript
+ * import { roll } from 'roll-parser';
+ * import { createMockRng } from 'roll-parser/testing';
+ *
+ * const result = roll('4d6kh3 + 2', { rng: createMockRng([3, 6, 2, 5]) });
+ * result.parts.type; // 'binaryOp'
+ * result.parts.total; // 16 — always equal to result.total
+ * describe(result.parts); // '4d6[3, 6, 2, 5] [1 keep/drop] + 2'
+ * ```
+ *
+ * @category Results
+ */
+export type RollPart =
+  | (RollPartBase & { type: 'literal'; value: number })
+  | (RollPartBase & { type: 'variable'; name: string; value: number })
+  | (RollPartBase & { type: 'dice'; count: number; sides: number; rolls: DieResult[] })
+  | (RollPartBase & { type: 'fateDice'; count: number; rolls: DieResult[] })
+  | (RollPartBase & { type: 'grouped'; inner: RollPart })
+  | (RollPartBase & {
+      type: 'binaryOp';
+      operator: '+' | '-' | '*' | '/' | '%' | '**';
+      left: RollPart;
+      right: RollPart;
+    })
+  | (RollPartBase & { type: 'unaryOp'; operator: '-'; operand: RollPart })
+  | (RollPartBase & { type: 'keepDrop'; specs: KeepDropSpec[]; target: RollPart })
+  | (RollPartBase & {
+      type: 'explode';
+      variant: 'standard' | 'compound' | 'penetrating';
+      threshold?: ResolvedComparePoint;
+      target: RollPart;
+    })
+  | (RollPartBase & {
+      type: 'reroll';
+      once: boolean;
+      condition: ResolvedComparePoint;
+      target: RollPart;
+    })
+  | (RollPartBase & { type: 'dieBound'; bound: 'min' | 'max'; value: number; target: RollPart })
+  | (RollPartBase & {
+      type: 'successCount';
+      threshold: ResolvedComparePoint;
+      failThreshold?: ResolvedComparePoint;
+      target: RollPart;
+      successes: number;
+      failures: number;
+    })
+  | (RollPartBase & { type: 'versus'; roll: RollPart; dc: RollPart; degree: DegreeOfSuccess })
+  | (RollPartBase & { type: 'functionCall'; name: string; args: RollPart[] })
+  | (RollPartBase & { type: 'group'; parts: RollPart[]; keptIndices?: number[] })
+  | (RollPartBase & {
+      type: 'sort';
+      order: 'ascending' | 'descending';
+      /**
+       * Every die the target produced, in sorted order, sharing `DieResult`
+       * references with `target` — so flags set after the sort (`4d6s dl1`)
+       * show through both. Like `RollResult.rolls` it keeps `'meta'` dice,
+       * which `rendered` omits from the bracket.
+       */
+      rolls: DieResult[];
+      target: RollPart;
+    })
+  | (RollPartBase & {
+      type: 'critThreshold';
+      successThresholds: ResolvedCritThreshold[];
+      failThresholds: ResolvedCritThreshold[];
+      target: RollPart;
+    });
+
+/**
+ * The 17 discriminant strings of {@link RollPart}. Convenience alias for
+ * consumers writing exhaustive switches or part-type lookup tables.
+ *
+ * @category Results
+ */
+export type RollPartType = RollPart['type'];
+
+/**
+ * Complete roll result with all metadata — what {@link roll} and
+ * {@link evaluate} return.
+ *
+ * The top level is `Readonly` — a result describes one completed evaluation
+ * and is never re-targeted. The `rolls` array and the `parts` tree stay
+ * mutable so consumers can annotate or re-sort their own views.
+ *
+ * Fully JSON-serializable; this is exactly what the CLI's `--json` flag emits.
+ *
+ * @example
+ * ```typescript
+ * import { roll } from 'roll-parser';
+ * import { createMockRng } from 'roll-parser/testing';
+ *
+ * const result = roll('3d6', { rng: createMockRng([4, 2, 6]) });
+ *
+ * JSON.stringify(result);
+ * // {
+ * //   "total": 12,
+ * //   "notation": "3d6",
+ * //   "expression": "3d6",
+ * //   "rendered": "3d6[4, 2, 6] = 12",
+ * //   "rolls": [
+ * //     { "sides": 6, "result": 4, "modifiers": ["kept"], "critical": false, "fumble": false },
+ * //     { "sides": 6, "result": 2, "modifiers": ["kept"], "critical": false, "fumble": false },
+ * //     { "sides": 6, "result": 6, "modifiers": ["kept"], "critical": true,  "fumble": false }
+ * //   ],
+ * //   "parts": {
+ * //     "type": "dice", "count": 3, "sides": 6,
+ * //     "rolls": [ ...the same three objects... ],
+ * //     "total": 12, "start": 0, "end": 3
+ * //   }
+ * // }
+ * ```
+ *
+ * @category Results
+ */
+export type RollResult = Readonly<{
   /** Final computed total */
   total: number;
   /** Original input notation */
@@ -71,18 +393,28 @@ export type RollResult = {
   expression: string;
   /** Rendered result with individual rolls shown */
   rendered: string;
-  /** All individual die results */
+  /**
+   * All individual die results, in evaluation order.
+   *
+   * Shares `DieResult` object references with the `rolls[]` arrays inside
+   * `parts` — no deep clone. Mutating a die here is visible through the part
+   * tree and vice versa; clone first if that matters.
+   */
   rolls: DieResult[];
+  /** Structured breakdown of the evaluated expression, mirroring the AST 1:1. */
+  parts: RollPart;
   /**
    * Number of dice tagged as success across the whole expression. Present
    * only when a success-counting modifier was used. Independent of `total` —
-   * arithmetic on top of a success count (e.g. `5d6>=5 * 2`) affects `total`
-   * but not `successes`.
+   * arithmetic on top of a success count (e.g. `{5d6>=5}+2`) affects `total`
+   * but not `successes`. Success counts are terminal, so the group braces are
+   * required: `5d6>=5 * 2` is an `INVALID_SUCCESS_COUNT_TARGET` parse error.
    */
   successes?: number;
   /**
    * Number of dice tagged as failure across the whole expression. Present
-   * only when a success-counting modifier with a fail threshold was used.
+   * whenever a success-counting modifier was used — `0` when no failure
+   * threshold was given, since nothing can be tagged as a failure.
    */
   failures?: number;
   /**
@@ -95,18 +427,78 @@ export type RollResult = {
    * exactly one kept d20 was rolled on the roll side of a `vs` expression.
    */
   natural?: number;
-};
+}>;
 
 /**
- * Options for the evaluate function.
+ * Evaluation guardrails and variable resolution, shared by `EvaluateOptions`
+ * and `RollOptions`. Every field is optional — the defaults bound adversarial
+ * notation without capping any realistic expression.
+ *
+ * Tighten them when the notation comes from users you do not control; the
+ * caps are the difference between a typed `EvaluatorError` and a request that
+ * rolls ten million dice. Parse depth is capped separately and
+ * unconditionally by {@link MAX_PARSE_DEPTH}.
+ *
+ * The three numeric limits fail closed: omit one — or pass `undefined` or
+ * `null`, the no-options path a partial config produces — and it takes its
+ * default, but supply anything else that is not a safe integer in range — a
+ * string, `NaN`, `±Infinity`, a negative, a fraction — and evaluation throws
+ * `INVALID_EVALUATION_LIMIT` before rolling. `maxDice` accepts `>= 1`, the two
+ * iteration limits `>= 0`. No coercion: `maxDice: Number(input)` on
+ * unparseable input rejects rather than quietly reverting to the permissive
+ * default.
+ *
+ * @example Untrusted input
+ * ```typescript
+ * import { isRollParserError, roll } from 'roll-parser';
+ *
+ * const limits = {
+ *   maxDice: 100,
+ *   maxExplodeIterations: 20,
+ *   maxRerollIterations: 20,
+ * };
+ *
+ * try {
+ *   roll('99999d6', limits).total;
+ * } catch (error) {
+ *   isRollParserError(error) && error.code; // 'DICE_LIMIT_EXCEEDED'
+ * }
+ * ```
+ *
+ * @example Variables
+ * ```typescript
+ * import { roll } from 'roll-parser';
+ *
+ * roll('1d20+@str', { context: { str: 4 }, seed: 'demo' }).total; // 5
+ * roll('1d20+@str', { onMissingVariable: 'zero', seed: 'demo' }).total; // 1
+ * ```
+ *
+ * @category Core
  */
-export type EvaluateOptions = {
-  /** Original notation string (for result metadata) */
-  notation?: string;
-  /** Maximum total dice allowed per evaluation (default: 10,000) */
+export type EvaluationOptions = {
+  /** Maximum total dice allowed per evaluation; integer >= 1 (default: 10,000) */
   maxDice?: number;
-  /** Maximum explosion iterations allowed per die (default: 1,000) */
+  /** Maximum explosion iterations allowed per die; integer >= 0 (default: 1,000) */
   maxExplodeIterations?: number;
-  /** Maximum reroll iterations allowed per die (default: 1,000) */
+  /** Maximum reroll iterations allowed per die; integer >= 0 (default: 1,000) */
   maxRerollIterations?: number;
+  /** Variable context for `@name` / `@{name}` references (default: empty) */
+  context?: Readonly<Record<string, number>>;
+  /** Behavior when a referenced variable is missing from context (default: 'throw') */
+  onMissingVariable?: 'throw' | 'zero';
+};
+
+/**
+ * Options for {@link evaluate}: the shared {@link EvaluationOptions} plus the
+ * original notation, which `evaluate` cannot recover from an AST.
+ *
+ * @category Core
+ */
+export type EvaluateOptions = EvaluationOptions & {
+  /**
+   * Original notation string, echoed back as `RollResult.notation`. When
+   * omitted, falls back to the normalized `expression` reconstructed from the
+   * AST — {@link roll} always forwards the string the caller typed.
+   */
+  notation?: string;
 };

package/src/version.ts

@@ -0,0 +1,2 @@
+// Generated by `bun run generate:version` from package.json — do not edit.
+export const version = '3.0.0';