roll-parser 3.0.0-alpha.0 → 3.0.0

package/dist/roll.d.ts

@@ -3,45 +3,79 @@
  *
  * @module roll
  */
-import type { RNG } from './rng/types';
-import type { RollResult } from './types';
+import type { RNG } from './rng/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;
 };
 /**
- * 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,aAAa,CAAC;AACvC,OAAO,KAAK,EAAmB,UAAU,EAAE,MAAM,SAAS,CAAC;AAM3D;;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;CAC9B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,UAAU,CAa5E"}
+{"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';
-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,YAAY,CAAC;AAEpB,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,38 +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
-};
+export { createMockRng, MockRNGExhaustedError } from './rng/mock.js';
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC"}