roll-parser 2.3.2 → 3.0.0-alpha.0

package/src/rng/mock.ts

@@ -0,0 +1,65 @@
+/**
+ * Mock RNG for deterministic testing.
+ *
+ * @module rng/mock
+ */
+
+import type { RNG } from './types';
+
+/**
+ * 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,127 @@
+/**
+ * Seedable RNG using xorshift128 algorithm.
+ *
+ * @module rng/seeded
+ */
+
+import type { RNG } from './types';
+
+/**
+ * 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;
+    }
+
+    // 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);
+  }
+}

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,66 @@
+/**
+ * Main public API for rolling dice expressions.
+ *
+ * @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';
+
+/**
+ * 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;
+};
+
+/**
+ * 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;
+  }
+  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';
+
+export const createMockRng = _createMockRng;
+export const MockRNGExhaustedError = _MockRNGExhaustedError;

package/src/types.ts

@@ -0,0 +1,112 @@
+/**
+ * Shared type definitions for roll results and comparison primitives.
+ *
+ * @module types
+ */
+
+import type { ASTNode } from './parser/ast';
+
+/**
+ * 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;
+};
+
+/**
+ * Modifier flags applied to individual die results.
+ */
+export type DieModifier = 'dropped' | 'kept' | 'exploded' | 'rerolled' | 'success' | 'failure';
+
+/**
+ * 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;
+  /** 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;
+};
+
+/**
+ * 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[];
+  /**
+   * 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;
+};

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 )));
-  }
-}();