@platonic-dice/core 2.2.2 → 3.0.0

package/dist/utils/index.js

@@ -16,19 +16,247 @@
  * // 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");
-const {
-  createOutcomeMap,
-  clearOutcomeMapCache,
-  getOutcomeMapCacheSize,
-} = require("./outcomeMapper.js");
-
-module.exports = {
-  determineOutcome,
-  generateResult,
-  numSides,
-  createOutcomeMap,
-  clearOutcomeMapCache,
-  getOutcomeMapCacheSize,
-};
+// 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.
+
+/** @type {typeof import("./determineOutcome").determineOutcome | undefined} */
+let _determineOutcome;
+Object.defineProperty(exports, "determineOutcome", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_determineOutcome !== undefined) return _determineOutcome;
+    _determineOutcome = require("./determineOutcome.js").determineOutcome;
+    return _determineOutcome;
+  },
+});
+
+/** @type {typeof import("./generateResult").generateResult | undefined} */
+let _generateResult;
+Object.defineProperty(exports, "generateResult", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_generateResult !== undefined) return _generateResult;
+    _generateResult = require("./generateResult.js").generateResult;
+    return _generateResult;
+  },
+});
+
+/** @type {typeof import("./generateResult").numSides | undefined} */
+let _numSides;
+Object.defineProperty(exports, "numSides", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_numSides !== undefined) return _numSides;
+    _numSides = require("./generateResult.js").numSides;
+    return _numSides;
+  },
+});
+
+/** @type {typeof import("./outcomeMapper").createOutcomeMap | undefined} */
+let _createOutcomeMap;
+Object.defineProperty(exports, "createOutcomeMap", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_createOutcomeMap !== undefined) return _createOutcomeMap;
+    _createOutcomeMap = require("./outcomeMapper.js").createOutcomeMap;
+    return _createOutcomeMap;
+  },
+});
+
+/** @type {typeof import("./outcomeMapper").clearOutcomeMapCache | undefined} */
+let _clearOutcomeMapCache;
+Object.defineProperty(exports, "clearOutcomeMapCache", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_clearOutcomeMapCache !== undefined) return _clearOutcomeMapCache;
+    _clearOutcomeMapCache = require("./outcomeMapper.js").clearOutcomeMapCache;
+    return _clearOutcomeMapCache;
+  },
+});
+
+/** @type {typeof import("./outcomeMapper").getOutcomeMapCacheSize | undefined} */
+let _getOutcomeMapCacheSize;
+Object.defineProperty(exports, "getOutcomeMapCacheSize", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_getOutcomeMapCacheSize !== undefined) return _getOutcomeMapCacheSize;
+    _getOutcomeMapCacheSize =
+      require("./outcomeMapper.js").getOutcomeMapCacheSize;
+    return _getOutcomeMapCacheSize;
+  },
+});
+
+/** @type {typeof import("./getEvaluator").getEvaluator | undefined} */
+let _getEvaluator;
+Object.defineProperty(exports, "getEvaluator", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_getEvaluator !== undefined) return _getEvaluator;
+    _getEvaluator = require("./getEvaluator.js").getEvaluator;
+    return _getEvaluator;
+  },
+});
+
+// testRegistry exports
+/** @type {typeof import("./testRegistry").registerTestType | undefined} */
+let _registerTestType;
+Object.defineProperty(exports, "registerTestType", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_registerTestType !== undefined) return _registerTestType;
+    _registerTestType = require("./testRegistry.js").registerTestType;
+    return _registerTestType;
+  },
+});
+
+/** @type {typeof import("./testRegistry").getRegistration | undefined} */
+let _getRegistration;
+Object.defineProperty(exports, "getRegistration", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_getRegistration !== undefined) return _getRegistration;
+    _getRegistration = require("./testRegistry.js").getRegistration;
+    return _getRegistration;
+  },
+});
+
+/** @type {typeof import("./testRegistry").registry | undefined} */
+let _registry;
+Object.defineProperty(exports, "registry", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_registry !== undefined) return _registry;
+    _registry = require("./testRegistry.js").registry;
+    return _registry;
+  },
+});
+
+// testValidators exports
+/** @type {typeof import("./testValidators").isValidFaceValue | undefined} */
+let _isValidFaceValue;
+Object.defineProperty(exports, "isValidFaceValue", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_isValidFaceValue !== undefined) return _isValidFaceValue;
+    _isValidFaceValue = require("./testValidators.js").isValidFaceValue;
+    return _isValidFaceValue;
+  },
+});
+
+/** @type {typeof import("./testValidators").areValidFaceValues | undefined} */
+let _areValidFaceValues;
+Object.defineProperty(exports, "areValidFaceValues", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_areValidFaceValues !== undefined) return _areValidFaceValues;
+    _areValidFaceValues = require("./testValidators.js").areValidFaceValues;
+    return _areValidFaceValues;
+  },
+});
+
+/** @type {typeof import("./testValidators").isValidThresholdOrder | undefined} */
+let _isValidThresholdOrder;
+Object.defineProperty(exports, "isValidThresholdOrder", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_isValidThresholdOrder !== undefined) return _isValidThresholdOrder;
+    _isValidThresholdOrder =
+      require("./testValidators.js").isValidThresholdOrder;
+    return _isValidThresholdOrder;
+  },
+});
+
+/** @type {typeof import("./testValidators").isValidTargetConditions | undefined} */
+let _isValidTargetConditions;
+Object.defineProperty(exports, "isValidTargetConditions", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_isValidTargetConditions !== undefined) return _isValidTargetConditions;
+    _isValidTargetConditions =
+      require("./testValidators.js").isValidTargetConditions;
+    return _isValidTargetConditions;
+  },
+});
+
+/** @type {typeof import("./testValidators").isValidSkillTestCondition | undefined} */
+let _isValidSkillTestCondition;
+Object.defineProperty(exports, "isValidSkillTestCondition", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_isValidSkillTestCondition !== undefined)
+      return _isValidSkillTestCondition;
+    _isValidSkillTestCondition =
+      require("./testValidators.js").isValidSkillTestCondition;
+    return _isValidSkillTestCondition;
+  },
+});
+
+/** @type {typeof import("./testValidators").isValidWithinConditions | undefined} */
+let _isValidWithinConditions;
+Object.defineProperty(exports, "isValidWithinConditions", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_isValidWithinConditions !== undefined) return _isValidWithinConditions;
+    _isValidWithinConditions =
+      require("./testValidators.js").isValidWithinConditions;
+    return _isValidWithinConditions;
+  },
+});
+
+/** @type {typeof import("./testValidators").isValidSpecificListConditions | undefined} */
+let _isValidSpecificListConditions;
+Object.defineProperty(exports, "isValidSpecificListConditions", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_isValidSpecificListConditions !== undefined)
+      return _isValidSpecificListConditions;
+    _isValidSpecificListConditions =
+      require("./testValidators.js").isValidSpecificListConditions;
+    return _isValidSpecificListConditions;
+  },
+});
+
+/** @type {typeof import("./testValidators").areValidValuesInRange | undefined} */
+let _areValidValuesInRange;
+Object.defineProperty(exports, "areValidValuesInRange", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_areValidValuesInRange !== undefined) return _areValidValuesInRange;
+    _areValidValuesInRange =
+      require("./testValidators.js").areValidValuesInRange;
+    return _areValidValuesInRange;
+  },
+});
+
+/** @type {typeof import("./testValidators").areValidTestConditions | undefined} */
+let _areValidTestConditions;
+Object.defineProperty(exports, "areValidTestConditions", {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (_areValidTestConditions !== undefined) return _areValidTestConditions;
+    _areValidTestConditions =
+      require("./testValidators.js").areValidTestConditions;
+    return _areValidTestConditions;
+  },
+});

package/dist/utils/outcomeMapper.js

@@ -2,7 +2,7 @@
  * @module @platonic-dice/core/src/utils/outcomeMapper
  * @description
  * Creates outcome maps for die rolls, handling natural crits and modifiers.
- * This provides a centralized way to determine all possible outcomes for a
+ * This provides a centralised way to determine all possible outcomes for a
  * given die configuration.
  *
  * Includes memoization cache for performance optimization.
@@ -41,7 +41,7 @@ function applyNaturalCritOverride(
   currentOutcome,
   isNaturalMax,
   isNaturalMin,
-  testType
+  testType,
 ) {
   const { TestType, Outcome } = getEntities();
 
@@ -77,8 +77,8 @@ function applyNaturalCritOverride(
  * @param {import("../entities/DieType").DieTypeValue} dieType
  * @param {import("../entities/TestType").TestTypeValue} testType
  * @param {import("../entities/TestConditions").TestConditionsInstance} testConditions
- * @param {import("../entities/RollModifier").RollModifierInstance|null} modifier
- * @param {boolean} useNaturalCrits
+ * @param {import("../entities/RollModifier").RollModifierInstance|undefined} modifier
+ * @param {boolean|undefined} useNaturalCrits
  * @returns {string}
  */
 function createCacheKey(
@@ -86,9 +86,9 @@ function createCacheKey(
   testType,
   testConditions,
   modifier,
-  useNaturalCrits
+  useNaturalCrits,
 ) {
-  // Serialize the conditions object for hashing
+  // serialise the conditions object for hashing
   const conditionsKey = JSON.stringify({
     testType: testConditions.testType,
     conditions: testConditions.conditions,
@@ -107,22 +107,45 @@ function createCacheKey(
  * @param {import("../entities/DieType").DieTypeValue} dieType - The type of die
  * @param {import("../entities/TestType").TestTypeValue} testType - The type of test being performed
  * @param {import("../entities/TestConditions").TestConditionsInstance} testConditions - The test conditions
- * @param {import("../entities/RollModifier").RollModifierInstance|null} modifier - Optional modifier to apply
- * @param {boolean|null} useNaturalCrits - Whether to use natural crits (null = auto-determine)
+ * @param {import("../entities/RollModifier").RollModifierInstance|undefined} modifier - Optional modifier to apply
+ * @param {boolean|undefined} useNaturalCrits - Whether to use natural crits (undefined = auto-determine)
  * @returns {Object.<number, import("../entities/Outcome").OutcomeValue>} Map of baseRoll -> outcome
  */
 function createOutcomeMap(
   dieType,
   testType,
   testConditions,
-  modifier = null,
-  useNaturalCrits = null
+  modifier = undefined,
+  useNaturalCrits = undefined,
 ) {
   const { TestType } = getEntities();
 
-  // Auto-determine useNaturalCrits if not specified
-  // Default: true for Skill tests, false for all others
-  const shouldUseNaturalCrits = useNaturalCrits ?? testType === TestType.Skill;
+  // Resolve `useNaturalCrits` with the following precedence:
+  // 1. Caller-provided `useNaturalCrits` (boolean)
+  // 2. Registry-provided `defaultUseNaturalCrits` (optional boolean)
+  // 3. Fallback default: true for Skill tests, false otherwise
+  let shouldUseNaturalCrits = useNaturalCrits;
+  // Try to get registry metadata (if registry is available) to consult any
+  // declared `defaultUseNaturalCrits` for this testType. We swallow errors
+  // to remain resilient if the registry cannot be loaded.
+  let reg;
+  try {
+    const tr = require("./testRegistry");
+    reg = tr.getRegistration(testType);
+    if (
+      shouldUseNaturalCrits == null &&
+      reg &&
+      typeof reg.defaultUseNaturalCrits === "boolean"
+    ) {
+      shouldUseNaturalCrits = reg.defaultUseNaturalCrits;
+    }
+  } catch (e) {
+    // ignore registry errors and fall back to heuristic below
+  }
+
+  if (shouldUseNaturalCrits == null) {
+    shouldUseNaturalCrits = testType === TestType.Skill;
+  }
 
   // Check cache first
   const cacheKey = createCacheKey(
@@ -130,13 +153,37 @@ function createOutcomeMap(
     testType,
     testConditions,
     modifier,
-    shouldUseNaturalCrits
+    shouldUseNaturalCrits,
   );
   const cached = outcomeMapCache.get(cacheKey);
   if (cached) {
     return cached;
   }
 
+  // Prefer registry builder when available to keep behavior consistent
+  // with registered evaluators. Fall back to per-base determineOutcome loop.
+  try {
+    if (reg && typeof reg.buildEvaluator === "function") {
+      const evaluator = reg.buildEvaluator(
+        dieType,
+        testConditions,
+        modifier,
+        shouldUseNaturalCrits,
+      );
+      const sides = numSides(dieType);
+      /** @type {Object.<number, import("../entities/Outcome").OutcomeValue>} */
+      const outcomeMap = {};
+      for (let baseRoll = 1; baseRoll <= sides; baseRoll++) {
+        outcomeMap[baseRoll] = evaluator(baseRoll);
+      }
+      outcomeMapCache.set(cacheKey, outcomeMap);
+      return outcomeMap;
+    }
+  } catch (e) {
+    // If registry cannot be loaded for any reason, gracefully fall back
+    // to the existing per-base logic below.
+  }
+
   const sides = numSides(dieType);
   /** @type {Object.<number, import("../entities/Outcome").OutcomeValue>} */
   const outcomeMap = {};
@@ -157,7 +204,7 @@ function createOutcomeMap(
         outcome,
         isNaturalMax,
         isNaturalMin,
-        testType
+        testType,
       );
     }
 

package/dist/utils/testRegistry.js

@@ -0,0 +1,91 @@
+/**
+ * Lightweight registry for test types.
+ *
+ * Allows future registration of new test types with associated
+ * `validateShape` and `buildEvaluator` functions. For now, only
+ * `validateShape` is populated using `testValidators`.
+ */
+
+const validators = require("./testValidators");
+
+/**
+ * @typedef {import("./testValidators").Conditions} Conditions
+ * @typedef {Record<string, unknown>} PlainObject
+ * @typedef {Conditions|PlainObject} ConditionsLike
+ *
+ * Evaluator: function that maps a rolled base value (1..sides) to an OutcomeValue.
+ * @typedef {(base: number) => import("../entities/Outcome").OutcomeValue} Evaluator
+ *
+ * BuildEvaluator: factory that builds an Evaluator for a specific die/conditions.
+ * @typedef {(dieType: import("../entities/DieType").DieTypeValue, testConditions: ConditionsLike, modifier?: import("../entities/RollModifier").RollModifierInstance, useNaturalCrits?: boolean) => Evaluator} BuildEvaluator
+ *
+ * RegistryEntry: describes the shape validator, optional evaluator builder, and
+ * optional default for `useNaturalCrits` for that test type.
+ * @typedef {{ validateShape: (c: ConditionsLike) => boolean, buildEvaluator?: BuildEvaluator, defaultUseNaturalCrits?: boolean }} RegistryEntry
+ */
+
+/** Internal registry map: testType -> { validateShape, buildEvaluator? } */
+const registry = new Map();
+
+// Populate with built-in test types using validators
+const builtIns = ["at_least", "at_most", "exact", "within", "in_list", "skill"];
+
+for (const t of builtIns) {
+  registry.set(t, {
+    /** @param {ConditionsLike} c */
+    validateShape: (c) => validators.areValidTestConditions(c, t),
+    // buildEvaluator: returns an evaluator function (base:number)=>outcome
+    /**
+     * @param {import("../entities/DieType").DieTypeValue} dieType
+     * @param {ConditionsLike} testConditions
+     * @param {import("../entities/RollModifier").RollModifierInstance} [modifier]
+     * @param {boolean} [useNaturalCrits]
+     * @returns {(base: number) => import("../entities/Outcome").OutcomeValue}
+     */
+    /** @type {import("./testRegistry").BuildEvaluator} */
+    buildEvaluator: (
+      dieType,
+      testConditions,
+      modifier = undefined,
+      useNaturalCrits = undefined,
+    ) => {
+      // require lazily to avoid circular requires at module init
+      const { createOutcomeMap } = require("./outcomeMapper");
+      // t is a string matching TestType values; TS/JSDoc will accept via runtime checks
+      const outcomeMap = createOutcomeMap(
+        dieType,
+        /** @type {import("../entities/TestType").TestTypeValue} */ (t),
+        /** @type {any} */ (testConditions),
+        modifier,
+        useNaturalCrits,
+      );
+      return /** @param {number} base */ (base) => outcomeMap[base];
+    },
+  });
+}
+
+/**
+ * Register a new test type.
+ * @param {string} name
+ * @param {{ validateShape: (c: ConditionsLike) => boolean, buildEvaluator?: Function }} opts
+ */
+function registerTestType(name, { validateShape, buildEvaluator = undefined }) {
+  if (!name || typeof name !== "string") {
+    throw new TypeError("test type name must be a non-empty string");
+  }
+  registry.set(name, { validateShape, buildEvaluator });
+}
+
+/**
+ * @param {string} name
+ * @returns {RegistryEntry|undefined}
+ */
+function getRegistration(name) {
+  return registry.get(name) || undefined;
+}
+
+module.exports = {
+  registerTestType,
+  getRegistration,
+  registry, // exported for introspection in tests/tools
+};

package/dist/utils/testValidators.js

@@ -0,0 +1,190 @@
+const { isValidDieType } = require("../entities/DieType");
+const { numSides } = require("./generateResult.js");
+
+/* Typedef ownership:
+ * - `PlainObject`, `Conditions`, `ConditionsLike`
+ */
+
+/**
+ * @typedef {import("../entities/TestType").TestTypeValue} TestTypeValue
+ * @typedef {import("../entities/DieType").DieTypeValue} DieTypeValue
+ *
+ * @typedef {Object} BaseTestCondition
+ * @property {DieTypeValue} dieType
+ *
+ * @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 {TargetConditions | SkillConditions | WithinConditions | SpecificListConditions} Conditions
+ *
+ * @typedef {Record<string, any>} PlainObject
+ * @typedef {Conditions|PlainObject} ConditionsLike
+ */
+
+/**
+ * Checks if a number is a valid face value for a die with the given sides.
+ */
+/**
+ * @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.
+ */
+/**
+ * @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.
+ */
+/**
+ * @param {SkillConditions|PlainObject} 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;
+}
+
+/**
+ * @param {TargetConditions|PlainObject} c
+ * @returns {boolean}
+ */
+function isValidTargetConditions(c) {
+  if (!c || !isValidDieType(c.dieType)) return false;
+  return isValidFaceValue(c.target, numSides(c.dieType));
+}
+
+/**
+ * @param {SkillConditions|PlainObject} 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;
+}
+
+/**
+ * @param {WithinConditions|PlainObject} 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;
+}
+
+/**
+ * @param {SpecificListConditions|PlainObject} 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));
+}
+
+/**
+ * Validates that the given keys on an object are integer values within
+ * an explicit inclusive range `[min, max]`.
+ *
+ * This is useful for modified-range validation where the permissible
+ * faces aren't 1..sides but an arbitrary min..max after applying modifiers.
+ *
+ * @param {PlainObject} obj
+ * @param {number} min
+ * @param {number} max
+ * @param {(string)[]} keys
+ * @returns {boolean}
+ */
+function areValidValuesInRange(obj, min, max, keys) {
+  if (!obj) return false;
+  if (!Number.isInteger(min) || !Number.isInteger(max) || min > max)
+    return false;
+  return keys.every((key) => {
+    const v = obj[key];
+    if (v == null) return true;
+    if (Array.isArray(v)) {
+      if (v.length === 0) return false;
+      return v.every(
+        (item) => Number.isInteger(item) && item >= min && item <= max
+      );
+    }
+    return Number.isInteger(v) && v >= min && v <= max;
+  });
+}
+
+/**
+ * Master validation function for all test conditions.
+ */
+/**
+ * @param {Conditions|PlainObject} c
+ * @param {TestTypeValue|string} testType
+ * @returns {boolean}
+ */
+function areValidTestConditions(c, testType) {
+  switch (testType) {
+    case "at_least":
+    case "at_most":
+    case "exact":
+      return isValidTargetConditions(c);
+    case "within":
+      return isValidWithinConditions(c);
+    case "in_list":
+      return isValidSpecificListConditions(c);
+    case "skill":
+      return isValidSkillTestCondition(c);
+    default:
+      return false;
+  }
+}
+
+module.exports = {
+  isValidFaceValue,
+  areValidFaceValues,
+  isValidThresholdOrder,
+  isValidTargetConditions,
+  isValidSkillTestCondition,
+  isValidWithinConditions,
+  isValidSpecificListConditions,
+  areValidTestConditions,
+  areValidValuesInRange,
+};