@platonic-dice/core 2.0.0

package/dist/entities/TestConditions.js

@@ -0,0 +1,324 @@
+/**
+ * @module @dice/core/src/entities/TestConditions
+ * @description
+ * This class validates the test type and associated conditions
+ * against the provided {@link DieType} during construction.
+ *
+ * @example
+ * const tc = new TestConditions(TestType.AtLeast, { target: 15 }, DieType.D20);
+ * const result = rollTest(DieType.D20, tc);
+ */
+
+const { isValidDieType } = require("./DieType");
+const { isValidTestType } = require("./TestType");
+const { numSides } = require("../utils");
+
+/**
+ * @typedef {import("./TestType").TestTypeValue} TestTypeValue
+ * @typedef {import("./DieType").DieTypeValue} DieTypeValue
+ */
+
+/**
+ * Represents a set of conditions for a dice roll test.
+ */
+class TestConditions {
+  /**
+   * @param {TestTypeValue} testType - The test type.
+   * @param {Conditions} conditions - The test conditions object.
+   * @param {DieTypeValue} dieType - The die type to validate numeric ranges.
+   * @throws {TypeError|RangeError} If the test type or conditions are invalid.
+   */
+  constructor(testType, conditions, dieType) {
+    if (!isValidTestType(testType)) {
+      throw new TypeError(`Invalid test type: ${testType}`);
+    }
+
+    if (!conditions || typeof conditions !== "object") {
+      throw new TypeError("conditions must be an object.");
+    }
+
+    if (!dieType) {
+      throw new TypeError("dieType is required to validate TestConditions.");
+    }
+
+    // Validate conditions immediately
+    if (!areValidTestConditions({ ...conditions, dieType }, testType)) {
+      switch (testType) {
+        case "at_least":
+        case "at_most":
+        case "exact":
+          throw new RangeError(
+            `Invalid ${testType} condition for die type ${dieType}: target must be an integer within valid die faces.`
+          );
+        case "within":
+          throw new RangeError(
+            `Invalid 'within' condition for die type ${dieType}: min must be ≤ max and both valid face values.`
+          );
+        case "in_list":
+          throw new RangeError(
+            `Invalid 'specificList' condition for die type ${dieType}: values must be a non-empty array of valid face values.`
+          );
+        case "skill":
+          throw new RangeError(
+            `Invalid 'skill' condition for die type ${dieType}: target, critical_success, and critical_failure must be valid and logically ordered.`
+          );
+        default:
+          throw new TypeError(`Unknown testType '${testType}'.`);
+      }
+    }
+
+    /** @type {TestTypeValue} */
+    this.testType = testType;
+    /** @type {Conditions} */
+    this.conditions = conditions;
+    /** @type {DieTypeValue} */
+    this.dieType = dieType;
+  }
+
+  /**
+   * Validates that the test conditions still conforms to spec.
+   * (Useful if they are loaded dynamically or serialized.)
+   * @throws {TypeError} If the test conditions are invalid.
+   */
+  validate() {
+    if (
+      !areValidTestConditions(
+        { ...this.conditions, dieType: this.dieType },
+        this.testType
+      )
+    ) {
+      throw new TypeError("Invalid test conditions shape.");
+    }
+  }
+}
+
+/**
+ * Master validation function for all test conditions.
+ *
+ * @function areValidTestConditions
+ * @param {Conditions} c
+ * @param {TestTypeValue} testType
+ * @returns {boolean}
+ */
+function areValidTestConditions(c, testType) {
+  switch (testType) {
+    case "at_least":
+    case "at_most":
+    case "exact":
+      // @ts-expect-error: we know c is TargetConditions for these test types
+      return isValidTargetConditions(c);
+    case "within":
+      // @ts-expect-error: we know c is WithinConditions for this test type
+      return isValidWithinConditions(c);
+    case "in_list":
+      // @ts-expect-error: we know c is SpecificListConditions
+      return isValidSpecificListConditions(c);
+    // case "odd":
+    // case "even":
+    //   return isValidOddEvenCondition(c);
+    case "skill":
+      // @ts-expect-error: we know c is SkillConditions
+      return isValidSkillTestCondition(c);
+    default:
+      return false;
+  }
+}
+
+/**
+ * Normalises any input into a {@link TestConditions} instance.
+ * Supports both pre-existing instances and plain objects.
+ * Automatically validates all conditions for the specified die type.
+ *
+ * @function normaliseTestConditions
+ * @param {TestConditions | { testType: TestTypeValue, [key: string]: any }} tc
+ *   A {@link TestConditions} instance or plain object with `testType` and other fields.
+ * @param {DieTypeValue} dieType
+ *   The die type (e.g., `'d6'`, `'d20'`) used for validation.
+ * @returns {TestConditions}
+ *   A validated {@link TestConditions} instance.
+ * @throws {TypeError}
+ *   If the input is neither a TestConditions instance nor a plain object.
+ *
+ * @example
+ * // Passing a plain object
+ * const conditions = normaliseTestConditions({ testType: 'atLeast', target: 4 }, 'd6');
+ *
+ * @example
+ * // Passing an existing TestConditions instance
+ * const existing = new TestConditions('exact', { target: 3 }, 'd6');
+ * const conditions2 = normaliseTestConditions(existing, 'd6');
+ */
+function normaliseTestConditions(tc, dieType) {
+  if (tc instanceof TestConditions) return tc;
+  if (tc && typeof tc === "object") {
+    const { testType, ...rest } = tc;
+
+    // @ts-expect-error: we are asserting that the rest of the object plus dieType
+    // will conform to the Conditions union when passed to the constructor
+    return new TestConditions(testType, { ...rest }, dieType);
+  }
+  throw new TypeError(
+    `Invalid TestConditions: must be a TestConditions instance or a plain object.`
+  );
+}
+
+/**
+ * Represents any valid dice roll test condition.
+ *
+ * This is a union type of all the internal test condition shapes:
+ * - `TargetConditions` – single target value
+ * - `SkillConditions` – target with optional critical thresholds
+ * - `WithinConditions` – min/max range
+ * - `SpecificListConditions` – array of specific allowed values
+ *
+ * @typedef {TargetConditions | SkillConditions | WithinConditions | SpecificListConditions} Conditions
+ */
+
+/**
+ * @typedef {InstanceType<typeof TestConditions>} TestConditionsInstance
+ */
+
+module.exports = {
+  TestConditions,
+  areValidTestConditions,
+  normaliseTestConditions,
+};
+
+//
+// PRIVATE HELPER FUNCTIONS
+//
+
+/**
+ * @private
+ * @typedef {Object} BaseTestCondition
+ * @property {DieTypeValue} dieType
+ */
+
+/**
+ * @private
+ * @typedef {BaseTestCondition & { target: number }} TargetConditions
+ * @private
+ * @typedef {BaseTestCondition & { min: number, max: number }} WithinConditions
+ * @private
+ * @typedef {BaseTestCondition & { values: number[] }} SpecificListConditions
+ * @private
+ * @typedef {BaseTestCondition & { target: number, critical_success?: number, critical_failure?: number }} SkillConditions
+ */
+
+/**
+ * Checks if a number is a valid face value for a die with the given sides.
+ *
+ * @private
+ * @function isValidFaceValue
+ * @param {number} n
+ * @param {number} sides
+ * @returns {boolean}
+ */
+function isValidFaceValue(n, sides) {
+  return Number.isInteger(n) && n >= 1 && n <= sides;
+}
+
+/**
+ * Checks multiple keys in an object for valid face values.
+ *
+ * @private
+ * @function areValidFaceValues
+ * @template T
+ * @param {T} obj
+ * @param {number} sides
+ * @param {(keyof T)[]} keys
+ * @returns {boolean}
+ */
+function areValidFaceValues(obj, sides, keys) {
+  return keys.every((key) => {
+    const value = obj[key];
+    return (
+      value == null || isValidFaceValue(/** @type {number} */ (value), sides)
+    );
+  });
+}
+
+/**
+ * Validates the ordering of target and critical thresholds.
+ *
+ * @private
+ * @function isValidThresholdOrder
+ * @param {SkillConditions} thresholds
+ * @returns {boolean}
+ */
+function isValidThresholdOrder({ target, critical_success, critical_failure }) {
+  if (critical_failure != null && critical_failure >= target) return false;
+  if (critical_success != null && critical_success < target) return false;
+  return true;
+}
+
+/**
+ * Validates a target-based condition.
+ *
+ * @private
+ * @function isValidTargetConditions
+ * @param {TargetConditions} c
+ * @returns {boolean}
+ */
+function isValidTargetConditions(c) {
+  if (!c || !isValidDieType(c.dieType)) return false;
+  return isValidFaceValue(c.target, numSides(c.dieType));
+}
+
+/**
+ * Validates a skill-based test condition.
+ *
+ * @private
+ * @function isValidSkillTestCondition
+ * @param {SkillConditions} c
+ * @returns {boolean}
+ */
+function isValidSkillTestCondition(c) {
+  if (!c || !isValidDieType(c.dieType)) return false;
+  const sides = numSides(c.dieType);
+
+  if (
+    !areValidFaceValues(c, sides, [
+      "target",
+      "critical_success",
+      "critical_failure",
+    ])
+  )
+    return false;
+  if (!isValidThresholdOrder(c)) return false;
+
+  return true;
+}
+
+/**
+ * Validates a "within" range condition.
+ *
+ * @private
+ * @function isValidWithinConditions
+ * @param {WithinConditions} c
+ * @returns {boolean}
+ */
+function isValidWithinConditions(c) {
+  if (!c || !isValidDieType(c.dieType)) return false;
+  const sides = numSides(c.dieType);
+
+  if (!areValidFaceValues(c, sides, ["min", "max"])) return false;
+  if (c.min > c.max) return false;
+
+  return true;
+}
+
+/**
+ * Validates a "specific list" condition.
+ *
+ * @private
+ * @function isValidSpecificListConditions
+ * @param {SpecificListConditions} c
+ * @returns {boolean}
+ */
+function isValidSpecificListConditions(c) {
+  if (!c || !isValidDieType(c.dieType)) return false;
+  const sides = numSides(c.dieType);
+  if (!Array.isArray(c.values) || c.values.length === 0) return false;
+  return c.values.every((v) => isValidFaceValue(v, sides));
+}

package/dist/entities/TestType.d.ts

@@ -0,0 +1,28 @@
+export type TestTypeKey = keyof typeof TestType;
+export type TestTypeValue = (typeof TestType)[keyof typeof TestType];
+export type TestType = string;
+/**
+ * @module @platonic-dice/core/src/entities/TestType
+ * @description
+ * Enum for test evaluation types (used in {@link TestConditions}).
+ *
+ * @readonly
+ * @enum {string}
+ */
+export const TestType: Readonly<{
+    Exact: "exact";
+    AtLeast: "at_least";
+    AtMost: "at_most";
+    Within: "within";
+    InList: "in_list";
+    Skill: "skill";
+}>;
+/**
+ * Checks whether a given value is a valid `TestType`.
+ *
+ * @function isValidTestType
+ * @param {TestTypeValue | null | undefined} testType
+ * @returns {boolean}
+ */
+export function isValidTestType(testType: TestTypeValue | null | undefined): boolean;
+//# sourceMappingURL=TestType.d.ts.map

package/dist/entities/TestType.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestType.d.ts","sourceRoot":"","sources":["../../src/entities/TestType.js"],"names":[],"mappings":"0BA+Ba,MAAM,OAAO,QAAQ;4BACrB,CAAA,OAAO,QAAQ,EAAC,MAAM,OAAO,QAAQ,CAAC;uBAzBzC,MAAM;AANhB;;;;;;;GAOG;AACH;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,0CAHW,aAAa,GAAG,IAAI,GAAG,SAAS,GAC9B,OAAO,CAKnB"}

package/dist/entities/TestType.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * @module @platonic-dice/core/src/entities/TestType
+ * @description
+ * Enum for test evaluation types (used in {@link TestConditions}).
+ *
+ * @readonly
+ * @enum {string}
+ */
+const TestType = Object.freeze({
+  Exact: "exact", // Must roll exactly this number
+  AtLeast: "at_least", // Roll ≥ target
+  AtMost: "at_most", // Roll ≤ target
+  Within: "within", // Roll within [min, max]
+  InList: "in_list", // Roll in array of valid values
+  Skill: "skill", // Classic skill/threshold test (with crits)
+});
+
+/**
+ * Checks whether a given value is a valid `TestType`.
+ *
+ * @function isValidTestType
+ * @param {TestTypeValue | null | undefined} testType
+ * @returns {boolean}
+ */
+function isValidTestType(testType) {
+  if (!testType) return false;
+  return Object.values(TestType).includes(testType);
+}
+
+/**
+ * @typedef {keyof typeof TestType} TestTypeKey
+ * @typedef {typeof TestType[keyof typeof TestType]} TestTypeValue
+ */
+
+module.exports = {
+  TestType,
+  isValidTestType,
+};

package/dist/entities/index.d.ts

@@ -0,0 +1,16 @@
+import { DieType } from "./DieType.js";
+import { isValidDieType } from "./DieType.js";
+import { Outcome } from "./Outcome.js";
+import { isValidOutcome } from "./Outcome.js";
+import { RollModifier } from "./RollModifier.js";
+import { isValidRollModifier } from "./RollModifier.js";
+import { normaliseRollModifier } from "./RollModifier.js";
+import { RollType } from "./RollType.js";
+import { isValidRollType } from "./RollType.js";
+import { TestConditions } from "./TestConditions.js";
+import { areValidTestConditions } from "./TestConditions.js";
+import { normaliseTestConditions } from "./TestConditions.js";
+import { TestType } from "./TestType.js";
+import { isValidTestType } from "./TestType.js";
+export { DieType, isValidDieType, Outcome, isValidOutcome, RollModifier, isValidRollModifier, normaliseRollModifier, RollType, isValidRollType, TestConditions, areValidTestConditions, normaliseTestConditions, TestType, isValidTestType };
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/entities/index.js

@@ -0,0 +1,46 @@
+/**
+ * @module @platonic-dice/core/src/entities
+ * @description
+ * Core entity definitions for the `@platonic-dice/core` package.
+ *
+ * Exports all primary enumerations, classes, and data types used throughout
+ * the dice logic system.
+ *
+ * @example
+ * import { DieType, RollType, RollModifier } from "@platonic-dice/core/src/entities";
+ *
+ * const mod = new RollModifier((n) => n + 2);
+ * const result = roll(DieType.D20, RollType.Advantage);
+ */
+
+const { DieType, isValidDieType } = require("./DieType.js");
+const { Outcome, isValidOutcome } = require("./Outcome.js");
+const {
+  RollModifier,
+  isValidRollModifier,
+  normaliseRollModifier,
+} = require("./RollModifier.js");
+const { RollType, isValidRollType } = require("./RollType.js");
+const {
+  TestConditions,
+  areValidTestConditions,
+  normaliseTestConditions,
+} = require("./TestConditions.js");
+const { TestType, isValidTestType } = require("./TestType.js");
+
+module.exports = {
+  DieType,
+  isValidDieType,
+  Outcome,
+  isValidOutcome,
+  RollModifier,
+  isValidRollModifier,
+  normaliseRollModifier,
+  RollType,
+  isValidRollType,
+  TestConditions,
+  areValidTestConditions,
+  normaliseTestConditions,
+  TestType,
+  isValidTestType,
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+declare const _exports: typeof import("./roll") & typeof import("./rollDice") & typeof import("./rollMod") & typeof import("./rollDiceMod") & typeof import("./rollTest") & typeof import("./entities") & {
+    default: any;
+};
+export = _exports;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"wBAsBU,cAAc,QAAQ,CAAC,GAChC,cAAuB,YAAY,CAAC,GACpC,cAAuB,WAAW,CAAC,GACnC,cAAuB,eAAe,CAAC,GACvC,cAAuB,YAAY,CAAC,GACpC,cAAuB,YAAY,CAAC,GACpC;IAAW,OAAO,EAAE,GAAG,CAAA;CAAE"}

package/dist/index.js

@@ -0,0 +1,42 @@
+/**
+ * @module core
+ * @description
+ * Primary entry point for the core dice logic.
+ * Re-exports all main rolling functions and modifiers.
+ *
+ * @example
+ * import { roll, rollMod, rollDice, rollDiceMod, rollTest } from "@platonic-dice/core";
+ */
+
+// --- Core modules ---
+const rollDice = require("./rollDice.js");
+const roll = require("./roll.js");
+const rollMod = require("./rollMod.js");
+const rollDiceMod = require("./rollDiceMod.js");
+const rollTest = require("./rollTest.js");
+
+// --- Entities (public API) ---
+const entities = require("./entities");
+
+/**
+ * Combined exports for Node and TypeScript users.
+ * @type {typeof import("./roll") &
+ *        typeof import("./rollDice") &
+ *        typeof import("./rollMod") &
+ *        typeof import("./rollDiceMod") &
+ *        typeof import("./rollTest") &
+ *        typeof import("./entities") &
+ *        { default: any }}
+ */
+module.exports = {
+  ...roll,
+  ...rollDice,
+  ...rollMod,
+  ...rollDiceMod,
+  ...entities,
+  ...rollTest,
+  default: undefined, // placeholder; will be overwritten
+};
+
+// assign default at runtime
+module.exports.default = module.exports;

package/dist/roll.d.ts

@@ -0,0 +1,66 @@
+export type DieTypeValue = import("./entities/DieType").DieTypeValue;
+export type RollTypeValue = import("./entities/RollType").RollTypeValue;
+/**
+ * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
+ * @typedef {import("./entities/RollType").RollTypeValue} RollTypeValue
+ */
+/**
+ * Rolls a single die of the specified type, optionally applying advantage or disadvantage.
+ *
+ * @function roll
+ * @param {DieTypeValue} dieType - The type of die to roll (e.g., `DieType.D20`).
+ * @param {RollTypeValue | undefined} [rollType=undefined] - Optional roll mode (`RollType.Advantage` or `RollType.Disadvantage`).
+ * @returns {number} The rolled value (integer between 1 and the die's maximum face).
+ * @throws {TypeError} If `dieType` or `rollType` are invalid.
+ *
+ * @example
+ * const result = roll(DieType.D20, RollType.Advantage);
+ */
+export function roll(dieType: DieTypeValue, rollType?: RollTypeValue | undefined): number;
+/**
+ * Rolls a die with advantage.
+ * @type {(dieType: DieTypeValue) => number}
+ *
+ * @example
+ * const result = rollAdv(DieType.D10);
+ */
+export const rollAdv: (dieType: DieTypeValue) => number;
+/**
+ * Rolls a die with disadvantage.
+ * @type {(dieType: DieTypeValue) => number}
+ *
+ * @example
+ * const result = rollDis(DieType.D10);
+ */
+export const rollDis: (dieType: DieTypeValue) => number;
+/**
+ * Rolls a D4 die.
+ * @type {(rollType?: RollTypeValue | undefined) => number}
+ */
+export const rollD4: (rollType?: RollTypeValue | undefined) => number;
+/**
+ * Rolls a D6 die.
+ * @type {(rollType?: RollTypeValue | undefined) => number}
+ */
+export const rollD6: (rollType?: RollTypeValue | undefined) => number;
+/**
+ * Rolls a D8 die.
+ * @type {(rollType?: RollTypeValue | undefined) => number}
+ */
+export const rollD8: (rollType?: RollTypeValue | undefined) => number;
+/**
+ * Rolls a D10 die.
+ * @type {(rollType?: RollTypeValue | undefined) => number}
+ */
+export const rollD10: (rollType?: RollTypeValue | undefined) => number;
+/**
+ * Rolls a D12 die.
+ * @type {(rollType?: RollTypeValue | undefined) => number}
+ */
+export const rollD12: (rollType?: RollTypeValue | undefined) => number;
+/**
+ * Rolls a D20 die.
+ * @type {(rollType?: RollTypeValue | undefined) => number}
+ */
+export const rollD20: (rollType?: RollTypeValue | undefined) => number;
+//# sourceMappingURL=roll.d.ts.map

package/dist/roll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roll.d.ts","sourceRoot":"","sources":["../src/roll.js"],"names":[],"mappings":"2BA8Ba,OAAO,oBAAoB,EAAE,YAAY;4BACzC,OAAO,qBAAqB,EAAE,aAAa;AAFxD;;;GAGG;AAEH;;;;;;;;;;;GAWG;AACH,8BARW,YAAY,aACZ,aAAa,GAAG,SAAS,GACvB,MAAM,CAwBlB;AAMD;;;;;;GAMG;AACH,sBALU,CAAC,OAAO,EAAE,YAAY,KAAK,MAAM,CAKoB;AAE/D;;;;;;GAMG;AACH,sBALU,CAAC,OAAO,EAAE,YAAY,KAAK,MAAM,CAKuB;AAElE;;;GAGG;AACH,qBAFU,CAAC,QAAQ,CAAC,EAAE,aAAa,GAAG,SAAS,KAAK,MAAM,CAEU;AAEpE;;;GAGG;AACH,qBAFU,CAAC,QAAQ,CAAC,EAAE,aAAa,GAAG,SAAS,KAAK,MAAM,CAEU;AAEpE;;;GAGG;AACH,qBAFU,CAAC,QAAQ,CAAC,EAAE,aAAa,GAAG,SAAS,KAAK,MAAM,CAEU;AAEpE;;;GAGG;AACH,sBAFU,CAAC,QAAQ,CAAC,EAAE,aAAa,GAAG,SAAS,KAAK,MAAM,CAEY;AAEtE;;;GAGG;AACH,sBAFU,CAAC,QAAQ,CAAC,EAAE,aAAa,GAAG,SAAS,KAAK,MAAM,CAEY;AAEtE;;;GAGG;AACH,sBAFU,CAAC,QAAQ,CAAC,EAAE,aAAa,GAAG,SAAS,KAAK,MAAM,CAEY"}