detailed roll option

README.md

@@ -31,7 +31,7 @@ const Dice = require('dice-notation-js');
 
 ## Usage
 
-Exposes two functions, `Dice()` and `Dice.parse()`.
+Exposes three functions, `Dice()`, `Dice.detailed()` and `Dice.parse()`.
 
 ### `Dice()`
 
@@ -68,6 +68,31 @@ Dice('3d6', prng) + 2;
 Dice(3, 6, prng) + 2;
 ```
 
+### `Dice.detailed()`
+
+**Syntax**:
+
+- `Dice.detailed(notation [, randomFunction])`
+- `Dice.detailed(number, type [, randomFunction])`
+
+Takes a string of dice notation, rolls it like `Dice()`, but returns additional details for your use.
+
+**Arguments**:
+
+- `notation` (*string*): You can pass the funciton a string of dice notation, e.g., `3d6+2`, or `1d20`.
+- `number` (*number*): You can pass the function a number of dice to roll and the number of sides each die should have. This argument is the number of dice to roll.
+- `type` (*number*): You can pass the function a number of dice to roll and the number of sides each die should have. This argument is the number of sides each die should have.
+- `randomFunction` (*function*) *optional*: You may pass a function that returns a random number between 0 and 1 that will be used in place of `Math.random()`, such as to use a seedable PRNG.
+
+**Examples**
+
+```javascript
+var roll = Dice.detailed('3d6+10');
+
+console.log(roll); 
+// -> { number: 3, type: 6, modifier: 10, rolls: [ 2, 1, 6 ], result: 19 } 
+```
+
 ### `Dice.parse()`
 
 **Syntax**: `Dice.parse(notation)`

dice.js

@@ -54,13 +54,18 @@
         if (!rnd) {
             rnd = Math.random;
         }
+        var rolls = [];
         var result = 0;
         for (var i = 0; i < a; i++) {
             var die = 0;
             die = Math.floor(rnd() * b) + 1;
             result += die;
+            rolls.push(die);
         }
-        return result;
+        return {
+            rolls : rolls,
+            result : result
+        };
     }
 
     function rollMe (a, b, rnd) {
@@ -79,13 +84,23 @@
         if (typeof b === 'function') {
             rnd = b;
         }
-        return roll(toRoll.number, toRoll.type, rnd) + toRoll.modifier;
+        var rolled = roll(toRoll.number, toRoll.type, rnd);
+        rolled.result += toRoll.modifier;
+        Object.assign(toRoll, rolled);
+        return toRoll;
     }
 
-    var Dice = rollMe;
+    function Dice (a, b, rnd) {
+        return rollMe(a, b, rnd).result;
+    }
+
+    function detailedRoll (a, b, rnd) {
+        return rollMe(a, b, rnd);
+    }
 
     Object.assign(Dice, {
-        parse : parse
+        parse : parse,
+        detailed : detailedRoll
     });
 
     return Dice;

test.js

@@ -41,6 +41,22 @@ describe('Dice()', function () {
     });
 });
 
+describe('Dice.detailed()', function () {
+    it('should create accurate, detailed rolls', function () {
+        var detailed = dice.detailed('3d6 + 10', prng);
+        console.log(detailed);
+        assert.strictEqual(3, detailed.rolls.length);
+        assert.strictEqual(3, detailed.number);
+        assert.strictEqual(10, detailed.modifier);
+        assert.strictEqual(19, detailed.result);
+    });
+    it('should output a valid object', function () {
+        var detailed = dice.detailed('1d4', prng);
+        assert.strictEqual("object", typeof detailed);
+        assert.strictEqual('{"number":1,"type":4,"modifier":0,"rolls":[3],"result":3}', JSON.stringify(detailed));
+    });
+});
+
 describe('Dice.parse()', function () {
     const parse = dice.parse('3d6');
     const parsePos = dice.parse('3d6+2');