@platonic-dice/core 2.1.2 → 3.0.0

package/dist/entities/TestConditions.js

@@ -9,13 +9,27 @@
  * const result = rollTest(DieType.D20, tc);
  */
 
-const { isValidDieType } = require("./DieType");
 const { isValidTestType } = require("./TestType");
-const { numSides } = require("../utils");
+const validators = require("../utils/testValidators");
+
+/* Typedef ownership:
+ * - `TestConditionsLike`
+ */
 
 /**
  * @typedef {import("./TestType").TestTypeValue} TestTypeValue
  * @typedef {import("./DieType").DieTypeValue} DieTypeValue
+ * @typedef {import("../utils/testValidators").Conditions} Conditions
+ * @typedef {import("../utils/testValidators").ConditionsLike} ConditionsLike
+ */
+
+/**
+ * A public 'like' type for test conditions accepted by many APIs.
+ * - Either a fully constructed `TestConditions` instance, or a plain
+ *   object containing at minimum a `testType` property and other condition
+ *   fields. We reuse `PlainObject` from `testValidators` for the plain case.
+ *
+ * @typedef {InstanceType<typeof TestConditions>|({ testType: TestTypeValue } & import("../utils/testValidators").PlainObject)} TestConditionsLike
  */
 
 /**
@@ -48,19 +62,19 @@ class TestConditions {
         case "at_most":
         case "exact":
           throw new RangeError(
-            `Invalid ${testType} condition for die type ${dieType}: target must be an integer within valid die faces.`
+            `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.`
+            `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.`
+            `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.`
+            `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}'.`);
@@ -77,14 +91,14 @@ class TestConditions {
 
   /**
    * Validates that the test conditions still conforms to spec.
-   * (Useful if they are loaded dynamically or serialized.)
+   * (Useful if they are loaded dynamically or serialised.)
    * @throws {TypeError} If the test conditions are invalid.
    */
   validate() {
     if (
       !areValidTestConditions(
         { ...this.conditions, dieType: this.dieType },
-        this.testType
+        this.testType,
       )
     ) {
       throw new TypeError("Invalid test conditions shape.");
@@ -101,27 +115,8 @@ class TestConditions {
  * @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;
-  }
+  // Delegate master validation to utils/testValidators for consistency
+  return validators.areValidTestConditions(c, testType);
 }
 
 /**
@@ -130,7 +125,7 @@ function areValidTestConditions(c, testType) {
  * Automatically validates all conditions for the specified die type.
  *
  * @function normaliseTestConditions
- * @param {TestConditions | { testType: TestTypeValue, [key: string]: any }} tc
+ * @param {TestConditions | TestConditionsLike} 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.
@@ -158,22 +153,10 @@ function normaliseTestConditions(tc, dieType) {
     return new TestConditions(testType, { ...rest }, dieType);
   }
   throw new TypeError(
-    `Invalid TestConditions: must be a TestConditions instance or a plain object.`
+    `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
  */
@@ -183,142 +166,3 @@ module.exports = {
   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/TestConditionsArray.js

@@ -0,0 +1,87 @@
+/**
+ * @module @platonic-dice/core/src/entities/TestConditionsArray
+ * @description
+ * Represents an ordered array of `TestConditions`-like entries which can be
+ * evaluated against a set of dice (or modified dice results) to produce an
+ * array of outcomes. This is a lightweight building block for multi-dice
+ * test types that need to evaluate multiple per-die or per-condition checks.
+ */
+
+const { TestConditions, normaliseTestConditions } = require("./TestConditions");
+
+/**
+ * @typedef {import("./TestConditions").TestConditionsInstance} TestConditionsInstance
+ * @typedef {import("./TestConditions").TestConditionsLike} TestConditionsLike
+ */
+
+class TestConditionsArray {
+  /**
+   * @param {Array<TestConditionsInstance|Object>} arr - Array of TestConditions instances or plain objects
+   * @param {string|undefined} [defaultDieType] - Optional default die type used to normalise plain objects
+  /**
+   * @param {Array<TestConditionsInstance|TestConditionsLike>} arr - Array of TestConditions instances or plain objects
+   * @param {string|undefined} [defaultDieType] - Optional default die type used to normalise plain objects
+   */
+  constructor(arr = [], defaultDieType = undefined) {
+    this.defaultDieType = defaultDieType;
+    /** @type {TestConditionsInstance[]} */
+    this.conditions = arr.map((c, idx) => {
+      // If already a TestConditions instance, accept as-is
+      if (c instanceof TestConditions) return c;
+
+      // Plain object: try to determine dieType per-entry
+      if (c && typeof c === "object") {
+        // c is a TestConditionsLike here; prefer per-entry dieType then default
+        const entryDie =
+          /** @type {TestConditionsLike} */ (c).dieType || defaultDieType;
+        if (!entryDie)
+          throw new TypeError(
+            `TestConditionsArray: element at index ${idx} requires a dieType (either on the element or a default passed to the constructor)`,
+          );
+        return normaliseTestConditions(
+          /** @type {TestConditionsLike} */ (c),
+          entryDie,
+        );
+      }
+
+      throw new TypeError(
+        `TestConditionsArray: element at index ${idx} must be a TestConditions instance or a plain object`,
+      );
+    });
+  }
+
+  /**
+   * Evaluate each contained condition against a provided numeric value.
+   * Returns an array of outcome values (strings) for each condition in order.
+   *
+   * @param {number} value - The numeric value to evaluate (e.g., a die face or modified value)
+   * @param {Function} evaluator - A function `(value, testConditionsInstance) => outcome`.
+   *        If omitted, each TestConditions instance is expected to be consumable by
+   *        existing utilities that accept a TestConditions instance.
+   * @returns {Array<string>} outcomes
+   */
+  evaluateEach(value, evaluator) {
+    if (typeof value !== "number")
+      throw new TypeError("value must be a number");
+    const evalFn = evaluator;
+    return this.conditions.map((tc) => {
+      if (typeof evalFn === "function") return evalFn(value, tc);
+      // Default: delegate to a helper that callers should provide; throw otherwise
+      throw new TypeError(
+        "No evaluator provided for TestConditionsArray.evaluateEach",
+      );
+    });
+  }
+
+  /**
+   * Convenience to return the raw TestConditions instances array.
+   * @returns {TestConditionsInstance[]}
+   */
+  toArray() {
+    return this.conditions.slice();
+  }
+}
+
+module.exports = {
+  TestConditionsArray,
+};

package/dist/entities/index.js

@@ -13,42 +13,253 @@
  * 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 {
-  ModifiedTestConditions,
-  areValidModifiedTestConditions,
-  computeModifiedRange,
-} = require("./ModifiedTestConditions.js");
-const { TestType, isValidTestType } = require("./TestType.js");
-
-module.exports = {
-  DieType,
-  isValidDieType,
-  Outcome,
-  isValidOutcome,
-  RollModifier,
-  isValidRollModifier,
-  normaliseRollModifier,
-  RollType,
-  isValidRollType,
-  TestConditions,
-  areValidTestConditions,
-  normaliseTestConditions,
-  ModifiedTestConditions,
-  areValidModifiedTestConditions,
-  computeModifiedRange,
-  TestType,
-  isValidTestType,
-};
+// Lazy-loaded per-export getters to avoid circular require during
+// module initialization. Each exported name is resolved on first
+// access and cached locally. Properties are `configurable: true`
+// so test frameworks (e.g., Jest) can spy/mock them.
+
+// DieType
+/** @type {typeof import("./DieType").DieType | undefined} */
+let _DieType;
+Object.defineProperty(exports, "DieType", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_DieType !== undefined) return _DieType;
+    _DieType = require("./DieType.js").DieType;
+    return _DieType;
+  },
+});
+
+/** @type {typeof import("./DieType").isValidDieType | undefined} */
+let _isValidDieType;
+Object.defineProperty(exports, "isValidDieType", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_isValidDieType !== undefined) return _isValidDieType;
+    _isValidDieType = require("./DieType.js").isValidDieType;
+    return _isValidDieType;
+  },
+});
+
+// Outcome
+/** @type {typeof import("./Outcome").Outcome | undefined} */
+let _Outcome;
+Object.defineProperty(exports, "Outcome", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_Outcome !== undefined) return _Outcome;
+    _Outcome = require("./Outcome.js").Outcome;
+    return _Outcome;
+  },
+});
+
+/** @type {typeof import("./Outcome").isValidOutcome | undefined} */
+let _isValidOutcome;
+Object.defineProperty(exports, "isValidOutcome", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_isValidOutcome !== undefined) return _isValidOutcome;
+    _isValidOutcome = require("./Outcome.js").isValidOutcome;
+    return _isValidOutcome;
+  },
+});
+
+// RollModifier
+/** @type {typeof import("./RollModifier").RollModifier | undefined} */
+let _RollModifier;
+Object.defineProperty(exports, "RollModifier", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_RollModifier !== undefined) return _RollModifier;
+    _RollModifier = require("./RollModifier.js").RollModifier;
+    return _RollModifier;
+  },
+});
+
+/** @type {typeof import("./RollModifier").isValidRollModifier | undefined} */
+let _isValidRollModifier;
+Object.defineProperty(exports, "isValidRollModifier", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_isValidRollModifier !== undefined) return _isValidRollModifier;
+    _isValidRollModifier = require("./RollModifier.js").isValidRollModifier;
+    return _isValidRollModifier;
+  },
+});
+
+/** @type {typeof import("./RollModifier").normaliseRollModifier | undefined} */
+let _normaliseRollModifier;
+Object.defineProperty(exports, "normaliseRollModifier", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_normaliseRollModifier !== undefined) return _normaliseRollModifier;
+    _normaliseRollModifier = require("./RollModifier.js").normaliseRollModifier;
+    return _normaliseRollModifier;
+  },
+});
+
+// RollType
+/** @type {typeof import("./RollType").RollType | undefined} */
+let _RollType;
+Object.defineProperty(exports, "RollType", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_RollType !== undefined) return _RollType;
+    _RollType = require("./RollType.js").RollType;
+    return _RollType;
+  },
+});
+
+/** @type {typeof import("./RollType").isValidRollType | undefined} */
+let _isValidRollType;
+Object.defineProperty(exports, "isValidRollType", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_isValidRollType !== undefined) return _isValidRollType;
+    _isValidRollType = require("./RollType.js").isValidRollType;
+    return _isValidRollType;
+  },
+});
+
+// TestConditions
+/** @type {typeof import("./TestConditions").TestConditions | undefined} */
+let _TestConditions;
+Object.defineProperty(exports, "TestConditions", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_TestConditions !== undefined) return _TestConditions;
+    _TestConditions = require("./TestConditions.js").TestConditions;
+    return _TestConditions;
+  },
+});
+
+/** @type {typeof import("./TestConditions").areValidTestConditions | undefined} */
+let _areValidTestConditions;
+Object.defineProperty(exports, "areValidTestConditions", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_areValidTestConditions !== undefined) return _areValidTestConditions;
+    _areValidTestConditions =
+      require("./TestConditions.js").areValidTestConditions;
+    return _areValidTestConditions;
+  },
+});
+
+/** @type {typeof import("./TestConditions").normaliseTestConditions | undefined} */
+let _normaliseTestConditions;
+Object.defineProperty(exports, "normaliseTestConditions", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_normaliseTestConditions !== undefined) return _normaliseTestConditions;
+    _normaliseTestConditions =
+      require("./TestConditions.js").normaliseTestConditions;
+    return _normaliseTestConditions;
+  },
+});
+
+// DiceTestConditions
+/** @type {typeof import("./DiceTestConditions").DiceTestConditions | undefined} */
+let _DiceTestConditions;
+Object.defineProperty(exports, "DiceTestConditions", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_DiceTestConditions !== undefined) return _DiceTestConditions;
+    _DiceTestConditions = require("./DiceTestConditions.js").DiceTestConditions;
+    return _DiceTestConditions;
+  },
+});
+
+// TestConditionsArray
+/** @type {typeof import("./TestConditionsArray").TestConditionsArray | undefined} */
+let _TestConditionsArray;
+Object.defineProperty(exports, "TestConditionsArray", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_TestConditionsArray !== undefined) return _TestConditionsArray;
+    _TestConditionsArray =
+      require("./TestConditionsArray.js").TestConditionsArray;
+    return _TestConditionsArray;
+  },
+});
+
+// ModifiedTestConditions
+/** @type {typeof import("./ModifiedTestConditions").ModifiedTestConditions | undefined} */
+let _ModifiedTestConditions;
+Object.defineProperty(exports, "ModifiedTestConditions", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_ModifiedTestConditions !== undefined) return _ModifiedTestConditions;
+    _ModifiedTestConditions =
+      require("./ModifiedTestConditions.js").ModifiedTestConditions;
+    return _ModifiedTestConditions;
+  },
+});
+
+/** @type {typeof import("./ModifiedTestConditions").areValidModifiedTestConditions | undefined} */
+let _areValidModifiedTestConditions;
+Object.defineProperty(exports, "areValidModifiedTestConditions", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_areValidModifiedTestConditions !== undefined)
+      return _areValidModifiedTestConditions;
+    _areValidModifiedTestConditions =
+      require("./ModifiedTestConditions.js").areValidModifiedTestConditions;
+    return _areValidModifiedTestConditions;
+  },
+});
+
+/** @type {typeof import("./ModifiedTestConditions").computeModifiedRange | undefined} */
+let _computeModifiedRange;
+Object.defineProperty(exports, "computeModifiedRange", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_computeModifiedRange !== undefined) return _computeModifiedRange;
+    _computeModifiedRange =
+      require("./ModifiedTestConditions.js").computeModifiedRange;
+    return _computeModifiedRange;
+  },
+});
+
+// TestType
+/** @type {typeof import("./TestType").TestType | undefined} */
+let _TestType;
+Object.defineProperty(exports, "TestType", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_TestType !== undefined) return _TestType;
+    _TestType = require("./TestType.js").TestType;
+    return _TestType;
+  },
+});
+
+/** @type {typeof import("./TestType").isValidTestType | undefined} */
+let _isValidTestType;
+Object.defineProperty(exports, "isValidTestType", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_isValidTestType !== undefined) return _isValidTestType;
+    _isValidTestType = require("./TestType.js").isValidTestType;
+    return _isValidTestType;
+  },
+});
+
+// Type exports are provided by @types/platonic-dice__core.