roll-parser 3.0.0-beta.0 → 3.0.0

package/dist/roll.d.ts

@@ -4,48 +4,78 @@
  * @module roll
  */
 import type { RNG } from './rng/types.js';
-import type { RollResult } from './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;
-    /** 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.
+ * Parses and evaluates a dice notation string in one call — the main entry
+ * point of the library.
  *
- * @param notation - Dice notation (e.g., "2d6+3", "4d6kh3")
- * @param options - Optional configuration (RNG or seed)
- * @returns Complete roll result with total and metadata
+ * 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'` 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 declare function roll(notation: string, options?: RollOptions): RollResult;
 //# sourceMappingURL=roll.d.ts.map

package/dist/roll.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"roll.d.ts","sourceRoot":"","sources":["../src/roll.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAAmB,UAAU,EAAE,MAAM,YAAY,CAAC;AAM9D;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,uDAAuD;IACvD,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,qFAAqF;IACrF,iBAAiB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACtC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,UAAU,CAiB5E"}
+{"version":3,"file":"roll.d.ts","sourceRoot":"","sources":["../src/roll.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEhE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG;IAC5C;;;OAGG;IACH,GAAG,CAAC,EAAE,GAAG,CAAC;IACV;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,UAAU,CAK5E"}

package/dist/roll.js

@@ -0,0 +1,8 @@
+import { evaluate } from './evaluator/evaluator.js';
+import { parse } from './parser/parser.js';
+import { SeededRNG } from './rng/seeded.js';
+export function roll(notation, options = {}) {
+    const { rng, seed, ...limits } = options;
+    return evaluate(parse(notation), rng ?? new SeededRNG(seed), { ...limits, notation });
+}
+//# sourceMappingURL=roll.js.map

package/dist/roll.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roll.js","sourceRoot":"","sources":["../src/roll.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AA6E5C,MAAM,UAAU,IAAI,CAAC,QAAgB,EAAE,OAAO,GAAgB,EAAE;IAE9D,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IAEzC,OAAO,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,GAAG,IAAI,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;AACxF,CAAC"}

package/dist/testing.d.ts

@@ -1,11 +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
  */
-import { MockRNGExhaustedError as _MockRNGExhaustedError, createMockRng as _createMockRng } from './rng/mock.js';
-export declare const createMockRng: typeof _createMockRng;
-export declare const MockRNGExhaustedError: typeof _MockRNGExhaustedError;
+export { createMockRng, MockRNGExhaustedError } from './rng/mock.js';
+export type { RNG } from './rng/types.js';
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,qBAAqB,IAAI,sBAAsB,EAC/C,aAAa,IAAI,cAAc,EAChC,MAAM,eAAe,CAAC;AAEvB,eAAO,MAAM,aAAa,uBAAiB,CAAC;AAC5C,eAAO,MAAM,qBAAqB,+BAAyB,CAAC"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACrE,YAAY,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/testing.js

@@ -1,41 +1,2 @@
-// 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
-};
-
-//# debugId=916ECEA68894E64864756E2164756E21
-//# sourceMappingURL=testing.js.map
+export { createMockRng, MockRNGExhaustedError } from './rng/mock.js';
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -1,11 +1 @@
-{
-  "version": 3,
-  "sources": ["../src/rng/mock.ts", "../src/testing.ts"],
-  "sourcesContent": [
-    "/**\n * Mock RNG for deterministic testing.\n *\n * @module rng/mock\n */\n\nimport type { RNG } from './types.js';\n\n/**\n * Error thrown when MockRNG exhausts its predefined values.\n *\n * This is intentional behavior to catch incorrect roll counts in tests.\n * If you see this error, your test is consuming more random values than expected.\n */\nexport class MockRNGExhaustedError extends Error {\n  readonly consumed: number;\n\n  constructor(consumed: number) {\n    super(`MockRNG exhausted: consumed ${consumed} values, no more available`);\n    this.name = 'MockRNGExhaustedError';\n    this.consumed = consumed;\n  }\n}\n\n/**\n * Creates a mock RNG that returns predefined values in sequence.\n *\n * IMPORTANT: Throws MockRNGExhaustedError when all values are consumed.\n * This behavior catches incorrect roll counts in tests - it never wraps around.\n *\n * @param values - Array of values to return (dice results for nextInt, floats for next)\n * @returns RNG instance returning predefined values\n *\n * @example\n * ```typescript\n * const rng = createMockRng([4, 2, 6]);\n * rng.nextInt(1, 6);  // Returns 4\n * rng.nextInt(1, 6);  // Returns 2\n * rng.nextInt(1, 6);  // Returns 6\n * rng.nextInt(1, 6);  // Throws MockRNGExhaustedError\n * ```\n */\nexport function createMockRng(values: number[]): RNG {\n  let index = 0;\n\n  const getNext = (): number => {\n    const value = values[index];\n    if (value === undefined) {\n      throw new MockRNGExhaustedError(index);\n    }\n    index++;\n    return value;\n  };\n\n  return {\n    next: getNext,\n    nextInt: (min: number, max: number): number => {\n      const value = getNext();\n      if (value < min || value > max) {\n        throw new RangeError(`MockRNG value ${value} is out of bounds [${min}, ${max}]`);\n      }\n      return value;\n    },\n  };\n}\n",
-    "/**\n * Test utilities for roll-parser consumers.\n *\n * Import from `roll-parser/testing` for deterministic dice testing.\n *\n * @module testing\n */\n\n// Direct value exports force the bundler to inline the code\nimport {\n  MockRNGExhaustedError as _MockRNGExhaustedError,\n  createMockRng as _createMockRng,\n} from './rng/mock.js';\n\nexport const createMockRng = _createMockRng;\nexport const MockRNGExhaustedError = _MockRNGExhaustedError;\n"
-  ],
-  "mappings": ";AAcO,MAAM,8BAA8B,MAAM;AAAA,EACtC;AAAA,EAET,WAAW,CAAC,UAAkB;AAAA,IAC5B,MAAM,+BAA+B,oCAAoC;AAAA,IACzE,KAAK,OAAO;AAAA,IACZ,KAAK,WAAW;AAAA;AAEpB;AAoBO,SAAS,aAAa,CAAC,QAAuB;AAAA,EACnD,IAAI,QAAQ;AAAA,EAEZ,MAAM,UAAU,MAAc;AAAA,IAC5B,MAAM,QAAQ,OAAO;AAAA,IACrB,IAAI,UAAU,WAAW;AAAA,MACvB,MAAM,IAAI,sBAAsB,KAAK;AAAA,IACvC;AAAA,IACA;AAAA,IACA,OAAO;AAAA;AAAA,EAGT,OAAO;AAAA,IACL,MAAM;AAAA,IACN,SAAS,CAAC,KAAa,QAAwB;AAAA,MAC7C,MAAM,QAAQ,QAAQ;AAAA,MACtB,IAAI,QAAQ,OAAO,QAAQ,KAAK;AAAA,QAC9B,MAAM,IAAI,WAAW,iBAAiB,2BAA2B,QAAQ,MAAM;AAAA,MACjF;AAAA,MACA,OAAO;AAAA;AAAA,EAEX;AAAA;;;ACjDK,IAAM,iBAAgB;AACtB,IAAM,yBAAwB;",
-  "debugId": "916ECEA68894E64864756E2164756E21",
-  "names": []
-}
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}