roll-parser 2.3.2 → 3.0.0-beta.0

package/src/rng/index.ts

@@ -0,0 +1,8 @@
+/**
+ * RNG module - Seedable random number generation.
+ *
+ * @module rng
+ */
+
+export type { RNG } from './types.js';
+export { SeededRNG } from './seeded.js';

package/src/rng/mock.ts

@@ -0,0 +1,65 @@
+/**
+ * Mock RNG for deterministic testing.
+ *
+ * @module rng/mock
+ */
+
+import type { RNG } from './types.js';
+
+/**
+ * Error thrown when MockRNG exhausts its predefined values.
+ *
+ * This is intentional behavior to catch incorrect roll counts in tests.
+ * If you see this error, your test is consuming more random values than expected.
+ */
+export class MockRNGExhaustedError extends Error {
+  readonly consumed: number;
+
+  constructor(consumed: number) {
+    super(`MockRNG exhausted: consumed ${consumed} values, no more available`);
+    this.name = 'MockRNGExhaustedError';
+    this.consumed = consumed;
+  }
+}
+
+/**
+ * Creates a mock RNG that returns predefined values in sequence.
+ *
+ * IMPORTANT: Throws MockRNGExhaustedError when all values are consumed.
+ * This behavior catches incorrect roll counts in tests - it never wraps around.
+ *
+ * @param values - Array of values to return (dice results for nextInt, floats for next)
+ * @returns RNG instance returning predefined values
+ *
+ * @example
+ * ```typescript
+ * const rng = createMockRng([4, 2, 6]);
+ * rng.nextInt(1, 6);  // Returns 4
+ * rng.nextInt(1, 6);  // Returns 2
+ * rng.nextInt(1, 6);  // Returns 6
+ * rng.nextInt(1, 6);  // Throws MockRNGExhaustedError
+ * ```
+ */
+export function createMockRng(values: number[]): RNG {
+  let index = 0;
+
+  const getNext = (): number => {
+    const value = values[index];
+    if (value === undefined) {
+      throw new MockRNGExhaustedError(index);
+    }
+    index++;
+    return value;
+  };
+
+  return {
+    next: getNext,
+    nextInt: (min: number, max: number): number => {
+      const value = getNext();
+      if (value < min || value > max) {
+        throw new RangeError(`MockRNG value ${value} is out of bounds [${min}, ${max}]`);
+      }
+      return value;
+    },
+  };
+}

package/src/rng/seeded.ts

@@ -0,0 +1,157 @@
+/**
+ * Seedable RNG using xorshift128 algorithm.
+ *
+ * @module rng/seeded
+ */
+
+import type { RNG } from './types.js';
+
+/**
+ * Seedable pseudo-random number generator using xorshift128.
+ *
+ * Produces reproducible sequences from identical seeds.
+ * Period: 2^128 - 1
+ *
+ * @example
+ * ```typescript
+ * // Same seed = same sequence
+ * const rng1 = new SeededRNG('test-seed');
+ * const rng2 = new SeededRNG('test-seed');
+ * rng1.nextInt(1, 6) === rng2.nextInt(1, 6); // true
+ * ```
+ */
+export class SeededRNG implements RNG {
+  private s0: number;
+  private s1: number;
+  private s2: number;
+  private s3: number;
+
+  constructor(seed?: string | number) {
+    // Initialize state to zero, will be set by initState
+    this.s0 = 0;
+    this.s1 = 0;
+    this.s2 = 0;
+    this.s3 = 0;
+
+    this.initState(seed);
+
+    // Warm-up: discard first 20 values for better initial distribution
+    for (let i = 0; i < 20; i++) {
+      this.nextUint32();
+    }
+  }
+
+  private initState(seed?: string | number): void {
+    const numSeed =
+      seed == null
+        ? (Date.now() ^ (Math.random() * 0xffffffff)) >>> 0
+        : typeof seed === 'string'
+          ? this.hashString(seed)
+          : seed >>> 0;
+
+    // Split seed into 4 state values using splitmix32
+    let s = numSeed;
+    const state: number[] = [];
+
+    for (let i = 0; i < 4; i++) {
+      s = (s + 0x9e3779b9) >>> 0;
+      let z = s;
+      z = Math.imul(z ^ (z >>> 16), 0x85ebca6b) >>> 0;
+      z = Math.imul(z ^ (z >>> 13), 0xc2b2ae35) >>> 0;
+      state.push((z ^ (z >>> 16)) >>> 0);
+    }
+
+    this.s0 = state[0] ?? 0;
+    this.s1 = state[1] ?? 0;
+    this.s2 = state[2] ?? 0;
+    this.s3 = state[3] ?? 0;
+
+    // Ensure non-zero state (xorshift requires at least one non-zero)
+    if (this.s0 === 0 && this.s1 === 0 && this.s2 === 0 && this.s3 === 0) {
+      this.s0 = 1;
+    }
+  }
+
+  private hashString(str: string): number {
+    // djb2 hash algorithm
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+      hash = ((hash << 5) + hash + str.charCodeAt(i)) >>> 0;
+    }
+    return hash;
+  }
+
+  private nextUint32(): number {
+    // xorshift128 algorithm
+    let t = this.s3;
+    const s = this.s0;
+
+    this.s3 = this.s2;
+    this.s2 = this.s1;
+    this.s1 = s;
+
+    t ^= t << 11;
+    t ^= t >>> 8;
+    this.s0 = (t ^ s ^ (s >>> 19)) >>> 0;
+
+    return this.s0;
+  }
+
+  next(): number {
+    // Convert uint32 to [0, 1) float
+    return this.nextUint32() / 0x100000000;
+  }
+
+  nextInt(min: number, max: number): number {
+    // Handle inverted bounds
+    const lo = min > max ? max : min;
+    const hi = min > max ? min : max;
+
+    const range = hi - lo + 1;
+
+    // Single value case
+    if (range <= 1) {
+      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;
+    let value: number;
+    do {
+      value = this.nextUint32();
+    } while (value < threshold);
+
+    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/rng/types.ts

@@ -0,0 +1,25 @@
+/**
+ * Random Number Generator interface.
+ *
+ * All dice rolling MUST use this interface - never use Math.random() directly.
+ *
+ * @module rng/types
+ */
+
+/**
+ * Random Number Generator interface for dice rolling.
+ */
+export type RNG = {
+  /**
+   * Returns a random floating-point number in the range [0, 1).
+   */
+  next(): number;
+
+  /**
+   * Returns a random integer in the inclusive range [min, max].
+   *
+   * @param min - Minimum value (inclusive)
+   * @param max - Maximum value (inclusive)
+   */
+  nextInt(min: number, max: number): number;
+};

package/src/roll.ts

@@ -0,0 +1,74 @@
+/**
+ * Main public API for rolling dice expressions.
+ *
+ * @module roll
+ */
+
+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.
+ */
+export type RollOptions = {
+  /** Custom RNG instance (takes precedence over seed) */
+  rng?: RNG;
+  /** Seed for deterministic rolls (ignored if rng provided) */
+  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;
+  /** 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';
+};
+
+/**
+ * Parses and evaluates a dice notation string.
+ *
+ * @param notation - Dice notation (e.g., "2d6+3", "4d6kh3")
+ * @param options - Optional configuration (RNG or seed)
+ * @returns Complete roll result with total and metadata
+ *
+ * @example
+ * ```typescript
+ * // Random roll
+ * const result = roll('2d6+3');
+ * console.log(result.total); // 5-15
+ *
+ * // Seeded for reproducibility
+ * const r1 = roll('4d6', { seed: 'test' });
+ * const r2 = roll('4d6', { seed: 'test' });
+ * r1.total === r2.total; // true
+ *
+ * // Custom RNG for testing
+ * const result = roll('1d20', { rng: createMockRng([15]) });
+ * result.total; // 15
+ * ```
+ */
+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;
+  }
+  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

@@ -0,0 +1,16 @@
+/**
+ * Test utilities for roll-parser consumers.
+ *
+ * Import from `roll-parser/testing` for deterministic dice testing.
+ *
+ * @module testing
+ */
+
+// Direct value exports force the bundler to inline the code
+import {
+  MockRNGExhaustedError as _MockRNGExhaustedError,
+  createMockRng as _createMockRng,
+} from './rng/mock.js';
+
+export const createMockRng = _createMockRng;
+export const MockRNGExhaustedError = _MockRNGExhaustedError;

package/src/types.ts

@@ -0,0 +1,237 @@
+/**
+ * Shared type definitions for roll results and comparison primitives.
+ *
+ * @module types
+ */
+
+import type { ASTNode } from './parser/ast.js';
+
+/**
+ * Comparison operator for compare points.
+ */
+export type CompareOp = '>' | '>=' | '<' | '<=' | '=';
+
+/**
+ * A comparison threshold used by exploding dice, reroll, and success counting.
+ *
+ * The value is an ASTNode to support computed thresholds (e.g., `>=ceil(5)`),
+ * matching the pattern used by DiceNode.count and DiceNode.sides.
+ */
+export type ComparePoint = {
+  operator: CompareOp;
+  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'
+  | 'meta';
+
+/**
+ * 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.
+ */
+export enum DegreeOfSuccess {
+  CriticalFailure = 0,
+  Failure = 1,
+  Success = 2,
+  CriticalSuccess = 3,
+}
+
+/**
+ * Individual die roll result with metadata.
+ */
+export type DieResult = {
+  /**
+   * Number of sides on the die. Normal dice use `sides >= 1`. Fate/Fudge
+   * dice use `sides = 0` as a sentinel — they have no configurable sides
+   * and always produce results in {-1, 0, +1}.
+   */
+  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) */
+  critical: boolean;
+  /** True if rolled 1 (always false for Fate dice) */
+  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.
+ */
+export type RollResult = {
+  /** Final computed total */
+  total: number;
+  /** Original input notation */
+  notation: string;
+  /** Normalized expression */
+  expression: string;
+  /** Rendered result with individual rolls shown */
+  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` —
+   * arithmetic on top of a success count (e.g. `5d6>=5 * 2`) affects `total`
+   * but not `successes`.
+   */
+  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.
+   */
+  failures?: number;
+  /**
+   * PF2e Degree of Success. Present only when the expression used the `vs`
+   * operator at the top level (e.g. `1d20+10 vs 25`).
+   */
+  degree?: DegreeOfSuccess;
+  /**
+   * Natural d20 value used for PF2e upgrade/downgrade — present only when
+   * exactly one kept d20 was rolled on the roll side of a `vs` expression.
+   */
+  natural?: number;
+};
+
+/**
+ * Options for the evaluate function.
+ */
+export type EvaluateOptions = {
+  /** Original notation string (for result metadata) */
+  notation?: string;
+  /** 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;
+  /** 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';
+};

package/bin/help.txt

@@ -1,19 +0,0 @@
-Usage:
-  roll-parser [options] [<rolls>]
-
-Options:
-  --help  # Print the module options and usage
-
-Arguments:
-  rolls   # Whitespace separated list of roll (classic or WoD) notations.
-          If omitted, classic d20 roll will be used by default.
-          Use quotes on arguments if WoD notation is passed, to prevent problems
-          with special characters like '>'.
-          Classic: 2d20+1
-          World of Darkness: 6d10!>6f1
-
-Examples:
-  roll-parser 2d20+1
-  roll-parser 4d10 5d6-1 d100
-  roll-parser '6d10!>6f1'
-  roll-parser --help

package/bin/roll-parser.js

@@ -1,23 +0,0 @@
-#!/usr/bin/env node
-
-process.title = 'roll-parser';
-
-/* eslint-disable max-len, no-console, no-var, vars-on-top, prefer-spread, global-require, import/no-dynamic-require, wrap-iife, no-void */
-
-const argv = require( 'minimist' )( process.argv.slice( 2 ));
-const path = require( 'path' );
-const fs = require( 'fs' );
-
-const rollParser = require( '../index' );
-
-const format = roll => `${ rollParser.parseAndRoll( roll ) || 'Invalid roll notation.' }`;
-
-void function cmd() {
-  // --help
-  if ( argv.help ) {
-    fs.createReadStream( path.resolve( __dirname, './help.txt' )).pipe( process.stdout );
-  } else {
-    const rolls = argv._.length > 0 ? argv._ : [ 'd20' ];
-    rolls.forEach( roll => console.log( format( roll )));
-  }
-}();