epic: Roll Parser v3 - TypeScript Rewrite #9
Description
Complete TypeScript rewrite of roll-parser using Pratt Parser architecture, targeting Bun runtime for high-performance dice notation parsing.
Motivation
v2 limitations:
- JavaScript codebase with inconsistent typing
- PEG-based parser with cold-start penalty
- Legacy tooling (Jest, ESLint, Travis CI)
- Limited modifier support
v3 goals:
- Performance: Pratt Parser outperforms recursive descent and PEG
- Type Safety: Strict TypeScript throughout (no
any) - Modern Tooling: Bun runtime, Biome linting, GitHub Actions
- Extensibility: Clean architecture for Stage 2/3 features
Target Systems (Stage 1)
- D&D 5e MVP
- Basic arithmetic (+, -, *, /, %, **)
- Keep/drop modifiers (advantage, disadvantage, stat generation)
Architecture
Input → [Lexer] → Tokens → [Pratt Parser] → AST → [Evaluator] → Result
Key Design Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Parser | Pratt | Handles precedence naturally, extensible for modifiers |
| Runtime | Bun | Fast startup, built-in test runner, native TypeScript |
| Linting | Biome | Single tool for lint + format, fast |
| Testing | fast-check | Property-based invariant testing |
Implementation Phases
Phase 0: Infrastructure
- chore: initialize v3 project infrastructure #2 chore: initialize v3 project infrastructure
Phase 1: Lexer
- feat: implement lexer and token system #3 feat: implement lexer and token system
Phase 2: Parser
- feat: implement Pratt parser and AST #4 feat: implement Pratt parser and AST
Phase 3: RNG
- feat: implement seedable RNG system #5 feat: implement seedable RNG system
Phase 4: Evaluator
- feat: implement AST evaluator with modifiers #6 feat: implement AST evaluator with modifiers
Phase 5: Public API
- feat: implement public API and integration tests #7 feat: implement public API and integration tests
Phase 6: CLI & Build
- feat: implement CLI and dual-format build #8 feat: implement CLI and dual-format build
Success Criteria
- All Stage 1 notation parses correctly
- Performance: <1ms for simple rolls
- Test coverage: >90% statements, 100% functions
- CI pipeline green
- npm publish works
- README updated with v3 documentation
Syntax Support (Stage 1)
| Feature | Syntax | Example |
|---|---|---|
| Basic roll | NdX |
2d6 |
| Implicit count | dX |
d20 → 1d20 |
| Arithmetic | +, -, *, /, %, ** |
1d20+5 |
| Parentheses | (...) |
(1d4+1)*2 |
| Keep Highest | khN or kN |
2d20kh1 |
| Keep Lowest | klN |
2d20kl1 |
| Drop Lowest | dlN |
4d6dl1 |
| Drop Highest | dhN |
4d6dh1 |
| Negative results | — | 1d4-5 → can be -4 |
| Computed dice | (expr)d(expr) |
(1+1)d(3*2) |
Future (Stage 2/3)
Not in scope for this epic:
- Exploding dice (
1d6!,1d6!!,1d6!p) - Reroll mechanics (
2d6r<2,2d6ro<3) - Success counting (
10d10>=6,10d10>=6f1) - Compare points (
>,>=,<,<=,=) - Math functions (
floor,ceil,max,min) - Variables (
@strMod,@{modifier}) - Grouped rolls (
{1d8, 1d10}kh1) - Sorting modifiers (
4d6s,4d6sd) - Critical thresholds (
1d20cs>19)
References
Files are local only.
Drafted with AI assistance