@platonic-dice/core 2.0.0

package/dist/roll.js

@@ -0,0 +1,135 @@
+/**
+ * @module @platonic-dice/core/src/roll
+ * @description
+ * Core logic for rolling a single die, with support for advantage/disadvantage
+ * and convenience aliases for common dice.
+ *
+ * Provides the fundamental random roll mechanism used throughout the library.
+ *
+ * @example
+ * import { roll, rollAdv, rollD20 } from "@platonic-dice/core";
+ *
+ * // Roll a d20 normally
+ * const result = roll(DieType.D20);
+ *
+ * // Roll a d20 with advantage
+ * const advantage = roll(DieType.D20, RollType.Advantage);
+ *
+ * // Roll a d6 using shorthand
+ * const six = rollD6();
+ */
+
+const {
+  DieType,
+  isValidDieType,
+  RollType,
+  isValidRollType,
+} = require("./entities");
+const utils = require("./utils");
+
+/**
+ * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
+ * @typedef {import("./entities/RollType").RollTypeValue} RollTypeValue
+ */
+
+/**
+ * Rolls a single die of the specified type, optionally applying advantage or disadvantage.
+ *
+ * @function roll
+ * @param {DieTypeValue} dieType - The type of die to roll (e.g., `DieType.D20`).
+ * @param {RollTypeValue | undefined} [rollType=undefined] - Optional roll mode (`RollType.Advantage` or `RollType.Disadvantage`).
+ * @returns {number} The rolled value (integer between 1 and the die's maximum face).
+ * @throws {TypeError} If `dieType` or `rollType` are invalid.
+ *
+ * @example
+ * const result = roll(DieType.D20, RollType.Advantage);
+ */
+function roll(dieType, rollType = undefined) {
+  // --- Validation ---
+  if (!isValidDieType(dieType)) {
+    throw new TypeError(`Invalid die type: ${dieType}`);
+  }
+
+  if (rollType !== undefined && !isValidRollType(rollType)) {
+    throw new TypeError(`Invalid roll type: ${rollType}`);
+  }
+
+  // --- Core Logic ---
+  const roll1 = utils.generateResult(dieType);
+  if (rollType === undefined) return roll1;
+
+  const roll2 = utils.generateResult(dieType);
+  return rollType === RollType.Advantage
+    ? Math.max(roll1, roll2)
+    : Math.min(roll1, roll2);
+}
+
+//
+// --- Convenience Aliases ---
+//
+
+/**
+ * Rolls a die with advantage.
+ * @type {(dieType: DieTypeValue) => number}
+ *
+ * @example
+ * const result = rollAdv(DieType.D10);
+ */
+const rollAdv = (dieType) => roll(dieType, RollType.Advantage);
+
+/**
+ * Rolls a die with disadvantage.
+ * @type {(dieType: DieTypeValue) => number}
+ *
+ * @example
+ * const result = rollDis(DieType.D10);
+ */
+const rollDis = (dieType) => roll(dieType, RollType.Disadvantage);
+
+/**
+ * Rolls a D4 die.
+ * @type {(rollType?: RollTypeValue | undefined) => number}
+ */
+const rollD4 = (rollType = undefined) => roll(DieType.D4, rollType);
+
+/**
+ * Rolls a D6 die.
+ * @type {(rollType?: RollTypeValue | undefined) => number}
+ */
+const rollD6 = (rollType = undefined) => roll(DieType.D6, rollType);
+
+/**
+ * Rolls a D8 die.
+ * @type {(rollType?: RollTypeValue | undefined) => number}
+ */
+const rollD8 = (rollType = undefined) => roll(DieType.D8, rollType);
+
+/**
+ * Rolls a D10 die.
+ * @type {(rollType?: RollTypeValue | undefined) => number}
+ */
+const rollD10 = (rollType = undefined) => roll(DieType.D10, rollType);
+
+/**
+ * Rolls a D12 die.
+ * @type {(rollType?: RollTypeValue | undefined) => number}
+ */
+const rollD12 = (rollType = undefined) => roll(DieType.D12, rollType);
+
+/**
+ * Rolls a D20 die.
+ * @type {(rollType?: RollTypeValue | undefined) => number}
+ */
+const rollD20 = (rollType = undefined) => roll(DieType.D20, rollType);
+
+module.exports = {
+  roll,
+  rollAdv,
+  rollDis,
+  rollD4,
+  rollD6,
+  rollD8,
+  rollD10,
+  rollD12,
+  rollD20,
+};

package/dist/rollDice.d.ts

@@ -0,0 +1,48 @@
+declare namespace _exports {
+    export { DieTypeValue, RollDiceAlias };
+}
+declare namespace _exports {
+    export { rollDice };
+}
+export = _exports;
+type DieTypeValue = import("./entities/DieType").DieTypeValue;
+type RollDiceAlias = (dieType: import("./entities/DieType").DieTypeValue) => {
+    array: number[];
+    sum: number;
+};
+/**
+ * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
+ */
+/**
+ * Rolls one or more dice of the specified type.
+ *
+ * @function rollDice
+ * @param {DieTypeValue} dieType - The type of die to roll (e.g., `DieType.D6`, `DieType.D20`).
+ * @param {Object} [options] - Optional configuration.
+ * @param {number} [options.count=1] - Number of dice to roll. Must be a positive integer.
+ * @returns {{ array: number[], sum: number }} An object containing:
+ *   - `array`: an array of individual die rolls.
+ *   - `sum`: the total sum of all rolls.
+ * @throws {TypeError} If `dieType` is invalid.
+ * @throws {TypeError} If `count` is not a positive integer.
+ *
+ * @example
+ * const result = rollDice(DieType.D6, { count: 5 });
+ * console.log(result.sum);   // e.g., 18
+ * console.log(result.array); // e.g., [2, 5, 3, 1, 7]
+ *
+ * @example
+ * // Roll a single d20
+ * const result = rollDice(DieType.D20);
+ *
+ * @example
+ * // Roll 3d6
+ * const result = rollDice(DieType.D6, { count: 3 });
+ */
+declare function rollDice(dieType: DieTypeValue, { count }?: {
+    count?: number | undefined;
+}): {
+    array: number[];
+    sum: number;
+};
+//# sourceMappingURL=rollDice.d.ts.map

package/dist/rollDice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollDice.d.ts","sourceRoot":"","sources":["../src/rollDice.js"],"names":[],"mappings":";;;;;;;oBAsBa,OAAO,oBAAoB,EAAE,YAAY;qBAmDzC,CAAC,OAAO,EAAE,OAAO,oBAAoB,EAAE,YAAY,KAAK;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE;AApDrG;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,mCAtBW,YAAY,cAEpB;IAAyB,KAAK;CAC9B,GAAU;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAoC5C"}

package/dist/rollDice.js

@@ -0,0 +1,92 @@
+/**
+ * @module @platonic-dice/core/src/rollDice
+ * @description
+ * Rolls one or more dice of a given type, returning both the individual rolls
+ * and their total sum. Includes convenient aliases for common counts (e.g., `roll3x` for 3 dice).
+ *
+ * @example
+ * import { rollDice, roll3x } from "@platonic-dice/core";
+ *
+ * // Roll a single d20
+ * const result = rollDice(DieType.D20);
+ * console.log(result.array, result.sum);
+ *
+ * // Roll 3d6 using an alias
+ * const rolls = roll3x(DieType.D6);
+ * console.log(rolls); // [2, 5, 4]
+ */
+
+const { isValidDieType } = require("./entities");
+const r = require("./roll.js");
+
+/**
+ * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
+ */
+
+/**
+ * Rolls one or more dice of the specified type.
+ *
+ * @function rollDice
+ * @param {DieTypeValue} dieType - The type of die to roll (e.g., `DieType.D6`, `DieType.D20`).
+ * @param {Object} [options] - Optional configuration.
+ * @param {number} [options.count=1] - Number of dice to roll. Must be a positive integer.
+ * @returns {{ array: number[], sum: number }} An object containing:
+ *   - `array`: an array of individual die rolls.
+ *   - `sum`: the total sum of all rolls.
+ * @throws {TypeError} If `dieType` is invalid.
+ * @throws {TypeError} If `count` is not a positive integer.
+ *
+ * @example
+ * const result = rollDice(DieType.D6, { count: 5 });
+ * console.log(result.sum);   // e.g., 18
+ * console.log(result.array); // e.g., [2, 5, 3, 1, 7]
+ *
+ * @example
+ * // Roll a single d20
+ * const result = rollDice(DieType.D20);
+ *
+ * @example
+ * // Roll 3d6
+ * const result = rollDice(DieType.D6, { count: 3 });
+ */
+function rollDice(dieType, { count = 1 } = {}) {
+  // --- Validation ---
+  if (!isValidDieType(dieType)) {
+    throw new TypeError(`Invalid die type: ${dieType}`);
+  }
+
+  if (typeof count !== "number" || !Number.isInteger(count) || count < 1) {
+    throw new TypeError(
+      `Invalid count: ${count}. Count must be a positive integer.`
+    );
+  }
+
+  // --- Core logic ---
+  const array = Array.from({ length: count }, () => r.roll(dieType));
+  const sum = array.reduce((total, n) => total + n, 0);
+
+  return { array, sum };
+}
+
+/** --- Friendly alias generation for convenience --- */
+
+/**
+ * @typedef {(dieType: import("./entities/DieType").DieTypeValue) => { array: number[], sum: number }} RollDiceAlias
+ */
+
+/**
+ * A collection of preconfigured dice roll functions like `roll2x`, `roll3x`, etc.
+ * @type {Record<string, RollDiceAlias>}
+ */
+const rollDiceAliases = {};
+
+const counts = [2, 3, 4, 5, 6, 7, 8, 9, 10, 25, 50, 100];
+
+for (const count of counts) {
+  rollDiceAliases[`roll${count}x`] = (dieType) => rollDice(dieType, { count });
+}
+
+module.exports = {
+  rollDice,
+  ...rollDiceAliases,
+};

package/dist/rollDiceMod.d.ts

@@ -0,0 +1,54 @@
+export type DieTypeValue = import("./entities/DieType").DieTypeValue;
+export type RollModifierFunction = import("./entities/RollModifier").RollModifierFunction;
+export type RollModifierInstance = import("./entities/RollModifier").RollModifierInstance;
+export type DiceModifier = import("./entities/RollModifier").DiceModifier;
+export type rollDiceModModifier = RollModifierInstance | RollModifierFunction | DiceModifier;
+/**
+ * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
+ * @typedef {import("./entities/RollModifier").RollModifierFunction} RollModifierFunction
+ * @typedef {import("./entities/RollModifier").RollModifierInstance} RollModifierInstance
+ * @typedef {import("./entities/RollModifier").DiceModifier} DiceModifier
+ */
+/**
+ * @typedef {RollModifierInstance | RollModifierFunction | DiceModifier} rollDiceModModifier
+ */
+/**
+ * Rolls multiple dice with optional per-die (`each`) and net (`net`) modifiers.
+ *
+ * @function rollDiceMod
+ * @param {DieTypeValue} dieType - The die type (e.g., `DieType.D6`).
+ * @param {rollDiceModModifier} [modifier={}] - The modifier(s) to apply.
+ * @param {{ count?: number }} [options={}] - Optional roll count (default: 1).
+ * @returns {{
+ *   base: { array: number[], sum: number },
+ *   modified: { each: { array: number[], sum: number }, net: { value: number } }
+ * }}
+ * @throws {TypeError} If `count` is invalid.
+ * @throws {TypeError} If any modifier is invalid.
+ */
+export function rollDiceMod(dieType: DieTypeValue, modifier?: rollDiceModModifier, { count }?: {
+    count?: number;
+}): {
+    base: {
+        array: number[];
+        sum: number;
+    };
+    modified: {
+        each: {
+            array: number[];
+            sum: number;
+        };
+        net: {
+            value: number;
+        };
+    };
+};
+/** @type {(dieType: DieTypeValue, modifier?: rollDiceModModifier, options?: { count?: number }) => number[]} */
+export const rollDiceModArr: (dieType: DieTypeValue, modifier?: rollDiceModModifier, options?: {
+    count?: number;
+}) => number[];
+/** @type {(dieType: DieTypeValue, modifier?: rollDiceModModifier, options?: { count?: number }) => number} */
+export const rollDiceModNet: (dieType: DieTypeValue, modifier?: rollDiceModModifier, options?: {
+    count?: number;
+}) => number;
+//# sourceMappingURL=rollDiceMod.d.ts.map

package/dist/rollDiceMod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollDiceMod.d.ts","sourceRoot":"","sources":["../src/rollDiceMod.js"],"names":[],"mappings":"2BAgCa,OAAO,oBAAoB,EAAE,YAAY;mCACzC,OAAO,yBAAyB,EAAE,oBAAoB;mCACtD,OAAO,yBAAyB,EAAE,oBAAoB;2BACtD,OAAO,yBAAyB,EAAE,YAAY;kCAI9C,oBAAoB,GAAG,oBAAoB,GAAG,YAAY;AARvE;;;;;GAKG;AAEH;;GAEG;AAEH;;;;;;;;;;;;;GAaG;AACH,qCAVW,YAAY,aACZ,mBAAmB,cACnB;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAChB;IACR,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,QAAQ,EAAE;QAAE,IAAI,EAAE;YAAE,KAAK,EAAE,MAAM,EAAE,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,GAAG,EAAE;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAA;CAC7E,CA4CH;AA8BD,gHAAgH;AAChH,6BADW,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,MAAM,EAAE,CAClE;AAE1C,8GAA8G;AAC9G,6BADW,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,MAAM,CACtE"}

package/dist/rollDiceMod.js

@@ -0,0 +1,137 @@
+/**
+ * @module @platonic-dice/core/src/rollDiceMod
+ * @description
+ * Rolls multiple dice with optional per-die (`each`) and total (`net`) modifiers.
+ * Returns structured results containing both the raw dice and all modified values.
+ *
+ * @example
+ * import { rollDiceMod, RollModifier } from "@platonic-dice/core";
+ * import { DieType } from "@platonic-dice/core/src/entities";
+ *
+ * // Apply a flat +1 to each die, then a +2 net bonus
+ * const result = rollDiceMod(DieType.D6, {
+ *   each: (n) => n + 1,
+ *   net: (sum) => sum + 2
+ * }, { count: 3 });
+ *
+ * console.log(result.base);     // { array: [2, 4, 1], sum: 7 }
+ * console.log(result.modified);
+ * // {
+ * //   each: { array: [3, 5, 2], sum: 10 },
+ * //   net: { value: 12 }
+ * // }
+ *
+ * @example
+ * // Single RollModifier for net only
+ * const bonus = new RollModifier((sum) => sum * 2);
+ * const result2 = rollDiceMod(DieType.D6, bonus, { count: 3 });
+ */
+const { normaliseRollModifier, RollModifier } = require("./entities");
+const rd = require("./rollDice.js");
+
+/**
+ * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
+ * @typedef {import("./entities/RollModifier").RollModifierFunction} RollModifierFunction
+ * @typedef {import("./entities/RollModifier").RollModifierInstance} RollModifierInstance
+ * @typedef {import("./entities/RollModifier").DiceModifier} DiceModifier
+ */
+
+/**
+ * @typedef {RollModifierInstance | RollModifierFunction | DiceModifier} rollDiceModModifier
+ */
+
+/**
+ * Rolls multiple dice with optional per-die (`each`) and net (`net`) modifiers.
+ *
+ * @function rollDiceMod
+ * @param {DieTypeValue} dieType - The die type (e.g., `DieType.D6`).
+ * @param {rollDiceModModifier} [modifier={}] - The modifier(s) to apply.
+ * @param {{ count?: number }} [options={}] - Optional roll count (default: 1).
+ * @returns {{
+ *   base: { array: number[], sum: number },
+ *   modified: { each: { array: number[], sum: number }, net: { value: number } }
+ * }}
+ * @throws {TypeError} If `count` is invalid.
+ * @throws {TypeError} If any modifier is invalid.
+ */
+function rollDiceMod(dieType, modifier = {}, { count = 1 } = {}) {
+  // --- Validation ---
+  if (typeof count !== "number" || !Number.isInteger(count) || count < 1) {
+    throw new TypeError(`Invalid count: ${count}. Must be a positive integer.`);
+  }
+
+  // --- Normalise modifier ---
+  let eachMod, netMod;
+
+  if (modifier instanceof RollModifier || typeof modifier === "function") {
+    // Single modifier → treated as net
+    eachMod = normaliseRollModifier(undefined); // identity
+    netMod = normaliseRollModifier(modifier);
+  } else if (typeof modifier === "object" && modifier !== null) {
+    const { each, net } = modifier;
+    eachMod = normaliseRollModifier(each);
+    netMod = normaliseRollModifier(net);
+  } else {
+    throw new TypeError(
+      `Invalid modifier: ${modifier}. Must be a function, RollModifier, or object.`
+    );
+  }
+
+  // --- Roll dice ---
+  const base = rd.rollDice(dieType, { count }); // { array, sum }
+
+  // --- Apply 'each' modifier ---
+  const eachArray = base.array.map((n) => eachMod.apply(n));
+  const eachSum = eachArray.reduce((a, b) => a + b, 0);
+
+  // --- Apply 'net' modifier ---
+  const netValue = netMod.apply(eachSum);
+
+  return {
+    base,
+    modified: {
+      each: { array: eachArray, sum: eachSum },
+      net: { value: netValue },
+    },
+  };
+}
+
+//
+// --- Convenience Aliases ---
+//
+
+/**
+ * @private
+ * Generates a simple accessor alias for `rollDiceMod`.
+ *
+ * @template {keyof { eachArray: number[]; net: number }} K
+ * @param {K} key
+ */
+function alias(key) {
+  /** @type {(...args: Parameters<typeof rollDiceMod>) => K extends 'eachArray' ? number[] : number} */
+  return (dieType, modifier = {}, options = {}) => {
+    const result = rollDiceMod(dieType, modifier, options);
+    switch (key) {
+      case "eachArray":
+        return /** @type {any} */ (result.modified.each.array);
+      case "net":
+        return /** @type {any} */ (result.modified.net.value);
+      default:
+        throw new TypeError(`Unknown alias key: ${key}`);
+    }
+  };
+}
+
+// --- Exports ---
+
+/** @type {(dieType: DieTypeValue, modifier?: rollDiceModModifier, options?: { count?: number }) => number[]} */
+const rollDiceModArr = alias("eachArray");
+
+/** @type {(dieType: DieTypeValue, modifier?: rollDiceModModifier, options?: { count?: number }) => number} */
+const rollDiceModNet = alias("net");
+
+module.exports = {
+  rollDiceMod,
+  rollDiceModArr,
+  rollDiceModNet,
+};

package/dist/rollMod.d.ts

@@ -0,0 +1,52 @@
+declare namespace _exports {
+    export { DieTypeValue, RollTypeValue, RollModifierFunction, RollModifierInstance, DieModifierAlias };
+}
+declare namespace _exports {
+    export { rollMod };
+}
+export = _exports;
+type DieTypeValue = import("./entities/DieType").DieTypeValue;
+type RollTypeValue = import("./entities/RollType").RollTypeValue;
+type RollModifierFunction = import("./entities/RollModifier").RollModifierFunction;
+type RollModifierInstance = import("./entities/RollModifier").RollModifierInstance;
+type DieModifierAlias = (rollType?: RollTypeValue | undefined) => number;
+/**
+ * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
+ * @typedef {import("./entities/RollType").RollTypeValue} RollTypeValue
+ * @typedef {import("./entities/RollModifier").RollModifierFunction} RollModifierFunction
+ * @typedef {import("./entities/RollModifier").RollModifierInstance} RollModifierInstance
+ */
+/**
+ * Rolls a single modified die by applying a modifier function or RollModifier.
+ *
+ * This function first rolls a base value using {@link roll}, then applies
+ * the provided modifier — either a function `(n) => number` or a
+ * {@link RollModifier} instance — to produce the final result.
+ *
+ * @function rollMod
+ * @param {DieTypeValue} dieType - The type of die to roll (e.g., `DieType.D20`).
+ * @param {RollModifierFunction|RollModifierInstance} modifier - The modifier to apply.
+ *   Can be either:
+ *   - A RollModifierFunction `(n: number) => number`
+ *   - A {@link RollModifier} instance
+ * @param {RollTypeValue | undefined} [rollType=undefined] - Optional roll mode (`RollType.Advantage` or `RollType.Disadvantage`).
+ * @returns {{ base: number, modified: number }} - The unmodified roll (`base`) and the modified result (`modified`).
+ * @throws {TypeError} If the modifier is invalid (not a function or RollModifier).
+ * @throws {TypeError} If the `dieType` or `rollType` are invalid (delegated to {@link roll}).
+ *
+ * @example
+ * const result = rollMod(DieType.D20, (n) => n + 2);
+ * console.log(result); // { base: 14, modified: 16 }
+ *
+ * @example
+ * const bonus = new RollModifier((n) => Math.min(n + 3, 20));
+ * const result = rollMod(DieType.D20, bonus);
+ *
+ * @example
+ * const result = rollMod(DieType.D10, (n) => Math.floor(n / 2), RollType.Advantage);
+ */
+declare function rollMod(dieType: DieTypeValue, modifier: RollModifierFunction | RollModifierInstance, rollType?: RollTypeValue | undefined): {
+    base: number;
+    modified: number;
+};
+//# sourceMappingURL=rollMod.d.ts.map

package/dist/rollMod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollMod.d.ts","sourceRoot":"","sources":["../src/rollMod.js"],"names":[],"mappings":";;;;;;;oBAuBa,OAAO,oBAAoB,EAAE,YAAY;qBACzC,OAAO,qBAAqB,EAAE,aAAa;4BAC3C,OAAO,yBAAyB,EAAE,oBAAoB;4BACtD,OAAO,yBAAyB,EAAE,oBAAoB;wBA8CtD,CAAC,QAAQ,CAAC,EAAE,aAAa,GAAG,SAAS,KAAK,MAAM;AAlD7D;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,kCArBW,YAAY,YACZ,oBAAoB,GAAC,oBAAoB,aAIzC,aAAa,GAAG,SAAS,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAsB9C"}

package/dist/rollMod.js

@@ -0,0 +1,114 @@
+/**
+ * @module @platonic-dice/core/src/rollMod
+ * @description
+ * Core logic for rolling a single die and applying a numeric or functional modifier.
+ *
+ * Provides the foundation for modified rolls — including bonuses, penalties,
+ * and scaling effects — as well as convenience aliases like `rollModP5`
+ * or `rollModT2` for fast use in common tabletop scenarios.
+ *
+ * @example
+ * import { rollMod, rollModP2, rollModT2 } from "@platonic-dice/core";
+ *
+ * // Roll a D20 with a +2 bonus
+ * const result = rollMod(DieType.D20, (n) => n + 2);
+ *
+ * // Or just the modified value
+ * const total = rollModP2(DieType.D20);
+ */
+
+const { DieType, RollModifier, normaliseRollModifier } = require("./entities");
+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
+ */
+
+/**
+ * Rolls a single modified die by applying a modifier function or RollModifier.
+ *
+ * This function first rolls a base value using {@link roll}, then applies
+ * the provided modifier — either a function `(n) => number` or a
+ * {@link RollModifier} instance — to produce the final result.
+ *
+ * @function rollMod
+ * @param {DieTypeValue} dieType - The type of die to roll (e.g., `DieType.D20`).
+ * @param {RollModifierFunction|RollModifierInstance} modifier - The modifier to apply.
+ *   Can be either:
+ *   - A RollModifierFunction `(n: number) => number`
+ *   - A {@link RollModifier} instance
+ * @param {RollTypeValue | undefined} [rollType=undefined] - Optional roll mode (`RollType.Advantage` or `RollType.Disadvantage`).
+ * @returns {{ base: number, modified: number }} - The unmodified roll (`base`) and the modified result (`modified`).
+ * @throws {TypeError} If the modifier is invalid (not a function or RollModifier).
+ * @throws {TypeError} If the `dieType` or `rollType` are invalid (delegated to {@link roll}).
+ *
+ * @example
+ * const result = rollMod(DieType.D20, (n) => n + 2);
+ * console.log(result); // { base: 14, modified: 16 }
+ *
+ * @example
+ * const bonus = new RollModifier((n) => Math.min(n + 3, 20));
+ * const result = rollMod(DieType.D20, bonus);
+ *
+ * @example
+ * const result = rollMod(DieType.D10, (n) => Math.floor(n / 2), RollType.Advantage);
+ */
+function rollMod(dieType, modifier, rollType = undefined) {
+  const mod = normaliseRollModifier(modifier);
+
+  const base = r.roll(dieType, rollType);
+  const modified = mod.apply(base);
+
+  return { base, modified };
+}
+
+//
+// --- Convenience Aliases ---
+//
+
+/**
+ * @typedef {(rollType?: RollTypeValue | undefined) => number} DieModifierAlias
+ */
+
+/**
+ * @description
+ * Container for all die-type-specific flat bonus and multiplicative aliases.
+ * Generated dynamically from DieType values.
+ *
+ * @type {Record<string, DieModifierAlias>}
+ */
+const dieTypeAliases = {};
+
+// --- Flat Bonus Aliases ---
+// Flat modifiers from -10 to +10 for each die type
+for (const [dieKey, dieValue] of Object.entries(DieType)) {
+  for (let i = 1; i <= 10; i++) {
+    /** @type {DieModifierAlias} */
+    dieTypeAliases[`roll${dieKey}P${i}`] = (rollType = undefined) =>
+      rollMod(dieValue, (n) => n + i, rollType).modified;
+
+    /** @type {DieModifierAlias} */
+    dieTypeAliases[`roll${dieKey}M${i}`] = (rollType = undefined) =>
+      rollMod(dieValue, (n) => n - i, rollType).modified;
+  }
+}
+
+// --- Multiplicative Aliases ---
+// Multiplicative modifiers such as ×2, ×10, ×100
+const multipliers = [2, 3, 5, 10, 50, 100];
+for (const [dieKey, dieValue] of Object.entries(DieType)) {
+  for (const m of multipliers) {
+    /** @type {DieModifierAlias} */
+    dieTypeAliases[`roll${dieKey}T${m}`] = (rollType = undefined) =>
+      rollMod(dieValue, (n) => n * m, rollType).modified;
+  }
+}
+
+// --- Export all aliases ---
+module.exports = {
+  rollMod,
+  ...dieTypeAliases,
+};

package/dist/rollTest.d.ts

@@ -0,0 +1,40 @@
+declare namespace _exports {
+    export { DieTypeValue, OutcomeValue, RollTypeValue, TestTypeValue, TestConditionsInstance };
+}
+declare namespace _exports {
+    export { rollTest };
+}
+export = _exports;
+type DieTypeValue = import("./entities/DieType").DieTypeValue;
+type OutcomeValue = import("./entities/Outcome").OutcomeValue;
+type RollTypeValue = import("./entities/RollType").RollTypeValue;
+type TestTypeValue = import("./entities/TestType").TestTypeValue;
+type TestConditionsInstance = import("./entities/TestConditions").TestConditionsInstance;
+/**
+ * @typedef {import("./entities/DieType").DieTypeValue} DieTypeValue
+ * @typedef {import("./entities/Outcome").OutcomeValue} OutcomeValue
+ * @typedef {import("./entities/RollType").RollTypeValue} RollTypeValue
+ * @typedef {import("./entities/TestType").TestTypeValue} TestTypeValue
+ * @typedef {import("./entities/TestConditions").TestConditionsInstance} TestConditionsInstance
+ */
+/**
+ * Rolls a die and evaluates it against specified test conditions.
+ *
+ * @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
+ *   Can be:
+ *   - A `TestConditions` instance.
+ *   - A plain object `{ testType, ...conditions }`.
+ * @param {RollTypeValue} [rollType=undefined] - Optional roll mode (`RollType.Advantage` or `RollType.Disadvantage`).
+ * @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): {
+    base: number;
+    outcome: OutcomeValue;
+};
+//# sourceMappingURL=rollTest.d.ts.map