Radical Overhaul of exports and internal mechanics (#643)

RANDSUM_DICE_NOTATION.md

@@ -60,7 +60,7 @@ roll({
 })
 ```
 
-### Custom Sides
+### Custom Faces
 
 ---
 
@@ -86,16 +86,16 @@ roll({
 })
 ```
 
-Note: When using custom sides with Randsum Dice Notation, we can only mark sides as single characters. When using full options, you can pass in strings of any length!
+Note: When using custom faces with Randsum Dice Notation, we can only mark faces as single characters. When using full options, you can pass in strings of any length!
 
-#### Custom Sides Caveats and Gotchas
+#### Custom Faces Caveats and Gotchas
 
 - Whenever _any_ dice pool leverages custom dice, the `total` of the `RandsumRollResult` will be `0`.
 - Modifiers are not compatible with custom sides. Under-the-hood, `randsum` is still rolling these as if they were numeric dice, then swapping out the numbers for faces at the end. While modifiers are technically feasible, it would be very easy to code yourself into a confusing place with non-obvious results.
   - for example, given the custom faces argument `[6, 5, 4, 3, 2, 1]`, `1` would be considered the "highest" number, and `6` the "lowest`, which would be silly!
   - In light of this, modifiers are ignored (if provided in JS) or rejected (in TS) when providing custom sides.
 
-### Plus
+### add
 
 ---
 
@@ -118,11 +118,11 @@ roll('6d20+5')
 roll({
   sides: 20,
   quantity: 6,
-  modifiers: { plus: 5 }
+  modifiers: { add: 5 }
 })
 ```
 
-### Minus
+### subtract
 
 **Key: `-`**
 
@@ -143,7 +143,7 @@ roll('6d20-5')
 roll({
   sides: 20,
   quantity: 6,
-  modifiers: { minus: 5 }
+  modifiers: { subtract: 5 }
 })
 ```
 

build.ts

@@ -1,10 +1,20 @@
 import dts from 'bun-plugin-dts'
 
-await Bun.build({
+const results = await Bun.build({
   entrypoints: ['./src/index.ts'],
   outdir: './dist',
-  target: 'node',
   splitting: true,
   sourcemap: 'inline',
   plugins: [dts()]
 })
+
+if (results.success == false) {
+  console.error('Build failed')
+  for (const message of results.logs) {
+    console.error(message)
+  }
+} else {
+  console.log('Compiled ' + results.outputs.length + ' javascript files...')
+}
+
+export {}

package.json

@@ -62,19 +62,22 @@
     }
   ],
   "devDependencies": {
-    "@eslint/js": "^9.14.0",
+    "@eslint/js": "^9.17.0",
     "@size-limit/preset-small-lib": "^11.1.6",
     "@types/eslint__js": "^8.42.3",
     "@typescript-eslint/eslint-plugin": "^5.62.0",
     "@typescript-eslint/parser": "^5.62.0",
     "bun-plugin-dts": "^0.3.0",
     "bun-types": "latest",
-    "eslint": "^9.14.0",
-    "prettier": "^3.3.3",
+    "eslint": "^9.17.0",
+    "prettier": "^3.4.2",
     "size-limit": "^11.1.6",
-    "typescript": "^5.6.3",
-    "typescript-eslint": "^8.13.0",
-    "typedoc": "^0.27.2"
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.18.1",
+    "typedoc": "^0.27.5"
+  },
+  "dependencies": {
+    "uuid": "^11.0.3"
   },
   "type": "module"
 }

src/dice/D.ts

@@ -0,0 +1,23 @@
+import { RollConfig } from '~src/types'
+import { coreRandom } from '~src/utils/coreRandom'
+
+export class D {
+  constructor(public sides: number) {
+    this.sides = sides
+  }
+
+  toRollConfig(): RollConfig {
+    return {
+      sides: this.sides,
+      quantity: 1
+    }
+  }
+
+  roll(): number {
+    return coreRandom(this.sides)
+  }
+
+  rollMany(quantity: number): number[] {
+    return Array.from({ length: quantity }, () => this.roll())
+  }
+}

src/dice/__tests__/D.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'bun:test'
+import { D } from '../D'
+
+describe('D', () => {
+  test('.sides returns the number given as sides', () => {
+    const sides = 6
+    const die = new D(sides)
+
+    expect(die.sides).toEqual(sides)
+  })
+
+  test('.roll() returns a number included in the constructor', () => {
+    const sides = 6
+    const die = new D(sides)
+
+    expect([1, 2, 3, 4, 5, 6]).toContain(die.roll())
+  })
+
+  test('.rollMany() returns an array of numbers ', () => {
+    const sides = 6
+    const die = new D(sides)
+    const quantity = 10
+    const rolls = die.rollMany(quantity)
+
+    expect(rolls.length).toEqual(quantity)
+    rolls.forEach((roll) => expect([1, 2, 3, 4, 5, 6]).toContain(roll))
+  })
+
+  test('toConfig() returns a RollConfig object', () => {
+    const sides = 6
+    const die = new D(sides)
+    const config = die.toRollConfig()
+
+    expect(config).toEqual({
+      sides,
+      quantity: 1
+    })
+  })
+})

src/dice/__tests__/dice.test.ts

@@ -0,0 +1,32 @@
+import { D10, D100, D12, D20, D4, D6, D8 } from '../dice'
+import { describe, expect, test } from 'bun:test'
+
+describe('exported dice', () => {
+  test('D4 should be a D with 4 sides', () => {
+    expect(D4.sides).toEqual(4)
+  })
+
+  test('D6 should be a D with 6 sides', () => {
+    expect(D6.sides).toEqual(6)
+  })
+
+  test('D8 should be a D with 8 sides', () => {
+    expect(D8.sides).toEqual(8)
+  })
+
+  test('D10 should be a D with 10 sides', () => {
+    expect(D10.sides).toEqual(10)
+  })
+
+  test('D12 should be a D with 12 sides', () => {
+    expect(D12.sides).toEqual(12)
+  })
+
+  test('D20 should be a D with 20 sides', () => {
+    expect(D20.sides).toEqual(20)
+  })
+
+  test('D100 should be a D with 100 sides', () => {
+    expect(D100.sides).toEqual(100)
+  })
+})

src/premadeDice.ts → src/dice/dice.ts

@@ -1,4 +1,4 @@
-import { D } from '~src/D'
+import { D } from './D'
 
 export const D4 = new D(4)
 export const D6 = new D(6)
@@ -7,6 +7,3 @@ export const D10 = new D(10)
 export const D12 = new D(12)
 export const D20 = new D(20)
 export const D100 = new D(100)
-
-export const Coin = new D(['Heads', 'Tails'])
-export const FudgeDice = new D(['+', '+', '+', '-', ' ', ' '])

src/dice/index.ts

@@ -0,0 +1,2 @@
+export { D } from './D'
+export * from './dice'

src/faces/__tests__/rollCustomFaces.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'bun:test'
+import { rollCustomFaces } from '../rollCustomFaces'
+
+import { CustomFacesD } from '../customFacesD'
+
+const loops = 9999
+
+describe('roll', () => {
+  describe('Stress Test', () => {
+    describe('custom dice and numerical dice mixed', () => {
+      const dummyArray = Array.from(
+        { length: loops },
+        () =>
+          rollCustomFaces(
+            20,
+            { sides: 20 },
+            new CustomFacesD(['H', 'T']),
+            '2d20'
+          ).result
+      )
+
+      test('returns an array of strings', () => {
+        dummyArray.forEach((individualRolls) => {
+          expect(individualRolls).toHaveLength(5)
+          individualRolls.flat().forEach((individualRoll) => {
+            expect(individualRoll).toSatisfy(
+              (value) => typeof value === 'string'
+            )
+          })
+        })
+      })
+    })
+  })
+})

src/faces/__tests__/utils/customNotificationToCustomRollConfig.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'bun:test'
+import { customFacesNotationToCustomFacesRollConfig } from '../../utils/customFacesNotationToCustomFacesRollConfig'
+
+describe('customNotificationToCustomFacesRollConfig', () => {
+  describe('given standard dice notation', () => {
+    const argument = '2d6'
+
+    it('returns a valid custom roll config', () => {
+      const result = customFacesNotationToCustomFacesRollConfig(argument)
+
+      expect(result).toEqual({
+        faces: ['1', '2', '3', '4', '5', '6'],
+        quantity: 2,
+        sides: 6
+      })
+    })
+  })
+
+  describe('given custom dice notation', () => {
+    const argument = '2d{++  --}'
+
+    it('returns a valid custom roll config', () => {
+      const result = customFacesNotationToCustomFacesRollConfig(argument)
+
+      expect(result).toEqual({
+        faces: ['+', '+', ' ', ' ', '-', '-'],
+        quantity: 2,
+        sides: 6
+      })
+    })
+  })
+})

src/faces/__tests__/validateCustomFacesNotation.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'bun:test'
+import { CustomFacesDiceNotation } from '../types'
+import { validateCustomFacesNotation } from '../validateCustomFacesNotation'
+
+describe('validateCustomFacesNotation', () => {
+  describe('when given a valid custom dice notation', () => {
+    const notation: CustomFacesDiceNotation = '2d{HT}'
+
+    it('returns a valid result', () => {
+      const result = validateCustomFacesNotation(notation)
+
+      expect(result).toEqual({
+        valid: true,
+        argument: notation,
+        notation: '2d{HT}',
+        config: {
+          sides: 2,
+          quantity: 2,
+          faces: ['H', 'T']
+        },
+        description: ['Roll 2 2-sided dice', 'with faces: H, T']
+      })
+    })
+  })
+
+  describe('when the notation is completely invalid', () => {
+    const notation = 'invalid-notation'
+
+    it('returns an error result', () => {
+      const result = validateCustomFacesNotation(notation)
+
+      expect(result).toEqual({
+        valid: false,
+        argument: notation,
+        notation: undefined,
+        config: undefined,
+        description: undefined
+      })
+    })
+  })
+})