@yipe/dice 0.2.0 → 0.2.2

package/dist/index.cjs

@@ -48,6 +48,14 @@ var LRUCache = class {
 
 // src/common/types.ts
 var EPS = 1e-12;
+var onAnyHit = ["hit", "crit"];
+var onCritOnly = ["crit"];
+var onHitOnly = ["hit"];
+var onMissOnly = ["missNone", "missDamage"];
+var onMissDamageOnly = ["missDamage"];
+var onSaveHalfOnly = ["saveHalf"];
+var onSaveFailOnly = ["saveFail"];
+var onPotentCantripOnly = ["pc"];
 
 // src/pmf/query.ts
 var _DiceQuery = class _DiceQuery {
@@ -1387,40 +1395,68 @@ var _PMF = class _PMF {
    *  - A PMF representing its outcome (e.g., damage dice).
    *  - A weight representing its probability of being selected.
    *
-   * This is useful for modeling situations like:
-   *  - Sneak Attack: 6d6 if first hit is a crit, 3d6 if first hit is non-crit, 0 otherwise.
-   *  - Multiple exclusive spells: Fireball vs Cone of Cold vs nothing.
-   *
    * Notes:
-   *  - If the total weight is less than 1, a zero PMF will automatically be added to
-   *    make up the remaining probability.
-   *  - Throws an error if the total weight is greater than 1 (invalid probability sum).
-   *
-   * @param options Array of `{ pmf, weight }` objects, each representing an outcome and its probability.
-   * @param label Optional name for debugging or charting.
-   * @param eps Optional tolerance for floating point rounding
-   * @returns A single PMF representing the exclusive mixture of all options.
+   *  - If total weight < 1 (within eps), leftover mass is assumed to be PMF.zero()
+   *
+   * @param options Array of `{ pmf, weight }` or `[PMF, number]`.
+   * @param eps Optional tolerance for floating point rounding.
    */
   static exclusive(options, eps = EPS) {
     const items = options.map(
       (o) => Array.isArray(o) ? { pmf: o[0], weight: o[1] } : o
     );
-    const totalWeight = items.reduce((s, { weight }) => s + weight, 0);
-    if (totalWeight - 1 > eps) {
+    for (const { weight } of items) {
+      if (!Number.isFinite(weight) || weight < -eps) {
+        throw new Error(`PMF.exclusive: invalid weight ${weight}.`);
+      }
+    }
+    let totalWeight = items.reduce((s, { weight }) => s + weight, 0);
+    if (Math.abs(totalWeight) <= eps) totalWeight = 0;
+    if (Math.abs(1 - totalWeight) <= eps) totalWeight = 1;
+    if (totalWeight > 1 + eps) {
       throw new Error(
         `PMF.exclusive: total weight ${totalWeight.toFixed(6)} exceeds 1.`
       );
     }
-    let out = items.reduce(
-      (acc, { pmf, weight }) => weight > 0 ? acc.addScaled(pmf, weight) : acc,
-      _PMF.empty(eps)
-    );
-    const leftover = 1 - totalWeight;
+    let out = _PMF.empty(eps);
+    for (const { pmf, weight } of items) {
+      if (weight > eps) out = out.addScaled(pmf, weight);
+    }
+    const leftover = Math.max(0, 1 - totalWeight);
     if (leftover > eps) {
       out = out.addScaled(_PMF.zero(), leftover);
     }
     return out;
   }
+  /**
+   * PMF.mix()
+   *
+   * Builds a PMF as a linear combination of input PMFs with the given weights.
+   * Unlike `exclusive`, this does NOT:
+   *  - enforce that weights sum to 1
+   *  - add leftover probability to δ0 (PMF.zero())
+   *
+   * Use when outcomes are not mutually exclusive, or for interpolation/blending.
+   *
+   * @param options Array of `{ pmf, weight }` or `[PMF, number]`.
+   * @param eps Optional tolerance for skipping tiny weights.
+   */
+  static mix(options, eps = EPS) {
+    const items = options.map(
+      (o) => Array.isArray(o) ? { pmf: o[0], weight: o[1] } : o
+    );
+    for (const { weight } of items) {
+      if (!Number.isFinite(weight)) {
+        throw new Error(`PMF.mix: invalid weight ${weight}.`);
+      }
+    }
+    let out = _PMF.empty(eps);
+    for (const { pmf, weight } of items) {
+      if (Math.abs(weight) <= eps) continue;
+      out = out.addScaled(pmf, weight);
+    }
+    return out;
+  }
   /**
    * General-purpose N-way mixture.
    * weights: Array of [weight, PMF].
@@ -3143,6 +3179,14 @@ exports.Mixture = Mixture;
 exports.PMF = PMF;
 exports.clearParserCache = clearParserCache;
 exports.getCachingEnabled = getCachingEnabled;
+exports.onAnyHit = onAnyHit;
+exports.onCritOnly = onCritOnly;
+exports.onHitOnly = onHitOnly;
+exports.onMissDamageOnly = onMissDamageOnly;
+exports.onMissOnly = onMissOnly;
+exports.onPotentCantripOnly = onPotentCantripOnly;
+exports.onSaveFailOnly = onSaveFailOnly;
+exports.onSaveHalfOnly = onSaveHalfOnly;
 exports.parse = parse;
 exports.pmfCache = pmfCache;
 exports.setCachingEnabled = setCachingEnabled;