@platonic-dice/core 2.0.2 → 2.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 Core JavaScript/TypeScript library providing dice-roll logic, modifiers, and test evaluation for tabletop RPGs.
 
-This package contains the pure logic used by higher-level packages (for example `@platonic-dice/dice`). It exports rolling helpers, entities (die types, roll types, outcomes), and utility functions.
+This package contains the pure logic used by higher-level packages (for example `@platonic-dice/dice`). It exports rolling helpers including `roll`, `rollMod`, `rollTest`, and `rollModTest` (combining modifiers with test evaluation), entities (die types, roll types, outcomes), and utility functions.
 
 ## Installation
 
@@ -17,17 +17,38 @@ npm install @platonic-dice/core
 CommonJS:
 
 ```js
-const { roll, rollDice, DieType, RollType } = require('@platonic-dice/core');
-
-console.log( roll(DieType.D20) );
-console.log( rollDice(DieType.D6, { count: 3 }) );
+const {
+  roll,
+  rollDice,
+  rollModTest,
+  DieType,
+  RollType,
+} = require("@platonic-dice/core");
+
+console.log(roll(DieType.D20));
+console.log(rollDice(DieType.D6, { count: 3 }));
+
+// New in 2.1.0: rollModTest combines modifiers with test evaluation
+const result = rollModTest(DieType.D20, (n) => n + 5, {
+  testType: "skill",
+  target: 15,
+});
+console.log(
+  `Roll: ${result.base}, Modified: ${result.modified}, Outcome: ${result.outcome}`
+);
 ```
 
 ESM / TypeScript:
 
 ```ts
-import { roll, DieType } from '@platonic-dice/core';
-console.log( roll(DieType.D20) );
+import { roll, rollModTest, DieType } from "@platonic-dice/core";
+console.log(roll(DieType.D20));
+
+// Combine modifiers with test evaluation
+const result = rollModTest(DieType.D20, (n) => n + 5, {
+  testType: "at_least",
+  target: 15,
+});
 ```
 
 ## Build & Test
@@ -48,6 +69,32 @@ cd packages/core
 npm test
 ```
 
+## Examples
+
+The `examples/` directory contains comprehensive examples for all major functions. Run them to see the library in action:
+
+```bash
+# Run all core examples (roll, rollDice, rollMod, rollDiceMod, rollTest, rollModTest)
+npm run examples
+
+# Run all examples including advanced features and analysis functions
+npm run examples:all
+
+# Run individual example files
+npm run examples:roll
+npm run examples:rollDice
+npm run examples:rollMod
+npm run examples:rollDiceMod
+npm run examples:rollTest
+npm run examples:rollModTest
+npm run examples:rollModTest:advanced
+npm run examples:analyseTest
+npm run examples:analyseModTest
+npm run examples:entities
+```
+
+Each example demonstrates practical usage patterns and outputs results to help you understand the API.
+
 ## Contributing
 
 See the repository root `README.md` for contribution guidelines. Keep changes backwards-compatible where possible and include tests.

package/dist/analyseModTest.d.ts

@@ -0,0 +1,126 @@
+export type DieTypeValue = import("./entities/DieType").DieTypeValue;
+export type OutcomeValue = import("./entities/Outcome").OutcomeValue;
+export type RollModifierFunction = import("./entities/RollModifier").RollModifierFunction;
+export type RollModifierInstance = import("./entities/RollModifier").RollModifierInstance;
+export type TestTypeValue = import("./entities/TestType").TestTypeValue;
+export type TestConditionsInstance = import("./entities/TestConditions").TestConditionsInstance;
+export type ModifiedTestAnalysis = {
+    /**
+     * - Total number of possible die rolls
+     */
+    totalPossibilities: number;
+    /**
+     * - Count of each outcome type
+     */
+    outcomeCounts: {
+        [x: string]: number;
+    };
+    /**
+     * - Probability (0-1) of each outcome
+     */
+    outcomeProbabilities: {
+        [x: string]: number;
+    };
+    /**
+     * - Map of base roll to outcome
+     */
+    outcomesByRoll: {
+        [x: number]: import("./entities").OutcomeValue;
+    };
+    /**
+     * - Map of base roll to modified value
+     */
+    modifiedValuesByRoll: {
+        [x: number]: number;
+    };
+    /**
+     * - Array of all possible base roll values
+     */
+    rolls: number[];
+    /**
+     * - Base rolls grouped by their outcome
+     */
+    rollsByOutcome: any;
+    /**
+     * - Range of modified values achievable
+     */
+    modifiedRange: {
+        min: number;
+        max: number;
+    };
+};
+export type analyseModTestOptions = {
+    /**
+     * - If true, natural max/min rolls trigger
+     * critical outcomes. Defaults to true for Skill tests, false otherwise.
+     */
+    useNaturalCrits?: boolean | undefined;
+};
+/**
+ * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
+ * @typedef {import("./entities/Outcome").OutcomeValue} OutcomeValue
+ * @typedef {import("./entities/RollModifier").RollModifierFunction} RollModifierFunction
+ * @typedef {import("./entities/RollModifier").RollModifierInstance} RollModifierInstance
+ * @typedef {import("./entities/TestType").TestTypeValue} TestTypeValue
+ * @typedef {import("./entities/TestConditions").TestConditionsInstance} TestConditionsInstance
+ */
+/**
+ * @typedef {Object} ModifiedTestAnalysis
+ * @property {number} totalPossibilities - Total number of possible die rolls
+ * @property {Object.<string, number>} outcomeCounts - Count of each outcome type
+ * @property {Object.<string, number>} outcomeProbabilities - Probability (0-1) of each outcome
+ * @property {Object.<number, OutcomeValue>} outcomesByRoll - Map of base roll to outcome
+ * @property {Object.<number, number>} modifiedValuesByRoll - Map of base roll to modified value
+ * @property {number[]} rolls - Array of all possible base roll values
+ * @property {Object.<OutcomeValue, number[]>} rollsByOutcome - Base rolls grouped by their outcome
+ * @property {{ min: number, max: number }} modifiedRange - Range of modified values achievable
+ */
+/**
+ * @typedef {Object} analyseModTestOptions
+ * @property {boolean} [useNaturalCrits] - If true, natural max/min rolls trigger
+ *   critical outcomes. Defaults to true for Skill tests, false otherwise.
+ */
+/**
+ * analyses modified test conditions without performing an actual roll.
+ *
+ * @function analyseModTest
+ * @param {DieTypeValue} dieType - The type of die (e.g., `DieType.D20`).
+ * @param {RollModifierFunction|RollModifierInstance} modifier - The modifier to apply to the roll.
+ * @param {TestConditionsInstance|{ testType: TestTypeValue, [key: string]: any }} testConditions
+ *   Can be:
+ *   - A `TestConditions` instance
+ *   - A plain object `{ testType, ...conditions }`
+ * @param {analyseModTestOptions} [options={}] - Optional configuration
+ * @returns {ModifiedTestAnalysis} Detailed analysis of the modified test outcomes
+ * @throws {TypeError} If `dieType`, `modifier`, or `testConditions` are invalid.
+ *
+ * @example
+ * // analyse a D20+5 skill check with DC 20
+ * const analysis = analyseModTest(
+ *   DieType.D20,
+ *   (n) => n + 5,
+ *   {
+ *     testType: TestType.Skill,
+ *     target: 20,
+ *     critical_success: 25,
+ *     critical_failure: 6
+ *   }
+ * );
+ *
+ * console.log(`Modified range: ${analysis.modifiedRange.min}-${analysis.modifiedRange.max}`);
+ * console.log(`Success rate: ${(analysis.outcomeProbabilities.success * 100).toFixed(1)}%`);
+ * console.log(`Need to roll: ${analysis.rollsByOutcome.success}`);
+ *
+ * @example
+ * // See how modifier affects outcomes
+ * const noMod = analyseTest(DieType.D20, { testType: TestType.AtLeast, target: 15 });
+ * const withMod = analyseModTest(DieType.D20, n => n + 5, { testType: TestType.AtLeast, target: 15 });
+ *
+ * console.log(`Without modifier: ${(noMod.outcomeProbabilities.success * 100).toFixed(1)}%`);
+ * console.log(`With +5 modifier: ${(withMod.outcomeProbabilities.success * 100).toFixed(1)}%`);
+ */
+export function analyseModTest(dieType: DieTypeValue, modifier: RollModifierFunction | RollModifierInstance, testConditions: TestConditionsInstance | {
+    testType: TestTypeValue;
+    [key: string]: any;
+}, options?: analyseModTestOptions): ModifiedTestAnalysis;
+//# sourceMappingURL=analyseModTest.d.ts.map

package/dist/analyseModTest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyseModTest.d.ts","sourceRoot":"","sources":["../src/analyseModTest.js"],"names":[],"mappings":"2BAyBa,OAAO,oBAAoB,EAAE,YAAY;2BACzC,OAAO,oBAAoB,EAAE,YAAY;mCACzC,OAAO,yBAAyB,EAAE,oBAAoB;mCACtD,OAAO,yBAAyB,EAAE,oBAAoB;4BACtD,OAAO,qBAAqB,EAAE,aAAa;qCAC3C,OAAO,2BAA2B,EAAE,sBAAsB;;;;;wBAKzD,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAKN,MAAM,EAAE;;;;;;;;mBAER;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;;;;;;;;;AAlB1C;;;;;;;GAOG;AAEH;;;;;;;;;;GAUG;AAEH;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wCAnCW,YAAY,YACZ,oBAAoB,GAAC,oBAAoB,kBACzC,sBAAsB,GAAC;IAAE,QAAQ,EAAE,aAAa,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,YAItE,qBAAqB,GACnB,oBAAoB,CAkHhC"}

package/dist/analyseModTest.js

@@ -0,0 +1,181 @@
+/**
+ * @module @platonic-dice/core/src/analyseModTest
+ * @description
+ * analyses modified test conditions without performing an actual roll.
+ * Provides probability information and possible outcomes for a given test configuration
+ * with modifiers applied.
+ *
+ * @example
+ * import { analyseModTest, DieType, TestType } from "@platonic-dice/core";
+ *
+ * const analysis = analyseModTest(
+ *   DieType.D20,
+ *   (n) => n + 5,
+ *   { testType: TestType.AtLeast, target: 20 }
+ * );
+ *
+ * console.log(analysis.successRate); // Probability with +5 modifier
+ */
+
+const { normaliseRollModifier } = require("./entities");
+const { ModifiedTestConditions } = require("./entities/ModifiedTestConditions");
+const { createOutcomeMap } = require("./utils/outcomeMapper");
+const { numSides } = require("./utils");
+
+/**
+ * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
+ * @typedef {import("./entities/Outcome").OutcomeValue} OutcomeValue
+ * @typedef {import("./entities/RollModifier").RollModifierFunction} RollModifierFunction
+ * @typedef {import("./entities/RollModifier").RollModifierInstance} RollModifierInstance
+ * @typedef {import("./entities/TestType").TestTypeValue} TestTypeValue
+ * @typedef {import("./entities/TestConditions").TestConditionsInstance} TestConditionsInstance
+ */
+
+/**
+ * @typedef {Object} ModifiedTestAnalysis
+ * @property {number} totalPossibilities - Total number of possible die rolls
+ * @property {Object.<string, number>} outcomeCounts - Count of each outcome type
+ * @property {Object.<string, number>} outcomeProbabilities - Probability (0-1) of each outcome
+ * @property {Object.<number, OutcomeValue>} outcomesByRoll - Map of base roll to outcome
+ * @property {Object.<number, number>} modifiedValuesByRoll - Map of base roll to modified value
+ * @property {number[]} rolls - Array of all possible base roll values
+ * @property {Object.<OutcomeValue, number[]>} rollsByOutcome - Base rolls grouped by their outcome
+ * @property {{ min: number, max: number }} modifiedRange - Range of modified values achievable
+ */
+
+/**
+ * @typedef {Object} analyseModTestOptions
+ * @property {boolean} [useNaturalCrits] - If true, natural max/min rolls trigger
+ *   critical outcomes. Defaults to true for Skill tests, false otherwise.
+ */
+
+/**
+ * analyses modified test conditions without performing an actual roll.
+ *
+ * @function analyseModTest
+ * @param {DieTypeValue} dieType - The type of die (e.g., `DieType.D20`).
+ * @param {RollModifierFunction|RollModifierInstance} modifier - The modifier to apply to the roll.
+ * @param {TestConditionsInstance|{ testType: TestTypeValue, [key: string]: any }} testConditions
+ *   Can be:
+ *   - A `TestConditions` instance
+ *   - A plain object `{ testType, ...conditions }`
+ * @param {analyseModTestOptions} [options={}] - Optional configuration
+ * @returns {ModifiedTestAnalysis} Detailed analysis of the modified test outcomes
+ * @throws {TypeError} If `dieType`, `modifier`, or `testConditions` are invalid.
+ *
+ * @example
+ * // analyse a D20+5 skill check with DC 20
+ * const analysis = analyseModTest(
+ *   DieType.D20,
+ *   (n) => n + 5,
+ *   {
+ *     testType: TestType.Skill,
+ *     target: 20,
+ *     critical_success: 25,
+ *     critical_failure: 6
+ *   }
+ * );
+ *
+ * console.log(`Modified range: ${analysis.modifiedRange.min}-${analysis.modifiedRange.max}`);
+ * console.log(`Success rate: ${(analysis.outcomeProbabilities.success * 100).toFixed(1)}%`);
+ * console.log(`Need to roll: ${analysis.rollsByOutcome.success}`);
+ *
+ * @example
+ * // See how modifier affects outcomes
+ * const noMod = analyseTest(DieType.D20, { testType: TestType.AtLeast, target: 15 });
+ * const withMod = analyseModTest(DieType.D20, n => n + 5, { testType: TestType.AtLeast, target: 15 });
+ *
+ * console.log(`Without modifier: ${(noMod.outcomeProbabilities.success * 100).toFixed(1)}%`);
+ * console.log(`With +5 modifier: ${(withMod.outcomeProbabilities.success * 100).toFixed(1)}%`);
+ */
+function analyseModTest(dieType, modifier, testConditions, 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, ...rest }
+    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
+  );
+
+  const sides = numSides(dieType);
+  const totalPossibilities = sides;
+
+  // Calculate modified values for each roll
+  /** @type {Object.<number, number>} */
+  const modifiedValuesByRoll = {};
+  for (let roll = 1; roll <= sides; roll++) {
+    modifiedValuesByRoll[roll] = mod.apply(roll);
+  }
+
+  // Determine modified range
+  const modifiedValues = Object.values(modifiedValuesByRoll);
+  const modifiedRange = {
+    min: Math.min(...modifiedValues),
+    max: Math.max(...modifiedValues),
+  };
+
+  // Count outcomes
+  /** @type {Object.<string, number>} */
+  const outcomeCounts = {};
+  /** @type {Object.<string, number[]>} */
+  const rollsByOutcome = {};
+
+  for (let roll = 1; roll <= sides; roll++) {
+    const outcome = outcomeMap[roll];
+
+    // Count outcomes
+    outcomeCounts[outcome] = (outcomeCounts[outcome] || 0) + 1;
+
+    // Group rolls by outcome
+    if (!rollsByOutcome[outcome]) {
+      rollsByOutcome[outcome] = [];
+    }
+    rollsByOutcome[outcome].push(roll);
+  }
+
+  // Calculate probabilities
+  /** @type {Object.<string, number>} */
+  const outcomeProbabilities = {};
+  for (const [outcome, count] of Object.entries(outcomeCounts)) {
+    outcomeProbabilities[outcome] = count / totalPossibilities;
+  }
+
+  return {
+    totalPossibilities,
+    outcomeCounts,
+    outcomeProbabilities,
+    outcomesByRoll: outcomeMap,
+    modifiedValuesByRoll,
+    rolls: Array.from({ length: sides }, (_, i) => i + 1),
+    rollsByOutcome,
+    modifiedRange,
+  };
+}
+
+module.exports = {
+  analyseModTest,
+};

package/dist/analyseTest.d.ts

@@ -0,0 +1,101 @@
+export type DieTypeValue = import("./entities/DieType").DieTypeValue;
+export type OutcomeValue = import("./entities/Outcome").OutcomeValue;
+export type TestTypeValue = import("./entities/TestType").TestTypeValue;
+export type TestConditionsInstance = import("./entities/TestConditions").TestConditionsInstance;
+export type TestAnalysis = {
+    /**
+     * - Total number of possible die rolls
+     */
+    totalPossibilities: number;
+    /**
+     * - Count of each outcome type
+     */
+    outcomeCounts: {
+        [x: string]: number;
+    };
+    /**
+     * - Probability (0-1) of each outcome
+     */
+    outcomeProbabilities: {
+        [x: string]: number;
+    };
+    /**
+     * - Map of roll value to outcome
+     */
+    outcomesByRoll: {
+        [x: number]: import("./entities").OutcomeValue;
+    };
+    /**
+     * - Array of all possible roll values
+     */
+    rolls: number[];
+    /**
+     * - Rolls grouped by their outcome
+     */
+    rollsByOutcome: any;
+};
+export type analyseTestOptions = {
+    /**
+     * - If true, natural max/min rolls trigger
+     * critical outcomes. Defaults to true for Skill tests, false otherwise.
+     */
+    useNaturalCrits?: boolean | undefined;
+};
+/**
+ * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
+ * @typedef {import("./entities/Outcome").OutcomeValue} OutcomeValue
+ * @typedef {import("./entities/TestType").TestTypeValue} TestTypeValue
+ * @typedef {import("./entities/TestConditions").TestConditionsInstance} TestConditionsInstance
+ */
+/**
+ * @typedef {Object} TestAnalysis
+ * @property {number} totalPossibilities - Total number of possible die rolls
+ * @property {Object.<string, number>} outcomeCounts - Count of each outcome type
+ * @property {Object.<string, number>} outcomeProbabilities - Probability (0-1) of each outcome
+ * @property {Object.<number, OutcomeValue>} outcomesByRoll - Map of roll value to outcome
+ * @property {number[]} rolls - Array of all possible roll values
+ * @property {Object.<OutcomeValue, number[]>} rollsByOutcome - Rolls grouped by their outcome
+ */
+/**
+ * @typedef {Object} analyseTestOptions
+ * @property {boolean} [useNaturalCrits] - If true, natural max/min rolls trigger
+ *   critical outcomes. Defaults to true for Skill tests, false otherwise.
+ */
+/**
+ * analyses test conditions without performing an actual roll.
+ *
+ * @function analyseTest
+ * @param {DieTypeValue} dieType - The type of die (e.g., `DieType.D20`).
+ * @param {TestConditionsInstance|{ testType: TestTypeValue, [key: string]: any }} testConditions
+ *   Can be:
+ *   - A `TestConditions` instance.
+ *   - A plain object `{ testType, ...conditions }`.
+ * @param {analyseTestOptions} [options={}] - Optional configuration for analysis
+ * @returns {TestAnalysis} Detailed analysis of the test outcomes
+ * @throws {TypeError} If `dieType` or `testConditions` are invalid.
+ *
+ * @example
+ * // analyse a D20 skill check with DC 15
+ * const analysis = analyseTest(DieType.D20, {
+ *   testType: TestType.Skill,
+ *   target: 15,
+ *   critical_success: 20,
+ *   critical_failure: 1
+ * });
+ *
+ * console.log(`Success rate: ${(analysis.outcomeProbabilities.success * 100).toFixed(1)}%`);
+ * console.log(`Critical success on: ${analysis.rollsByOutcome.critical_success}`);
+ *
+ * @example
+ * // analyse without natural crits
+ * const analysis = analyseTest(
+ *   DieType.D20,
+ *   { testType: TestType.AtLeast, target: 15 },
+ *   { useNaturalCrits: false }
+ * );
+ */
+export function analyseTest(dieType: DieTypeValue, testConditions: TestConditionsInstance | {
+    testType: TestTypeValue;
+    [key: string]: any;
+}, options?: analyseTestOptions): TestAnalysis;
+//# sourceMappingURL=analyseTest.d.ts.map

package/dist/analyseTest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyseTest.d.ts","sourceRoot":"","sources":["../src/analyseTest.js"],"names":[],"mappings":"2BA0Ba,OAAO,oBAAoB,EAAE,YAAY;2BACzC,OAAO,oBAAoB,EAAE,YAAY;4BACzC,OAAO,qBAAqB,EAAE,aAAa;qCAC3C,OAAO,2BAA2B,EAAE,sBAAsB;;;;;wBAKzD,MAAM;;;;;;;;;;;;;;;;;;;;;;WAIN,MAAM,EAAE;;;;;;;;;;;;;AAbtB;;;;;GAKG;AAEH;;;;;;;;GAQG;AAEH;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qCA7BW,YAAY,kBACZ,sBAAsB,GAAC;IAAE,QAAQ,EAAE,aAAa,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,YAItE,kBAAkB,GAChB,YAAY,CA8ExB"}

package/dist/analyseTest.js

@@ -0,0 +1,141 @@
+/**
+ * @module @platonic-dice/core/src/analyseTest
+ * @description
+ * analyses test conditions without performing an actual roll.
+ * Provides probability information and possible outcomes for a given test configuration.
+ *
+ * @example
+ * import { analyseTest, DieType, TestType } from "@platonic-dice/core";
+ *
+ * const analysis = analyseTest(DieType.D20, {
+ *   testType: TestType.AtLeast,
+ *   target: 15
+ * });
+ *
+ * console.log(analysis.totalPossibilities); // 20
+ * console.log(analysis.successCount);       // 6
+ * console.log(analysis.successRate);        // 0.3 (30%)
+ * console.log(analysis.outcomesByRoll);     // { 1: "failure", 2: "failure", ... }
+ */
+
+const { DieType, TestType } = require("./entities");
+const tc = require("./entities/TestConditions.js");
+const { createOutcomeMap } = require("./utils/outcomeMapper");
+const { numSides } = require("./utils");
+
+/**
+ * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
+ * @typedef {import("./entities/Outcome").OutcomeValue} OutcomeValue
+ * @typedef {import("./entities/TestType").TestTypeValue} TestTypeValue
+ * @typedef {import("./entities/TestConditions").TestConditionsInstance} TestConditionsInstance
+ */
+
+/**
+ * @typedef {Object} TestAnalysis
+ * @property {number} totalPossibilities - Total number of possible die rolls
+ * @property {Object.<string, number>} outcomeCounts - Count of each outcome type
+ * @property {Object.<string, number>} outcomeProbabilities - Probability (0-1) of each outcome
+ * @property {Object.<number, OutcomeValue>} outcomesByRoll - Map of roll value to outcome
+ * @property {number[]} rolls - Array of all possible roll values
+ * @property {Object.<OutcomeValue, number[]>} rollsByOutcome - Rolls grouped by their outcome
+ */
+
+/**
+ * @typedef {Object} analyseTestOptions
+ * @property {boolean} [useNaturalCrits] - If true, natural max/min rolls trigger
+ *   critical outcomes. Defaults to true for Skill tests, false otherwise.
+ */
+
+/**
+ * analyses test conditions without performing an actual roll.
+ *
+ * @function analyseTest
+ * @param {DieTypeValue} dieType - The type of die (e.g., `DieType.D20`).
+ * @param {TestConditionsInstance|{ testType: TestTypeValue, [key: string]: any }} testConditions
+ *   Can be:
+ *   - A `TestConditions` instance.
+ *   - A plain object `{ testType, ...conditions }`.
+ * @param {analyseTestOptions} [options={}] - Optional configuration for analysis
+ * @returns {TestAnalysis} Detailed analysis of the test outcomes
+ * @throws {TypeError} If `dieType` or `testConditions` are invalid.
+ *
+ * @example
+ * // analyse a D20 skill check with DC 15
+ * const analysis = analyseTest(DieType.D20, {
+ *   testType: TestType.Skill,
+ *   target: 15,
+ *   critical_success: 20,
+ *   critical_failure: 1
+ * });
+ *
+ * console.log(`Success rate: ${(analysis.outcomeProbabilities.success * 100).toFixed(1)}%`);
+ * console.log(`Critical success on: ${analysis.rollsByOutcome.critical_success}`);
+ *
+ * @example
+ * // analyse without natural crits
+ * const analysis = analyseTest(
+ *   DieType.D20,
+ *   { testType: TestType.AtLeast, target: 15 },
+ *   { useNaturalCrits: false }
+ * );
+ */
+function analyseTest(dieType, testConditions, options = {}) {
+  if (!dieType) throw new TypeError("dieType is required.");
+
+  // Normalise testConditions (skip if already a TestConditions instance)
+  const conditionSet =
+    testConditions instanceof tc.TestConditions
+      ? testConditions
+      : tc.normaliseTestConditions(testConditions, dieType);
+
+  // Create outcome map for all possible rolls
+  const outcomeMap = createOutcomeMap(
+    dieType,
+    conditionSet.testType,
+    conditionSet,
+    null, // no modifier
+    options.useNaturalCrits
+  );
+
+  const sides = numSides(dieType);
+  const totalPossibilities = sides;
+
+  // Count outcomes
+  /** @type {Object.<string, number>} */
+  const outcomeCounts = {};
+  /** @type {Object.<string, number[]>} */
+  const rollsByOutcome = {};
+
+  for (let roll = 1; roll <= sides; roll++) {
+    const outcome = outcomeMap[roll];
+
+    // Count outcomes
+    outcomeCounts[outcome] = (outcomeCounts[outcome] || 0) + 1;
+
+    // Group rolls by outcome
+    if (!rollsByOutcome[outcome]) {
+      rollsByOutcome[outcome] = [];
+    }
+    rollsByOutcome[outcome].push(roll);
+  }
+
+  // Calculate probabilities
+  /** @type {Object.<string, number>} */
+  const outcomeProbabilities = {};
+  for (const [outcome, count] of Object.entries(outcomeCounts)) {
+    outcomeProbabilities[outcome] = count / totalPossibilities;
+  }
+
+  return {
+    totalPossibilities,
+    outcomeCounts,
+    outcomeProbabilities,
+    outcomesByRoll: outcomeMap,
+    rolls: Array.from({ length: sides }, (_, i) => i + 1),
+    rollsByOutcome,
+  };
+}
+
+module.exports = {
+  analyseTest,
+};