roll-parser 3.0.0-alpha.0 → 3.0.0-beta.0

package/src/rng/index.ts

@@ -4,5 +4,5 @@
  * @module rng
  */
 
-export type { RNG } from './types';
-export { SeededRNG } from './seeded';
+export type { RNG } from './types.js';
+export { SeededRNG } from './seeded.js';

package/src/rng/mock.ts

@@ -4,7 +4,7 @@
  * @module rng/mock
  */
 
-import type { RNG } from './types';
+import type { RNG } from './types.js';
 
 /**
  * Error thrown when MockRNG exhausts its predefined values.

package/src/rng/seeded.ts

@@ -4,7 +4,7 @@
  * @module rng/seeded
  */
 
-import type { RNG } from './types';
+import type { RNG } from './types.js';
 
 /**
  * Seedable pseudo-random number generator using xorshift128.
@@ -114,6 +114,12 @@ export class SeededRNG implements RNG {
       return lo;
     }
 
+    // Ranges wider than 2^32 need two draws — a single uint32 can never
+    // produce the upper part of the range and would silently truncate it.
+    if (range > 0x100000000) {
+      return lo + this.nextBoundedWide(range);
+    }
+
     // Rejection sampling for unbiased distribution
     // Avoids modulo bias by rejecting values that would cause uneven distribution
     const threshold = (0x100000000 - range) % range;
@@ -124,4 +130,28 @@ export class SeededRNG implements RNG {
 
     return lo + (value % range);
   }
+
+  /**
+   * Unbiased sampling in `[0, range)` for ranges above 2^32, built from two
+   * uint32 draws combined into a 53-bit integer (the largest width JS numbers
+   * represent exactly). Ranges beyond 2^53 cannot be sampled without bias —
+   * throw instead of silently degrading.
+   */
+  private nextBoundedWide(range: number): number {
+    const MAX_53 = 2 ** 53;
+    if (range > MAX_53) {
+      throw new RangeError(`nextInt range ${range} exceeds 2^53 and cannot be sampled exactly`);
+    }
+
+    // Largest multiple of `range` below 2^53 — values at or above it are
+    // rejected to avoid modulo bias.
+    const limit = Math.floor(MAX_53 / range) * range;
+    let value: number;
+    do {
+      // 32 high bits shifted up by 21 + top 21 bits of a second draw = 53 bits.
+      value = this.nextUint32() * 0x200000 + (this.nextUint32() >>> 11);
+    } while (value >= limit);
+
+    return value % range;
+  }
 }

package/src/roll.ts

@@ -4,12 +4,12 @@
  * @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 type { RNG } from './rng/types.js';
+import type { EvaluateOptions, RollResult } from './types.js';
+import { evaluate } from './evaluator/evaluator.js';
+import { lex } from './lexer/lexer.js';
+import { Parser } from './parser/parser.js';
+import { SeededRNG } from './rng/seeded.js';
 
 /**
  * Options for the roll function.
@@ -25,6 +25,10 @@ export type RollOptions = {
   maxExplodeIterations?: number;
   /** Maximum reroll iterations allowed per die (default: 1,000) */
   maxRerollIterations?: number;
+  /** Variable context for `@name` / `@{name}` references (default: empty) */
+  context?: Record<string, number>;
+  /** Behavior when a referenced variable is missing from context (default: 'throw') */
+  onMissingVariable?: 'throw' | 'zero';
 };
 
 /**
@@ -62,5 +66,9 @@ export function roll(notation: string, options: RollOptions = {}): RollResult {
   if (options.maxRerollIterations != null) {
     evalOptions.maxRerollIterations = options.maxRerollIterations;
   }
+  if (options.context != null) evalOptions.context = options.context;
+  if (options.onMissingVariable != null) {
+    evalOptions.onMissingVariable = options.onMissingVariable;
+  }
   return evaluate(ast, rng, evalOptions);
 }

package/src/testing.ts

@@ -10,7 +10,7 @@
 import {
   MockRNGExhaustedError as _MockRNGExhaustedError,
   createMockRng as _createMockRng,
-} from './rng/mock';
+} from './rng/mock.js';
 
 export const createMockRng = _createMockRng;
 export const MockRNGExhaustedError = _MockRNGExhaustedError;

package/src/types.ts

@@ -4,7 +4,7 @@
  * @module types
  */
 
-import type { ASTNode } from './parser/ast';
+import type { ASTNode } from './parser/ast.js';
 
 /**
  * Comparison operator for compare points.
@@ -22,10 +22,32 @@ export type ComparePoint = {
   value: ASTNode;
 };
 
+/**
+ * A ComparePoint whose value has been evaluated to a number. Used in
+ * `RollPart` where meta-expressions are already resolved.
+ */
+export type ResolvedComparePoint = {
+  operator: CompareOp;
+  value: number;
+};
+
+/**
+ * A resolved crit threshold — `'default'` means the per-die default rule
+ * (`result === sides` for critical, `result === 1` for fumble).
+ */
+export type ResolvedCritThreshold = ResolvedComparePoint | 'default';
+
 /**
  * Modifier flags applied to individual die results.
  */
-export type DieModifier = 'dropped' | 'kept' | 'exploded' | 'rerolled' | 'success' | 'failure';
+export type DieModifier =
+  | 'dropped'
+  | 'kept'
+  | 'exploded'
+  | 'rerolled'
+  | 'success'
+  | 'failure'
+  | 'meta';
 
 /**
  * PF2e Degree of Success. Produced by the `vs` operator when comparing a
@@ -51,6 +73,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) */
@@ -59,6 +88,96 @@ export type DieResult = {
   fumble: boolean;
 };
 
+/**
+ * Per-spec keep/drop entry inside a flattened modifier chain. Counts are
+ * resolved at evaluation time (meta-expressions like `kh(1d2)` become the
+ * rolled number).
+ */
+export type ModifierSpec = {
+  kind: 'keep' | 'drop';
+  selector: 'highest' | 'lowest';
+  count: number;
+};
+
+/**
+ * Fields shared by every 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.
+ */
+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.
+ */
+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: 'modifier'; specs: ModifierSpec[]; target: RollPart })
+  | (RollPartBase & {
+      type: 'explode';
+      variant: 'standard' | 'compound' | 'penetrating';
+      threshold?: ResolvedComparePoint;
+      target: RollPart;
+    })
+  | (RollPartBase & {
+      type: 'reroll';
+      once: boolean;
+      condition: ResolvedComparePoint;
+      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'; target: RollPart })
+  | (RollPartBase & {
+      type: 'critThreshold';
+      successThresholds: ResolvedCritThreshold[];
+      failThresholds: ResolvedCritThreshold[];
+      target: RollPart;
+    });
+
+/** Convenience alias for consumers writing exhaustive switches. */
+export type RollPartType = RollPart['type'];
+
 /**
  * Complete roll result with all metadata.
  */
@@ -73,6 +192,8 @@ export type RollResult = {
   rendered: string;
   /** All individual die results */
   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` —
@@ -109,4 +230,8 @@ export type EvaluateOptions = {
   maxExplodeIterations?: number;
   /** Maximum reroll iterations allowed per die (default: 1,000) */
   maxRerollIterations?: number;
+  /** Variable context for `@name` / `@{name}` references (default: empty) */
+  context?: Record<string, number>;
+  /** Behavior when a referenced variable is missing from context (default: 'throw') */
+  onMissingVariable?: 'throw' | 'zero';
 };