roll-parser 3.0.0-beta.0 → 3.1.0

package/src/index.ts

@@ -4,31 +4,45 @@
  * @module roll-parser
  */
 
-// * Error hierarchy
-export { RollParserError, isRollParserError } from './errors.js';
-export type { RollParserErrorCode } from './errors.js';
+import { version } from './version.js';
 
-// * Lexer exports
-export { LexerError } from './lexer/lexer.js';
-
-// * Parser exports
-export { parse, ParseError } from './parser/parser.js';
+export type { ErrorSpan, NotationErrorCode, RollParserErrorCode } from './errors.js';
+export {
+  getErrorSpan,
+  isNotationError,
+  isRollParserError,
+  NOTATION_ERROR_CODES,
+  ROLL_PARSER_ERROR_CODES,
+  RollParserError,
+} from './errors.js';
+export {
+  DEFAULT_MAX_DICE,
+  DEFAULT_MAX_EXPLODE_ITERATIONS,
+  DEFAULT_MAX_REROLL_ITERATIONS,
+  EvaluatorError,
+  evaluate,
+} from './evaluator/evaluator.js';
+export { LexerError, lex } from './lexer/lexer.js';
+export type { Token } from './lexer/tokens.js';
+export { TokenType } from './lexer/tokens.js';
 export type {
   ASTNode,
   BinaryOpNode,
+  CritThreshold,
+  CritThresholdNode,
   DiceNode,
-  NodeSpan,
+  DieBoundNode,
   ExplodeNode,
   FateDiceNode,
   FunctionCallNode,
   GroupedNode,
+  GroupNode,
+  KeepDropNode,
   LiteralNode,
-  ModifierNode,
+  NodeSpan,
   RerollNode,
-  SuccessCountNode,
   SortNode,
-  CritThresholdNode,
-  GroupNode,
+  SuccessCountNode,
   UnaryOpNode,
   VariableNode,
   VersusNode,
@@ -37,13 +51,14 @@ export {
   isBinaryOp,
   isCritThreshold,
   isDice,
+  isDieBound,
   isExplode,
   isFateDice,
   isFunctionCall,
   isGroup,
   isGrouped,
+  isKeepDrop,
   isLiteral,
-  isModifier,
   isReroll,
   isSort,
   isSuccessCount,
@@ -51,40 +66,46 @@ export {
   isVariable,
   isVersus,
 } from './parser/ast.js';
-
-// * RNG exports
-export type { RNG } from './rng/types.js';
+export { MAX_PARSE_DEPTH, ParseError, parse } from './parser/parser.js';
+export type { RngState } from './rng/seeded.js';
 export { SeededRNG } from './rng/seeded.js';
-
-// * Evaluator exports
-export {
-  DEFAULT_MAX_DICE,
-  DEFAULT_MAX_EXPLODE_ITERATIONS,
-  DEFAULT_MAX_REROLL_ITERATIONS,
-  evaluate,
-  EvaluatorError,
-} from './evaluator/evaluator.js';
+export type { RNG } from './rng/types.js';
+export type { RollOptions } from './roll.js';
+export { roll } from './roll.js';
 export type {
   CompareOp,
   ComparePoint,
   DieModifier,
   DieResult,
   EvaluateOptions,
-  ModifierSpec,
+  EvaluationOptions,
+  KeepDropSpec,
   ResolvedComparePoint,
   ResolvedCritThreshold,
   RollPart,
+  RollPartBase,
   RollPartType,
   RollResult,
 } from './types.js';
 export { DegreeOfSuccess } from './types.js';
 
-// * Public API
-export { roll } from './roll.js';
-export type { RollOptions } from './roll.js';
-
-// ? Named import — Bun's bundler tree-shakes the JSON module down to the
-//   single used property, so the full manifest is not embedded in dist.
-import { version } from '../package.json';
-
+/**
+ * Installed roll-parser version — the exact string in `package.json`, so
+ * pre-releases keep their suffix (`'3.0.0-beta.0'`). Sourced from the
+ * generated `src/version.ts`, kept in sync with the manifest by
+ * `bun run generate:version` and gated by `check:version` and CI.
+ *
+ * Useful in bug reports and for feature-gating against a minimum version. The
+ * CLI prints it for `--version` and in the `--help` header.
+ *
+ * @example
+ * ```typescript
+ * import { VERSION } from 'roll-parser';
+ *
+ * VERSION; // e.g. '3.0.0', or '3.1.0-beta.0' on a pre-release
+ * VERSION.startsWith('3.'); // true
+ * ```
+ *
+ * @category Core
+ */
 export const VERSION: string = version;

package/src/lexer/lexer.ts

@@ -5,24 +5,72 @@
  */
 
 import type { RollParserErrorCode } from '../errors.js';
-import { RollParserError } from '../errors.js';
+import { describeValue, RollParserError } from '../errors.js';
 import { type Token, TokenType } from './tokens.js';
 
 /**
  * Error thrown when the lexer encounters an invalid character.
+ *
+ * `position` is a zero-based UTF-16 offset into the input. It is deliberately
+ * absent from `message` — read it from the field, or uniformly across all
+ * roll-parser errors via `getErrorSpan`.
+ *
+ * Codes: `UNEXPECTED_CHARACTER` for a character that cannot start any token,
+ * `UNEXPECTED_IDENTIFIER` for a word that is not a known keyword.
+ *
+ * @example
+ * ```typescript
+ * import { LexerError, roll } from 'roll-parser';
+ *
+ * try {
+ *   roll('2d6+&');
+ * } catch (error) {
+ *   const typed = error as LexerError;
+ *   typed.code; // 'UNEXPECTED_CHARACTER'
+ *   typed.character; // '&'
+ *   typed.position; // 4
+ * }
+ * ```
+ *
+ * @category Errors
  */
 export class LexerError extends RollParserError {
+  /** Zero-based UTF-16 offset of the offending character in the input. */
   readonly position: number;
+  /**
+   * The offending text — a single character for `UNEXPECTED_CHARACTER` (the
+   * whole code point, so astral symbols are not split into surrogates), or
+   * the unrecognized word for `UNEXPECTED_IDENTIFIER`.
+   */
   readonly character: string;
 
-  constructor(message: string, code: RollParserErrorCode, position: number, character: string) {
-    super(`${message} at position ${position}: '${character}'`, code);
+  constructor(
+    message: string,
+    code: RollParserErrorCode,
+    position: number,
+    character: string,
+    options?: ErrorOptions,
+  ) {
+    super(`${message}: '${character}'`, code, options);
     this.name = 'LexerError';
     this.position = position;
     this.character = character;
   }
 }
 
+//
+// * Character codes
+//
+
+// Range tests compare code units: `char.toLowerCase()` per character allocated
+// a string on the lexer's hottest loop.
+const CHAR_DIGIT_0 = 48;
+const CHAR_DIGIT_9 = 57;
+const CHAR_UPPER_A = 65;
+const CHAR_UPPER_Z = 90;
+const CHAR_LOWER_A = 97;
+const CHAR_LOWER_Z = 122;
+
 /** Known identifier keywords mapped to their token types. */
 const IDENTIFIER_KEYWORDS: Record<string, TokenType> = {
   kh: TokenType.KEEP_HIGH,
@@ -39,6 +87,8 @@ const IDENTIFIER_KEYWORDS: Record<string, TokenType> = {
   ceil: TokenType.FUNCTION,
   round: TokenType.FUNCTION,
   abs: TokenType.FUNCTION,
+  sqrt: TokenType.FUNCTION,
+  pow: TokenType.FUNCTION,
   max: TokenType.FUNCTION,
   min: TokenType.FUNCTION,
   s: TokenType.SORT_ASC,
@@ -106,22 +156,18 @@ export class Lexer {
     const startPos = this.pos;
     const char = this.peek();
 
-    // * Numbers
     if (this.isDigit(char)) {
       return this.scanNumber();
     }
 
-    // * Identifiers (d, kh, kl, dh, dl, r, ro, f, vs, floor, ceil, ...)
     if (this.isAlpha(char)) {
       return this.scanIdentifier();
     }
 
-    // * Variable reference
     if (char === '@') {
       return this.scanAt();
     }
 
-    // * Operators and punctuation
     this.advance();
 
     switch (char) {
@@ -166,8 +212,7 @@ export class Lexer {
         if (this.match('!')) {
           return this.createTokenAt(TokenType.EXPLODE_COMPOUND, '!!', startPos);
         }
-        if (!this.isAtEnd() && this.peek().toLowerCase() === 'p') {
-          this.advance();
+        if (this.match('p') || this.match('P')) {
           return this.createTokenAt(TokenType.EXPLODE_PENETRATING, '!p', startPos);
         }
         return this.createTokenAt(TokenType.EXPLODE, char, startPos);
@@ -181,7 +226,9 @@ export class Lexer {
     }
   }
 
+  //
   // * Private helpers
+  //
 
   private skipWhitespace(): void {
     while (!this.isAtEnd() && this.isWhitespace(this.peek())) {
@@ -189,24 +236,23 @@ export class Lexer {
     }
   }
 
+  // Scanners slice once from a recorded start offset rather than accumulating
+  // `value += this.advance()` — one string per token instead of one per character.
   private scanNumber(): Token {
     const startPos = this.pos;
-    let value = '';
 
-    // Integer part
     while (!this.isAtEnd() && this.isDigit(this.peek())) {
-      value += this.advance();
+      this.pos++;
     }
 
-    // Decimal part
     if (!this.isAtEnd() && this.peek() === '.' && this.isDigit(this.peekNext())) {
-      value += this.advance(); // consume '.'
+      this.pos++;
       while (!this.isAtEnd() && this.isDigit(this.peek())) {
-        value += this.advance();
+        this.pos++;
       }
     }
 
-    return this.createTokenAt(TokenType.NUMBER, value, startPos);
+    return this.createTokenAt(TokenType.NUMBER, this.input.slice(startPos, this.pos), startPos);
   }
 
   /**
@@ -227,18 +273,15 @@ export class Lexer {
     const first = this.peek();
     const second = this.peekNext();
     if ((first === 'd' || first === 'D') && (second === 'f' || second === 'F')) {
-      this.advance();
-      this.advance();
+      this.pos += 2;
       return this.createTokenAt(TokenType.DICE_FATE, 'df', startPos);
     }
 
-    let value = '';
-
     while (!this.isAtEnd() && this.isAlpha(this.peek())) {
-      value += this.advance();
+      this.pos++;
     }
 
-    const lower = value.toLowerCase();
+    const lower = this.input.slice(startPos, this.pos).toLowerCase();
 
     if (lower === 'd' && !this.isAtEnd() && this.peek() === '%') {
       this.advance();
@@ -272,11 +315,11 @@ export class Lexer {
    */
   private scanAt(): Token {
     const startPos = this.pos;
-    this.advance(); // consume '@'
+    this.advance();
 
     let name: string;
     if (!this.isAtEnd() && this.peek() === '{') {
-      this.advance(); // consume '{'
+      this.advance();
       const nameStart = this.pos;
       while (!this.isAtEnd() && this.peek() !== '}' && this.peek() !== '\n') {
         this.advance();
@@ -285,7 +328,7 @@ export class Lexer {
         throw new LexerError('Unterminated @{...} variable', 'UNEXPECTED_CHARACTER', startPos, '@');
       }
       name = this.input.slice(nameStart, this.pos);
-      this.advance(); // consume '}'
+      this.advance();
     } else {
       const nameStart = this.pos;
       if (this.isAtEnd() || !this.isIdentifierStart(this.peek())) {
@@ -324,13 +367,19 @@ export class Lexer {
     return this.pos >= this.input.length;
   }
 
+  // `NaN` from an empty `peek()` fails every comparison, so end-of-input
+  // still reads as "not a digit / not alpha" without an extra guard.
   private isDigit(char: string): boolean {
-    return char >= '0' && char <= '9';
+    const code = char.charCodeAt(0);
+    return code >= CHAR_DIGIT_0 && code <= CHAR_DIGIT_9;
   }
 
   private isAlpha(char: string): boolean {
-    const c = char.toLowerCase();
-    return c >= 'a' && c <= 'z';
+    const code = char.charCodeAt(0);
+    return (
+      (code >= CHAR_LOWER_A && code <= CHAR_LOWER_Z) ||
+      (code >= CHAR_UPPER_A && code <= CHAR_UPPER_Z)
+    );
   }
 
   private isIdentifierStart(char: string): boolean {
@@ -345,8 +394,8 @@ export class Lexer {
     return char === ' ' || char === '\t' || char === '\n' || char === '\r';
   }
 
-  // ? Both factories run after the token's characters were consumed, so
-  //   `this.pos` is the exclusive end offset.
+  // Both factories run after the token's characters were consumed, so
+  // `this.pos` is the exclusive end offset.
   private createToken(type: TokenType, value: string): Token {
     return { type, value, position: this.pos, end: this.pos };
   }
@@ -357,18 +406,42 @@ export class Lexer {
 }
 
 /**
- * Tokenize a dice notation string.
+ * Tokenizes a dice notation string. The first stage of the pipeline —
+ * {@link parse} calls it for you; reach for `lex` directly only to build a
+ * syntax highlighter or an editor integration.
+ *
+ * Notation is case-insensitive and whitespace-tolerant: `2D20 + 5` and
+ * `2d20+5` produce the same tokens, and identifier tokens carry a lowercased
+ * `value`. The one exception is `@name`, whose case is preserved.
  *
  * @param input - The dice notation to tokenize
- * @returns Array of tokens including EOF
- * @throws {LexerError} If an invalid character is encountered
+ * @returns Every token in source order, always ending with one
+ *   `TokenType.EOF` token
+ * @throws {LexerError} If an invalid character or unknown identifier is found
+ * @throws {RollParserError} `INVALID_NOTATION_TYPE` when `input` is not a
+ *   string — raised before scanning, so it carries no position
  *
  * @example
  * ```typescript
+ * import { lex, TokenType } from 'roll-parser';
+ *
  * const tokens = lex('2d20+5');
- * // [NUMBER(2), DICE, NUMBER(20), PLUS, NUMBER(5), EOF]
+ * tokens.length; // 6 — NUMBER DICE NUMBER PLUS NUMBER EOF
+ * tokens[0]; // { type: TokenType.NUMBER, value: '2', position: 0, end: 1 }
+ * tokens[1].type === TokenType.DICE; // true
+ * tokens.at(-1)?.type === TokenType.EOF; // true
  * ```
+ *
+ * @category Core
  */
 export function lex(input: string): Token[] {
+  // ! The pipeline's only notation type guard — `parse` and `roll` both funnel through here.
+  if (typeof input !== 'string') {
+    throw new RollParserError(
+      `Notation must be a string, received ${describeValue(input)}`,
+      'INVALID_NOTATION_TYPE',
+    );
+  }
+
   return new Lexer(input).tokenize();
 }

package/src/lexer/tokens.ts

@@ -9,6 +9,8 @@
  *
  * Grouped semantically. Numeric values are stable identifiers — the specific
  * numbers don't matter, but they must be unique.
+ *
+ * @category AST
  */
 export enum TokenType {
   //
@@ -116,7 +118,11 @@ export enum TokenType {
   // * Functions
   //
 
-  /** Math function: 'floor', 'ceil', 'round', 'abs', 'max', 'min' */
+  /**
+   * Math function: 'floor', 'ceil', 'round', 'abs', 'sqrt', 'pow', 'max',
+   * 'min'. In postfix position, 'min'/'max' double as per-die clamp
+   * modifiers (`4d6min2`) — the parser decides by position, not the lexer.
+   */
   FUNCTION = 28,
 
   //
@@ -169,19 +175,38 @@ export enum TokenType {
 }
 
 /**
- * A token produced by the lexer.
+ * A token produced by {@link lex}: what it is, the text it came from, and
+ * where in the input that text sits.
+ *
+ * `position`/`end` are a half-open range, so `input.slice(position, end)`
+ * recovers the original source text — useful for syntax highlighting, where
+ * `value` alone is lossy.
+ *
+ * @example
+ * ```typescript
+ * import { lex, TokenType } from 'roll-parser';
+ *
+ * const input = '4D6KH3';
+ * const tokens = lex(input);
+ * tokens[1]; // { type: TokenType.DICE, value: 'd', position: 1, end: 2 }
+ * tokens[3].type === TokenType.KEEP_HIGH; // true
+ * input.slice(tokens[3].position, tokens[3].end); // 'KH' — original casing
+ * tokens[3].value; // 'kh' — normalized
+ * ```
+ *
+ * @category AST
  */
 export type Token = {
   /** The type of this token */
-  type: TokenType;
+  readonly type: TokenType;
   /** The raw string value from input (lowercased for identifiers) */
-  value: string;
+  readonly value: string;
   /** Zero-based start offset in the input string (UTF-16 code units) */
-  position: number;
+  readonly position: number;
   /**
    * Zero-based end offset (exclusive). Not always `position + value.length` —
    * braced variables (`@{name}` stores only `name`) and case-normalized
    * identifiers consume more input than their `value` retains.
    */
-  end: number;
+  readonly end: number;
 };