@platonic-dice/core 2.0.0

package/dist/rollTest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollTest.d.ts","sourceRoot":"","sources":["../src/rollTest.js"],"names":[],"mappings":";;;;;;;oBA6Ba,OAAO,oBAAoB,EAAE,YAAY;oBACzC,OAAO,oBAAoB,EAAE,YAAY;qBACzC,OAAO,qBAAqB,EAAE,aAAa;qBAC3C,OAAO,qBAAqB,EAAE,aAAa;8BAC3C,OAAO,2BAA2B,EAAE,sBAAsB;AALvE;;;;;;GAMG;AAEH;;;;;;;;;;;;GAYG;AACH,mCATW,YAAY,kBACZ,sBAAsB,GAAC;IAAE,QAAQ,EAAE,aAAa,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,aAItE,aAAa,GACX;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAgBnD"}

package/dist/rollTest.js

@@ -0,0 +1,100 @@
+/**
+ * @module @platonic-dice/core/src/rollTest
+ * @description
+ * Rolls a die and evaluates it against a set of test conditions.
+ * Supports either a `TestConditions` instance or a plain object
+ * with `{ testType, ...conditions }`.
+ *
+ * @example
+ * import { rollTest, TestType, DieType, RollType } from "@platonic-dice/core";
+ *
+ * // Basic "at least" test
+ * const result = rollTest(DieType.D20, { testType: TestType.AtLeast, target: 15 });
+ * console.log(result.base);     // e.g., 12
+ * console.log(result.outcome);  // e.g., "failure"
+ *
+ * @example
+ * // Roll with advantage
+ * const resultAdv = rollTest(
+ *   DieType.D20,
+ *   { testType: TestType.AtMost, target: 5 },
+ *   RollType.Advantage
+ * );
+ */
+const { DieType, TestType } = require("./entities");
+const tc = require("./entities/TestConditions.js");
+const r = require("./roll.js");
+const utils = require("./utils");
+
+/**
+ * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
+ * @typedef {import("./entities/Outcome").OutcomeValue} OutcomeValue
+ * @typedef {import("./entities/RollType").RollTypeValue} RollTypeValue
+ * @typedef {import("./entities/TestType").TestTypeValue} TestTypeValue
+ * @typedef {import("./entities/TestConditions").TestConditionsInstance} TestConditionsInstance
+ */
+
+/**
+ * Rolls a die and evaluates it against specified test conditions.
+ *
+ * @function rollTest
+ * @param {DieTypeValue} dieType - The type of die to roll (e.g., `DieType.D6`, `DieType.D20`).
+ * @param {TestConditionsInstance|{ testType: TestTypeValue, [key: string]: any }} testConditions
+ *   Can be:
+ *   - A `TestConditions` instance.
+ *   - A plain object `{ testType, ...conditions }`.
+ * @param {RollTypeValue} [rollType=undefined] - Optional roll mode (`RollType.Advantage` or `RollType.Disadvantage`).
+ * @returns {{ base: number, outcome: OutcomeValue }} The raw roll and its evaluated outcome.
+ * @throws {TypeError} If `dieType` or `testConditions` are invalid.
+ */
+function rollTest(dieType, testConditions, rollType = undefined) {
+  if (!dieType) throw new TypeError("dieType is required.");
+
+  // Normalise testConditions
+  const conditionSet = tc.normaliseTestConditions(testConditions, dieType);
+
+  // Perform the roll
+  const base = r.roll(dieType, rollType);
+
+  // Determine the outcome using the normalized conditions
+  const outcome = utils.determineOutcome(base, conditionSet);
+
+  return { base, outcome };
+}
+
+//
+// --- Convenience Aliases ---
+//
+
+/**
+ * Generates a DieType + TestType-specific alias for `rollTest`.
+ *
+ * @private
+ * @param {DieTypeValue} dieType
+ * @param {TestTypeValue} testType
+ * @returns {(target: number, rollType?: RollTypeValue|undefined) => { base: number, outcome: OutcomeValue }}
+ */
+function alias(dieType, testType) {
+  return (target, rollType = undefined) =>
+    rollTest(dieType, { testType, target }, rollType);
+}
+
+/**
+ * Container for all dynamically generated aliases.
+ * @type {Record<string, (target: number, rollType?: RollTypeValue|undefined) => { base: number, outcome: OutcomeValue }>}
+ */
+const aliases = {};
+
+// Dynamically generate aliases for all DieTypes × TestTypes
+for (const [dieKey, dieValue] of Object.entries(DieType)) {
+  for (const [testKey, testValue] of Object.entries(TestType)) {
+    const aliasName = `roll${dieKey}${testKey}`; // e.g., rollD20AtLeast
+    aliases[aliasName] = alias(dieValue, testValue);
+  }
+}
+
+// Export all generated aliases
+module.exports = {
+  rollTest,
+  ...aliases,
+};

package/dist/utils/determineOutcome.d.ts

@@ -0,0 +1,45 @@
+export type OutcomeValue = import("../entities/Outcome").OutcomeValue;
+export type TestConditionsInstance = import("../entities/TestConditions").TestConditionsInstance;
+export type Conditions = import("../entities/TestConditions").Conditions;
+export type TestTypeValue = import("../entities/TestType").TestTypeValue;
+export type DieTypeValue = import("../entities/DieType").DieTypeValue;
+export type TestConditionsLike = {
+    testType: TestTypeValue;
+    dieType: DieTypeValue;
+} & Conditions;
+/**
+ * @typedef {import("../entities/Outcome").OutcomeValue} OutcomeValue
+ * @typedef {import("../entities/TestConditions").TestConditionsInstance} TestConditionsInstance
+ * @typedef {import("../entities/TestConditions").Conditions} Conditions
+ * @typedef {import("../entities/TestType").TestTypeValue} TestTypeValue
+ * @typedef {import("../entities/DieType").DieTypeValue} DieTypeValue
+ */
+/**
+ * @private
+ * @typedef {{ testType: TestTypeValue, dieType: DieTypeValue } & Conditions} TestConditionsLike
+ */
+/**
+ * Determines the outcome of a roll based on provided {@link TestConditions}.
+ * Returns standard {@link Outcome} values including success, failure, and criticals.
+ *
+ * @function determineOutcome
+ * @param {number} value - The rolled (possibly modified) result.
+ * @param {TestConditionsInstance|TestConditionsLike} testConditions - The conditions defining success/failure thresholds.
+ * @returns {OutcomeValue} The resulting outcome.
+ * @throws {TypeError} If the provided conditions or test type are invalid.
+ *
+ * @example
+ * const test = new TestConditions(TestType.AtLeast, { target: 12 });
+ * const outcome = determineOutcome(14, test);
+ * console.log(outcome); // "success"
+ *
+ * @example
+ * const skill = new TestConditions(TestType.Skill, {
+ *   target: 10,
+ *   critical_success: 20,
+ *   critical_failure: 1
+ * });
+ * console.log(determineOutcome(1, skill)); // "critical_failure"
+ */
+export function determineOutcome(value: number, testConditions: TestConditionsInstance | TestConditionsLike): OutcomeValue;
+//# sourceMappingURL=determineOutcome.d.ts.map

package/dist/utils/determineOutcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"determineOutcome.d.ts","sourceRoot":"","sources":["../../src/utils/determineOutcome.js"],"names":[],"mappings":"2BAWa,OAAO,qBAAqB,EAAE,YAAY;qCAC1C,OAAO,4BAA4B,EAAE,sBAAsB;yBAC3D,OAAO,4BAA4B,EAAE,UAAU;4BAC/C,OAAO,sBAAsB,EAAE,aAAa;2BAC5C,OAAO,qBAAqB,EAAE,YAAY;iCAK1C;IAAE,QAAQ,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GAAG,UAAU;AAV5E;;;;;;GAMG;AAEH;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wCAlBW,MAAM,kBACN,sBAAsB,GAAC,kBAAkB,GACvC,YAAY,CAgFxB"}

package/dist/utils/determineOutcome.js

@@ -0,0 +1,115 @@
+/**
+ * @module @platonic-dice/core/src/utils/determineOutcome
+ * @description
+ * Determines the outcome of a roll based on provided test conditions.
+ */
+
+function getEntities() {
+  return require("../entities");
+}
+
+/**
+ * @typedef {import("../entities/Outcome").OutcomeValue} OutcomeValue
+ * @typedef {import("../entities/TestConditions").TestConditionsInstance} TestConditionsInstance
+ * @typedef {import("../entities/TestConditions").Conditions} Conditions
+ * @typedef {import("../entities/TestType").TestTypeValue} TestTypeValue
+ * @typedef {import("../entities/DieType").DieTypeValue} DieTypeValue
+ */
+
+/**
+ * @private
+ * @typedef {{ testType: TestTypeValue, dieType: DieTypeValue } & Conditions} TestConditionsLike
+ */
+
+/**
+ * Determines the outcome of a roll based on provided {@link TestConditions}.
+ * Returns standard {@link Outcome} values including success, failure, and criticals.
+ *
+ * @function determineOutcome
+ * @param {number} value - The rolled (possibly modified) result.
+ * @param {TestConditionsInstance|TestConditionsLike} testConditions - The conditions defining success/failure thresholds.
+ * @returns {OutcomeValue} The resulting outcome.
+ * @throws {TypeError} If the provided conditions or test type are invalid.
+ *
+ * @example
+ * const test = new TestConditions(TestType.AtLeast, { target: 12 });
+ * const outcome = determineOutcome(14, test);
+ * console.log(outcome); // "success"
+ *
+ * @example
+ * const skill = new TestConditions(TestType.Skill, {
+ *   target: 10,
+ *   critical_success: 20,
+ *   critical_failure: 1
+ * });
+ * console.log(determineOutcome(1, skill)); // "critical_failure"
+ */
+function determineOutcome(value, testConditions) {
+  const { Outcome, TestType, TestConditions } = getEntities();
+
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    throw new TypeError("value must be a valid number.");
+  }
+
+  // Normalise plain object input into a TestConditions instance
+  if (!(testConditions instanceof TestConditions)) {
+    const { testType, dieType, ...rest } = /** @type {TestConditionsLike} */ (
+      testConditions
+    );
+
+    // Inject dieType into the conditions object to satisfy TestConditions
+    const fullConditions = { ...rest, dieType };
+
+    testConditions = new TestConditions(testType, fullConditions, dieType);
+  }
+
+  /** @type {TestConditionsInstance} */
+  const { testType, conditions } = testConditions;
+
+  switch (testType) {
+    case TestType.AtLeast:
+    case TestType.AtMost:
+    case TestType.Exact: {
+      const { target } = /** @type {{ target: number }} */ (conditions);
+      if (testType === TestType.AtLeast)
+        return value >= target ? Outcome.Success : Outcome.Failure;
+      if (testType === TestType.AtMost)
+        return value <= target ? Outcome.Success : Outcome.Failure;
+      return value === target ? Outcome.Success : Outcome.Failure;
+    }
+
+    case TestType.Within: {
+      const { min, max } = /** @type {{ min: number, max: number }} */ (
+        conditions
+      );
+      return value >= min && value <= max ? Outcome.Success : Outcome.Failure;
+    }
+
+    case TestType.InList: {
+      const { values } = /** @type {{ values: number[] }} */ (conditions);
+      return Array.isArray(values) && values.includes(value)
+        ? Outcome.Success
+        : Outcome.Failure;
+    }
+
+    case TestType.Skill: {
+      const { target, critical_success, critical_failure } =
+        /** @type {{ target: number, critical_success?: number, critical_failure?: number }} */ (
+          conditions
+        );
+
+      if (critical_failure != null && value <= critical_failure)
+        return Outcome.CriticalFailure;
+      if (critical_success != null && value >= critical_success)
+        return Outcome.CriticalSuccess;
+      return value >= target ? Outcome.Success : Outcome.Failure;
+    }
+
+    default:
+      throw new TypeError(`Unknown or unsupported testType '${testType}'.`);
+  }
+}
+
+module.exports = {
+  determineOutcome,
+};

package/dist/utils/generateResult.d.ts

@@ -0,0 +1,30 @@
+export type DieTypeValue = import("../entities/DieType").DieTypeValue;
+/**
+ * Generates a single roll result for a given die type.
+ *
+ * @function generateResult
+ * @param {DieTypeValue} dieType - The type of die to roll (e.g., "d6", "d20").
+ * @returns {number} The result of rolling the die.
+ * @throws {TypeError} If the die type is invalid.
+ *
+ * @example
+ * const result = generateResult("d6");
+ * console.log(result); // 1..6
+ */
+export function generateResult(dieType: DieTypeValue): number;
+/**
+ * @typedef {import("../entities/DieType").DieTypeValue} DieTypeValue
+ */
+/**
+ * Returns the number of sides on a die given its type.
+ *
+ * @function numSides
+ * @param {DieTypeValue} dieType - The die type (e.g., "d6", "d20").
+ * @returns {number} Number of sides.
+ * @throws {TypeError} If the die type is invalid.
+ *
+ * @example
+ * console.log(numSides("d6")); // 6
+ */
+export function numSides(dieType: DieTypeValue): number;
+//# sourceMappingURL=generateResult.d.ts.map

package/dist/utils/generateResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateResult.d.ts","sourceRoot":"","sources":["../../src/utils/generateResult.js"],"names":[],"mappings":"2BASa,OAAO,qBAAqB,EAAE,YAAY;AAqBvD;;;;;;;;;;;GAWG;AACH,wCARW,YAAY,GACV,MAAM,CAUlB;AArCD;;GAEG;AAEH;;;;;;;;;;GAUG;AACH,kCAPW,YAAY,GACV,MAAM,CAWlB"}

package/dist/utils/generateResult.js

@@ -0,0 +1,51 @@
+/**
+ * @module @platonic-dice/core/src/utils/generateResult
+ * @description
+ * Generates a single roll result for a given die type.
+ */
+
+const { isValidDieType } = require("../entities/DieType");
+
+/**
+ * @typedef {import("../entities/DieType").DieTypeValue} DieTypeValue
+ */
+
+/**
+ * Returns the number of sides on a die given its type.
+ *
+ * @function numSides
+ * @param {DieTypeValue} dieType - The die type (e.g., "d6", "d20").
+ * @returns {number} Number of sides.
+ * @throws {TypeError} If the die type is invalid.
+ *
+ * @example
+ * console.log(numSides("d6")); // 6
+ */
+function numSides(dieType) {
+  if (!isValidDieType(dieType)) {
+    throw new TypeError(`Invalid die type: ${dieType}`);
+  }
+  return parseInt(dieType.slice(1));
+}
+
+/**
+ * Generates a single roll result for a given die type.
+ *
+ * @function generateResult
+ * @param {DieTypeValue} dieType - The type of die to roll (e.g., "d6", "d20").
+ * @returns {number} The result of rolling the die.
+ * @throws {TypeError} If the die type is invalid.
+ *
+ * @example
+ * const result = generateResult("d6");
+ * console.log(result); // 1..6
+ */
+function generateResult(dieType) {
+  const sides = numSides(dieType); // validation of dieType happens here
+  return Math.floor(Math.random() * sides) + 1;
+}
+
+module.exports = {
+  generateResult,
+  numSides,
+};

package/dist/utils/index.d.ts

@@ -0,0 +1,5 @@
+import { determineOutcome } from "./determineOutcome.js";
+import { generateResult } from "./generateResult.js";
+import { numSides } from "./generateResult.js";
+export { determineOutcome, generateResult, numSides };
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/utils/index.js

@@ -0,0 +1,26 @@
+/**
+ * @module @platonic-dice/core/src/utils
+ * @description
+ * Internal utility functions for core dice logic.
+ *
+ * These functions provide shared, low-level logic such as
+ * generating random die results, computing number of sides,
+ * and evaluating roll outcomes.
+ *
+ * They are used internally by the `@platonic-dice/core/src` roll functions
+ * and entity validation routines.
+ *
+ * @private
+ *
+ * @example
+ * // Internal usage only — not part of the public API
+ * import { generateDieResult, determineOutcome } from "../utils";
+ */
+const { determineOutcome } = require("./determineOutcome.js");
+const { generateResult, numSides } = require("./generateResult.js");
+
+module.exports = {
+  determineOutcome,
+  generateResult,
+  numSides,
+};

package/dist-types.d.ts

@@ -0,0 +1,48 @@
+// Convenience type re-exports for consumers. This file points at the generated
+// declaration files in `dist/entities` so TypeScript users can import type
+// aliases directly from the package root via the `types` field.
+
+export type {
+  RollModifierFunction,
+  RollModifierInstance,
+} from "./dist/entities/RollModifier";
+export type { OutcomeValue } from "./dist/entities/Outcome";
+export type { TestConditionsInstance } from "./dist/entities/TestConditions";
+export type { RollTypeValue } from "./dist/entities/RollType";
+export type { TestTypeValue } from "./dist/entities/TestType";
+export type { DieTypeValue } from "./dist/entities/DieType";
+
+// Re-export other commonly used entity types
+export * from "./dist/entities/index";
+
+// Re-export top-level runtime APIs (roll helpers) so consumers can import
+// functions like `roll`, `rollMod`, and `rollTest` from the package root.
+export * from "./dist/roll";
+export * from "./dist/rollMod";
+export * from "./dist/rollDice";
+export * from "./dist/rollDiceMod";
+export * from "./dist/rollTest";
+
+// The `rollMod`/`rollTest` d.ts files are emitted using a CommonJS `export =`
+// shape which doesn't always expose named exports for consumers under some
+// moduleResolution strategies. Provide explicit ESM-style type declarations
+// here so TypeScript imports like `import { rollMod } from '@platonic-dice/core'`
+// resolve correctly.
+export function rollMod(
+  dieType: import("./dist/entities/DieType").DieTypeValue,
+  modifier:
+    | import("./dist/entities/RollModifier").RollModifierFunction
+    | import("./dist/entities/RollModifier").RollModifierInstance,
+  rollType?: import("./dist/entities/RollType").RollTypeValue
+): { base: number; modified: number };
+
+export function rollTest(
+  dieType: import("./dist/entities/DieType").DieTypeValue,
+  testConditions:
+    | import("./dist/entities/TestConditions").TestConditionsInstance
+    | {
+        testType: import("./dist/entities/TestType").TestTypeValue;
+        [k: string]: any;
+      },
+  rollType?: import("./dist/entities/RollType").RollTypeValue
+): { base: number; outcome: import("./dist/entities/Outcome").OutcomeValue };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@platonic-dice/core",
+  "version": "2.0.0",
+  "description": "Core JavaScript logic for simulating TTRPG dice rolls.",
+  "main": "dist/index.js",
+  "types": "dist-types.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "types": "./dist-types.d.ts"
+    },
+    "./entities": {
+      "require": "./dist/entities/index.js",
+      "types": "./dist/entities/index.d.ts"
+    }
+  },
+  "files": ["dist", "dist-types.d.ts"],
+  "keywords": [
+    "dice",
+    "TTRPG",
+    "random",
+    "game",
+    "d20",
+    "dnd",
+    "core"
+  ],
+  "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": "rm -rf dist && mkdir -p dist && cp -R src/* dist/ && tsc -p tsconfig.json --emitDeclarationOnly",
+    "prepublishOnly": "npm run build",
+    "test": "jest",
+    "test:types": "tsd"
+  },
+  "tsd": {
+    "directory": "src/test-d"
+  }
+}