roll-parser 2.3.2 → 3.0.0-alpha.0

package/README.md

@@ -1,210 +1,79 @@
 <h1 align="center">Roll Parser</h1>
 
 <p align="center">
-Parser for classic (2d6+1), simple (2 6 1), and WoD (4d10!>6f1) dice rolls.
+High-performance dice notation parser for tabletop RPGs.<br>
+TypeScript-first, Bun-optimized, Pratt parser architecture.
 </p>
 
-[![Travis Build Status][travis-image]][travis-url]
-[![AppVeyor Build Status][appveyor-image]][appveyor-url]
-[![Coverage Status][coveralls-image]][coveralls-url]
-[![devDependency Status][devdep-image]][devdep-url]
-<!-- [![Dependency Status][dep-image]][dep-url] -->
+<p align="center">
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-6-blue.svg" alt="TypeScript"></a>
+  <a href="https://bun.sh/"><img src="https://img.shields.io/badge/Bun-1.3+-black.svg" alt="Bun"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-22%2B-339933.svg" alt="Node.js"></a>
+</p>
 
-[![Node.js version][node-image]][node-url]
-[![Project is on npm][npm-image]][npm-url]
+## Status
 
-## Documentation
+> **v3 Alpha** — Stage 1 (Core Engine) is complete with 300+ tests.
+> Stages 2–3 are planned.
+>
+> For production use, install [v2.3.2](https://www.npmjs.com/package/roll-parser/v/2.3.2).
 
-Please review the [API documentation](http://edloidas.com/roll-parser/).
+## Features
 
-## Install
+### Stage 1: Core Engine (Complete)
 
-#### Node:
+- Basic dice notation: `2d6`, `d20`, `4d6+4`
+- Full arithmetic: `+`, `-`, `*`, `/`, `%`, `**`
+- Parentheses: `(1d4+1)*2`
+- Keep/Drop modifiers: `4d6kh3`, `2d20kl1`, `4d6dl1`
+- Computed dice: `(1+1)d(3*2)`
+- Seedable RNG for reproducible rolls
 
-```
-npm install roll-parser
-```
-
-Then in the console or JS file:
-```js
-const rollParser = require('roll-parser');
-```
+### Stage 2: System Compatibility (Planned)
 
-#### Browser:
+- Exploding dice: `1d6!`, `1d6!!`, `1d6!p`
+- Reroll mechanics: `2d6r<2`, `2d6ro<3`
+- Success counting: `10d10>=6`, `10d10>=6f1`
+- Math functions: `floor()`, `ceil()`, `max()`, `min()`
 
-```html
-<script src="https://unpkg.com/roll-parser/dist/roll-parser.js"></script>
-```
-Minified version:
-```html
-<script src="https://unpkg.com/roll-parser/dist/roll-parser.min.js"></script>
-```
+### Stage 3: Advanced Features (Planned)
 
-Then access all functions from `rollParser` object.
+- Variables: `1d20+@str`, `1d20+@{modifier}`
+- Grouped rolls: `{1d8, 1d10}kh1`
+- Rich JSON output with roll breakdown
 
-#### Console:
+## Installation
 
 ```bash
-$ roll-parser [options] [<rolls>]
+bun add roll-parser
+npm install roll-parser
 ```
 
-Run `roll-parser --help` for more details.
-
 ## Usage
 
-```js
-const { parse, roll, parseAndRoll, Roll } = require('roll-parser');
-
-// `parse()` function parses any notation and returns `Roll` or `WodRoll` object
-//=> { dice: 6, count: 4, modifier: 1 }
-const parsedRoll = parse('4d6+1');
-
-// `Roll` or `WodRoll` can be stringified
-//=> '4d6+1'
-const rollNotation = parsedRoll.toString();
-
-//=> { notation: '4d6+1', value: 16, rolls: [3, 1, 6, 5] }
-const result1 = roll(parsedRoll);
-//=> { notation: '2d20-3', value: 23, rolls: [11, 15] }
-const result2 = roll(new Roll(20, 2, -3));
-// Can also accept plain objects
-//=> { notation: '2d10>7', value: 1, rolls: [4, 8] }
-const result3 = roll({dice: 10, count: 2, success: 7});
+```typescript
+import { roll } from 'roll-parser';
 
-// `parseAndRoll()` function can parse any notation and then roll the dice
-// Any invalid arguments, except `null` or `undefined`, will be parsed as default `Roll`
-//=> { notation: '3d10!>8f1', value: 2, rolls: [3, 10, 7, 9] }
-const result4 = parseAndRoll('3d10!>8f1');
-
-//=> '(3d10!>8f1) 2 [3,10,7,9]'
-const resultNotation = result4.toString();
-```
-
-Specific parsers can be used.
-
-__Classic (D&D):__
-
-```js
-const {
-  parseClassicRoll,
-  rollClassic,
-  parseAndRollClassic,
-  Roll
-} = require('roll-parser');
-
-//=> { dice: 10, count: 1, modifier: 0 }
-const parsedRoll = parseClassicRoll('d10');
-
-//=> { notation: 'd10', value: 7, rolls: [7] }
-const result1 = rollClassic(parsedRoll);
-
-//=> { notation: '2d20', value: 26, rolls: [11, 15] }
-const result2 = rollClassic(new Roll(20, 2));
-
-//=> { notation: '4d10+1', value: 22, rolls: [4, 6, 2, 9] }
-const result3 = rollClassic({ dice: 10, count: 4, modifier: 1 });
-
-//=> { notation: '3d6', value: 15, rolls: [6, 6, 3] }
-const result4 = parseAndRollClassic('3d6');
+const result = roll('4d6kh3');
+console.log(result.total);    // e.g., 14
+console.log(result.notation); // "4d6kh3"
 ```
 
-__WoD (World of Darkness):__
-
-```js
-const {
-  parseWodRoll,
-  rollWod,
-  parseAndRollWod,
-  WodRoll
-} = require('roll-parser');
-
-//=> { dice: 10, count: 1, again: false, success: 6, fail: 0 }
-const parsedRoll = parseWodRoll('d10>6');
-
-// Returns notation, number of success rolls and list of all dice rolls
-//=> { notation: 'd10', value: 1, rolls: [7] }
-const result1 = rollWod(parsedRoll);
-
-//=> { notation: '4d10>6f1', value: 1, rolls: [4, 10, 5, 2] }
-const result2 = rollWod(new WodRoll(10, 4, false, 6, 1));
+### CLI
 
-//=> { notation: '4d10!>8f1', value: 22, rolls: [1, 8, 5, 10, 10, 4] }
-const result3 = rollWod({ dice: 10, count: 2, again: true, success: 8, fail: 1 });
-
-//=> { notation: '4d10>7f4', value: 1, rolls: [6, 3, 8, 4] }
-const result4 = parseAndRollWod('4d10>7f4');
-```
-
-__Simple (D&D, space-separated):__
-
-```js
-const { parseSimpleRoll, parseAndRollSimple } = require('roll-parser');
-
-//=> { dice: 10, count: 1, modifier: 0 }
-const parsedRoll = parseSimpleRoll('10');
-
-//=> { notation: '4d10-1', value: 23, rolls: [3, 6, 8, 7] }
-const result = parseAndRollSimple('4 10 -1');
-```
-
-Random number generator can be used to roll the dice.
-
-```js
-const { random } = require('roll-parser');
-
-//=> 84 - d100-like roll
-random(100);
-
-//=> 7 - d10-like roll
-random(10);
-
-//=> [2, 5, 2, 6] - 4d6-like roll
-[...Array(4)].map(() => random(6));
-```
-
-Even so the parse&roll functions uses checks to convert non-standard objects to `Roll` or `WodRoll`, explicit conversion can be used in some cases:
-
-```js
-const { convert } = require('roll-parser');
-
-//=> new Roll(undefined, 4, -3)
-convert({ count: 4, modifier: -3 });
-
-//=> new WodRoll(10, 6, true, undefined, 2)
-convert({ dice: 10, count: 6, again: true, fail: 2 });
+```bash
+roll-parser 2d6+3
+roll-parser 4d6kh3
+roll-parser --help
 ```
 
-## Releases
+## Known Limitations
 
-Please review the [changelog](https://github.com/edloidas/roll-parser/releases).
-
-## Contributing
-
-♥ [roll-parser](https://github.com/edloidas/roll-parser) and want to get involved?<br>
-Please, check the [guide](CONTRIBUTING.md) first.
+- **`4d6d1` parses as nested dice, not "drop 1".** The bare `d` token is always
+  interpreted as the dice operator, so `4d6d1` becomes `(4d6)d1` (roll 4d6, then
+  use the result as the count for d1). To drop dice, use the explicit `dl`
+  (drop lowest) or `dh` (drop highest) modifiers: `4d6dl1`.
 
 ## License
 
 [MIT](LICENSE) © [Mikita Taukachou](https://edloidas.com)
-
-<!-- Links -->
-[travis-url]: https://travis-ci.org/edloidas/roll-parser
-[travis-image]: https://img.shields.io/travis/edloidas/roll-parser.svg?label=linux%20build
-
-[appveyor-url]: https://ci.appveyor.com/project/edloidas/roll-parser
-[appveyor-image]: https://img.shields.io/appveyor/ci/edloidas/roll-parser.svg?label=windows%20build
-
-[coveralls-url]: https://coveralls.io/github/edloidas/roll-parser?branch=master
-[coveralls-image]: https://coveralls.io/repos/github/edloidas/roll-parser/badge.svg?branch=master
-
-[dep-url]: https://david-dm.org/edloidas/roll-parser
-[dep-image]: https://david-dm.org/edloidas/roll-parser.svg
-
-[devdep-url]: https://david-dm.org/edloidas/roll-parser#info=devDependencies
-[devdep-image]: https://david-dm.org/edloidas/roll-parser/dev-status.svg
-
-[node-url]: https://nodejs.org
-[node-image]: https://img.shields.io/badge/node-≥%206.0.0-green.svg
-
-[npm-url]: https://www.npmjs.com/package/roll-parser
-[npm-image]: https://img.shields.io/badge/npm-roll--parser-blue.svg

package/dist/cli/args.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CLI argument parser.
+ *
+ * Pure function that parses process.argv-style string arrays into typed options.
+ *
+ * @module cli/args
+ */
+/**
+ * Parsed CLI arguments.
+ */
+export type CliArgs = {
+    notation: string | undefined;
+    verbose: boolean;
+    seed: string | undefined;
+    showHelp: boolean;
+    showVersion: boolean;
+};
+/**
+ * Result of parsing CLI arguments — either success or a usage error.
+ */
+export type ParseArgsResult = {
+    ok: true;
+    args: CliArgs;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parses a raw argument array into typed CLI options.
+ *
+ * @param argv - Arguments to parse (typically `process.argv.slice(2)`)
+ * @returns Parsed result or an error message for usage errors
+ */
+export declare function parseArgs(argv: string[]): ParseArgsResult;
+//# sourceMappingURL=args.d.ts.map

package/dist/cli/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CAyCzD"}

package/dist/cli/format.d.ts

@@ -0,0 +1,20 @@
+/**
+ * CLI output formatting.
+ *
+ * Transforms RollResult into terminal-appropriate strings.
+ *
+ * @module cli/format
+ */
+import type { RollResult } from '../types';
+/**
+ * Formats a roll result for terminal display.
+ *
+ * In normal mode, returns just the total. In verbose mode, returns the
+ * rendered breakdown with terminal-safe formatting for dropped dice.
+ *
+ * @param result - The roll result to format
+ * @param verbose - Whether to show the detailed breakdown
+ * @returns Formatted string for terminal output
+ */
+export declare function formatResult(result: RollResult, verbose: boolean): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/cli/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/cli/format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAMzE"}

package/dist/cli/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for roll-parser.
+ *
+ * @module cli/index
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAEA;;;;GAIG"}