roll-parser 2.3.2 → 3.0.0-alpha.0

package/dist/testing.js

@@ -0,0 +1,38 @@
+// src/rng/mock.ts
+class MockRNGExhaustedError extends Error {
+  consumed;
+  constructor(consumed) {
+    super(`MockRNG exhausted: consumed ${consumed} values, no more available`);
+    this.name = "MockRNGExhaustedError";
+    this.consumed = consumed;
+  }
+}
+function createMockRng(values) {
+  let index = 0;
+  const getNext = () => {
+    const value = values[index];
+    if (value === undefined) {
+      throw new MockRNGExhaustedError(index);
+    }
+    index++;
+    return value;
+  };
+  return {
+    next: getNext,
+    nextInt: (min, max) => {
+      const value = getNext();
+      if (value < min || value > max) {
+        throw new RangeError(`MockRNG value ${value} is out of bounds [${min}, ${max}]`);
+      }
+      return value;
+    }
+  };
+}
+
+// src/testing.ts
+var createMockRng2 = createMockRng;
+var MockRNGExhaustedError2 = MockRNGExhaustedError;
+export {
+  createMockRng2 as createMockRng,
+  MockRNGExhaustedError2 as MockRNGExhaustedError
+};

package/dist/testing.mjs

@@ -0,0 +1,39 @@
+// @bun
+// src/rng/mock.ts
+class MockRNGExhaustedError extends Error {
+  consumed;
+  constructor(consumed) {
+    super(`MockRNG exhausted: consumed ${consumed} values, no more available`);
+    this.name = "MockRNGExhaustedError";
+    this.consumed = consumed;
+  }
+}
+function createMockRng(values) {
+  let index = 0;
+  const getNext = () => {
+    const value = values[index];
+    if (value === undefined) {
+      throw new MockRNGExhaustedError(index);
+    }
+    index++;
+    return value;
+  };
+  return {
+    next: getNext,
+    nextInt: (min, max) => {
+      const value = getNext();
+      if (value < min || value > max) {
+        throw new RangeError(`MockRNG value ${value} is out of bounds [${min}, ${max}]`);
+      }
+      return value;
+    }
+  };
+}
+
+// src/testing.ts
+var createMockRng2 = createMockRng;
+var MockRNGExhaustedError2 = MockRNGExhaustedError;
+export {
+  createMockRng2 as createMockRng,
+  MockRNGExhaustedError2 as MockRNGExhaustedError
+};

package/dist/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 declare 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;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAE/F;;;;GAIG;AACH,oBAAY,eAAe;IACzB,eAAe,IAAI;IACnB,OAAO,IAAI;IACX,OAAO,IAAI;IACX,eAAe,IAAI;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;IAClB,oDAAoD;IACpD,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC"}

package/package.json

@@ -1,18 +1,40 @@
 {
   "name": "roll-parser",
-  "version": "2.3.2",
-  "description": "Parser for classic (2d6+1), simple (2 6 1), and WoD (4d10!>6f1) dice rolls.",
-  "main": "index.js",
-  "bin": "bin/roll-parser.js",
+  "version": "3.0.0-alpha.0",
+  "description": "High-performance dice notation parser for tabletop RPGs. TypeScript-first, Bun-optimized.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "bin": { "roll-parser": "./dist/cli.js" },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.mjs",
+      "require": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
   "keywords": [
     "parser",
     "dice",
     "roll",
     "rpg",
     "dnd",
-    "wod",
-    "random",
-    "d20"
+    "d20",
+    "pratt-parser",
+    "typescript",
+    "bun"
   ],
   "homepage": "https://github.com/edloidas/roll-parser#readme",
   "bugs": {
@@ -20,50 +42,47 @@
   },
   "license": "MIT",
   "author": "Mikita Taukachou <edloidas@gmail.com> (https://edloidas.com)",
-  "files": [
-    "index.js",
-    "bin",
-    "dist",
-    "src"
-  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/edloidas/roll-parser.git"
   },
-  "scripts": {
-    "test": "jest",
-    "cover": "jest --coverage",
-    "report": "node_modules/.bin/jest --coverage && cat coverage/lcov.info | node_modules/coveralls/bin/coveralls.js",
-    "fix": "eslint --fix .",
-    "api": "rimraf api/ && jsdoc -c .jsdocrc",
-    "clean": "rimraf dist/*",
-    "build:bundle": "browserify index.js --debug --standalone rollParser -o dist/roll-parser.js",
-    "build:minify": "babili dist/roll-parser.js --out-file dist/roll-parser.min.js",
-    "build": "npm run build:bundle && npm run build:minify",
-    "prepush": "npm test",
-    "prepublishOnly": "npm run fix && npm test && npm run clean && npm run build"
+  "publishConfig": {
+    "access": "public"
   },
-  "dependencies": {
-    "minimist": "^1.2.0"
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write .",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "check": "bun typecheck && bun lint && bun format:check",
+    "check:fix": "bun typecheck && bun lint:fix && bun format",
+    "check:version": "bun scripts/check-version.ts",
+    "check:changelog": "bun scripts/check-changelog.ts",
+    "clean": "rm -rf dist coverage",
+    "build": "bun run clean && bun run build:esm && bun run build:cjs && bun run build:esm:testing && bun run build:cjs:testing && bun run build:cli && bun run build:types",
+    "build:esm": "bun build src/index.ts --outfile dist/index.mjs --target bun",
+    "build:cjs": "bun build src/index.ts --outfile dist/index.js --target node",
+    "build:esm:testing": "bun build src/testing.ts --outfile dist/testing.mjs --target bun",
+    "build:cjs:testing": "bun build src/testing.ts --outfile dist/testing.js --target node",
+    "build:cli": "bun build src/cli/index.ts --outfile dist/cli.js --target node",
+    "build:types": "tsc --emitDeclarationOnly -p tsconfig.build.json",
+    "test": "bun test",
+    "test:node": "node -e \"import('./dist/index.mjs').then(m => { const r = m.roll('1d6'); if (!(r.total >= 1 && r.total <= 6)) throw new Error('ESM smoke failed: total=' + r.total); console.log('Node.js ESM smoke: ok'); })\" && node -e \"const m = require('./dist/index.js'); const r = m.roll('1d6'); if (!(r.total >= 1 && r.total <= 6)) throw new Error('CJS smoke failed: total=' + r.total); console.log('Node.js CJS smoke: ok');\"",
+    "test:watch": "bun test --watch",
+    "test:ci": "bun test --bail",
+    "validate": "bun run check && bun run build && bun test:ci",
+    "coverage": "bun test --coverage",
+    "release:dry": "bun run check:version && bun run check:changelog && bun run check && bun run build && bun test",
+    "prepublishOnly": "bun run release:dry"
   },
   "devDependencies": {
-    "babel-core": "^6.24.1",
-    "babel-preset-babili": "^0.1.2",
-    "babili": "^0.1.2",
-    "browserify": "^14.4.0",
-    "coveralls": "^2.13.1",
-    "docdash": "^0.4.0",
-    "eslint": "^3.19.0",
-    "eslint-config-airbnb-base": "^11.2.0",
-    "eslint-plugin-import": "^2.3.0",
-    "husky": "^0.13.4",
-    "istanbul": "^0.4.5",
-    "jest": "^20.0.4",
-    "jsdoc": "^3.4.3",
-    "rimraf": "^2.6.1"
+    "@biomejs/biome": "^2.4.9",
+    "@types/bun": "^1.3.0",
+    "fast-check": "^4.6.0",
+    "typescript": "^6.0.2"
   },
   "engines": {
-    "node": ">= 6.0.0",
-    "npm": ">= 3.8.6"
+    "node": ">= 22.0.0"
   }
 }

package/src/cli/args.ts

@@ -0,0 +1,72 @@
+/**
+ * CLI argument parser.
+ *
+ * Pure function that parses process.argv-style string arrays into typed options.
+ *
+ * @module cli/args
+ */
+
+/**
+ * Parsed CLI arguments.
+ */
+export type CliArgs = {
+  notation: string | undefined;
+  verbose: boolean;
+  seed: string | undefined;
+  showHelp: boolean;
+  showVersion: boolean;
+};
+
+/**
+ * Result of parsing CLI arguments — either success or a usage error.
+ */
+export type ParseArgsResult = { ok: true; args: CliArgs } | { ok: false; error: string };
+
+/**
+ * Parses a raw argument array into typed CLI options.
+ *
+ * @param argv - Arguments to parse (typically `process.argv.slice(2)`)
+ * @returns Parsed result or an error message for usage errors
+ */
+export function parseArgs(argv: string[]): ParseArgsResult {
+  let verbose = false;
+  let seed: string | undefined;
+  let showHelp = false;
+  let showVersion = false;
+  const positional: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i] as string;
+
+    if (arg === '--help' || arg === '-h') {
+      showHelp = true;
+    } else if (arg === '--version') {
+      showVersion = true;
+    } else if (arg === '--verbose' || arg === '-v') {
+      verbose = true;
+    } else if (arg === '--seed') {
+      const next = argv[i + 1];
+      if (next === undefined || (next.startsWith('-') && !/^-\d/.test(next))) {
+        return { ok: false, error: 'Missing value for --seed' };
+      }
+      seed = next;
+      i++;
+    } else if (arg.startsWith('--seed=')) {
+      const value = arg.slice('--seed='.length);
+      if (value === '') {
+        return { ok: false, error: 'Missing value for --seed' };
+      }
+      seed = value;
+    } else if (arg.startsWith('--')) {
+      return { ok: false, error: `Unknown option: ${arg}` };
+    } else if (arg.startsWith('-') && arg.length > 1 && !/^\d/.test(arg.slice(1))) {
+      return { ok: false, error: `Unknown option: ${arg}` };
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  const notation = positional.length > 0 ? positional.join(' ') : undefined;
+
+  return { ok: true, args: { notation, verbose, seed, showHelp, showVersion } };
+}

package/src/cli/format.ts

@@ -0,0 +1,45 @@
+/**
+ * CLI output formatting.
+ *
+ * Transforms RollResult into terminal-appropriate strings.
+ *
+ * @module cli/format
+ */
+
+import type { RollResult } from '../types';
+
+/**
+ * Formats a roll result for terminal display.
+ *
+ * In normal mode, returns just the total. In verbose mode, returns the
+ * rendered breakdown with terminal-safe formatting for dropped dice.
+ *
+ * @param result - The roll result to format
+ * @param verbose - Whether to show the detailed breakdown
+ * @returns Formatted string for terminal output
+ */
+export function formatResult(result: RollResult, verbose: boolean): string {
+  if (!verbose) {
+    return String(result.total);
+  }
+
+  return formatRendered(result.rendered);
+}
+
+/**
+ * Converts markdown-style dice markers to terminal-friendly forms.
+ *
+ * The evaluator uses markdown syntax in the rendered field:
+ *   `~~value~~` — dropped dice
+ *   `**value**` — dice counted as success
+ *   `__value__` — dice counted as failure
+ *
+ * For plain terminals these become `(value)`, `[value]`, and `{value}` so
+ * the per-die classification stays visible without any markup dependency.
+ */
+function formatRendered(rendered: string): string {
+  return rendered
+    .replace(/~~(-?\d+)~~/g, '($1)')
+    .replace(/\*\*(-?\d+)\*\*/g, '[$1]')
+    .replace(/__(-?\d+)__/g, '{$1}');
+}

package/src/cli/index.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for roll-parser.
+ *
+ * @module cli/index
+ */
+
+import { isRollParserError } from '../errors';
+import { VERSION } from '../index';
+import { roll } from '../roll';
+import { parseArgs } from './args';
+import { formatResult } from './format';
+
+const HELP_TEXT = `roll-parser v${VERSION}
+
+Usage: roll-parser <notation> [options]
+
+Options:
+  -h, --help       Show this help message
+  --version        Show version number
+  -v, --verbose    Show detailed roll breakdown
+  --seed <value>   Use seed for reproducible rolls
+
+Examples:
+  roll-parser 2d6+3
+  roll-parser 4d6kh3 --verbose
+  roll-parser 4d6dl1 --seed "character-str"
+`;
+
+function main(): void {
+  const parsed = parseArgs(process.argv.slice(2));
+
+  if (!parsed.ok) {
+    process.stderr.write(`Error: ${parsed.error}\n`);
+    process.stderr.write('Run "roll-parser --help" for usage.\n');
+    process.exitCode = 2;
+    return;
+  }
+
+  const { args } = parsed;
+
+  if (args.showHelp) {
+    process.stdout.write(HELP_TEXT);
+    return;
+  }
+
+  if (args.showVersion) {
+    process.stdout.write(`${VERSION}\n`);
+    return;
+  }
+
+  if (args.notation == null) {
+    process.stderr.write('Error: No dice notation provided.\n');
+    process.stderr.write('Run "roll-parser --help" for usage.\n');
+    process.exitCode = 2;
+    return;
+  }
+
+  try {
+    const options = args.seed != null ? { seed: args.seed } : {};
+    const result = roll(args.notation, options);
+    const output = formatResult(result, args.verbose);
+    process.stdout.write(`${output}\n`);
+  } catch (error) {
+    if (isRollParserError(error)) {
+      process.stderr.write(`Error: ${error.message}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  }
+}
+
+main();

package/src/errors.ts

@@ -0,0 +1,78 @@
+/**
+ * Common error base class and error codes for roll-parser.
+ *
+ * @module errors
+ */
+
+/**
+ * All known roll-parser error codes. Single source of truth — the
+ * `RollParserErrorCode` type and the runtime `VALID_CODES` set are
+ * both derived from this array.
+ *
+ * Lexer: `UNEXPECTED_CHARACTER`, `UNEXPECTED_IDENTIFIER`
+ * Parser: `UNEXPECTED_TOKEN`, `UNEXPECTED_END`, `EXPECTED_TOKEN`,
+ *   `INVALID_EXPLODE_TARGET`, `INVALID_SUCCESS_COUNT_TARGET`, `NESTED_VERSUS`,
+ *   `INVALID_FUNCTION_ARITY`
+ * Evaluator: `INVALID_DICE_COUNT`, `INVALID_DICE_SIDES`, `DICE_LIMIT_EXCEEDED`,
+ *   `DIVISION_BY_ZERO`, `MODULO_BY_ZERO`, `UNKNOWN_OPERATOR`, `UNKNOWN_NODE_TYPE`,
+ *   `INVALID_MODIFIER_COUNT`, `EXPLODE_LIMIT_EXCEEDED`, `REROLL_LIMIT_EXCEEDED`,
+ *   `INVALID_THRESHOLD`, `NESTED_VERSUS`, `UNKNOWN_FUNCTION`
+ */
+const ROLL_PARSER_ERROR_CODES = [
+  'UNEXPECTED_CHARACTER',
+  'UNEXPECTED_IDENTIFIER',
+  'UNEXPECTED_TOKEN',
+  'UNEXPECTED_END',
+  'EXPECTED_TOKEN',
+  'INVALID_DICE_COUNT',
+  'INVALID_DICE_SIDES',
+  'DICE_LIMIT_EXCEEDED',
+  'DIVISION_BY_ZERO',
+  'MODULO_BY_ZERO',
+  'UNKNOWN_OPERATOR',
+  'UNKNOWN_NODE_TYPE',
+  'INVALID_MODIFIER_COUNT',
+  'EXPLODE_LIMIT_EXCEEDED',
+  'INVALID_EXPLODE_TARGET',
+  'REROLL_LIMIT_EXCEEDED',
+  'INVALID_SUCCESS_COUNT_TARGET',
+  'INVALID_THRESHOLD',
+  'NESTED_VERSUS',
+  'INVALID_FUNCTION_ARITY',
+  'UNKNOWN_FUNCTION',
+] as const;
+
+export type RollParserErrorCode = (typeof ROLL_PARSER_ERROR_CODES)[number];
+
+/**
+ * Base error class for all roll-parser errors.
+ *
+ * Provides a typed `code` field for programmatic error handling.
+ * All library errors (`LexerError`, `ParseError`, `EvaluatorError`)
+ * extend this class.
+ */
+export class RollParserError extends Error {
+  readonly code: RollParserErrorCode;
+
+  constructor(message: string, code: RollParserErrorCode) {
+    super(message);
+    this.name = 'RollParserError';
+    this.code = code;
+  }
+}
+
+const VALID_CODES: Set<string> = new Set<string>(ROLL_PARSER_ERROR_CODES);
+
+/**
+ * Type guard for roll-parser errors. Checks `instanceof` first, then
+ * falls back to duck-typing for cross-realm safety.
+ */
+export function isRollParserError(value: unknown): value is RollParserError {
+  if (value instanceof RollParserError) return true;
+  return (
+    value instanceof Error &&
+    'code' in value &&
+    typeof (value as RollParserError).code === 'string' &&
+    VALID_CODES.has((value as RollParserError).code)
+  );
+}