@platonic-dice/core 2.1.2 → 3.0.0

package/README.md

@@ -9,7 +9,7 @@ This package contains the pure logic used by higher-level packages (for example
 Install from npm:
 
 ```bash
-npm install @platonic-dice/core
+npm install @platonic-dice/core @types/platonic-dice__core
 ```
 
 ## Quick usage
@@ -34,7 +34,7 @@ const result = rollModTest(DieType.D20, (n) => n + 5, {
   target: 15,
 });
 console.log(
-  `Roll: ${result.base}, Modified: ${result.modified}, Outcome: ${result.outcome}`
+  `Roll: ${result.base}, Modified: ${result.modified}, Outcome: ${result.outcome}`,
 );
 ```
 
@@ -69,6 +69,15 @@ cd packages/core
 npm test
 ```
 
+### Type Testing
+
+Type definitions are provided by the separate `@types/platonic-dice__core` package. To test the type surface:
+
+```bash
+cd packages/types-core
+pnpm run test:types
+```
+
 ## Examples
 
 The `examples/` directory contains comprehensive examples for all major functions. Run them to see the library in action:

package/dist/analyseModTest.js

@@ -21,12 +21,12 @@ const { normaliseRollModifier } = require("./entities");
 const { ModifiedTestConditions } = require("./entities/ModifiedTestConditions");
 const { createOutcomeMap } = require("./utils/outcomeMapper");
 const { numSides } = require("./utils");
+const { getEvaluator } = require("./utils/getEvaluator");
 
 /**
  * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
  * @typedef {import("./entities/Outcome").OutcomeValue} OutcomeValue
- * @typedef {import("./entities/RollModifier").RollModifierFunction} RollModifierFunction
- * @typedef {import("./entities/RollModifier").RollModifierInstance} RollModifierInstance
+ * @typedef {import("./entities/RollModifier").RollModifierLike} RollModifierLike
  * @typedef {import("./entities/TestType").TestTypeValue} TestTypeValue
  * @typedef {import("./entities/TestConditions").TestConditionsInstance} TestConditionsInstance
  */
@@ -54,8 +54,9 @@ const { numSides } = require("./utils");
  *
  * @function analyseModTest
  * @param {DieTypeValue} dieType - The type of die (e.g., `DieType.D20`).
- * @param {RollModifierFunction|RollModifierInstance} modifier - The modifier to apply to the roll.
- * @param {TestConditionsInstance|{ testType: TestTypeValue, [key: string]: any }} testConditions
+ * @param {RollModifierLike} modifier - The modifier to apply to the roll.
+ * @typedef {import("./entities/TestConditions").TestConditionsLike} TestConditionsLike
+ * @param {TestConditionsLike} testConditions
  *   Can be:
  *   - A `TestConditions` instance
  *   - A plain object `{ testType, ...conditions }`
@@ -98,7 +99,7 @@ function analyseModTest(dieType, modifier, testConditions, options = {}) {
   const mod =
     modifier instanceof RollModifier
       ? modifier
-      : normaliseRollModifier(modifier);
+      : normaliseRollModifier(/** @type {any} */ (modifier));
 
   // Create ModifiedTestConditions if input is a plain object
   let conditionSet;
@@ -111,17 +112,18 @@ function analyseModTest(dieType, modifier, testConditions, options = {}) {
     conditionSet = new ModifiedTestConditions(testType, rest, dieType, mod);
   }
 
-  // Create outcome map for all possible rolls (with modifier applied)
-  const outcomeMap = createOutcomeMap(
+  // Obtain evaluator (registry or fallback) and build outcome map
+  const evaluator = getEvaluator(
     dieType,
-    conditionSet.testType,
     // @ts-ignore - ModifiedTestConditions is compatible with TestConditions for outcome mapping
     conditionSet,
-    mod, // include modifier
+    mod,
     options.useNaturalCrits
   );
-
   const sides = numSides(dieType);
+  /** @type {Object.<number, OutcomeValue>} */
+  const outcomeMap = {};
+  for (let roll = 1; roll <= sides; roll++) outcomeMap[roll] = evaluator(roll);
   const totalPossibilities = sides;
 
   // Calculate modified values for each roll

package/dist/analyseTest.js

@@ -22,6 +22,7 @@ const { DieType, TestType } = require("./entities");
 const tc = require("./entities/TestConditions.js");
 const { createOutcomeMap } = require("./utils/outcomeMapper");
 const { numSides } = require("./utils");
+const { getEvaluator } = require("./utils/getEvaluator");
 
 /**
  * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
@@ -51,7 +52,8 @@ const { numSides } = require("./utils");
  *
  * @function analyseTest
  * @param {DieTypeValue} dieType - The type of die (e.g., `DieType.D20`).
- * @param {TestConditionsInstance|{ testType: TestTypeValue, [key: string]: any }} testConditions
+ * @typedef {import("./entities/TestConditions").TestConditionsLike} TestConditionsLike
+ * @param {TestConditionsLike} testConditions
  *   Can be:
  *   - A `TestConditions` instance.
  *   - A plain object `{ testType, ...conditions }`.
@@ -83,21 +85,51 @@ function analyseTest(dieType, testConditions, options = {}) {
   if (!dieType) throw new TypeError("dieType is required.");
 
   // Normalise testConditions (skip if already a TestConditions instance)
-  const conditionSet =
-    testConditions instanceof tc.TestConditions
-      ? testConditions
-      : tc.normaliseTestConditions(testConditions, dieType);
+  let conditionSet;
+  if (testConditions instanceof tc.TestConditions) {
+    conditionSet = testConditions;
+  } else {
+    // Plain object: validate early for clearer errors, then normalise.
+    // We still call `normaliseTestConditions` so tests and any instrumentation
+    // that spy on it will observe the delegation (and the constructor remains
+    // the final authority for detailed RangeErrors).
+    const { testType, ...rest } = testConditions;
+    const fullConditions = { ...rest, dieType };
+    const validators = require("./utils/testValidators");
+    const { isValidTestType } = require("./entities/TestType");
 
-  // Create outcome map for all possible rolls
-  const outcomeMap = createOutcomeMap(
+    if (!isValidTestType(testType)) {
+      try {
+        tc.normaliseTestConditions(testConditions, dieType);
+      } catch (err) {
+        // ignore deeper error
+      }
+      throw new TypeError(`Invalid test type: ${testType}`);
+    }
+
+    if (!validators.areValidTestConditions(fullConditions, testType)) {
+      try {
+        tc.normaliseTestConditions(testConditions, dieType);
+      } catch (err) {
+        // ignore deeper error
+      }
+      throw new TypeError("Invalid test conditions shape.");
+    }
+
+    conditionSet = tc.normaliseTestConditions(testConditions, dieType);
+  }
+
+  // Obtain evaluator (registry or fallback) and build outcome map
+  const evaluator = getEvaluator(
     dieType,
-    conditionSet.testType,
     conditionSet,
-    null, // no modifier
-    options.useNaturalCrits
+    undefined,
+    options.useNaturalCrits,
   );
-
   const sides = numSides(dieType);
+  /** @type {Object.<number, OutcomeValue>} */
+  const outcomeMap = {};
+  for (let roll = 1; roll <= sides; roll++) outcomeMap[roll] = evaluator(roll);
   const totalPossibilities = sides;
 
   // Count outcomes

package/dist/entities/DiceTestConditions.js

@@ -0,0 +1,174 @@
+/**
+ * @module @platonic-dice/core/src/entities/DiceTestConditions
+ * @description
+ * Aggregates `TestConditionsArray` evaluations across multiple dice and
+ * applies simple aggregation rules such as "at least N dice equal X" or
+ * "at least N dice satisfy condition #k".
+ */
+
+const { TestConditionsArray } = require("./TestConditionsArray");
+const { getArrayEvaluator } = require("../utils/getArrayEvaluator");
+const { Outcome } = require("./Outcome");
+const { DieType } = require("./DieType");
+
+/**
+ * @typedef {import("./TestConditions").TestConditionsLike} TestConditionsLike
+ */
+
+/**
+ * @typedef {Object} Rule
+ * @property {"value_count"|"condition_count"} type
+ * @property {number} [value]
+ * @property {number} [conditionIndex]
+ * @property {number} [exact]
+ * @property {number} [atLeast]
+ * @property {number} [atMost]
+ */
+
+class DiceTestConditions {
+  /**
+   * @param {{ count?: number, conditions?: TestConditionsLike[]|TestConditionsArray, rules?: Rule[], dieType?: string }} [opts]
+   */
+  constructor(opts = {}) {
+    const { count, conditions, rules = [], dieType = undefined } = opts;
+    if (typeof count !== "number" || !Number.isInteger(count) || count < 1) {
+      throw new TypeError("count must be a positive integer");
+    }
+    this.count = count;
+
+    // Normalise conditions into TestConditionsArray
+    if (conditions instanceof TestConditionsArray) {
+      this.tcArray = conditions;
+    } else if (Array.isArray(conditions)) {
+      // If caller didn't supply a default die type, assume D6 for value-based
+      // multi-dice tests (most common simple use-case in tests).
+      const defaultDie = dieType || DieType.D6;
+      this.tcArray = new TestConditionsArray(
+        conditions,
+        /** @type {any} */ (defaultDie),
+      );
+    } else {
+      throw new TypeError("conditions must be an array or TestConditionsArray");
+    }
+
+    // Rules are simple objects. We'll validate minimally here.
+    this.rules = rules.map((r, idx) => {
+      if (!r || typeof r !== "object")
+        throw new TypeError(`rule ${idx} must be an object`);
+      // Ensure required shape
+      if (r.type !== "value_count" && r.type !== "condition_count")
+        throw new TypeError(`unsupported rule type: ${r.type}`);
+      return /** @type {Rule} */ (r);
+    });
+  }
+
+  /**
+   * Returns an evaluator function that accepts an array of rolled values
+   * and returns an aggregated result object.
+   *
+   * @param {import("./RollModifier").RollModifierInstance} [modifier]
+   * @param {boolean} [useNaturalCrits]
+   * @returns {(rolls: number[]) => Object}
+   */
+  toEvaluator(modifier = undefined, useNaturalCrits = undefined) {
+    const tcArray = this.tcArray;
+    const arrayEvaluator = getArrayEvaluator(
+      tcArray,
+      modifier,
+      useNaturalCrits,
+    );
+    const expectedCount = this.count;
+    const rules = this.rules;
+
+    return /** @param {number[]} rolls */ (rolls) => {
+      if (!Array.isArray(rolls))
+        throw new TypeError("rolls must be an array of numbers");
+      if (rolls.length !== expectedCount)
+        throw new TypeError(
+          `rolls length ${rolls.length} does not match expected count ${expectedCount}`,
+        );
+
+      // Build matrix: for each die -> array of outcomes per condition
+      const matrix = rolls.map((v) => arrayEvaluator(v));
+
+      // Count successes per condition (treat success or critical_success as match)
+      /** @type {{[k:number]: number}} */
+      const condCount = {};
+      for (let i = 0; i < tcArray.toArray().length; i++) condCount[i] = 0;
+
+      matrix.forEach((outcomes) => {
+        outcomes.forEach((o, condIdx) => {
+          if (o === Outcome.Success || o === Outcome.CriticalSuccess)
+            condCount[condIdx]++;
+        });
+      });
+
+      // Count literal values matches (raw equality)
+      /** @type {{[k:number]: number}} */
+      const valueCounts = {};
+      rolls.forEach((v) => {
+        valueCounts[v] = (valueCounts[v] || 0) + 1;
+      });
+
+      // Evaluate rules
+      const ruleResults = rules.map((r, idx) => {
+        if (r.type === "value_count") {
+          const val = /** @type {number|undefined} */ (r.value);
+          const cnt = val == null ? 0 : valueCounts[val] || 0;
+          const passed = _checkThreshold(cnt, r);
+          return { id: idx, rule: r, count: cnt, passed };
+        }
+
+        // condition_count
+        if (r.type === "condition_count") {
+          const ci = /** @type {number|undefined} */ (r.conditionIndex);
+          if (typeof ci !== "number" || !(ci in condCount)) {
+            throw new TypeError(`invalid conditionIndex in rule ${idx}`);
+          }
+          const cnt = condCount[ci] || 0;
+          const passed = _checkThreshold(cnt, r);
+          return { id: idx, rule: r, count: cnt, passed };
+        }
+        // unreachable
+        return { id: idx, rule: r, passed: false };
+      });
+
+      const passed = ruleResults.every((rr) => rr.passed);
+
+      return {
+        matrix,
+        condCount,
+        valueCounts,
+        ruleResults,
+        passed,
+      };
+    };
+  }
+
+  /**
+   * Convenience: evaluate immediately against provided rolls
+   * @param {number[]} rolls
+   * @param {import("./RollModifier").RollModifierInstance|undefined} [modifier=undefined]
+   * @param {boolean|undefined} [useNaturalCrits=undefined]
+   */
+  evaluateRolls(rolls, modifier = undefined, useNaturalCrits = undefined) {
+    return this.toEvaluator(modifier, useNaturalCrits)(rolls);
+  }
+}
+
+/**
+ * @param {number} count
+ * @param {Rule} rule
+ * @returns {boolean}
+ */
+function _checkThreshold(count, rule) {
+  if (rule.exact != null) return count === rule.exact;
+  if (rule.atLeast != null) return count >= rule.atLeast;
+  if (rule.atMost != null) return count <= rule.atMost;
+  // default: require atLeast 1 if nothing provided
+  return count >= 1;
+}
+
+module.exports = {
+  DiceTestConditions,
+};

package/dist/entities/ModifiedTestConditions.js

@@ -21,12 +21,18 @@ const { isValidDieType } = require("./DieType");
 const { isValidTestType } = require("./TestType");
 const { normaliseRollModifier } = require("./RollModifier");
 const { numSides } = require("../utils");
+const validators = require("../utils/testValidators");
 
 /**
  * @typedef {import("./TestType").TestTypeValue} TestTypeValue
  * @typedef {import("./DieType").DieTypeValue} DieTypeValue
  * @typedef {import("./RollModifier").RollModifierFunction} RollModifierFunction
  * @typedef {import("./RollModifier").RollModifierInstance} RollModifierInstance
+ * @typedef {import("./RollModifier").RollModifierLike} RollModifierLike
+ */
+/**
+ * @typedef {import("../utils/testValidators").Conditions} Conditions
+ * @typedef {import("../utils/testValidators").PlainObject} PlainObject
  */
 
 /**
@@ -64,7 +70,7 @@ class ModifiedTestConditions {
    * @param {TestTypeValue} testType - The test type.
    * @param {Conditions} conditions - The test conditions object.
    * @param {DieTypeValue} dieType - The base die type.
-   * @param {RollModifierFunction | RollModifierInstance} modifier - The modifier to apply.
+   * @param {RollModifierLike} modifier - The modifier to apply.
    * @throws {TypeError|RangeError} If the test type or conditions are invalid.
    */
   constructor(testType, conditions, dieType, modifier) {
@@ -84,8 +90,8 @@ class ModifiedTestConditions {
       throw new TypeError("modifier is required.");
     }
 
-    // Normalize the modifier
-    const mod = normaliseRollModifier(modifier);
+    // normalise the modifier
+    const mod = normaliseRollModifier(/** @type {any} */ (modifier));
 
     // Compute the achievable range with this modifier
     const range = computeModifiedRange(dieType, mod);
@@ -153,7 +159,7 @@ class ModifiedTestConditions {
  * Validates test conditions against a modified range.
  *
  * @private
- * @param {Conditions & Record<string, any>} c - Conditions with modifiedRange
+ * @param {ModifiedConditions & PlainObject} c - Conditions with modifiedRange
  * @param {TestTypeValue} testType
  * @returns {boolean}
  */
@@ -185,13 +191,12 @@ function areValidModifiedTestConditions(c, testType) {
       );
 
     case "in_list":
+      // Use shared validator helper for range checks (accepts arrays)
       return (
         Array.isArray(c.values) &&
-        c.values.length > 0 &&
-        c.values.every(
-          (v) =>
-            typeof v === "number" && Number.isInteger(v) && v >= min && v <= max
-        )
+        validators.areValidValuesInRange({ values: c.values }, min, max, [
+          "values",
+        ])
       );
 
     case "skill":
@@ -205,33 +210,17 @@ function areValidModifiedTestConditions(c, testType) {
         return false;
       }
 
-      // critical_success is optional but must be valid if present
-      if (c.critical_success !== undefined) {
-        if (
-          typeof c.critical_success !== "number" ||
-          !Number.isInteger(c.critical_success) ||
-          c.critical_success < min ||
-          c.critical_success > max ||
-          c.critical_success < c.target
-        ) {
-          return false;
-        }
-      }
-
-      // critical_failure is optional but must be valid if present
-      if (c.critical_failure !== undefined) {
-        if (
-          typeof c.critical_failure !== "number" ||
-          !Number.isInteger(c.critical_failure) ||
-          c.critical_failure < min ||
-          c.critical_failure > max ||
-          c.critical_failure > c.target
-        ) {
-          return false;
-        }
-      }
+      // Validate critical thresholds are within range if present using helper
+      if (
+        !validators.areValidValuesInRange(c, min, max, [
+          "critical_success",
+          "critical_failure",
+        ])
+      )
+        return false;
 
-      return true;
+      // Check logical ordering using shared helper
+      return validators.isValidThresholdOrder(c);
 
     default:
       return false;
@@ -239,19 +228,19 @@ function areValidModifiedTestConditions(c, testType) {
 }
 
 /**
- * @typedef {Object} BaseTestCondition
+ * @typedef {Object} ModifiedBaseTestCondition
  * @property {{ min: number, max: number }} modifiedRange
  */
 
 /**
- * @typedef {BaseTestCondition & { target: number }} TargetConditions
- * @typedef {BaseTestCondition & { min: number, max: number }} WithinConditions
- * @typedef {BaseTestCondition & { values: number[] }} SpecificListConditions
- * @typedef {BaseTestCondition & { target: number, critical_success?: number, critical_failure?: number }} SkillConditions
+ * @typedef {ModifiedBaseTestCondition & { target: number }} ModifiedTargetConditions
+ * @typedef {ModifiedBaseTestCondition & { min: number, max: number }} ModifiedWithinConditions
+ * @typedef {ModifiedBaseTestCondition & { values: number[] }} ModifiedSpecificListConditions
+ * @typedef {ModifiedBaseTestCondition & { target: number, critical_success?: number, critical_failure?: number }} ModifiedSkillConditions
  */
 
 /**
- * @typedef {TargetConditions | SkillConditions | WithinConditions | SpecificListConditions} Conditions
+ * @typedef {ModifiedTargetConditions | ModifiedSkillConditions | ModifiedWithinConditions | ModifiedSpecificListConditions} ModifiedConditions
  */
 
 /**

package/dist/entities/RollModifier.js

@@ -11,6 +11,11 @@
  * const result = bonus.apply(10); // 12
  */
 
+/*
+ * Typedef ownership:
+ * - `RollModifierLike`, `RollModifierFunction`, `DiceModifier`, `RollModifierInstance`
+ */
+
 /**
  * @typedef {(n: number) => number} RollModifierFunction
  * @description
@@ -54,6 +59,15 @@
 /**
  * Represents a numeric modifier applied to dice rolls.
  */
+
+/**
+ * Public 'like' type for modifiers accepted across APIs.
+ * - a `RollModifier` instance
+ * - a plain function `(n:number)=>number`
+ * - a composite `DiceModifier` object with optional `each`/`net`
+ *
+ * @typedef {RollModifier | RollModifierFunction | DiceModifier} RollModifierLike
+ */
 class RollModifier {
   /**
    * @param {RollModifierFunction} fn - Modifier function.
@@ -81,7 +95,7 @@ class RollModifier {
 
   /**
    * Validates that this modifier still conforms to spec.
-   * (Useful if modifiers are loaded dynamically or serialized.)
+   * (Useful if modifiers are loaded dynamically or serialised.)
    * @throws {TypeError} If the modifier is invalid.
    */
   validate() {