@platonic-dice/core 2.0.2 → 2.1.0

package/dist/rollModTest.js

@@ -0,0 +1,208 @@
+/**
+ * @module @platonic-dice/core/src/rollModTest
+ * @description
+ * Rolls a die with a modifier and evaluates the modified result against test conditions.
+ * Combines the logic of {@link rollMod} and {@link rollTest}.
+ *
+ * @example
+ * import { rollModTest, TestType, DieType } from "@platonic-dice/core";
+ *
+ * // Roll a D20 with +5 bonus, check if result ≥ 15
+ * const result = rollModTest(
+ *   DieType.D20,
+ *   (n) => n + 5,
+ *   { testType: TestType.AtLeast, target: 15 }
+ * );
+ * console.log(result.base);      // e.g., 12
+ * console.log(result.modified);  // e.g., 17
+ * console.log(result.outcome);   // e.g., "success"
+ *
+ * @example
+ * // Skill check with advantage and modifier
+ * const result = rollModTest(
+ *   DieType.D20,
+ *   new RollModifier((n) => n + 3),
+ *   { testType: TestType.Skill, target: 12, critical_success: 20, critical_failure: 1 },
+ *   RollType.Advantage
+ * );
+ */
+
+const { normaliseRollModifier } = require("./entities");
+const { ModifiedTestConditions } = require("./entities/ModifiedTestConditions");
+const r = require("./roll.js");
+const utils = require("./utils");
+const { createOutcomeMap } = require("./utils/outcomeMapper");
+
+/**
+ * @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/TestType").TestTypeValue} TestTypeValue
+ * @typedef {import("./entities/TestConditions").TestConditionsInstance} TestConditionsInstance
+ */
+
+/**
+ * Helper to rank outcomes for comparison.
+ * @private
+ * @param {OutcomeValue} outcome
+ * @returns {number}
+ */
+function rankOutcome(outcome) {
+  const { Outcome } = require("./entities");
+  switch (outcome) {
+    case Outcome.CriticalFailure:
+      return 0;
+    case Outcome.Failure:
+      return 1;
+    case Outcome.Success:
+      return 2;
+    case Outcome.CriticalSuccess:
+      return 3;
+    default:
+      return 1; // Default to failure rank
+  }
+}
+
+/**
+ * Rolls a die with a modifier and evaluates the modified result against test conditions.
+ *
+ * @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.
+ *   Can be either:
+ *   - A function `(n: number) => number`
+ *   - A {@link RollModifier} instance
+ * @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`).
+ * @param {Object} [options={}] - Optional configuration.
+ * @param {boolean} [options.useNaturalCrits] - If true, natural max/min rolls on the die trigger
+ *   critical success/failure (for Skill tests) or success/failure (for other test types).
+ *   If undefined, defaults to true for Skill test type and false for all others.
+ * @returns {{ base: number, modified: number, outcome: OutcomeValue }}
+ *   - `base`: The raw die roll
+ *   - `modified`: The roll after applying the modifier
+ *   - `outcome`: The success/failure result based on test conditions
+ * @throws {TypeError} If `dieType`, `modifier`, or `testConditions` are invalid.
+ *
+ * @example
+ * const result = rollModTest(
+ *   DieType.D20,
+ *   (n) => n + 2,
+ *   { testType: TestType.AtLeast, target: 15 }
+ * );
+ * console.log(result); // { base: 14, modified: 16, outcome: "success" }
+ *
+ * @example
+ * // With natural crits enabled (TTRPG style)
+ * const result = rollModTest(
+ *   DieType.D20,
+ *   (n) => n + 5,
+ *   { testType: TestType.Skill, target: 15, critical_success: 25, critical_failure: 2 },
+ *   undefined,
+ *   { useNaturalCrits: true }
+ * );
+ * // If base roll is 20, outcome is always "critical_success"
+ * // If base roll is 1, outcome is always "critical_failure"
+ *
+ * @example
+ * // With advantage - compares outcomes, not just base rolls
+ * const result = rollModTest(
+ *   DieType.D20,
+ *   (n) => n + 3,
+ *   { testType: TestType.Skill, target: 12, critical_success: 20, critical_failure: 1 },
+ *   RollType.Advantage
+ * );
+ * // Rolls twice, returns the result with the better outcome
+ */
+function rollModTest(
+  dieType,
+  modifier,
+  testConditions,
+  rollType = undefined,
+  options = {}
+) {
+  if (!dieType) throw new TypeError("dieType is required.");
+  if (!modifier) throw new TypeError("modifier is required.");
+  if (!testConditions) throw new TypeError("testConditions is required.");
+
+  // Normalise the modifier (skip if already a RollModifier instance)
+  const { RollModifier } = require("./entities");
+  const mod =
+    modifier instanceof RollModifier
+      ? modifier
+      : normaliseRollModifier(modifier);
+
+  // Create ModifiedTestConditions if input is a plain object
+  let conditionSet;
+  if (testConditions instanceof ModifiedTestConditions) {
+    conditionSet = testConditions;
+  } else {
+    // Plain object: { testType, ...conditions }
+    const { testType, ...rest } = testConditions;
+    // @ts-ignore - rest is validated by ModifiedTestConditions constructor
+    conditionSet = new ModifiedTestConditions(testType, rest, dieType, mod);
+  }
+
+  // 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
+  );
+
+  // Handle advantage/disadvantage by comparing outcomes
+  if (rollType) {
+    const { RollType } = require("./entities");
+
+    // Roll twice
+    const roll1 = utils.generateResult(dieType);
+    const roll2 = utils.generateResult(dieType);
+
+    // Look up outcomes from pre-computed map
+    const outcome1 = outcomeMap[roll1];
+    const outcome2 = outcomeMap[roll2];
+
+    // Build result objects
+    const result1 = {
+      base: roll1,
+      modified: mod.apply(roll1),
+      outcome: outcome1,
+    };
+    const result2 = {
+      base: roll2,
+      modified: mod.apply(roll2),
+      outcome: outcome2,
+    };
+
+    // Compare outcomes: higher rank is better
+    const rank1 = rankOutcome(outcome1);
+    const rank2 = rankOutcome(outcome2);
+
+    if (rollType === RollType.Advantage) {
+      // Return the result with better outcome (higher rank)
+      return rank1 >= rank2 ? result1 : result2;
+    } else {
+      // Disadvantage: return the result with worse outcome (lower rank)
+      return rank1 <= rank2 ? result1 : result2;
+    }
+  }
+
+  // Normal roll (no advantage/disadvantage)
+  const base = r.roll(dieType);
+  const outcome = outcomeMap[base];
+  const modified = mod.apply(base);
+
+  return { base, modified, outcome };
+}
+
+module.exports = {
+  rollModTest,
+};

package/dist/rollTest.d.ts

@@ -1,5 +1,5 @@
 declare namespace _exports {
-    export { DieTypeValue, OutcomeValue, RollTypeValue, TestTypeValue, TestConditionsInstance };
+    export { DieTypeValue, OutcomeValue, RollTypeValue, TestTypeValue, TestConditionsInstance, RollTestOptions };
 }
 declare namespace _exports {
     export { rollTest };
@@ -10,6 +10,16 @@ type OutcomeValue = import("./entities/Outcome").OutcomeValue;
 type RollTypeValue = import("./entities/RollType").RollTypeValue;
 type TestTypeValue = import("./entities/TestType").TestTypeValue;
 type TestConditionsInstance = import("./entities/TestConditions").TestConditionsInstance;
+type RollTestOptions = {
+    /**
+     * - If true, rolling the die's maximum value
+     * triggers CriticalSuccess (for Skill tests) or Success (for AtLeast/AtMost tests),
+     * and rolling 1 triggers CriticalFailure (for Skill tests) or Failure (for AtLeast)
+     * or Success (for AtMost). If undefined, defaults to true for TestType.Skill
+     * and false for all other test types.
+     */
+    useNaturalCrits?: boolean | undefined;
+};
 /**
  * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
  * @typedef {import("./entities/Outcome").OutcomeValue} OutcomeValue
@@ -17,6 +27,14 @@ type TestConditionsInstance = import("./entities/TestConditions").TestConditions
  * @typedef {import("./entities/TestType").TestTypeValue} TestTypeValue
  * @typedef {import("./entities/TestConditions").TestConditionsInstance} TestConditionsInstance
  */
+/**
+ * @typedef {Object} RollTestOptions
+ * @property {boolean} [useNaturalCrits] - If true, rolling the die's maximum value
+ *   triggers CriticalSuccess (for Skill tests) or Success (for AtLeast/AtMost tests),
+ *   and rolling 1 triggers CriticalFailure (for Skill tests) or Failure (for AtLeast)
+ *   or Success (for AtMost). If undefined, defaults to true for TestType.Skill
+ *   and false for all other test types.
+ */
 /**
  * Rolls a die and evaluates it against specified test conditions.
  *
@@ -27,13 +45,14 @@ type TestConditionsInstance = import("./entities/TestConditions").TestConditions
  *   - A `TestConditions` instance.
  *   - A plain object `{ testType, ...conditions }`.
  * @param {RollTypeValue} [rollType=undefined] - Optional roll mode (`RollType.Advantage` or `RollType.Disadvantage`).
+ * @param {RollTestOptions} [options={}] - Optional configuration for natural crits
  * @returns {{ base: number, outcome: OutcomeValue }} The raw roll and its evaluated outcome.
  * @throws {TypeError} If `dieType` or `testConditions` are invalid.
  */
 declare function rollTest(dieType: DieTypeValue, testConditions: TestConditionsInstance | {
     testType: TestTypeValue;
     [key: string]: any;
-}, rollType?: RollTypeValue): {
+}, rollType?: RollTypeValue, options?: RollTestOptions): {
     base: number;
     outcome: OutcomeValue;
 };

package/dist/rollTest.d.ts.map

@@ -1 +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"}
+{"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;;;;;;;GAOG;AAEH;;;;;;;;;;;;;GAaG;AACH,mCAVW,YAAY,kBACZ,sBAAsB,GAAC;IAAE,QAAQ,EAAE,aAAa,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,aAItE,aAAa,YACb,eAAe,GACb;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CA4BnD"}

package/dist/rollTest.js

@@ -24,7 +24,7 @@
 const { DieType, TestType } = require("./entities");
 const tc = require("./entities/TestConditions.js");
 const r = require("./roll.js");
-const utils = require("./utils");
+const { createOutcomeMap } = require("./utils/outcomeMapper");
 
 /**
  * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
@@ -34,6 +34,15 @@ const utils = require("./utils");
  * @typedef {import("./entities/TestConditions").TestConditionsInstance} TestConditionsInstance
  */
 
+/**
+ * @typedef {Object} RollTestOptions
+ * @property {boolean} [useNaturalCrits] - If true, rolling the die's maximum value
+ *   triggers CriticalSuccess (for Skill tests) or Success (for AtLeast/AtMost tests),
+ *   and rolling 1 triggers CriticalFailure (for Skill tests) or Failure (for AtLeast)
+ *   or Success (for AtMost). If undefined, defaults to true for TestType.Skill
+ *   and false for all other test types.
+ */
+
 /**
  * Rolls a die and evaluates it against specified test conditions.
  *
@@ -44,20 +53,33 @@ const utils = require("./utils");
  *   - A `TestConditions` instance.
  *   - A plain object `{ testType, ...conditions }`.
  * @param {RollTypeValue} [rollType=undefined] - Optional roll mode (`RollType.Advantage` or `RollType.Disadvantage`).
+ * @param {RollTestOptions} [options={}] - Optional configuration for natural crits
  * @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) {
+function rollTest(dieType, testConditions, rollType = undefined, options = {}) {
   if (!dieType) throw new TypeError("dieType is required.");
 
-  // Normalise testConditions
-  const conditionSet = tc.normaliseTestConditions(testConditions, dieType);
+  // Normalise testConditions (skip if already a TestConditions instance)
+  const conditionSet =
+    testConditions instanceof tc.TestConditions
+      ? testConditions
+      : tc.normaliseTestConditions(testConditions, dieType);
+
+  // Create outcome map for all possible rolls
+  const outcomeMap = createOutcomeMap(
+    dieType,
+    conditionSet.testType,
+    conditionSet,
+    null, // no modifier
+    options.useNaturalCrits
+  );
 
   // Perform the roll
   const base = r.roll(dieType, rollType);
 
-  // Determine the outcome using the normalized conditions
-  const outcome = utils.determineOutcome(base, conditionSet);
+  // Look up outcome from pre-computed map
+  const outcome = outcomeMap[base];
 
   return { base, outcome };
 }

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

@@ -1 +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"}
+{"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,CAmDxB"}

package/dist/utils/determineOutcome.js

@@ -46,11 +46,23 @@ function getEntities() {
  */
 function determineOutcome(value, testConditions) {
   const { Outcome, TestType, TestConditions } = getEntities();
+  const {
+    ModifiedTestConditions,
+  } = require("../entities/ModifiedTestConditions");
 
   if (typeof value !== "number" || Number.isNaN(value)) {
     throw new TypeError("value must be a valid number.");
   }
 
+  // Handle ModifiedTestConditions instances - no need to re-validate
+  if (testConditions instanceof ModifiedTestConditions) {
+    /** @type {TestConditionsInstance} */
+    // @ts-ignore - ModifiedTestConditions has compatible structure for outcome evaluation
+    const { testType, conditions } = testConditions;
+    // Use the switch statement below to determine outcome
+    return evaluateOutcome(value, testType, conditions, Outcome, TestType);
+  }
+
   // Normalise plain object input into a TestConditions instance
   if (!(testConditions instanceof TestConditions)) {
     const { testType, dieType, ...rest } = /** @type {TestConditionsLike} */ (
@@ -66,6 +78,20 @@ function determineOutcome(value, testConditions) {
   /** @type {TestConditionsInstance} */
   const { testType, conditions } = testConditions;
 
+  return evaluateOutcome(value, testType, conditions, Outcome, TestType);
+}
+
+/**
+ * Core evaluation logic extracted for reuse.
+ * @private
+ * @param {number} value
+ * @param {TestTypeValue} testType
+ * @param {Conditions | any} conditions
+ * @param {any} Outcome
+ * @param {any} TestType
+ * @returns {OutcomeValue}
+ */
+function evaluateOutcome(value, testType, conditions, Outcome, TestType) {
   switch (testType) {
     case TestType.AtLeast:
     case TestType.AtMost:

package/dist/utils/index.d.ts

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

package/dist/utils/index.js

@@ -18,9 +18,17 @@
  */
 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,
 };

package/dist/utils/outcomeMapper.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Creates an outcome map for all possible base rolls given the configuration.
+ * Uses memoization cache for performance.
+ *
+ * @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)
+ * @returns {Object.<number, import("../entities/Outcome").OutcomeValue>} Map of baseRoll -> outcome
+ */
+export function createOutcomeMap(dieType: import("../entities/DieType").DieTypeValue, testType: import("../entities/TestType").TestTypeValue, testConditions: import("../entities/TestConditions").TestConditionsInstance, modifier?: import("../entities/RollModifier").RollModifierInstance | null, useNaturalCrits?: boolean | null): {
+    [x: number]: import("../entities").OutcomeValue;
+};
+/**
+ * Clears the outcome map cache.
+ * Useful for testing or memory management.
+ *
+ * @function clearOutcomeMapCache
+ */
+export function clearOutcomeMapCache(): void;
+/**
+ * Gets the current size of the outcome map cache.
+ *
+ * @function getOutcomeMapCacheSize
+ * @returns {number}
+ */
+export function getOutcomeMapCacheSize(): number;
+//# sourceMappingURL=outcomeMapper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"outcomeMapper.d.ts","sourceRoot":"","sources":["../../src/utils/outcomeMapper.js"],"names":[],"mappings":"AAsGA;;;;;;;;;;GAUG;AACH,0CAPW,OAAO,qBAAqB,EAAE,YAAY,YAC1C,OAAO,sBAAsB,EAAE,aAAa,kBAC5C,OAAO,4BAA4B,EAAE,sBAAsB,aAC3D,OAAO,0BAA0B,EAAE,oBAAoB,GAAC,IAAI,oBAC5D,OAAO,GAAC,IAAI;;EA4DtB;AAED;;;;;GAKG;AACH,6CAEC;AAED;;;;;GAKG;AACH,0CAFa,MAAM,CAIlB"}

package/dist/utils/outcomeMapper.js

@@ -0,0 +1,197 @@
+/**
+ * @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
+ * given die configuration.
+ *
+ * Includes memoization cache for performance optimization.
+ */
+
+const { determineOutcome } = require("./determineOutcome");
+const { numSides } = require("./generateResult");
+
+/**
+ * Lazy-loaded entities to avoid circular dependencies.
+ * @private
+ */
+function getEntities() {
+  return require("../entities");
+}
+
+/**
+ * Memoization cache for outcome maps.
+ * @private
+ * @type {Map<string, Object.<number, import("../entities/Outcome").OutcomeValue>>}
+ */
+const outcomeMapCache = new Map();
+
+/**
+ * Applies natural crit logic based on test type.
+ * Only applies to Skill, AtLeast, and AtMost test types.
+ *
+ * @private
+ * @param {import("../entities/Outcome").OutcomeValue} currentOutcome - The outcome before natural crit override
+ * @param {boolean} isNaturalMax - Whether this is the maximum die value
+ * @param {boolean} isNaturalMin - Whether this is the minimum die value (1)
+ * @param {import("../entities/TestType").TestTypeValue} testType - The type of test
+ * @returns {import("../entities/Outcome").OutcomeValue} The potentially overridden outcome
+ */
+function applyNaturalCritOverride(
+  currentOutcome,
+  isNaturalMax,
+  isNaturalMin,
+  testType
+) {
+  const { TestType, Outcome } = getEntities();
+
+  // Skill tests: natural crits become Critical outcomes
+  if (testType === TestType.Skill) {
+    if (isNaturalMax) return Outcome.CriticalSuccess;
+    if (isNaturalMin) return Outcome.CriticalFailure;
+    return currentOutcome;
+  }
+
+  // At-Most tests: natural max is BAD (failure), natural min is GOOD (success)
+  if (testType === TestType.AtMost) {
+    if (isNaturalMax) return Outcome.Failure;
+    if (isNaturalMin) return Outcome.Success;
+    return currentOutcome;
+  }
+
+  // At-Least tests: natural max is GOOD (success), natural min is BAD (failure)
+  if (testType === TestType.AtLeast) {
+    if (isNaturalMax) return Outcome.Success;
+    if (isNaturalMin) return Outcome.Failure;
+    return currentOutcome;
+  }
+
+  // Other test types (Exact, Within, InList): natural crits don't apply
+  return currentOutcome;
+}
+
+/**
+ * Creates a cache key for outcome map memoization.
+ *
+ * @private
+ * @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
+ * @returns {string}
+ */
+function createCacheKey(
+  dieType,
+  testType,
+  testConditions,
+  modifier,
+  useNaturalCrits
+) {
+  // Serialize the conditions object for hashing
+  const conditionsKey = JSON.stringify({
+    testType: testConditions.testType,
+    conditions: testConditions.conditions,
+  });
+
+  // Create modifier key (use function toString for consistent hashing)
+  const modifierKey = modifier ? modifier.fn.toString() : "none";
+
+  return `${dieType}|${testType}|${conditionsKey}|${modifierKey}|${useNaturalCrits}`;
+}
+
+/**
+ * Creates an outcome map for all possible base rolls given the configuration.
+ * Uses memoization cache for performance.
+ *
+ * @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)
+ * @returns {Object.<number, import("../entities/Outcome").OutcomeValue>} Map of baseRoll -> outcome
+ */
+function createOutcomeMap(
+  dieType,
+  testType,
+  testConditions,
+  modifier = null,
+  useNaturalCrits = null
+) {
+  const { TestType } = getEntities();
+
+  // Auto-determine useNaturalCrits if not specified
+  // Default: true for Skill tests, false for all others
+  const shouldUseNaturalCrits = useNaturalCrits ?? testType === TestType.Skill;
+
+  // Check cache first
+  const cacheKey = createCacheKey(
+    dieType,
+    testType,
+    testConditions,
+    modifier,
+    shouldUseNaturalCrits
+  );
+  const cached = outcomeMapCache.get(cacheKey);
+  if (cached) {
+    return cached;
+  }
+
+  const sides = numSides(dieType);
+  /** @type {Object.<number, import("../entities/Outcome").OutcomeValue>} */
+  const outcomeMap = {};
+
+  for (let baseRoll = 1; baseRoll <= sides; baseRoll++) {
+    // Apply modifier if present
+    const value = modifier ? modifier.apply(baseRoll) : baseRoll;
+
+    // Determine base outcome from test evaluation
+    let outcome = determineOutcome(value, testConditions);
+
+    // Apply natural crit overrides if enabled
+    if (shouldUseNaturalCrits) {
+      const isNaturalMax = baseRoll === sides;
+      const isNaturalMin = baseRoll === 1;
+
+      outcome = applyNaturalCritOverride(
+        outcome,
+        isNaturalMax,
+        isNaturalMin,
+        testType
+      );
+    }
+
+    outcomeMap[baseRoll] = outcome;
+  }
+
+  // Store in cache before returning
+  outcomeMapCache.set(cacheKey, outcomeMap);
+
+  return outcomeMap;
+}
+
+/**
+ * Clears the outcome map cache.
+ * Useful for testing or memory management.
+ *
+ * @function clearOutcomeMapCache
+ */
+function clearOutcomeMapCache() {
+  outcomeMapCache.clear();
+}
+
+/**
+ * Gets the current size of the outcome map cache.
+ *
+ * @function getOutcomeMapCacheSize
+ * @returns {number}
+ */
+function getOutcomeMapCacheSize() {
+  return outcomeMapCache.size;
+}
+
+module.exports = {
+  createOutcomeMap,
+  clearOutcomeMapCache,
+  getOutcomeMapCacheSize,
+};

package/dist-types.d.ts

@@ -22,8 +22,11 @@ export * from "./dist/rollMod";
 export * from "./dist/rollDice";
 export * from "./dist/rollDiceMod";
 export * from "./dist/rollTest";
+export * from "./dist/rollModTest";
+export * from "./dist/analyseTest";
+export * from "./dist/analyseModTest";
 
-// The `rollMod`/`rollTest` d.ts files are emitted using a CommonJS `export =`
+// The `rollMod`/`rollTest`/`rollModTest` 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'`
@@ -46,3 +49,22 @@ export function rollTest(
       },
   rollType?: import("./dist/entities/RollType").RollTypeValue
 ): { base: number; outcome: import("./dist/entities/Outcome").OutcomeValue };
+
+export function rollModTest(
+  dieType: import("./dist/entities/DieType").DieTypeValue,
+  modifier:
+    | import("./dist/entities/RollModifier").RollModifierFunction
+    | import("./dist/entities/RollModifier").RollModifierInstance,
+  testConditions:
+    | import("./dist/entities/TestConditions").TestConditionsInstance
+    | {
+        testType: import("./dist/entities/TestType").TestTypeValue;
+        [k: string]: any;
+      },
+  rollType?: import("./dist/entities/RollType").RollTypeValue,
+  options?: { useNaturalCrits?: boolean }
+): {
+  base: number;
+  modified: number;
+  outcome: import("./dist/entities/Outcome").OutcomeValue;
+};