roll-parser 2.3.2 → 3.0.0-alpha.0

package/dist/lexer/lexer.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Dice notation lexer with character-by-character scanning.
+ *
+ * @module lexer/lexer
+ */
+import type { RollParserErrorCode } from '../errors';
+import { RollParserError } from '../errors';
+import { type Token } from './tokens';
+/**
+ * Error thrown when the lexer encounters an invalid character.
+ */
+export declare class LexerError extends RollParserError {
+    readonly position: number;
+    readonly character: string;
+    constructor(message: string, code: RollParserErrorCode, position: number, character: string);
+}
+/**
+ * Lexer for dice notation.
+ *
+ * Produces a stream of tokens from an input string using character-by-character
+ * scanning with maximal munch for multi-character tokens.
+ */
+export declare class Lexer {
+    private pos;
+    private readonly input;
+    constructor(input: string);
+    /**
+     * Tokenize the entire input and return all tokens.
+     */
+    tokenize(): Token[];
+    /**
+     * Get the next token from the input.
+     */
+    nextToken(): Token;
+    private skipWhitespace;
+    private scanNumber;
+    /**
+     * Scans an identifier using full-accumulation: collects all consecutive
+     * alpha characters, then classifies the result against known keywords.
+     *
+     * Special cases run before/after the accumulation loop:
+     * - `dF` / `Df` / `dF` / `DF` produces DICE_FATE. Must be handled BEFORE
+     *   the loop because `F` is alpha and would otherwise be greedily merged
+     *   into identifiers like `dfkh` (from `4dFkh2`) or `dfdf` (from `dFdF`).
+     *   Reserves the `d[fF]` prefix namespace for Fate dice.
+     * - Bare `d` followed by `%` produces DICE_PERCENT. `%` is not alpha so the
+     *   accumulation loop stops naturally and the post-loop check handles it.
+     */
+    private scanIdentifier;
+    private peek;
+    private peekNext;
+    private advance;
+    private match;
+    private isAtEnd;
+    private isDigit;
+    private isAlpha;
+    private isWhitespace;
+    private createToken;
+    private createTokenAt;
+}
+/**
+ * Tokenize a dice notation string.
+ *
+ * @param input - The dice notation to tokenize
+ * @returns Array of tokens including EOF
+ * @throws {LexerError} If an invalid character is encountered
+ *
+ * @example
+ * ```typescript
+ * const tokens = lex('2d20+5');
+ * // [NUMBER(2), DICE, NUMBER(20), PLUS, NUMBER(5), EOF]
+ * ```
+ */
+export declare function lex(input: string): Token[];
+//# sourceMappingURL=lexer.d.ts.map

package/dist/lexer/lexer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexer.d.ts","sourceRoot":"","sources":["../../src/lexer/lexer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,KAAK,KAAK,EAAa,MAAM,UAAU,CAAC;AAEjD;;GAEG;AACH,qBAAa,UAAW,SAAQ,eAAe;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAM5F;AAsBD;;;;;GAKG;AACH,qBAAa,KAAK;IAChB,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,KAAK,EAAE,MAAM;IAIzB;;OAEG;IACH,QAAQ,IAAI,KAAK,EAAE;IAYnB;;OAEG;IACH,SAAS,IAAI,KAAK;IAyElB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,UAAU;IAoBlB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,cAAc;IAgCtB,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,KAAK;IAOb,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,aAAa;CAGtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,EAAE,CAE1C"}

package/dist/lexer/tokens.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Token type definitions for the dice notation lexer.
+ *
+ * @module lexer/tokens
+ */
+/**
+ * Token types for dice notation.
+ *
+ * Grouped semantically. Numeric values are stable identifiers — the specific
+ * numbers don't matter, but they must be unique.
+ */
+export declare enum TokenType {
+    /** Numeric literal: integer or decimal */
+    NUMBER = 0,
+    /** Dice operator: 'd' or 'D' */
+    DICE = 1,
+    /** Percentile dice operator: 'd%' (alias for d100) */
+    DICE_PERCENT = 2,
+    /** Fate/Fudge dice operator: 'dF' */
+    DICE_FATE = 3,
+    /** Addition operator: '+' */
+    PLUS = 4,
+    /** Subtraction operator: '-' */
+    MINUS = 5,
+    /** Multiplication operator: '*' */
+    MULTIPLY = 6,
+    /** Division operator: '/' */
+    DIVIDE = 7,
+    /** Modulo operator: '%' */
+    MODULO = 8,
+    /** Power operator: '**' or '^' */
+    POWER = 9,
+    /** Greater than: '>' */
+    GREATER = 10,
+    /** Greater than or equal: '>=' */
+    GREATER_EQUAL = 11,
+    /** Less than: '<' */
+    LESS = 12,
+    /** Less than or equal: '<=' */
+    LESS_EQUAL = 13,
+    /** Equal: '=' */
+    EQUAL = 14,
+    /** Left parenthesis: '(' */
+    LPAREN = 15,
+    /** Right parenthesis: ')' */
+    RPAREN = 16,
+    /** Argument separator: ',' */
+    COMMA = 17,
+    /** Keep highest modifier: 'kh' or 'k' */
+    KEEP_HIGH = 18,
+    /** Keep lowest modifier: 'kl' */
+    KEEP_LOW = 19,
+    /** Drop highest modifier: 'dh' */
+    DROP_HIGH = 20,
+    /** Drop lowest modifier: 'dl' */
+    DROP_LOW = 21,
+    /** Standard explode: '!' */
+    EXPLODE = 22,
+    /** Compounding explode: '!!' */
+    EXPLODE_COMPOUND = 23,
+    /** Penetrating explode: '!p' */
+    EXPLODE_PENETRATING = 24,
+    /** Recursive reroll: 'r' */
+    REROLL = 25,
+    /** Reroll once: 'ro' */
+    REROLL_ONCE = 26,
+    /** Fail marker: 'f' */
+    FAIL = 27,
+    /** Math function: 'floor', 'ceil', 'round', 'abs', 'max', 'min' */
+    FUNCTION = 28,
+    /** Versus operator: 'vs' */
+    VS = 29,
+    /** End of input marker */
+    EOF = 30
+}
+/**
+ * A token produced by the lexer.
+ */
+export type Token = {
+    /** The type of this token */
+    type: TokenType;
+    /** The raw string value from input (lowercased for identifiers) */
+    value: string;
+    /** Zero-based position in the input string */
+    position: number;
+};
+//# sourceMappingURL=tokens.d.ts.map

package/dist/lexer/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/lexer/tokens.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,oBAAY,SAAS;IAKnB,0CAA0C;IAC1C,MAAM,IAAI;IAMV,gCAAgC;IAChC,IAAI,IAAI;IACR,sDAAsD;IACtD,YAAY,IAAI;IAChB,qCAAqC;IACrC,SAAS,IAAI;IAMb,6BAA6B;IAC7B,IAAI,IAAI;IACR,gCAAgC;IAChC,KAAK,IAAI;IACT,mCAAmC;IACnC,QAAQ,IAAI;IACZ,6BAA6B;IAC7B,MAAM,IAAI;IACV,2BAA2B;IAC3B,MAAM,IAAI;IACV,kCAAkC;IAClC,KAAK,IAAI;IAMT,wBAAwB;IACxB,OAAO,KAAK;IACZ,kCAAkC;IAClC,aAAa,KAAK;IAClB,qBAAqB;IACrB,IAAI,KAAK;IACT,+BAA+B;IAC/B,UAAU,KAAK;IACf,iBAAiB;IACjB,KAAK,KAAK;IAMV,4BAA4B;IAC5B,MAAM,KAAK;IACX,6BAA6B;IAC7B,MAAM,KAAK;IACX,8BAA8B;IAC9B,KAAK,KAAK;IAMV,yCAAyC;IACzC,SAAS,KAAK;IACd,iCAAiC;IACjC,QAAQ,KAAK;IACb,kCAAkC;IAClC,SAAS,KAAK;IACd,iCAAiC;IACjC,QAAQ,KAAK;IAMb,4BAA4B;IAC5B,OAAO,KAAK;IACZ,gCAAgC;IAChC,gBAAgB,KAAK;IACrB,gCAAgC;IAChC,mBAAmB,KAAK;IAMxB,4BAA4B;IAC5B,MAAM,KAAK;IACX,wBAAwB;IACxB,WAAW,KAAK;IAMhB,uBAAuB;IACvB,IAAI,KAAK;IAMT,mEAAmE;IACnE,QAAQ,KAAK;IAMb,4BAA4B;IAC5B,EAAE,KAAK;IAMP,0BAA0B;IAC1B,GAAG,KAAK;CACT;AAED;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG;IAClB,6BAA6B;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC"}

package/dist/parser/ast.d.ts

@@ -0,0 +1,183 @@
+/**
+ * AST node type definitions for the dice notation parser.
+ *
+ * @module parser/ast
+ */
+import type { ComparePoint } from '../types';
+/**
+ * Numeric literal node.
+ */
+export type LiteralNode = {
+    type: 'Literal';
+    value: number;
+};
+/**
+ * Dice roll node.
+ * Count and sides can be expressions to support computed dice like (1+1)d(3*2).
+ */
+export type DiceNode = {
+    type: 'Dice';
+    count: ASTNode;
+    sides: ASTNode;
+};
+/**
+ * Fate/Fudge dice node (`dF`).
+ * Each die produces a result in {-1, 0, +1}. No configurable sides.
+ */
+export type FateDiceNode = {
+    type: 'FateDice';
+    count: ASTNode;
+};
+/**
+ * Binary operation node.
+ */
+export type BinaryOpNode = {
+    type: 'BinaryOp';
+    operator: '+' | '-' | '*' | '/' | '%' | '**';
+    left: ASTNode;
+    right: ASTNode;
+};
+/**
+ * Unary operation node.
+ */
+export type UnaryOpNode = {
+    type: 'UnaryOp';
+    operator: '-';
+    operand: ASTNode;
+};
+/**
+ * Keep/drop modifier node.
+ * Wraps a dice expression with keep highest/lowest or drop highest/lowest.
+ */
+export type ModifierNode = {
+    type: 'Modifier';
+    modifier: 'keep' | 'drop';
+    selector: 'highest' | 'lowest';
+    count: ASTNode;
+    target: ASTNode;
+};
+/**
+ * Exploding dice node (`!`, `!!`, `!p`, `!>Y`).
+ * Wraps a dice expression with a standard, compounding, or penetrating
+ * explosion. An absent `threshold` means "explode on the die's maximum face".
+ */
+export type ExplodeNode = {
+    type: 'Explode';
+    variant: 'standard' | 'compound' | 'penetrating';
+    threshold?: ComparePoint;
+    target: ASTNode;
+};
+/**
+ * Reroll node (`r<COND>`, `ro<COND>`).
+ * Re-rolls dice that match a comparison condition. `once: true` for `ro`
+ * keeps the second result regardless of match; `once: false` for `r`
+ * re-rolls recursively until the condition no longer matches.
+ */
+export type RerollNode = {
+    type: 'Reroll';
+    once: boolean;
+    condition: ComparePoint;
+    target: ASTNode;
+};
+/**
+ * Success counting node (`>=T`, `>T`, `<T`, `<=T`, `=T`, with optional `f=F`).
+ *
+ * Transforms a dice pool into a success count: each die meeting `threshold`
+ * adds +1, each die meeting `failThreshold` subtracts 1. Terminal — no further
+ * postfix modifiers may wrap a `SuccessCountNode`. The `failThreshold`
+ * operator is always `=` (fail on an exact value).
+ */
+export type SuccessCountNode = {
+    type: 'SuccessCount';
+    target: ASTNode;
+    threshold: ComparePoint;
+    failThreshold?: ComparePoint;
+};
+/**
+ * Versus node (`<roll> vs <dc>`) — PF2e Degrees of Success.
+ *
+ * Both sides are full expressions. The `roll` side is evaluated and compared
+ * against the `dc` side total, producing a `DegreeOfSuccess` with natural
+ * d20 upgrade/downgrade applied when exactly one kept d20 appears on the
+ * roll side. Lowest-precedence operator — chaining (`a vs b vs c`) is
+ * rejected at parse time; nesting via parens (`a vs (b vs c)`) is rejected
+ * at evaluation time.
+ */
+export type VersusNode = {
+    type: 'Versus';
+    roll: ASTNode;
+    dc: ASTNode;
+};
+/**
+ * Math function call node (`floor(expr)`, `max(a, b, ...)`, etc.).
+ *
+ * Supports the fixed-arity functions `floor`, `ceil`, `round`, `abs`, and the
+ * variadic functions `max`, `min` (minimum 2 args). Arity is validated at
+ * parse time against a static table; by the time the evaluator sees a
+ * `FunctionCallNode`, `args.length` is guaranteed to match the function.
+ */
+export type FunctionCallNode = {
+    type: 'FunctionCall';
+    name: string;
+    args: ASTNode[];
+};
+/**
+ * Union type of all AST nodes.
+ */
+export type ASTNode = LiteralNode | DiceNode | FateDiceNode | BinaryOpNode | UnaryOpNode | ModifierNode | ExplodeNode | RerollNode | SuccessCountNode | VersusNode | FunctionCallNode;
+/**
+ * Type guard for LiteralNode.
+ */
+export declare function isLiteral(node: ASTNode): node is LiteralNode;
+/**
+ * Type guard for DiceNode.
+ */
+export declare function isDice(node: ASTNode): node is DiceNode;
+/**
+ * Type guard for FateDiceNode.
+ */
+export declare function isFateDice(node: ASTNode): node is FateDiceNode;
+/**
+ * Type guard for BinaryOpNode.
+ */
+export declare function isBinaryOp(node: ASTNode): node is BinaryOpNode;
+/**
+ * Type guard for UnaryOpNode.
+ */
+export declare function isUnaryOp(node: ASTNode): node is UnaryOpNode;
+/**
+ * Type guard for ModifierNode.
+ */
+export declare function isModifier(node: ASTNode): node is ModifierNode;
+/**
+ * Type guard for ExplodeNode.
+ */
+export declare function isExplode(node: ASTNode): node is ExplodeNode;
+/**
+ * Type guard for RerollNode.
+ */
+export declare function isReroll(node: ASTNode): node is RerollNode;
+/**
+ * Type guard for SuccessCountNode.
+ */
+export declare function isSuccessCount(node: ASTNode): node is SuccessCountNode;
+/**
+ * Type guard for VersusNode.
+ */
+export declare function isVersus(node: ASTNode): node is VersusNode;
+/**
+ * Type guard for FunctionCallNode.
+ */
+export declare function isFunctionCall(node: ASTNode): node is FunctionCallNode;
+/**
+ * Returns `true` if the AST contains a `Dice` or `FateDice` node reachable
+ * through structural composition (BinaryOp, UnaryOp, keep/drop, explode,
+ * reroll, success-count wrappers). Meta-expressions — dice count/sides,
+ * modifier counts, and ComparePoint values — are treated as leaves and
+ * never recursed into.
+ *
+ * Used by the parser to reject success-counting targets that don't actually
+ * roll any dice (e.g. `1>=3`, `(1+2)>=3`).
+ */
+export declare function containsDice(node: ASTNode): boolean;
+//# sourceMappingURL=ast.d.ts.map

package/dist/parser/ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/parser/ast.ts"],"names":[],"mappings":"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"}

package/dist/parser/parser.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Pratt parser for dice notation.
+ *
+ * @module parser/parser
+ */
+import type { RollParserErrorCode } from '../errors';
+import { RollParserError } from '../errors';
+import { type Token } from '../lexer/tokens';
+import type { ComparePoint } from '../types';
+import type { ASTNode } from './ast';
+/**
+ * Error thrown when the parser encounters invalid syntax.
+ */
+export declare class ParseError extends RollParserError {
+    readonly position: number;
+    readonly token: Token | undefined;
+    constructor(message: string, code: RollParserErrorCode, position: number, token?: Token);
+}
+/**
+ * Pratt parser for dice notation.
+ *
+ * Uses binding power (precedence) to handle operator associativity and
+ * precedence without left recursion issues.
+ */
+export declare class Parser {
+    private readonly tokens;
+    private pos;
+    constructor(tokens: Token[]);
+    /**
+     * Parse the token stream into an AST.
+     */
+    parse(): ASTNode;
+    /**
+     * Parse an expression with minimum binding power.
+     */
+    private parseExpression;
+    /**
+     * NUD - Null Denotation.
+     * Handles tokens that appear at the start of an expression (prefix position).
+     */
+    private parseNud;
+    /**
+     * LED - Left Denotation.
+     * Handles tokens that appear between expressions (infix/postfix position).
+     */
+    private parseLed;
+    private parseLiteral;
+    private parseUnaryMinus;
+    private parsePrefixDice;
+    private parseInfixDice;
+    private parsePrefixDicePercent;
+    private parseInfixDicePercent;
+    private parsePrefixFateDice;
+    private parseInfixFateDice;
+    private parseGrouped;
+    private parseFunctionCall;
+    private parseBinaryOp;
+    private rejectSuccessCountTarget;
+    private parseModifier;
+    private parseExplode;
+    private parseReroll;
+    private parseSuccessCount;
+    private parseVersus;
+    /**
+     * Checks whether the next token is a comparison operator.
+     */
+    isComparePointAhead(): boolean;
+    /**
+     * Parses a comparison operator followed by a value expression.
+     * Called by modifier parsers (explode, reroll, success counting).
+     *
+     * @returns A ComparePoint with the operator and value AST node
+     * @throws {ParseError} If the next token is not a comparison operator
+     */
+    parseComparePoint(): ComparePoint;
+    private getCompareOp;
+    private getOperatorSymbol;
+    private getLeftBp;
+    private getRightBp;
+    private peek;
+    private advance;
+    private expect;
+    private hasTokens;
+}
+/**
+ * Parse a dice notation string into an AST.
+ *
+ * @param notation - The dice notation to parse
+ * @returns The root AST node
+ * @throws {LexerError} If the input contains invalid characters
+ * @throws {ParseError} If the input has invalid syntax
+ *
+ * @example
+ * ```typescript
+ * const ast = parse('2d6+3');
+ * // { type: 'BinaryOp', operator: '+',
+ * //   left: { type: 'Dice', count: 2, sides: 6 },
+ * //   right: { type: 'Literal', value: 3 } }
+ * ```
+ */
+export declare function parse(notation: string): ASTNode;
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/parser/parser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,EAAE,KAAK,KAAK,EAAa,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,KAAK,EACV,OAAO,EAYR,MAAM,OAAO,CAAC;AAGf;;GAEG;AACH,qBAAa,UAAW,SAAQ,eAAe;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAMxF;AAkDD;;;;;GAKG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,GAAG,CAAK;gBAEJ,MAAM,EAAE,KAAK,EAAE;IAI3B;;OAEG;IACH,KAAK,IAAI,OAAO;IAqBhB;;OAEG;IACH,OAAO,CAAC,eAAe;IAgBvB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAsChB;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAwDhB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,sBAAsB;IAS9B,OAAO,CAAC,qBAAqB;IAS7B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,kBAAkB;IAU1B,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,iBAAiB;IAgDzB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,wBAAwB;IAWhC,OAAO,CAAC,aAAa;IA2BrB,OAAO,CAAC,YAAY;IA4BpB,OAAO,CAAC,WAAW;IAmBnB,OAAO,CAAC,iBAAiB;IAgCzB,OAAO,CAAC,WAAW;IAenB;;OAEG;IACH,mBAAmB,IAAI,OAAO;IAW9B;;;;;;OAMG;IACH,iBAAiB,IAAI,YAAY;IAWjC,OAAO,CAAC,YAAY;IAwBpB,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,SAAS;IA8CjB,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,MAAM;IAcd,OAAO,CAAC,SAAS;CAGlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI/C"}

package/dist/rng/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * RNG module - Seedable random number generation.
+ *
+ * @module rng
+ */
+export type { RNG } from './types';
+export { SeededRNG } from './seeded';
+//# sourceMappingURL=index.d.ts.map

package/dist/rng/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rng/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}

package/dist/rng/mock.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 declare class MockRNGExhaustedError extends Error {
+    readonly consumed: number;
+    constructor(consumed: number);
+}
+/**
+ * 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 declare function createMockRng(values: number[]): RNG;
+//# sourceMappingURL=mock.d.ts.map

package/dist/rng/mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../src/rng/mock.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAEnC;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM;CAK7B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAsBnD"}

package/dist/rng/seeded.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 declare class SeededRNG implements RNG {
+    private s0;
+    private s1;
+    private s2;
+    private s3;
+    constructor(seed?: string | number);
+    private initState;
+    private hashString;
+    private nextUint32;
+    next(): number;
+    nextInt(min: number, max: number): number;
+}
+//# sourceMappingURL=seeded.d.ts.map

package/dist/rng/seeded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seeded.d.ts","sourceRoot":"","sources":["../../src/rng/seeded.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAEnC;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAU,YAAW,GAAG;IACnC,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;IACnB,OAAO,CAAC,EAAE,CAAS;gBAEP,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM;IAelC,OAAO,CAAC,SAAS;IA+BjB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,UAAU;IAgBlB,IAAI,IAAI,MAAM;IAKd,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;CAsB1C"}

package/dist/rng/types.d.ts

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

package/dist/rng/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/rng/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,MAAM,GAAG,GAAG;IAChB;;OAEG;IACH,IAAI,IAAI,MAAM,CAAC;IAEf;;;;;OAKG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3C,CAAC"}

package/dist/roll.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Main public API for rolling dice expressions.
+ *
+ * @module roll
+ */
+import type { RNG } from './rng/types';
+import type { RollResult } from './types';
+/**
+ * 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 declare function roll(notation: string, options?: RollOptions): RollResult;
+//# sourceMappingURL=roll.d.ts.map

package/dist/roll.d.ts.map

@@ -0,0 +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"}

package/dist/testing.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Test utilities for roll-parser consumers.
+ *
+ * Import from `roll-parser/testing` for deterministic dice testing.
+ *
+ * @module testing
+ */
+import { MockRNGExhaustedError as _MockRNGExhaustedError, createMockRng as _createMockRng } from './rng/mock';
+export declare const createMockRng: typeof _createMockRng;
+export declare const MockRNGExhaustedError: typeof _MockRNGExhaustedError;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +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"}