@platonic-dice/core 2.2.2 → 3.0.0

package/dist/index.js

@@ -13,6 +13,7 @@ const rollDice = require("./rollDice.js");
 const roll = require("./roll.js");
 const rollMod = require("./rollMod.js");
 const rollDiceMod = require("./rollDiceMod.js");
+const rollDiceTest = require("./rollDiceTest.js");
 const rollTest = require("./rollTest.js");
 const rollModTest = require("./rollModTest.js");
 const analyseTest = require("./analyseTest.js");
@@ -22,30 +23,46 @@ const analyseModTest = require("./analyseModTest.js");
 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("./rollModTest") &
- *        typeof import("./analyseTest") &
- *        typeof import("./analyseModTest") &
- *        typeof import("./entities") &
- *        { default: any }}
+ * Attach named exports onto `exports` so consumers can access
+ * all helpers from the package root.
  */
-module.exports = {
-  ...roll,
-  ...rollDice,
-  ...rollMod,
-  ...rollDiceMod,
-  ...entities,
-  ...rollTest,
-  ...rollModTest,
-  ...analyseTest,
-  ...analyseModTest,
-  default: undefined, // placeholder; will be overwritten
-};
+Object.assign(exports, roll);
+Object.assign(exports, rollDice);
+Object.assign(exports, rollMod);
+Object.assign(exports, rollDiceMod);
+Object.assign(exports, rollDiceTest);
+Object.assign(exports, entities);
+Object.assign(exports, rollTest);
+Object.assign(exports, rollModTest);
+Object.assign(exports, analyseTest);
+Object.assign(exports, analyseModTest);
 
-// assign default at runtime
-module.exports.default = module.exports;
+// provide a `default` export for compatibility
+exports.default = exports;
+
+// Re-export all named exports explicitly for compatibility
+exports.DieType = entities.DieType;
+exports.isValidDieType = entities.isValidDieType;
+exports.Outcome = entities.Outcome;
+exports.isValidOutcome = entities.isValidOutcome;
+exports.RollType = entities.RollType;
+exports.isValidRollType = entities.isValidRollType;
+exports.TestType = entities.TestType;
+exports.isValidTestType = entities.isValidTestType;
+exports.RollModifier = entities.RollModifier;
+exports.isValidRollModifier = entities.isValidRollModifier;
+exports.normaliseRollModifier = entities.normaliseRollModifier;
+exports.TestConditions = entities.TestConditions;
+exports.areValidTestConditions = entities.areValidTestConditions;
+exports.normaliseTestConditions = entities.normaliseTestConditions;
+exports.TestConditionsArray = entities.TestConditionsArray;
+exports.DiceTestConditions = entities.DiceTestConditions;
+exports.ModifiedTestConditions = entities.ModifiedTestConditions;
+exports.areValidModifiedTestConditions =
+  entities.areValidModifiedTestConditions;
+exports.computeModifiedRange = entities.computeModifiedRange;
+exports.rollTest = rollTest.rollTest;
+exports.rollModTest = rollModTest.rollModTest;
+exports.rollDiceTest = rollDiceTest.rollDiceTest;
+exports.analyseTest = analyseTest.analyseTest;
+exports.analyseModTest = analyseModTest.analyseModTest;

package/dist/rollDiceMod.js

@@ -34,10 +34,7 @@ const rd = require("./rollDice.js");
  * @typedef {import("./entities/RollModifier").RollModifierFunction} RollModifierFunction
  * @typedef {import("./entities/RollModifier").RollModifierInstance} RollModifierInstance
  * @typedef {import("./entities/RollModifier").DiceModifier} DiceModifier
- */
-
-/**
- * @typedef {RollModifierInstance | RollModifierFunction | DiceModifier} rollDiceModModifier
+ * @typedef {import("./entities/RollModifier").RollModifierLike} RollModifierLike
  */
 
 /**
@@ -45,7 +42,7 @@ const rd = require("./rollDice.js");
  *
  * @function rollDiceMod
  * @param {DieTypeValue} dieType - The die type (e.g., `DieType.D6`).
- * @param {rollDiceModModifier} [modifier={}] - The modifier(s) to apply.
+ * @param {RollModifierLike} [modifier={}] - The modifier(s) to apply.
  * @param {{ count?: number }} [options={}] - Optional roll count (default: 1).
  * @returns {{
  *   base: { array: number[], sum: number },
@@ -68,12 +65,16 @@ function rollDiceMod(dieType, modifier = {}, { count = 1 } = {}) {
     eachMod = normaliseRollModifier(undefined); // identity
     netMod = normaliseRollModifier(modifier);
   } else if (typeof modifier === "object" && modifier !== null) {
-    const { each, net } = modifier;
+    let each, net;
+    if (modifier && typeof modifier === "object") {
+      each = modifier.each;
+      net = modifier.net;
+    }
     eachMod = normaliseRollModifier(each);
     netMod = normaliseRollModifier(net);
   } else {
     throw new TypeError(
-      `Invalid modifier: ${modifier}. Must be a function, RollModifier, or object.`
+      `Invalid modifier: ${modifier}. Must be a function, RollModifier, or object.`,
     );
   }
 
@@ -103,19 +104,27 @@ function rollDiceMod(dieType, modifier = {}, { count = 1 } = {}) {
 /**
  * @private
  * Generates a simple accessor alias for `rollDiceMod`.
- *
- * @template {keyof { eachArray: number[]; net: number }} K
- * @param {K} key
+ * Returns either the `each.array` or the `net.value` depending on `key`.
+ * We keep the implementation untyped to avoid complex conditional JSDoc generics
+ * which cause TypeScript complaints; callers below provide explicit typings.
+ */
+/**
+ * @param {'eachArray'|'net'} key
+ * @returns {(dieType: DieTypeValue, modifier?: RollModifierLike, options?: { count?: number }) => number|number[]}
  */
 function alias(key) {
-  /** @type {(...args: Parameters<typeof rollDiceMod>) => K extends 'eachArray' ? number[] : number} */
+  /**
+   * @param {DieTypeValue} dieType
+   * @param {RollModifierLike} [modifier]
+   * @param {{ count?: number }} [options]
+   */
   return (dieType, modifier = {}, options = {}) => {
     const result = rollDiceMod(dieType, modifier, options);
     switch (key) {
       case "eachArray":
-        return /** @type {any} */ (result.modified.each.array);
+        return result.modified.each.array;
       case "net":
-        return /** @type {any} */ (result.modified.net.value);
+        return result.modified.net.value;
       default:
         throw new TypeError(`Unknown alias key: ${key}`);
     }
@@ -124,11 +133,15 @@ function alias(key) {
 
 // --- Exports ---
 
-/** @type {(dieType: DieTypeValue, modifier?: rollDiceModModifier, options?: { count?: number }) => number[]} */
-const rollDiceModArr = alias("eachArray");
+const rollDiceModArr =
+  /** @type {(dieType: DieTypeValue, modifier?: RollModifierLike, options?: { count?: number }) => number[]} */ (
+    alias("eachArray")
+  );
 
-/** @type {(dieType: DieTypeValue, modifier?: rollDiceModModifier, options?: { count?: number }) => number} */
-const rollDiceModNet = alias("net");
+const rollDiceModNet =
+  /** @type {(dieType: DieTypeValue, modifier?: RollModifierLike, options?: { count?: number }) => number} */ (
+    alias("net")
+  );
 
 module.exports = {
   rollDiceMod,

package/dist/rollDiceTest.js

@@ -0,0 +1,68 @@
+/**
+ * @module @platonic-dice/core/src/rollDiceTest
+ * @description
+ * Rolls multiple dice and evaluates each die against a set of test conditions
+ * using `DiceTestConditions`.
+ */
+
+const entities = require("./entities");
+const { isValidDieType, DiceTestConditions, TestConditionsArray } = entities;
+const { rollDice } = require("./rollDice.js");
+
+/**
+ * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
+ */
+
+/**
+ * Roll multiple dice and evaluate them against provided conditions.
+ *
+ * @param {DieTypeValue} dieType
+ * @param {import("./entities").DiceTestConditions|import("./entities/TestConditionsArray").TestConditionsArray|Array<import("./entities/TestConditions").TestConditionsLike>} conditions
+ * @param {{ count?: number, rules?: Array<{ type: "value_count"|"condition_count", value?: number, conditionIndex?: number, exact?: number, atLeast?: number, atMost?: number }>, useNaturalCrits?: boolean }} [options={}]
+ *
+ * @returns {{ base: { array: number[], sum: number }, result: Object }}
+ */
+function rollDiceTest(
+  dieType,
+  conditions,
+  { count = 1, rules = [], useNaturalCrits = undefined } = {},
+) {
+  if (!isValidDieType(dieType))
+    throw new TypeError(`Invalid die type: ${dieType}`);
+  if (typeof count !== "number" || !Number.isInteger(count) || count < 1) {
+    throw new TypeError("count must be a positive integer");
+  }
+
+  // Construct or validate provided DiceTestConditions
+  /** @type {import("./entities").DiceTestConditions} */
+  let dtc;
+  if (conditions instanceof DiceTestConditions) {
+    dtc = conditions;
+    if (dtc.count !== count)
+      throw new TypeError(
+        "Provided DiceTestConditions count does not match requested count",
+      );
+  } else if (
+    conditions instanceof TestConditionsArray ||
+    Array.isArray(conditions)
+  ) {
+    dtc = new DiceTestConditions({ count, conditions, rules, dieType });
+  } else {
+    throw new TypeError(
+      "conditions must be a DiceTestConditions instance, TestConditionsArray, or an array of TestConditions-like objects",
+    );
+  }
+
+  // Roll the dice
+  const base = rollDice(dieType, { count });
+
+  // Evaluate rolls using the DiceTestConditions evaluator
+  const evaluator = dtc.toEvaluator(undefined, useNaturalCrits);
+  const result = evaluator(base.array);
+
+  return { base, result };
+}
+
+module.exports = {
+  rollDiceTest,
+};

package/dist/rollMod.js

@@ -23,8 +23,7 @@ const r = require("./roll.js");
 /**
  * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
  * @typedef {import("./entities/RollType").RollTypeValue} RollTypeValue
- * @typedef {import("./entities/RollModifier").RollModifierFunction} RollModifierFunction
- * @typedef {import("./entities/RollModifier").RollModifierInstance} RollModifierInstance
+ * @typedef {import("./entities/RollModifier").RollModifierLike} RollModifierLike
  */
 
 /**
@@ -36,7 +35,7 @@ const r = require("./roll.js");
  *
  * @function rollMod
  * @param {DieTypeValue} dieType - The type of die to roll (e.g., `DieType.D20`).
- * @param {RollModifierFunction|RollModifierInstance} modifier - The modifier to apply.
+ * @param {RollModifierLike} modifier - The modifier to apply.
  *   Can be either:
  *   - A RollModifierFunction `(n: number) => number`
  *   - A {@link RollModifier} instance
@@ -57,7 +56,7 @@ const r = require("./roll.js");
  * const result = rollMod(DieType.D10, (n) => Math.floor(n / 2), RollType.Advantage);
  */
 function rollMod(dieType, modifier, rollType = undefined) {
-  const mod = normaliseRollModifier(modifier);
+  const mod = normaliseRollModifier(/** @type {any} */ (modifier));
 
   const base = r.roll(dieType, rollType);
   const modified = mod.apply(base);

package/dist/rollModTest.js

@@ -32,13 +32,13 @@ const { ModifiedTestConditions } = require("./entities/ModifiedTestConditions");
 const r = require("./roll.js");
 const utils = require("./utils");
 const { createOutcomeMap } = require("./utils/outcomeMapper");
+const { numSides } = require("./utils");
 
 /**
  * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
  * @typedef {import("./entities/Outcome").OutcomeValue} OutcomeValue
  * @typedef {import("./entities/RollType").RollTypeValue} RollTypeValue
- * @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
  */
@@ -70,11 +70,12 @@ function rankOutcome(outcome) {
  *
  * @function rollModTest
  * @param {DieTypeValue} dieType - The type of die to roll (e.g., `DieType.D20`).
- * @param {RollModifierFunction|RollModifierInstance} modifier - The modifier to apply to the roll.
+ * @param {RollModifierLike} modifier - The modifier to apply to the roll.
  *   Can be either:
  *   - A function `(n: number) => number`
  *   - A {@link RollModifier} instance
- * @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 }`
@@ -135,7 +136,7 @@ function rollModTest(
   const mod =
     modifier instanceof RollModifier
       ? modifier
-      : normaliseRollModifier(modifier);
+      : normaliseRollModifier(/** @type {any} */ (modifier));
 
   // Create ModifiedTestConditions if input is a plain object
   let conditionSet;
@@ -149,14 +150,40 @@ function rollModTest(
   }
 
   // Create outcome map for all possible rolls (with modifier applied)
-  const outcomeMap = createOutcomeMap(
-    dieType,
-    conditionSet.testType,
-    // @ts-ignore - ModifiedTestConditions is compatible with TestConditions for outcome mapping
-    conditionSet,
-    mod, // include modifier
-    options.useNaturalCrits
-  );
+  // Prefer registry evaluator if available; otherwise build outcome map.
+  /** @type {Record<number, OutcomeValue>|undefined} */
+  let outcomeMap;
+  try {
+    const { getRegistration } = require("./utils/testRegistry");
+    const reg = getRegistration(conditionSet.testType);
+    if (reg && typeof reg.buildEvaluator === "function") {
+      /** @type {import("./utils/testRegistry").Evaluator} */
+      const evaluator = reg.buildEvaluator(
+        dieType,
+        // @ts-ignore - ModifiedTestConditions is compatible with TestConditions for outcome mapping
+        conditionSet,
+        mod,
+        options.useNaturalCrits
+      );
+      outcomeMap = {};
+      const sides = numSides(dieType);
+      for (let roll = 1; roll <= sides; roll++)
+        outcomeMap[roll] = evaluator(roll);
+    }
+  } catch (err) {
+    // fall through to legacy logic
+  }
+
+  if (!outcomeMap) {
+    outcomeMap = createOutcomeMap(
+      dieType,
+      conditionSet.testType,
+      // @ts-ignore - ModifiedTestConditions is compatible with TestConditions for outcome mapping
+      conditionSet,
+      mod, // include modifier
+      options.useNaturalCrits
+    );
+  }
 
   // Handle advantage/disadvantage by comparing outcomes
   if (rollType) {

package/dist/rollTest.js

@@ -25,6 +25,7 @@ const { DieType, TestType } = require("./entities");
 const tc = require("./entities/TestConditions.js");
 const r = require("./roll.js");
 const { createOutcomeMap } = require("./utils/outcomeMapper");
+const { numSides } = require("./utils");
 
 /**
  * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
@@ -48,7 +49,7 @@ const { createOutcomeMap } = require("./utils/outcomeMapper");
  *
  * @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
+ * @param {TestConditionsInstance|import("./entities/TestConditions").TestConditionsLike} testConditions
  *   Can be:
  *   - A `TestConditions` instance.
  *   - A plain object `{ testType, ...conditions }`.
@@ -61,19 +62,56 @@ function rollTest(dieType, testConditions, rollType = undefined, 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)) {
+      // Call normaliser so callers/spies see the delegation, then throw
+      // a consistent TypeError for unsupported test types.
+      try {
+        tc.normaliseTestConditions(testConditions, dieType);
+      } catch (err) {
+        // ignore original error; prefer consistent message
+      }
+      throw new TypeError(`Invalid test type: ${testType}`);
+    }
+
+    if (!validators.areValidTestConditions(fullConditions, testType)) {
+      // Call the normaliser to preserve existing call-sites/tests that expect
+      // the delegation; then fail fast with a standardised message.
+      try {
+        tc.normaliseTestConditions(testConditions, dieType);
+      } catch (err) {
+        // swallow the deeper error in favor of a clearer TypeError below
+      }
+      throw new TypeError("Invalid test conditions shape.");
+    }
+
+    conditionSet = tc.normaliseTestConditions(testConditions, dieType);
+  }
+
+  // Use centralised evaluator helper (registry or fallback)
+  const { getEvaluator } = require("./utils/getEvaluator");
+  const evaluator = getEvaluator(
     dieType,
-    conditionSet.testType,
     conditionSet,
-    null, // no modifier
-    options.useNaturalCrits
+    undefined,
+    options.useNaturalCrits,
   );
+  const sides = numSides(dieType);
+  /** @type {Record<number, OutcomeValue>} */
+  const outcomeMap = {};
+  for (let b = 1; b <= sides; b++) outcomeMap[b] = evaluator(b);
 
   // Perform the roll
   const base = r.roll(dieType, rollType);
@@ -115,8 +153,5 @@ for (const [dieKey, dieValue] of Object.entries(DieType)) {
   }
 }
 
-// Export all generated aliases
-module.exports = {
-  rollTest,
-  ...aliases,
-};
+// Export all generated aliases as named exports so tsc emits named declarations
+Object.assign(exports, { rollTest, ...aliases });

package/dist/utils/determineOutcome.js

@@ -18,7 +18,7 @@ function getEntities() {
 
 /**
  * @private
- * @typedef {{ testType: TestTypeValue, dieType: DieTypeValue } & Conditions} TestConditionsLike
+ * @typedef {import("../entities/TestConditions").TestConditionsLike & { dieType: DieTypeValue }} TestConditionsLike
  */
 
 /**
@@ -69,14 +69,42 @@ function determineOutcome(value, testConditions) {
       testConditions
     );
 
-    // Inject dieType into the conditions object to satisfy TestConditions
+    // Inject dieType into the conditions object to satisfy validators
     const fullConditions = { ...rest, dieType };
 
-    testConditions = new TestConditions(testType, fullConditions, dieType);
+    // Fast-path validation using shared validators to provide clearer,
+    // centralised error messages for plain-object inputs before attempting
+    // construction of a TestConditions instance.
+    const validators = require("../utils/testValidators");
+    const { isValidTestType } = require("../entities/TestType");
+
+    if (!isValidTestType(testType)) {
+      // Mirror the constructor's TypeError for unsupported test types.
+      throw new TypeError(`Invalid test type: ${testType}`);
+    }
+
+    if (!validators.areValidTestConditions(fullConditions, testType)) {
+      // Fail fast with a clear TypeError for invalid shapes. The validator
+      // returns false for malformed conditions (range errors, missing keys,
+      // etc.). Consumers constructing TestConditions directly will still
+      // receive more specific RangeError messages from the constructor;
+      // here we centralise failure for plain-object inputs.
+      throw new TypeError("Invalid test conditions shape.");
+    }
+
+    // At this point the plain object is well-formed; normalise via the
+    // constructor to obtain a proper TestConditions instance.
+    testConditions = new TestConditions(
+      testType,
+      /** @type {any} */ (fullConditions),
+      dieType
+    );
   }
 
   /** @type {TestConditionsInstance} */
-  const { testType, conditions } = testConditions;
+  const { testType, conditions } = /** @type {TestConditionsInstance} */ (
+    testConditions
+  );
 
   return evaluateOutcome(value, testType, conditions, Outcome, TestType);
 }
@@ -86,9 +114,9 @@ function determineOutcome(value, testConditions) {
  * @private
  * @param {number} value
  * @param {TestTypeValue} testType
- * @param {Conditions | any} conditions
- * @param {any} Outcome
- * @param {any} TestType
+ * @param {Conditions} conditions
+ * @param {typeof import("../entities/Outcome").Outcome} Outcome
+ * @param {typeof import("../entities/TestType").TestType} TestType
  * @returns {OutcomeValue}
  */
 function evaluateOutcome(value, testType, conditions, Outcome, TestType) {

package/dist/utils/getArrayEvaluator.js

@@ -0,0 +1,48 @@
+/**
+ * @module @platonic-dice/core/src/utils/getArrayEvaluator
+ * @description
+ * Builds an evaluator function for a `TestConditionsArray` that maps a single
+ * numeric input to an array of outcomes (one per contained TestConditions).
+ */
+
+const { getEvaluator } = require("./getEvaluator");
+
+/**
+ * @typedef {import("../entities/TestConditions").TestConditionsInstance} TestConditionsInstance
+ * @typedef {import("../entities/TestConditions").TestConditionsLike} TestConditionsLike
+ * @typedef {import("../entities/TestConditionsArray").TestConditionsArrayInstance} TestConditionsArrayInstance
+ */
+
+/**
+ * Create an evaluator for a TestConditionsArray instance.
+ *
+ * @param {TestConditionsArrayInstance} tcArray - The TestConditionsArray instance
+ * @param {import("../entities/RollModifier").RollModifierInstance} [modifier]
+ * @param {boolean} [useNaturalCrits]
+ * @returns {(value: number) => string[]} Function mapping numeric value -> array of Outcome values
+ */
+function getArrayEvaluator(
+  tcArray,
+  modifier = undefined,
+  useNaturalCrits = undefined,
+) {
+  if (!tcArray) throw new TypeError("tcArray is required");
+
+  if (typeof tcArray.toArray !== "function") {
+    throw new TypeError("tcArray must be a TestConditionsArray instance");
+  }
+
+  const conditions = tcArray.toArray();
+
+  // Build per-entry evaluators using existing getEvaluator (reuses createOutcomeMap cache)
+  const perEntryEvaluators = conditions.map((tc) =>
+    getEvaluator(tc.dieType, tc, modifier, useNaturalCrits),
+  );
+
+  return /** @param {number} value */ (value) =>
+    perEntryEvaluators.map((fn) => fn(value));
+}
+
+module.exports = {
+  getArrayEvaluator,
+};

package/dist/utils/getEvaluator.js

@@ -0,0 +1,84 @@
+/**
+ * @module @platonic-dice/core/src/utils/getEvaluator
+ * @description
+ * Helper to obtain a per-base evaluator for a given die + conditions.
+ *
+ * It first consults the `testRegistry` for a `buildEvaluator`. If none is
+ * registered, it falls back to building an outcome map via
+ * `createOutcomeMap` and returns a function that indexes into that map.
+ */
+
+const { createOutcomeMap } = require("./outcomeMapper");
+const { numSides } = require("./generateResult");
+
+/**
+ * @typedef {import("../entities/DieType").DieTypeValue} DieTypeValue
+ * @typedef {import("../entities/TestType").TestTypeValue} TestTypeValue
+ * @typedef {import("../entities/Outcome").OutcomeValue} OutcomeValue
+ * @typedef {import("../entities/TestConditions").TestConditionsInstance} TestConditionsInstance
+ * @typedef {(base: number) => OutcomeValue} Evaluator
+ */
+
+/**
+ * Get an evaluator function mapping base roll -> OutcomeValue.
+ *
+ * @typedef {import("../entities/TestConditions").TestConditionsLike} TestConditionsLike
+ * @param {DieTypeValue} dieType
+ * @param {TestConditionsLike} testConditions
+ * @param {import("../entities/RollModifier").RollModifierInstance} [modifier]
+ * @param {boolean} [useNaturalCrits]
+ * @returns {Evaluator}
+ */
+function getEvaluator(
+  dieType,
+  testConditions,
+  modifier = undefined,
+  useNaturalCrits = undefined,
+) {
+  if (!testConditions || !testConditions.testType) {
+    throw new TypeError(
+      "testConditions must include a 'testType' field or be a TestConditions instance",
+    );
+  }
+
+  const { getRegistration } = require("./testRegistry");
+
+  const testType = testConditions.testType;
+  const reg = getRegistration(testType);
+  if (reg && typeof reg.buildEvaluator === "function") {
+    return reg.buildEvaluator(
+      dieType,
+      testConditions,
+      modifier,
+      useNaturalCrits,
+    );
+  }
+
+  // Fallback: build an outcome map and return a simple indexer
+  // Ensure we pass a TestConditions instance into createOutcomeMap to match
+  // its runtime/typing contract. Normalise plain objects when necessary.
+  const {
+    TestConditions,
+    normaliseTestConditions,
+  } = require("../entities/TestConditions");
+  let tcInstance = testConditions;
+  if (!(testConditions instanceof TestConditions)) {
+    // Runtime normalization: `normaliseTestConditions` will validate and return a
+    // `TestConditions` instance when given a plain object.
+    tcInstance = normaliseTestConditions(testConditions, dieType);
+  }
+
+  const outcomeMap = createOutcomeMap(
+    dieType,
+    testType,
+    // `tcInstance` is a validated TestConditions instance at runtime
+    tcInstance,
+    modifier,
+    useNaturalCrits,
+  );
+  return /** @param {number} base */ (base) => outcomeMap[base];
+}
+
+module.exports = {
+  getEvaluator,
+};