@platonic-dice/dice 2.0.0

package/README.md

@@ -0,0 +1,50 @@
+# @platonic-dice/dice
+
+Persistent dice objects with roll history and TypeScript support. This package builds on top of `@platonic-dice/core` and provides classes such as `Die` which maintain roll history, validators, and utilities for consuming applications.
+
+## Installation
+
+```bash
+npm install @platonic-dice/dice
+```
+
+## Usage
+
+CommonJS:
+
+```js
+const { Die } = require("@platonic-dice/dice");
+const { DieType } = require("@platonic-dice/core");
+
+const d20 = new Die(DieType.D20);
+console.log(d20.roll());
+console.log(d20.history.getAll());
+```
+
+TypeScript:
+
+```ts
+import { Die } from "@platonic-dice/dice";
+import { DieType } from "@platonic-dice/core";
+
+const d20 = new Die(DieType.D20);
+console.log(d20.roll());
+```
+
+## Build
+
+This package is written in TypeScript and compiles to `dist/`.
+
+```bash
+cd packages/dice
+npm run build
+```
+
+## Notes on publishing
+
+- This package depends on `@platonic-dice/core`. When publishing both packages in the same release, ensure both `package.json` versions are bumped to the same release tag (the repository's release workflow can publish matching versions automatically).
+- The package is scoped (`@platonic-dice/dice`) — make sure the npm scope exists for your account or organization before publishing.
+
+## License
+
+MIT — see the repository `LICENSE` file.

package/dist/__tests__/components/die-history/history-cache.spec.js

@@ -0,0 +1,106 @@
+/// <reference types="vitest" />
+import { describe, it, expect, beforeEach } from "vitest";
+import { HistoryCache } from "@dice/components/die-history";
+describe("RollHistoryCache", () => {
+    let cache;
+    beforeEach(() => {
+        cache = new HistoryCache({
+            maxRecordsPerKey: 3,
+            maxKeys: 2,
+        });
+    });
+    it("starts empty", () => {
+        expect(cache.activeManager).toBeUndefined();
+        expect(cache.getAll()).toEqual([]);
+    });
+    it("throws if add called before setting active key", () => {
+        expect(() => cache.add({ roll: 1, timestamp: new Date() })).toThrow(/No active history key set/);
+    });
+    it("creates and sets an active key", () => {
+        cache.setActiveKey("first");
+        expect(cache.activeManager).toBeDefined();
+        expect(cache.getAll()).toEqual([]);
+    });
+    it("adds records to the active key", () => {
+        cache.setActiveKey("key1");
+        const record = { roll: 5, timestamp: new Date() };
+        cache.add(record);
+        const all = cache.getAll(true);
+        expect(all.length).toBe(1);
+        expect(all[0].roll).toBe(5);
+    });
+    it("respects maxRecordsPerKey", () => {
+        cache.setActiveKey("key1");
+        const now = new Date();
+        for (let i = 1; i <= 5; i++) {
+            cache.add({ roll: i, timestamp: new Date(now.getTime() + i) });
+        }
+        const all = cache.getAll(true);
+        expect(all.length).toBe(3); // capped
+        expect(all[0].roll).toBe(3); // oldest removed
+        expect(all[2].roll).toBe(5);
+    });
+    it("switching keys creates independent histories", () => {
+        cache.setActiveKey("A");
+        cache.add({ roll: 1, timestamp: new Date() });
+        cache.setActiveKey("B");
+        cache.add({ roll: 2, timestamp: new Date() });
+        cache.setActiveKey("A");
+        expect(cache.getAll(true)[0].roll).toBe(1);
+        cache.setActiveKey("B");
+        expect(cache.getAll(true)[0].roll).toBe(2);
+    });
+    it("evicts oldest key when maxKeys exceeded", () => {
+        cache.setActiveKey("K1");
+        cache.add({ roll: 1, timestamp: new Date() });
+        cache.setActiveKey("K2");
+        cache.add({ roll: 2, timestamp: new Date() });
+        // Max keys = 2, next key should evict K1
+        cache.setActiveKey("K3");
+        cache.add({ roll: 3, timestamp: new Date() });
+        const report = cache.report({ verbose: true });
+        expect(Object.keys(report)).not.toContain("K1");
+        expect(Object.keys(report)).toContain("K2");
+        expect(Object.keys(report)).toContain("K3");
+    });
+    it("clearActive clears only the active key", () => {
+        cache.setActiveKey("A");
+        cache.add({ roll: 1, timestamp: new Date() });
+        cache.setActiveKey("B");
+        cache.add({ roll: 2, timestamp: new Date() });
+        cache.setActiveKey("A");
+        cache.clearActive();
+        expect(cache.getAll(true)).toEqual([]);
+        cache.setActiveKey("B");
+        expect(cache.getAll(true).length).toBe(1);
+    });
+    it("clearAll clears everything", () => {
+        cache.setActiveKey("X");
+        cache.add({ roll: 1, timestamp: new Date() });
+        cache.setActiveKey("Y");
+        cache.add({ roll: 2, timestamp: new Date() });
+        cache.clearAll();
+        expect(cache.getAll()).toEqual([]);
+        expect(Object.keys(cache.report())).toEqual([]);
+    });
+    it("report returns correct verbose and non-verbose data", () => {
+        cache.setActiveKey("R1");
+        cache.add({ roll: 10, timestamp: new Date() });
+        const reportsVerbose = cache.report({ verbose: true });
+        const reportsNonVerbose = cache.report({ verbose: false });
+        expect(reportsVerbose["R1"][0]).toHaveProperty("timestamp");
+        expect(reportsNonVerbose["R1"][0]).not.toHaveProperty("timestamp");
+    });
+    it("toString returns a readable summary", () => {
+        cache.setActiveKey("Active");
+        expect(cache.toString()).toMatch(/HistoryCache: 1 keys \(active: Active\)/);
+    });
+    it("toJSON returns object with arrays of RollRecords", () => {
+        cache.setActiveKey("J");
+        const record = { roll: 7, timestamp: new Date() };
+        cache.add(record);
+        const json = cache.toJSON();
+        expect(json).toHaveProperty("J");
+        expect(json["J"][0].roll).toBe(7);
+    });
+});

package/dist/__tests__/components/die-history/internal/roll-record-manager/internal/roll-record-storage.spec.js

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import RollRecordStorage from "@dice/components/die-history/internal/roll-record-manager/internal/roll-record-storage";
+describe("RollRecordStorage", () => {
+    it("evicts oldest when capacity exceeded", () => {
+        const s = new RollRecordStorage(2);
+        s.add({ roll: 1, timestamp: new Date() });
+        s.add({ roll: 2, timestamp: new Date() });
+        s.add({ roll: 3, timestamp: new Date() });
+        expect(s.size).toBe(2);
+        expect(s.full.map((r) => r.roll)).toEqual([2, 3]);
+    });
+    it("last returns correct slice and order", () => {
+        const s = new RollRecordStorage(10);
+        s.add({ roll: 1, timestamp: new Date() });
+        s.add({ roll: 2, timestamp: new Date() });
+        s.add({ roll: 3, timestamp: new Date() });
+        s.add({ roll: 4, timestamp: new Date() });
+        const last2 = s.last(2);
+        expect(last2.map((r) => r.roll)).toEqual([3, 4]);
+    });
+    it("getters return array copies (mutating returned arrays doesn't affect storage)", () => {
+        const s = new RollRecordStorage(3);
+        s.add({ roll: 1, timestamp: new Date() });
+        const full = s.full;
+        full.pop();
+        expect(s.size).toBe(1);
+        const last = s.last(1);
+        // mutating the returned array should not affect internal storage length
+        last.pop();
+        expect(s.size).toBe(1);
+    });
+    it("throws for invalid constructor args and parameters", () => {
+        // call via any to test runtime throw without TS compile errors
+        expect(() => new RollRecordStorage(0)).toThrow(TypeError);
+        const s = new RollRecordStorage(2);
+        expect(() => s.last(0)).toThrow(TypeError);
+        // pass null to add
+        expect(() => s.add(null)).toThrow(TypeError);
+    });
+});

package/dist/__tests__/components/die-history/internal/roll-record-manager/roll-record-manager.spec.js

@@ -0,0 +1,112 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { Outcome } from "@platonic-dice/core";
+import { DEFAULT_MAX_RECORDS, RollRecordManager, } from "@dice/components/die-history/internal";
+describe("RollRecordManager", () => {
+    let manager;
+    const dieRoll = {
+        roll: 5,
+        timestamp: new Date(),
+    };
+    const modifiedDieRoll = {
+        roll: 3,
+        modified: 1,
+        timestamp: new Date(),
+    };
+    const targetDieRoll = {
+        roll: 20,
+        outcome: Outcome.Success,
+        timestamp: new Date(),
+    };
+    beforeEach(() => {
+        manager = new RollRecordManager();
+    });
+    it("should initialize empty with default maxRecords", () => {
+        expect(manager.length).toBe(0);
+        expect(manager.maxRecordsCount).toBe(DEFAULT_MAX_RECORDS);
+        expect(manager.full).toEqual([]);
+        expect(manager.all).toEqual([]);
+    });
+    it("should add DieRollRecord correctly", () => {
+        manager.add(dieRoll);
+        expect(manager.length).toBe(1);
+        expect(manager.full[0]).toEqual(dieRoll);
+        expect(manager.all[0]).toEqual({ roll: dieRoll.roll });
+    });
+    it("should add ModifiedDieRollRecord correctly", () => {
+        manager.add(modifiedDieRoll);
+        expect(manager.length).toBe(1);
+        expect(manager.full[0]).toEqual(modifiedDieRoll);
+        expect(manager.all[0]).toEqual({
+            roll: modifiedDieRoll.roll,
+            modified: modifiedDieRoll.modified,
+        });
+    });
+    it("should add TargetDieRollRecord correctly", () => {
+        manager.add(targetDieRoll);
+        expect(manager.length).toBe(1);
+        expect(manager.full[0]).toEqual(targetDieRoll);
+        expect(manager.all[0]).toEqual({
+            roll: targetDieRoll.roll,
+            outcome: targetDieRoll.outcome,
+        });
+    });
+    it("should throw TypeError for invalid records", () => {
+        // @ts-expect-error testing runtime validation
+        expect(() => manager.add({})).toThrow(TypeError);
+        // @ts-expect-error testing runtime validation
+        expect(() => manager.add(null)).toThrow(TypeError);
+        // @ts-expect-error testing runtime validation
+        expect(() => manager.add({ roll: 5, foo: "bar" })).toThrow(TypeError);
+    });
+    it("should maintain maxRecords correctly", () => {
+        const smallManager = new RollRecordManager(2);
+        smallManager.add({ roll: 1, timestamp: new Date() });
+        smallManager.add({ roll: 2, timestamp: new Date() });
+        smallManager.add({ roll: 3, timestamp: new Date() }); // should push out oldest
+        expect(smallManager.length).toBe(2);
+        expect(smallManager.full.map((r) => r.roll)).toEqual([2, 3]);
+    });
+    it("should return last N records with last()", () => {
+        manager.add(dieRoll);
+        manager.add(modifiedDieRoll);
+        manager.add(targetDieRoll);
+        const lastOne = manager.last();
+        expect(lastOne).toEqual([
+            { roll: targetDieRoll.roll, outcome: targetDieRoll.outcome },
+        ]);
+        const lastTwo = manager.last(2);
+        expect(lastTwo).toEqual([
+            { roll: modifiedDieRoll.roll, modified: modifiedDieRoll.modified },
+            { roll: targetDieRoll.roll, outcome: targetDieRoll.outcome },
+        ]);
+        const verboseLastTwo = manager.last(2, true);
+        expect(verboseLastTwo).toEqual([modifiedDieRoll, targetDieRoll]);
+    });
+    it("should report records with report()", () => {
+        manager.add(dieRoll);
+        manager.add(modifiedDieRoll);
+        manager.add(targetDieRoll);
+        expect(manager.report()).toEqual(manager.all);
+        expect(manager.report({ verbose: true })).toEqual(manager.full);
+        expect(manager.report({ limit: 2 })).toEqual(manager.all.slice(-2));
+        expect(manager.report({ limit: 2, verbose: true })).toEqual(manager.full.slice(-2));
+    });
+    it("should clear records with clear()", () => {
+        manager.add(dieRoll);
+        manager.clear();
+        expect(manager.length).toBe(0);
+        expect(manager.full).toEqual([]);
+    });
+    it("toString() should reflect last roll", () => {
+        expect(manager.toString()).toContain("empty");
+        manager.add(dieRoll);
+        const str = manager.toString();
+        expect(str).toContain("1/");
+        expect(str).toContain(dieRoll.roll.toString());
+        expect(str).toContain(dieRoll.timestamp.toISOString());
+    });
+    it("toJSON() should return full records", () => {
+        manager.add(dieRoll);
+        expect(manager.toJSON()).toEqual(manager.full);
+    });
+});

package/dist/__tests__/components/die-history/internal/roll-record-validator.spec.js

@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest";
+import { Outcome } from "@platonic-dice/core";
+import { isDieRollRecord, isModifiedDieRollRecord, isTargetDieRollRecord, stripTimestamp, } from "@dice/components/die-history/internal";
+describe("RollRecord validator", () => {
+    const now = new Date();
+    const dieRecord = {
+        roll: 5,
+        timestamp: now,
+    };
+    const modifiedRecord = {
+        roll: 10,
+        modified: 12,
+        timestamp: now,
+    };
+    const targetRecord = {
+        roll: 17,
+        outcome: Outcome.Success,
+        timestamp: now,
+    };
+    it("recognises valid shapes", () => {
+        expect(isDieRollRecord(dieRecord)).toBe(true);
+        expect(isModifiedDieRollRecord(modifiedRecord)).toBe(true);
+        expect(isTargetDieRollRecord(targetRecord)).toBe(true);
+    });
+    it("rejects invalid shapes", () => {
+        // missing timestamp
+        expect(isDieRollRecord({ roll: 5 })).toBe(false);
+        // wrong modified type
+        expect(isModifiedDieRollRecord({ roll: 5, modified: "x" })).toBe(false);
+        // invalid outcome
+        expect(isTargetDieRollRecord({ roll: 5, outcome: "nope" })).toBe(false);
+    });
+    it("stripTimestamp removes timestamp and preserves other fields", () => {
+        const stripped = stripTimestamp(dieRecord);
+        expect(stripped.timestamp).toBeUndefined();
+        expect(stripped.roll).toBe(dieRecord.roll);
+    });
+});

package/dist/__tests__/components/die-history/roll-record-factory.spec.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { RollRecordFactory } from "@dice/components/die-history";
+import { DieType } from "@platonic-dice/core";
+describe("RollRecordFactory", () => {
+    const factory = new RollRecordFactory();
+    it("should create a valid DieRollRecord for normal rolls", () => {
+        const record = factory.createNormalRoll(DieType.D6);
+        expect(record).toMatchObject({
+            roll: expect.any(Number),
+            timestamp: expect.any(Date),
+        });
+        expect(record.roll).toBeGreaterThanOrEqual(1);
+        expect(record.roll).toBeLessThanOrEqual(6);
+    });
+    it("should create a valid ModifiedDieRollRecord for modified rolls", () => {
+        const record = factory.createModifiedRoll(DieType.D20, (n) => n + 2);
+        expect(record).toMatchObject({
+            roll: expect.any(Number),
+            modified: expect.any(Number),
+            timestamp: expect.any(Date),
+        });
+        expect(record.roll).toBeGreaterThanOrEqual(1);
+        expect(record.roll).toBeLessThanOrEqual(20);
+        expect(record.modified).toBe(record.roll + 2);
+    });
+    it("should create a valid TestDieRollRecord for test rolls", () => {
+        const record = factory.createTestRoll(DieType.D10, {
+            testType: "at_least",
+            target: 5,
+        });
+        expect(record).toMatchObject({
+            roll: expect.any(Number),
+            outcome: expect.any(String),
+            timestamp: expect.any(Date),
+        });
+        expect(record.roll).toBeGreaterThanOrEqual(1);
+        expect(record.roll).toBeLessThanOrEqual(10);
+        expect(["Success", "Failure"].map((o) => o.toLowerCase())).toContain(record.outcome.toLowerCase());
+    });
+    it("should throw an error for invalid RollType in createNormalRoll", () => {
+        expect(() => factory.createNormalRoll(DieType.D6, "InvalidRollType")).toThrow(TypeError);
+    });
+});

package/dist/__tests__/die.spec.js

@@ -0,0 +1,140 @@
+/// <reference types="vitest" />
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { Die } from "@dice/die";
+import { DieType, RollType, roll as coreRoll, rollMod as coreRollMod, rollTest as coreRollTest, } from "@platonic-dice/core";
+// ------------------------
+// MOCK @platonic-dice/core
+// ------------------------
+vi.mock("@platonic-dice/core", async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        roll: vi.fn(),
+        rollMod: vi.fn(),
+        rollTest: vi.fn(),
+    };
+});
+// ------------------------
+// TEST SUITE
+// ------------------------
+describe("Die class", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    // ---------------------
+    // CONSTRUCTOR VALIDATION
+    // ---------------------
+    it("creates a die with a valid type", () => {
+        const die = new Die(DieType.D6);
+        expect(die.type).toBe(DieType.D6);
+        expect(die.result).toBe(undefined);
+        expect(die.history("normal")).toEqual([]);
+    });
+    it("throws for invalid die type", () => {
+        expect(() => new Die("INVALID")).toThrowError(/Invalid die type/);
+    });
+    // ---------------------
+    // FACE COUNT
+    // ---------------------
+    it("returns the correct faceCount", () => {
+        expect(new Die(DieType.D4).faceCount).toBe(4);
+        expect(new Die(DieType.D6).faceCount).toBe(6);
+        expect(new Die(DieType.D20).faceCount).toBe(20);
+    });
+    // ---------------------
+    // BASIC ROLL
+    // ---------------------
+    it("rolls and records a basic DieRollRecord", () => {
+        const die = new Die(DieType.D6);
+        coreRoll.mockReturnValue(4);
+        const result = die.roll();
+        expect(result).toBe(4);
+        expect(die.result).toBe(4);
+        const history = die.history("normal", true);
+        expect(history.length).toBe(1);
+        expect(history[0]).toMatchObject({ roll: 4 });
+    });
+    it("passes through rollType to coreRoll()", () => {
+        const die = new Die(DieType.D20);
+        coreRoll.mockReturnValue(17);
+        die.roll(RollType.Advantage);
+        expect(coreRoll).toHaveBeenCalledWith(DieType.D20, RollType.Advantage);
+    });
+    it("throws for invalid rollType", () => {
+        const die = new Die(DieType.D8);
+        expect(() => die.roll("INVALID")).toThrowError(/Invalid roll type/);
+    });
+    // ---------------------
+    // MODIFIED ROLL
+    // ---------------------
+    it("rollMod records ModifiedDieRollRecord", () => {
+        const die = new Die(DieType.D6);
+        coreRollMod.mockReturnValue({ base: 3, modified: 5 });
+        const result = die.rollMod((n) => n + 2);
+        expect(result).toBe(5);
+        expect(die.result).toBe(5);
+        const history = die.history("modifier", true);
+        expect(history.length).toBe(1);
+        expect(history[0]).toMatchObject({ roll: 3, modified: 5 });
+    });
+    // ---------------------
+    // TEST ROLL
+    // ---------------------
+    it("rollTest records TargetDieRollRecord", () => {
+        const die = new Die(DieType.D6);
+        coreRollTest.mockReturnValue({ base: 4, outcome: "success" });
+        const result = die.rollTest({ testType: "at_least", target: 3 });
+        expect(result).toBe(4);
+        expect(die.result).toBe(4);
+        const history = die.history("test", true);
+        expect(history.length).toBe(1);
+        expect(history[0]).toMatchObject({ roll: 4, outcome: "success" });
+    });
+    // ---------------------
+    // HISTORY ACCESS
+    // ---------------------
+    it("history returns timestamp-stripped records when verbose=false", () => {
+        const die = new Die(DieType.D6);
+        coreRoll.mockReturnValue(2);
+        die.roll();
+        const hist = die.history("normal", false);
+        expect(hist[0]).not.toHaveProperty("timestamp");
+        const histVerbose = die.history("normal", true);
+        expect(histVerbose[0]).toHaveProperty("timestamp");
+    });
+    // ---------------------
+    // RESET
+    // ---------------------
+    it("reset clears latest result and optionally all histories", () => {
+        const die = new Die(DieType.D6);
+        coreRoll.mockReturnValue(5);
+        die.roll();
+        die.reset();
+        expect(die.result).toBeUndefined();
+        die.roll();
+        die.reset(true);
+        expect(die.result).toBeUndefined();
+        expect(die.history("normal")).toEqual([]);
+        expect(die.history("modifier")).toEqual([]);
+        expect(die.history("test")).toEqual([]);
+    });
+    // ---------------------
+    // toString / toJSON
+    // ---------------------
+    it("toString reports correctly", () => {
+        const die = new Die(DieType.D6);
+        expect(die.toString()).toMatch(/not rolled yet/);
+        coreRoll.mockReturnValue(3);
+        die.roll();
+        expect(die.toString()).toMatch(/latest=3/);
+    });
+    it("toJSON returns all histories keyed by type", () => {
+        const die = new Die(DieType.D6);
+        coreRoll.mockReturnValue(4);
+        die.roll();
+        const json = die.toJSON();
+        expect(json).toHaveProperty("normal");
+        expect(json.normal.length).toBe(1);
+        expect(json.normal[0]).toMatchObject({ roll: 4 });
+    });
+});

package/dist/__tests__/types/roll-record.types.spec.js

@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vitest";
+import { Outcome } from "@platonic-dice/core/entities";
+describe("RollRecord types (runtime shape validation)", () => {
+    const now = new Date();
+    const dieRecord = {
+        roll: 5,
+        timestamp: now,
+    };
+    const modifiedRecord = {
+        roll: 10,
+        modified: 12,
+        timestamp: now,
+    };
+    const targetRecord = {
+        roll: 17,
+        outcome: Outcome.Success,
+        timestamp: now,
+    };
+    it("should have the correct shape for DieRollRecord", () => {
+        expect(dieRecord).toHaveProperty("roll");
+        expect(dieRecord).toHaveProperty("timestamp");
+        expect(dieRecord.timestamp).toBeInstanceOf(Date);
+        expect(Object.keys(dieRecord)).toHaveLength(2);
+    });
+    it("should have the correct shape for ModifiedDieRollRecord", () => {
+        expect(modifiedRecord).toHaveProperty("roll");
+        expect(modifiedRecord).toHaveProperty("modified");
+        expect(modifiedRecord).toHaveProperty("timestamp");
+        expect(modifiedRecord.timestamp).toBeInstanceOf(Date);
+    });
+    it("should have the correct shape for TargetDieRollRecord", () => {
+        expect(targetRecord).toHaveProperty("roll");
+        expect(targetRecord).toHaveProperty("outcome");
+        expect(targetRecord).toHaveProperty("timestamp");
+        expect(targetRecord.timestamp).toBeInstanceOf(Date);
+    });
+    it("should be compatible with the RollRecord union", () => {
+        const records = [dieRecord, modifiedRecord, targetRecord];
+        expect(records).toHaveLength(3);
+    });
+});

package/dist/src/components/die-history/history-cache.js

@@ -0,0 +1,123 @@
+import { RollRecordManager, DEFAULT_MAX_RECORDS } from "./internal";
+/**
+ * A wrapper for RollRecordManager that maintains multiple, independently capped histories.
+ *
+ * Useful for scenarios where a single RollRecordManager needs to support "history parking",
+ * such as storing separate roll histories per modifier or context.
+ *
+ * @template R - The type of roll records stored
+ */
+/**
+ * A wrapper for RollRecordManager that maintains multiple, independently capped histories.
+ *
+ * Useful for scenarios where a single RollRecordManager needs to support "history parking",
+ * such as storing separate roll histories per modifier or context.
+ *
+ * @template R - The type of roll records stored
+ */
+export class HistoryCache {
+    constructor({ maxRecordsPerKey = Math.floor(DEFAULT_MAX_RECORDS / 10), maxKeys = 10, } = {}) {
+        this.cache = new Map();
+        this.maxRecordsPerKey = maxRecordsPerKey;
+        this.maxKeys = maxKeys;
+    }
+    /**
+     * Sets the currently active history key. If the key does not exist it will be created.
+     *
+     * @param {string} key - History key to activate.
+     */
+    setActiveKey(key) {
+        if (!this.cache.has(key)) {
+            if (this.cache.size >= this.maxKeys) {
+                const oldestKey = this.cache.keys().next().value;
+                if (!oldestKey)
+                    throw new Error("Unexpected empty cache while evicting oldest key");
+                this.cache.delete(oldestKey);
+            }
+            this.cache.set(key, new RollRecordManager(this.maxRecordsPerKey));
+        }
+        this.activeKey = key;
+    }
+    /**
+     * Returns the currently active RollRecordManager for the active key.
+     *
+     * @returns {RollRecordManager<R> | undefined} The manager for the active key (if any).
+     */
+    get activeManager() {
+        if (!this.activeKey)
+            return undefined;
+        return this.cache.get(this.activeKey);
+    }
+    /**
+     * Adds a roll record to the active history.
+     *
+     * @param {R} record - The roll record to add.
+     * @throws {Error} If no active history key is set.
+     */
+    add(record) {
+        const manager = this.activeManager;
+        if (!manager)
+            throw new Error("No active history key set. Call setActiveKey() first.");
+        manager.add(record);
+    }
+    /**
+     * Returns a copy of the roll records for the active key.
+     *
+     * @param {boolean} [verbose=false] - When true include timestamps.
+     * @returns {R[] | Omit<R, "timestamp">[]} Array of records for the active key.
+     */
+    getAll(verbose = false) {
+        const manager = this.activeManager;
+        if (!manager)
+            return [];
+        return verbose ? manager.full : manager.all;
+    }
+    /**
+     * Clears all roll records for the active key.
+     */
+    clearActive() {
+        const manager = this.activeManager;
+        if (manager)
+            manager.clear();
+    }
+    /**
+     * Clears all cached histories and resets the active key.
+     */
+    clearAll() {
+        this.cache.clear();
+        this.activeKey = undefined;
+    }
+    /**
+     * Returns a roll history report for all cached keys.
+     *
+     * @param {{limit?: number, verbose?: boolean}} [options] - Report options.
+     * @returns {Record<string, (R | Omit<R, "timestamp">)[]>} Map of key→records.
+     */
+    report({ limit, verbose = false, } = {}) {
+        const reports = {};
+        for (const [key, manager] of this.cache.entries()) {
+            reports[key] = manager.report({ limit, verbose });
+        }
+        return reports;
+    }
+    /**
+     * Returns a string summary of the cache.
+     *
+     * @returns {string} Summary containing number of keys and active key.
+     */
+    toString() {
+        return `RollHistoryCache: ${this.cache.size} keys (active: ${this.activeKey ?? "none"})`;
+    }
+    /**
+     * Returns a JSON-friendly object mapping keys to arrays of RollRecords.
+     *
+     * @returns {Record<string, R[]>} The cache contents as plain arrays.
+     */
+    toJSON() {
+        const json = {};
+        for (const [key, manager] of this.cache.entries()) {
+            json[key] = manager.toJSON();
+        }
+        return json;
+    }
+}

package/dist/src/components/die-history/index.js

@@ -0,0 +1,2 @@
+export { RollRecordFactory } from "./roll-record-factory";
+export { HistoryCache } from "./history-cache";

package/dist/src/components/die-history/internal/index.js

@@ -0,0 +1,2 @@
+export { RollRecordManager, DEFAULT_MAX_RECORDS } from "./roll-record-manager";
+export * from "./roll-record-validator";

package/dist/src/components/die-history/internal/roll-record-manager/index.js

@@ -0,0 +1 @@
+export { RollRecordManager, DEFAULT_MAX_RECORDS } from "./roll-record-manager";

package/dist/src/components/die-history/internal/roll-record-manager/internal/index.js

@@ -0,0 +1 @@
+export * from "./roll-record-storage";

package/dist/src/components/die-history/internal/roll-record-manager/internal/roll-record-storage.js

@@ -0,0 +1,66 @@
+/**
+ * Simple in-memory storage for roll records with a fixed capacity.
+ *
+ * This class focuses solely on storage and eviction policy. It does not
+ * perform shape validation of records (delegated to validators elsewhere).
+ */
+export class RollRecordStorage {
+    /**
+     * Create a new storage container.
+     * @param maxRecords Maximum number of records to retain (FIFO eviction).
+     */
+    /**
+     * Create a new storage container.
+     *
+     * @param {number} [maxRecords=1000] Maximum number of records to retain (FIFO eviction).
+     */
+    constructor(maxRecords = 1000) {
+        this.records = [];
+        if (typeof maxRecords !== "number" || maxRecords < 1) {
+            throw new TypeError("maxRecords must be a positive number");
+        }
+        this.maxRecords = Math.floor(maxRecords);
+    }
+    /** Number of records currently stored */
+    get size() {
+        return this.records.length;
+    }
+    /** Configured maximum number of records */
+    get maxRecordsCount() {
+        return this.maxRecords;
+    }
+    /** Returns a shallow copy of all records (timestamps preserved) */
+    get full() {
+        return [...this.records];
+    }
+    /** Add a new record and evict oldest if capacity exceeded */
+    add(record) {
+        if (!record || typeof record !== "object") {
+            throw new TypeError("Record must be an object");
+        }
+        this.records.push(record);
+        if (this.records.length > this.maxRecords) {
+            this.records.shift();
+        }
+    }
+    /** Clear all stored records */
+    clear() {
+        this.records = [];
+    }
+    /** Return the most recent N records in chronological order (oldest first) */
+    last(n = 1) {
+        if (typeof n !== "number" || n < 1) {
+            throw new TypeError("Parameter n must be a positive number");
+        }
+        const len = this.records.length;
+        if (len === 0)
+            return [];
+        const slice = this.records.slice(Math.max(len - n, 0));
+        return [...slice];
+    }
+    /** JSON-friendly copy of stored records */
+    toJSON() {
+        return this.full;
+    }
+}
+export default RollRecordStorage;

package/dist/src/components/die-history/internal/roll-record-manager/roll-record-manager.js

@@ -0,0 +1,124 @@
+import { isDieRollRecord, isModifiedDieRollRecord, isTargetDieRollRecord, stripTimestamp, } from "../roll-record-validator";
+import { RollRecordStorage } from "./internal";
+/**
+ * Default maximum number of roll records stored.
+ */
+export const DEFAULT_MAX_RECORDS = 1000;
+/**
+ * Utility class for managing roll history of Die and child/composite classes.
+ *
+ * Provides methods to add roll records, retrieve the last N rolls,
+ * produce history reports, and manage roll record storage.
+ *
+ * @template R Type of roll record, defaults to all RollRecord variants.
+ */
+export class RollRecordManager {
+    /**
+     * Create a RollRecordManager.
+     *
+     * @param {number} [maxRecords=DEFAULT_MAX_RECORDS] - Maximum records to retain.
+     */
+    constructor(maxRecords = DEFAULT_MAX_RECORDS) {
+        this.maxRecords = maxRecords;
+        this.storage = new RollRecordStorage(maxRecords);
+    }
+    /**
+     * Returns a copy of all roll records (including timestamps).
+     *
+     * @returns {R[]} All records (timestamps preserved).
+     */
+    get full() {
+        return this.storage.full;
+    }
+    /**
+     * Returns a copy of all roll records with timestamps stripped.
+     *
+     * @returns {Omit<R, "timestamp">[]} Records without timestamps.
+     */
+    get all() {
+        return this.storage.full.map(stripTimestamp);
+    }
+    /**
+     * Returns the number of roll records stored.
+     *
+     * @returns {number} Number of stored records.
+     */
+    get length() {
+        return this.storage.size;
+    }
+    /**
+     * Returns the configured maximum number of roll records.
+     *
+     * @returns {number} Maximum records configured.
+     */
+    get maxRecordsCount() {
+        return this.storage.maxRecordsCount;
+    }
+    /**
+     * Adds a roll record to the history.
+     *
+     * @param {R} record - The record to add.
+     * @throws {TypeError} If the record is not a valid roll record shape.
+     */
+    add(record) {
+        if (!record || typeof record !== "object") {
+            throw new TypeError("Record must be an object");
+        }
+        if (!isDieRollRecord(record) &&
+            !isModifiedDieRollRecord(record) &&
+            !isTargetDieRollRecord(record)) {
+            throw new TypeError("Record must be a valid DieRollRecord, ModifiedDieRollRecord, or TargetDieRollRecord");
+        }
+        this.storage.add(record);
+    }
+    /**
+     * Clears the roll history storage.
+     */
+    clear() {
+        this.storage.clear();
+    }
+    /**
+     * Returns the last N roll records.
+     *
+     * @param {number} [n=1] - Number of records to retrieve.
+     * @param {boolean} [verbose=false] - Include timestamps when true.
+     * @returns {(R | Omit<R, "timestamp">)[]} Array of records.
+     */
+    last(n = 1, verbose = false) {
+        if (typeof n !== "number" || n < 1) {
+            throw new TypeError("Parameter n must be a positive number.");
+        }
+        const len = this.storage.size;
+        if (len === 0)
+            return [];
+        const slice = this.storage.last(n);
+        return verbose ? slice : slice.map(stripTimestamp);
+    }
+    /**
+     * Produces a roll history report based on the given options.
+     *
+     * @param {{limit?: number; verbose?: boolean}} [options]
+     * @returns {(R | Omit<R, "timestamp">)[]} An array of records per options.
+     */
+    report(options) {
+        const { limit, verbose = false } = options || {};
+        const n = Math.min(limit ?? this.storage.size, this.storage.size);
+        return n === 0 ? [] : this.last(n, verbose);
+    }
+    /**
+     * Human-readable string summary of roll history.
+     *
+     * @returns {string} Summary that contains last roll and counts.
+     */
+    toString() {
+        if (this.storage.size === 0) {
+            return `RollRecordManager: empty (maxRecords=${this.maxRecords})`;
+        }
+        const lastRecord = this.storage.full[this.storage.size - 1];
+        return `RollRecordManager: ${this.storage.size}/${this.maxRecords} rolls (last: ${lastRecord.roll} @ ${lastRecord.timestamp.toISOString()})`;
+    }
+    /** Returns the full history as an array of records */
+    toJSON() {
+        return this.storage.toJSON();
+    }
+}

package/dist/src/components/die-history/internal/roll-record-validator.js

@@ -0,0 +1,43 @@
+import { Outcome } from "@platonic-dice/core";
+/**
+ * Runtime type-guards for RollRecord shapes.
+ * Kept intentionally small and side-effect free.
+ */
+export function isDieRollRecord(record) {
+    return (!!record &&
+        typeof record.roll === "number" &&
+        record.timestamp instanceof Date &&
+        !("modified" in record) &&
+        !("outcome" in record));
+}
+export function isModifiedDieRollRecord(record) {
+    return (!!record &&
+        typeof record.roll === "number" &&
+        typeof record.modified === "number" &&
+        record.timestamp instanceof Date &&
+        !("outcome" in record));
+}
+export function isTargetDieRollRecord(record) {
+    return (!!record &&
+        typeof record.roll === "number" &&
+        "outcome" in record &&
+        Object.values(Outcome).includes(record.outcome) &&
+        record.timestamp instanceof Date);
+}
+/**
+ * Remove timestamp property from a record (immutable-friendly).
+ *
+ * @template R
+ * @param {R} record - The record to strip timestamp from.
+ * @returns {Omit<R, "timestamp">} The record without the timestamp property.
+ */
+export function stripTimestamp(record) {
+    const { timestamp, ...rest } = record;
+    return rest;
+}
+export default {
+    isDieRollRecord,
+    isModifiedDieRollRecord,
+    isTargetDieRollRecord,
+    stripTimestamp,
+};

package/dist/src/components/die-history/roll-record-factory.js

@@ -0,0 +1,55 @@
+import { RollType, roll as coreRoll, rollMod as coreRollMod, rollTest as coreRollTest, } from "@platonic-dice/core";
+import { isDieRollRecord, isModifiedDieRollRecord, isTargetDieRollRecord, } from "./internal";
+/**
+ * Default implementation that delegates to `@platonic-dice/core` and uses
+ * the system clock. This keeps the public API simple and avoids DI.
+ */
+/**
+ * Implementation of RollRecordFactory that delegates to @platonic-dice/core and uses the system clock.
+ * This keeps the public API simple and avoids DI.
+ */
+export class RollRecordFactory {
+    createNormalRoll(dieType, rollType) {
+        // Runtime validation without `any` casts: compare against the known
+        // RollType members (explicit checks keep types narrow and avoid casts).
+        if (rollType !== undefined &&
+            rollType !== RollType.Advantage &&
+            rollType !== RollType.Disadvantage) {
+            throw new TypeError(`Invalid rollType: ${String(rollType)}`);
+        }
+        // Delegate to core roll implementation and attach a timestamp.
+        const value = coreRoll(dieType, rollType);
+        const ts = new Date();
+        const record = { roll: value, timestamp: ts };
+        if (!isDieRollRecord(record)) {
+            throw new Error("Factory produced invalid DieRollRecord");
+        }
+        return record;
+    }
+    createModifiedRoll(dieType, modifier, rollType) {
+        // Resolve base and modified values using the core helper, then stamp.
+        const { base, modified } = coreRollMod(dieType, modifier, rollType);
+        const ts = new Date();
+        const record = {
+            roll: base,
+            modified,
+            timestamp: ts,
+        };
+        if (!isModifiedDieRollRecord(record)) {
+            throw new Error("Factory produced invalid ModifiedDieRollRecord");
+        }
+        return record;
+    }
+    createTestRoll(dieType, testConditions, rollType) {
+        // Core normalises and evaluates test conditions; we retain the outcome
+        // and attach a timestamp to produce a TestDieRollRecord.
+        const { base, outcome } = coreRollTest(dieType, testConditions, rollType);
+        const ts = new Date();
+        const record = { roll: base, outcome, timestamp: ts };
+        if (!isTargetDieRollRecord(record)) {
+            throw new Error("Factory produced invalid TestDieRollRecord");
+        }
+        return record;
+    }
+}
+export default RollRecordFactory;

package/dist/src/components/index.js

@@ -0,0 +1 @@
+export * from "./die-history";

package/dist/src/die.js

@@ -0,0 +1,226 @@
+import { DieType, RollType } from "@platonic-dice/core";
+import { RollRecordFactory, HistoryCache } from "@dice/components";
+/**
+ * Represents a single die with flexible history tracking.
+ *
+ * The Die class provides:
+ * - Normal rolls (numeric)
+ * - Modified rolls (numeric or functional modifiers)
+ * - Test rolls (success/failure evaluation)
+ *
+ * Each roll type is stored independently in a `RollHistoryCache`.
+ *
+ * Example:
+ * ```ts
+ * const d20 = new Die(DieType.D20);
+ * const result = d20.roll(); // normal roll
+ * const modResult = d20.rollMod(n => n + 2); // modified roll
+ * const testResult = d20.rollTest({ testType: "AtLeast", target: 15 });
+ * ```
+ */
+export class Die {
+    /**
+     * Create a new Die instance.
+     * @param type - The die type (must be a value from `DieType`)
+     * @param historyCache - Optional custom `RollHistoryCache` instance
+     */
+    /**
+     * Create a new Die instance.
+     *
+     * @param {DieTypeValue} type - The die type (must be a value from `DieType`).
+     * @param {HistoryCache<RollRecord>} [historyCache] - Optional custom history cache instance.
+     * @throws {Error} If `type` is not a valid `DieType` value.
+     */
+    constructor(type, historyCache) {
+        this.recordFactory = new RollRecordFactory();
+        // Accept only the narrow literal union type (DieTypeValue) for strictness.
+        // Runtime validation still guards against invalid values.
+        if (!Object.values(DieType).includes(type)) {
+            throw new Error(`Invalid die type: ${type}`);
+        }
+        this.typeValue = type;
+        this.rolls = historyCache ?? new HistoryCache({ maxKeys: 10 });
+    }
+    /**
+     * Notes on behavior and contracts
+     * - `resultValue` holds the most recent numeric value produced by a roll
+     *   operation. It is updated from factory-produced records: for normal and
+     *   test rolls it tracks `record.roll`; for modified rolls it tracks
+     *   `record.modified`.
+     * - `rolls` is a `HistoryCache` that stores separate histories keyed by
+     *   roll type (normal/modifier/test). Each public roll method sets the
+     *   corresponding active key, creates a factory-produced record and adds
+     *   it to the active history. Record shape validation happens at the
+     *   `RollRecordManager.add()` boundary.
+     */
+    /** The die type (e.g., `d6`, `d20`) */
+    get type() {
+        return this.typeValue;
+    }
+    /** The most recent numeric roll result, or undefined if not rolled yet */
+    get result() {
+        return this.resultValue;
+    }
+    /** Number of faces on this die */
+    get faceCount() {
+        const lookup = {
+            [DieType.D4]: 4,
+            [DieType.D6]: 6,
+            [DieType.D8]: 8,
+            [DieType.D10]: 10,
+            [DieType.D12]: 12,
+            [DieType.D20]: 20,
+        };
+        return lookup[this.typeValue];
+    }
+    /**
+     * Reset the most recent result.
+     * @param complete - If true, clears all histories for all roll types
+     */
+    reset(complete = false) {
+        this.resultValue = undefined;
+        if (complete)
+            this.rolls.clearAll();
+    }
+    /**
+     * Perform a normal die roll.
+     * @param rollType - Optional roll mode (`RollType.Advantage` / `RollType.Disadvantage`)
+     * @returns The numeric result
+     */
+    /**
+     * Perform a normal die roll.
+     *
+     * @param {RollTypeValue} [rollType] - Optional roll mode (`RollType.Advantage` / `RollType.Disadvantage`).
+     * @returns {number} The numeric result of the roll.
+     * @throws {Error} If `rollType` is provided but invalid.
+     */
+    roll(rollType) {
+        if (rollType !== undefined &&
+            !Object.values(RollType).includes(rollType)) {
+            throw new Error(`Invalid roll type: ${rollType}`);
+        }
+        // Delegate record creation to the RollRecordFactory to centralize shape
+        const record = this.recordFactory.createNormalRoll(this.typeValue, rollType);
+        this.resultValue = record.roll;
+        this.rolls.setActiveKey(Die.NORMAL_KEY);
+        this.rolls.add(record);
+        return record.roll;
+    }
+    /**
+     * Perform a roll with a modifier.
+     *
+     * @param modifier - Numeric or functional modifier (function `(n: number) => number` or `RollModifierInstance`)
+     * @param rollType - Optional roll mode (`RollType.Advantage` / `RollType.Disadvantage`)
+     * @returns The modified numeric result
+     *
+     * Example:
+     * ```ts
+     * d20.rollMod(n => n + 2); // adds +2 to the roll
+     * ```
+     */
+    /**
+     * Perform a roll with a modifier.
+     *
+     * @param {RollModifierFunction | RollModifierInstance} modifier - Numeric or functional modifier applied to the base roll.
+     * @param {RollTypeValue} [rollType] - Optional roll mode (`RollType.Advantage` / `RollType.Disadvantage`).
+     * @returns {number} The modified numeric result.
+     * @example
+     * d20.rollMod(n => n + 2); // adds +2 to the roll
+     */
+    rollMod(modifier, rollType) {
+        const record = this.recordFactory.createModifiedRoll(this.typeValue, modifier, rollType);
+        this.resultValue = record.modified;
+        this.rolls.setActiveKey(Die.MODIFIER_KEY);
+        this.rolls.add(record);
+        return record.modified;
+    }
+    /**
+     * Perform a roll against test conditions (success/failure evaluation).
+     *
+     * @param testConditions - Test conditions (plain object or `TestConditionsInstance`)
+     * @param rollType - Optional roll mode (`RollType.Advantage` / `RollType.Disadvantage`)
+     * @returns The base numeric roll
+     *
+     * Example:
+     * ```ts
+     * d20.rollTest({ testType: "AtLeast", target: 15 });
+     * ```
+     */
+    /**
+     * Perform a roll against test conditions (success/failure evaluation).
+     *
+     * @param {TestConditionsInstance | { testType: TestTypeValue; [k: string]: any }} testConditions - Test conditions (plain object or normalized `TestConditions` instance).
+     * @param {RollTypeValue} [rollType] - Optional roll mode (`RollType.Advantage` / `RollType.Disadvantage`).
+     * @returns {number} The base numeric roll used to evaluate the test.
+     * @throws {Error} If `testConditions` or `rollType` are invalid (delegated to core).
+     * @example
+     * d20.rollTest({ testType: "at_least", target: 15 });
+     */
+    rollTest(testConditions, rollType) {
+        const record = this.recordFactory.createTestRoll(this.typeValue, testConditions, rollType);
+        this.resultValue = record.roll;
+        this.rolls.setActiveKey(Die.TEST_KEY);
+        this.rolls.add(record);
+        return record.roll;
+    }
+    /**
+     * Retrieve roll history for a given key.
+     *
+     * @param key - `"normal" | "modifier" | "test"`
+     * @param verbose - Include timestamps if true
+     * @returns Array of roll records (timestamps included if verbose)
+     */
+    /**
+     * Retrieve roll history for a given key.
+     *
+     * @param {string} [key=Die.NORMAL_KEY] - One of "normal" | "modifier" | "test".
+     * @param {boolean} [verbose=false] - Include timestamps when true.
+     * @returns {Array} Array of roll records (timestamps included when verbose).
+     */
+    history(key = Die.NORMAL_KEY, verbose = false) {
+        this.rolls.setActiveKey(key);
+        return this.rolls.getAll(verbose);
+    }
+    /**
+     * Retrieve a roll report for a specific key.
+     *
+     * @param key - `"normal" | "modifier" | "test"`
+     * @param options - Optional report options (`limit` and `verbose`)
+     * @returns Array of roll records (subject to limit and verbose)
+     */
+    /**
+     * Retrieve a roll report for a specific key.
+     *
+     * @param {string} [key=Die.NORMAL_KEY] - History key to report on.
+     * @param {{limit?: number, verbose?: boolean}} [options] - Report options.
+     * @returns {Array} Array of roll records (subject to `limit` and `verbose`).
+     */
+    report(key = Die.NORMAL_KEY, options) {
+        this.rolls.setActiveKey(key);
+        return this.rolls.activeManager?.report(options) ?? [];
+    }
+    /** Human-readable summary of the die */
+    /**
+     * Human-readable summary of the die
+     *
+     * @returns {string} Short description including last result if present.
+     */
+    toString() {
+        if (this.resultValue === undefined)
+            return `Die(${this.typeValue}): not rolled yet`;
+        return `Die(${this.typeValue}): latest=${this.resultValue}`;
+    }
+    /** JSON representation of all histories keyed by roll type */
+    /**
+     * JSON representation of all histories keyed by roll type
+     *
+     * @returns {Record<string, RollRecord[]>} Mapping of history keys to arrays of records.
+     */
+    toJSON() {
+        return this.rolls.toJSON();
+    }
+}
+/** Keys used internally for history separation */
+Die.NORMAL_KEY = "normal";
+Die.MODIFIER_KEY = "modifier";
+Die.TEST_KEY = "test";

package/dist/src/types/index.js

@@ -0,0 +1 @@
+export * from "./roll-record.types";

package/dist/src/types/roll-record.types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@platonic-dice/dice",
+  "version": "2.0.0",
+  "description": "Persistent dice objects with roll history and TypeScript support.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "dice",
+    "TTRPG",
+    "random",
+    "game",
+    "d20",
+    "dnd"
+  ],
+  "author": "Stephen James Saunders",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sjs2k20/platonic-dice.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sjs2k20/platonic-dice.git/issues"
+  },
+  "homepage": "https://github.com/sjs2k20/platonic-dice.git#readme",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@platonic-dice/core": "^2.0.0"
+  },
+  "devDependencies": {
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^4.0.9"
+  }
+}