@dice-o-rolla/dice-core 0.1.0 → 0.2.0

package/README.md

@@ -9,8 +9,11 @@ building a custom engine composition or consuming the domain model independently
 ```ts
 import { parseNotation, SeededRandomSource } from '@dice-o-rolla/dice-core';
 
-const expression = parseNotation('2d20 + 4');
+const expression = parseNotation('4d20kh3s{1=-2,17..19=1,20=2} + 1');
 const random = new SeededRandomSource(42);
 ```
 
+Standard dice terms support `kh`, `kl`, `dh`, and `dl` selection followed by an optional score map.
+Unlisted faces score zero. Paired percentile and d66 terms intentionally reject these operations.
+
 Licensed under Apache-2.0. See `LICENSE`, `NOTICE`, and `THIRD_PARTY_NOTICES.md` in the package.

package/dist/dice/types.d.ts

@@ -18,10 +18,14 @@ export interface DiceComponentResult {
 export interface StandardDieResult extends BaseDieResult {
     readonly type: Exclude<DieType, 'd100'>;
     readonly component?: never;
+    readonly included?: boolean;
+    readonly score?: number;
 }
 export interface ComponentDieResult extends BaseDieResult {
     readonly type: DieType;
     readonly component: DiceComponentResult;
+    readonly included?: never;
+    readonly score?: never;
 }
 export type DieResult = StandardDieResult | ComponentDieResult;
 export declare function isDieType(value: unknown): value is DieType;

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export type { DiceComponentResult, DiceComponentRole, ComponentDieResult, DieDef
 export { isDieType, STANDARD_DIE_TYPES } from './dice/types.js';
 export { TypedEventEmitter } from './events/typed-event-emitter.js';
 export type { QuaternionLike, Vector3Like } from './math/types.js';
-export type { DiceExpression, ModifierExpression, PairedDiceExpression, PairedDiceType, RollExpression, RollNotation, } from './notation/ast.js';
+export type { DiceExpression, DiceScoreRule, DiceSelection, DiceSelectionOperator, ModifierExpression, PairedDiceExpression, PairedDiceType, RollExpression, RollNotation, } from './notation/ast.js';
 export { NotationParseError } from './notation/errors.js';
 export type { NotationParseErrorCode } from './notation/errors.js';
 export { parseNotation } from './notation/parser.js';

package/dist/notation/ast.d.ts

@@ -1,7 +1,19 @@
+export type DiceSelectionOperator = 'kh' | 'kl' | 'dh' | 'dl';
+export interface DiceSelection {
+    readonly operator: DiceSelectionOperator;
+    readonly count: number;
+}
+export interface DiceScoreRule {
+    readonly minimum: number;
+    readonly maximum: number;
+    readonly score: number;
+}
 export interface DiceExpression {
     readonly kind: 'dice';
     readonly count: number;
     readonly sides: number;
+    readonly selection?: DiceSelection;
+    readonly score?: readonly DiceScoreRule[];
 }
 export type PairedDiceType = 'd100' | 'd66';
 export interface PairedDiceExpression {

package/dist/notation/errors.d.ts

@@ -1,4 +1,4 @@
-export type NotationParseErrorCode = 'EMPTY_NOTATION' | 'EXPECTED_OPERATOR' | 'EXPECTED_TERM' | 'INVALID_COUNT' | 'INVALID_SIDES' | 'NEGATIVE_DICE' | 'UNSAFE_INTEGER' | 'UNEXPECTED_CHARACTER';
+export type NotationParseErrorCode = 'EMPTY_NOTATION' | 'EXPECTED_OPERATOR' | 'EXPECTED_TERM' | 'INVALID_COUNT' | 'INVALID_DICE_OPERATION' | 'INVALID_SCORE_RULE' | 'INVALID_SELECTION' | 'INVALID_SIDES' | 'NEGATIVE_DICE' | 'OVERLAPPING_SCORE_RULE' | 'UNSAFE_INTEGER' | 'UNEXPECTED_CHARACTER';
 export declare class NotationParseError extends Error {
     readonly code: NotationParseErrorCode;
     readonly index: number;

package/dist/notation/parser.js

@@ -62,6 +62,7 @@ class NotationParser {
             }
             if (this.#current() === '%') {
                 this.#index += 1;
+                this.#assertNoPairedDiceOperations();
                 return {
                     kind: 'paired-dice',
                     count,
@@ -78,17 +79,18 @@ class NotationParser {
                 this.#failAt('INVALID_SIDES', 'A die must have at least two sides', sidesStart);
             }
             if (sides === 100 || sides === 66) {
+                this.#assertNoPairedDiceOperations();
                 return {
                     kind: 'paired-dice',
                     count,
                     type: `d${sides}`,
                 };
             }
-            return {
+            return this.#readDiceOperations({
                 kind: 'dice',
                 count,
                 sides,
-            };
+            });
         }
         if (integerStart === integerEnd) {
             const character = this.#current();
@@ -103,6 +105,136 @@ class NotationParser {
             value,
         };
     }
+    #readDiceOperations(expression) {
+        this.#skipWhitespace();
+        const selection = this.#startsSelection() ? this.#readSelection(expression.count) : undefined;
+        this.#skipWhitespace();
+        const score = this.#current()?.toLowerCase() === 's' ? this.#readScoreRules(expression.sides) : undefined;
+        this.#skipWhitespace();
+        if (this.#startsSelection() || this.#current()?.toLowerCase() === 's') {
+            this.#fail('INVALID_DICE_OPERATION', 'Dice operations must contain at most one keep/drop operator followed by one score map');
+        }
+        return {
+            ...expression,
+            ...(selection === undefined ? {} : { selection }),
+            ...(score === undefined ? {} : { score }),
+        };
+    }
+    #readSelection(diceCount) {
+        const start = this.#index;
+        const first = this.#current()?.toLowerCase();
+        const second = this.#peek(1)?.toLowerCase();
+        if ((first !== 'k' && first !== 'd') || (second !== 'h' && second !== 'l')) {
+            return this.#failAt('INVALID_SELECTION', 'Expected kh, kl, dh, or dl', start);
+        }
+        const operator = `${first}${second}`;
+        this.#index += 2;
+        this.#skipWhitespace();
+        const countStart = this.#index;
+        this.#consumeDigits();
+        if (countStart === this.#index) {
+            this.#failAt('INVALID_SELECTION', `Selection ${operator} requires a count`, start);
+        }
+        const count = this.#readInteger(countStart, this.#index, 'selection count');
+        if (count < 1) {
+            this.#failAt('INVALID_SELECTION', 'Selection count must be at least one', countStart);
+        }
+        const keepsDice = operator === 'kh' || operator === 'kl';
+        if ((keepsDice && count > diceCount) || (!keepsDice && count >= diceCount)) {
+            this.#failAt('INVALID_SELECTION', keepsDice
+                ? 'Cannot keep more dice than the term rolls'
+                : 'Drop count must leave at least one die', countStart);
+        }
+        return { operator, count };
+    }
+    #readScoreRules(sides) {
+        const operationStart = this.#index;
+        this.#index += 1;
+        this.#skipWhitespace();
+        if (this.#current() !== '{') {
+            this.#failAt('INVALID_SCORE_RULE', 'Score notation requires "{" after "s"', operationStart);
+        }
+        this.#index += 1;
+        this.#skipWhitespace();
+        if (this.#current() === '}') {
+            this.#fail('INVALID_SCORE_RULE', 'Score map must contain at least one rule');
+        }
+        const rules = [];
+        while (true) {
+            const ruleStart = this.#index;
+            const minimum = this.#readScoreFace();
+            this.#skipWhitespace();
+            let maximum = minimum;
+            if (this.#current() === '.') {
+                if (this.#peek(1) !== '.') {
+                    this.#fail('INVALID_SCORE_RULE', 'Score ranges must use ".."');
+                }
+                this.#index += 2;
+                this.#skipWhitespace();
+                maximum = this.#readScoreFace();
+            }
+            if (minimum > maximum) {
+                this.#failAt('INVALID_SCORE_RULE', 'Score range minimum must not exceed its maximum', ruleStart);
+            }
+            if (minimum < 1 || maximum > sides) {
+                this.#failAt('INVALID_SCORE_RULE', `Score rule faces must be within [1, ${sides}]`, ruleStart);
+            }
+            this.#skipWhitespace();
+            if (this.#current() !== '=') {
+                this.#fail('INVALID_SCORE_RULE', 'Score rule requires "=" before its score');
+            }
+            this.#index += 1;
+            this.#skipWhitespace();
+            const score = this.#readSignedScore();
+            if (rules.some((rule) => minimum <= rule.maximum && maximum >= rule.minimum)) {
+                this.#failAt('OVERLAPPING_SCORE_RULE', 'Score rule ranges must not overlap', ruleStart);
+            }
+            rules.push({ minimum, maximum, score });
+            this.#skipWhitespace();
+            if (this.#current() === '}') {
+                this.#index += 1;
+                return Object.freeze(rules.map((rule) => Object.freeze(rule)));
+            }
+            if (this.#current() !== ',') {
+                this.#fail('INVALID_SCORE_RULE', 'Score rules must be separated by commas');
+            }
+            this.#index += 1;
+            this.#skipWhitespace();
+            if (this.#current() === '}') {
+                this.#fail('INVALID_SCORE_RULE', 'Score map must not have a trailing comma');
+            }
+        }
+    }
+    #readScoreFace() {
+        const start = this.#index;
+        this.#consumeDigits();
+        if (start === this.#index) {
+            this.#fail('INVALID_SCORE_RULE', 'Score rule requires a face value');
+        }
+        return this.#readInteger(start, this.#index, 'score rule face');
+    }
+    #readSignedScore() {
+        const sign = this.#current() === '-' ? -1 : 1;
+        if (this.#current() === '-' || this.#current() === '+')
+            this.#index += 1;
+        const start = this.#index;
+        this.#consumeDigits();
+        if (start === this.#index) {
+            this.#fail('INVALID_SCORE_RULE', 'Score rule requires an integer score');
+        }
+        return this.#readInteger(start, this.#index, 'score') * sign;
+    }
+    #assertNoPairedDiceOperations() {
+        this.#skipWhitespace();
+        if (this.#startsSelection() || this.#current()?.toLowerCase() === 's') {
+            this.#fail('INVALID_DICE_OPERATION', 'Keep/drop and score operations are not supported for paired dice');
+        }
+    }
+    #startsSelection() {
+        const first = this.#current()?.toLowerCase();
+        const second = this.#peek(1)?.toLowerCase();
+        return (first === 'k' || first === 'd') && (second === 'h' || second === 'l');
+    }
     #readInteger(start, end, description) {
         const value = Number(this.#input.slice(start, end));
         if (!Number.isSafeInteger(value)) {
@@ -123,6 +255,9 @@ class NotationParser {
     #current() {
         return this.#input[this.#index];
     }
+    #peek(offset) {
+        return this.#input[this.#index + offset];
+    }
     #isAtEnd() {
         return this.#index >= this.#input.length;
     }

package/dist/roll/aggregation.js

@@ -8,10 +8,7 @@ export function createRollResult(options) {
     if (options.completedAt < options.startedAt) {
         throw new RangeError('Roll completion time must not precede its start time');
     }
-    const dice = Object.freeze(options.dice.map((die) => Object.freeze({
-        ...die,
-        ...(die.component === undefined ? {} : { component: Object.freeze({ ...die.component }) }),
-    })));
+    const dice = Object.freeze(options.dice.map(freezeDieResult));
     const diceTotal = getDiceTotal(dice);
     return Object.freeze({
         id: options.id,
@@ -23,15 +20,24 @@ export function createRollResult(options) {
         completedAt: options.completedAt,
     });
 }
+function freezeDieResult(die) {
+    if (die.component === undefined)
+        return Object.freeze({ ...die });
+    return Object.freeze({ ...die, component: Object.freeze({ ...die.component }) });
+}
 function getDiceTotal(dice) {
     let total = 0;
     const groups = new Map();
     for (const die of dice) {
         const component = die.component;
         if (component === undefined) {
-            total += die.value;
+            if (die.included !== false)
+                total += die.score ?? die.value;
             continue;
         }
+        if (die.included !== undefined || die.score !== undefined) {
+            throw new RangeError('Keep/drop and score metadata is not supported on paired dice components');
+        }
         const existing = groups.get(component.groupId);
         const group = existing ?? { type: component.groupType };
         if (group.type !== component.groupType) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dice-o-rolla/dice-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Framework-neutral dice notation, roll results, events, and random sources.",
   "keywords": [
     "dice",
@@ -8,7 +8,16 @@
     "rpg",
     "typescript"
   ],
+  "homepage": "https://github.com/creepiest-space/dice-o-rolla#readme",
+  "bugs": {
+    "url": "https://github.com/creepiest-space/dice-o-rolla/issues"
+  },
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/creepiest-space/dice-o-rolla.git",
+    "directory": "packages/dice-core"
+  },
   "files": [
     "dist",
     "README.md",