@yipe/dice 0.1.1 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-007ec6.svg)](LICENSE)
 ![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178c6?logo=typescript)
 ![Size](https://img.shields.io/bundlephobia/minzip/@yipe/dice?logo=npm&logoColor=fff&label=Size)
-![Dice](https://dprcalc.com/api/roll)
+![Dice](https://dprcalc.com/api/roll.svg)
 
 ![Last Commit](https://img.shields.io/github/last-commit/yipe/dice?logo=github)
 ![Dependencies](https://img.shields.io/librariesio/release/npm/@yipe/dice?logo=npm)
@@ -33,8 +33,6 @@ console.log("DPR:", attack.mean());
 
 ## 🚀 Installation
 
-(COMING SOON!)
-
 ```bash
 # Install with npm or yarn
 npm install @yipe/dice

package/dist/index.cjs

@@ -47,20 +47,19 @@ var LRUCache = class {
 };
 
 // src/types.ts
-var COMPUTATIONAL_EPS = 1e-40;
-var TEST_EPS = 1e-10;
+var EPS = 1e-12;
 
 // src/query.ts
 var _DiceQuery = class _DiceQuery {
-  constructor(singles, combined) {
+  constructor(singles, combined, eps = EPS) {
     __publicField(this, "singles");
     __publicField(this, "combined");
     this.singles = Array.isArray(singles) ? singles : [singles];
-    const c = combined ?? PMF.convolveMany(this.singles);
-    this.combined = Math.abs(c.mass() - 1) <= 1e-12 ? c : c.normalize();
     if (this.singles.some((s) => s === void 0)) {
       throw new Error("DiceQuery contains undefined singles");
     }
+    const c = combined ?? PMF.convolveMany(this.singles);
+    this.combined = Math.abs(c.mass() - 1) <= eps ? c : c.normalize();
   }
   /**
    * Returns the expected damage across all possible outcomes.
@@ -358,23 +357,16 @@ var _DiceQuery = class _DiceQuery {
    * - "How much damage comes from miss effects (like save-for-half spells)?"
    */
   expectedDamageFrom(labels) {
-    if (typeof labels === "string") {
-      return this._expectedDamageFromSingle(labels);
-    }
-    let totalExpectedDamage = 0;
-    for (const [, probabilityBin] of this.combined) {
-      for (const label of labels) {
-        totalExpectedDamage += probabilityBin.attr?.[label] || 0;
+    const wanted = Array.isArray(labels) ? labels : [labels];
+    let total = 0;
+    for (const single of this.singles) {
+      for (const [dmg, bin] of single) {
+        let p = 0;
+        for (const label of wanted) p += bin.count[label] ?? 0;
+        total += dmg * p;
       }
     }
-    return totalExpectedDamage;
-  }
-  _expectedDamageFromSingle(label) {
-    let totalExpectedDamage = 0;
-    for (const [, probabilityBin] of this.combined) {
-      totalExpectedDamage += probabilityBin.attr?.[label] || 0;
-    }
-    return totalExpectedDamage;
+    return total;
   }
   /**
    * Returns damage statistics for scenarios where AT LEAST ONE attack results in
@@ -597,7 +589,7 @@ var _DiceQuery = class _DiceQuery {
    * query.toStackedChartData(['hit', 'crit'])
    * // → {labels: [0, 6, 12, ...], datasets: [{label: 'hit', data: [0, 0.03, ...]}, ...]}
    */
-  toStackedChartData(labels = [], epsilon = 1e-12) {
+  toStackedChartData(labels = [], epsilon = EPS) {
     const damageValues = this.combined.support();
     damageValues.map((dmg) => {
       const bin = this.combined.map.get(dmg);
@@ -1229,7 +1221,7 @@ var _DiceQuery = class _DiceQuery {
    *
    * Returns tuple: [pFirstNonSubset, pFirstSubset, pAnySuccess, pNone]
    */
-  firstSuccessSplit(successOutcome, subsetOutcome, eps = COMPUTATIONAL_EPS) {
+  firstSuccessSplit(successOutcome, subsetOutcome, eps = EPS) {
     const pmfs = this.singles;
     if (!pmfs.length) {
       throw new Error("firstSuccessSplitFromPMFs: pmfs must be non-empty");
@@ -1278,15 +1270,14 @@ __publicField(_DiceQuery, "DEFAULT_OUTCOMES", [
   "missNone"
 ]);
 var DiceQuery = _DiceQuery;
-var EPSILON = COMPUTATIONAL_EPS;
 var pmfCache = new LRUCache(1e3);
 var _PMF = class _PMF {
-  constructor(map = /* @__PURE__ */ new Map(), epsilon = EPSILON, normalized = false, identifier = `anon#${_PMF.__anonIdCounter++}`, _preservedProvidence = true) {
+  constructor(map = /* @__PURE__ */ new Map(), epsilon = EPS, normalized = false, identifier = `anon#${_PMF.__anonIdCounter++}`, _preservedProvenance = true) {
     this.map = map;
     this.epsilon = epsilon;
     this.normalized = normalized;
     this.identifier = identifier;
-    this._preservedProvidence = _preservedProvidence;
+    this._preservedProvenance = _preservedProvenance;
     // Cached computed values
     __publicField(this, "_support");
     __publicField(this, "_min");
@@ -1296,15 +1287,18 @@ var _PMF = class _PMF {
     __publicField(this, "_variance");
     __publicField(this, "_stdev");
   }
-  static empty(epsilon = EPSILON, identifier = "empty") {
+  static empty(epsilon = EPS, identifier = "empty") {
     return new _PMF(/* @__PURE__ */ new Map(), epsilon, false, identifier);
   }
   // This has a single bin at value 0, mass of 1
-  static zero(epsilon = EPSILON) {
+  static zero(epsilon = EPS) {
     const m = /* @__PURE__ */ new Map();
     m.set(0, { p: 1, count: { miss: 1 }, attr: {} });
     return new _PMF(m, epsilon, false, "zero");
   }
+  static delta(value, epsilon = EPS) {
+    return _PMF.fromMap(/* @__PURE__ */ new Map([[value, 1]]), epsilon);
+  }
   // This creates a single bin at value 0, but with weight 0.
   static emptyMass() {
     return _PMF.zero().scaleMass(0);
@@ -1407,7 +1401,7 @@ var _PMF = class _PMF {
    * @param eps Optional tolerance for floating point rounding
    * @returns A single PMF representing the exclusive mixture of all options.
    */
-  static exclusive(options, eps = 1e-12) {
+  static exclusive(options, eps = EPS) {
     const items = options.map(
       (o) => Array.isArray(o) ? { pmf: o[0], weight: o[1] } : o
     );
@@ -1437,8 +1431,7 @@ var _PMF = class _PMF {
    *   [pCrit, critPMF],
    * ]);
    */
-  static mixN(weights) {
-    const eps = 1e-12;
+  static mixN(weights, eps = EPS) {
     const filtered = weights.filter(([w]) => w > eps);
     if (filtered.length === 0) {
       return _PMF.emptyMass();
@@ -1460,17 +1453,23 @@ var _PMF = class _PMF {
   // This is a convenience method for when we use power
   // TODO: It can be smarter in the future, and we can also add it to query
   // That way statistics operations on invalid PMFs can throw an error
-  // TODO… how can we detect if manually merging two queries' combined PMFs, as that loses providence?
-  setPreservedProvidence(preserved) {
-    if (!this._preservedProvidence && preserved) {
+  // TODO… how can we detect if manually merging two queries' combined PMFs, as that loses provenance?
+  setPreservedProvenance(preserved) {
+    if (!this._preservedProvenance && preserved) {
       throw new Error(
-        "Preserved providence is already set to false, cannot fix that"
+        "Preserved provenance is already set to false, cannot fix that"
       );
     }
-    this._preservedProvidence = preserved;
+    this._preservedProvenance = preserved;
   }
-  preservedProvidence() {
-    return this._preservedProvidence;
+  preservedProvenance() {
+    return this._preservedProvenance;
+  }
+  getPowerCacheKey(n, eps) {
+    const id = this.identifier;
+    let key = `${id}`;
+    for (let i = 1; i < n; i++) key += `+${id}`;
+    return `${key}@${eps}`;
   }
   /**
    * Efficiently computes this PMF convolved with itself `n` times.
@@ -1488,7 +1487,7 @@ var _PMF = class _PMF {
     }
     if (n === 1) return this;
     const epsilon = eps ?? this.epsilon;
-    const key = getPowerCacheKey(this, n, epsilon);
+    const key = this.getPowerCacheKey(n, epsilon);
     {
       const cached = pmfCache?.get(key);
       if (cached) return cached;
@@ -1505,7 +1504,7 @@ var _PMF = class _PMF {
         base = base.convolve(base, epsilon);
       }
     }
-    result.setPreservedProvidence(false);
+    result.setPreservedProvenance(false);
     {
       pmfCache?.set(key, result);
     }
@@ -1534,7 +1533,7 @@ var _PMF = class _PMF {
   outcomeMass(outcome) {
     let totalProbabilityMass = 0;
     for (const { p, count } of this.map.values()) {
-      totalProbabilityMass += p * count[outcome];
+      totalProbabilityMass += p * (count[outcome] ?? 0);
     }
     return totalProbabilityMass;
   }
@@ -1797,7 +1796,7 @@ var _PMF = class _PMF {
   }
   convolve(other, eps, raw = false) {
     const epsilon = eps ?? this.epsilon;
-    const norm = (x) => raw ? x : Math.abs(x.mass() - 1) <= 1e-12 ? x : x.normalize();
+    const norm = (x) => raw ? x : Math.abs(x.mass() - 1) <= epsilon ? x : x.normalize();
     const A0 = norm(this);
     const B0 = norm(other);
     const [A, B] = A0.identifier <= B0.identifier ? [A0, B0] : [B0, A0];
@@ -1832,14 +1831,13 @@ var _PMF = class _PMF {
       epsilon,
       !raw,
       `${A.identifier}${raw ? "*" : "+"}${B.identifier}`
-      // ← canonical order
     );
     const mExp = (raw ? A.mass() : 1) * (raw ? B.mass() : 1);
     const mGot = result.mass();
-    if (mExp !== 0 && Math.abs(mGot - mExp) > 1e-12) {
+    if (mExp !== 0 && Math.abs(mGot - mExp) > epsilon) {
       result = result.scaleMass(mExp / mGot);
     }
-    if (!raw && Math.abs(result.mass() - 1) > 1e-12)
+    if (!raw && Math.abs(result.mass() - 1) > epsilon)
       result = result.normalize();
     pmfCache?.set(cacheKey, result);
     return result;
@@ -1887,7 +1885,7 @@ var _PMF = class _PMF {
    * - Similar PMF lists share common prefixes (A+B, (A+B)+C, etc.)
    * - Order-independent cache keys work better with consistent build patterns
    */
-  static convolveMany(pmfList, eps = EPSILON) {
+  static convolveMany(pmfList, eps = EPS) {
     if (pmfList.length === 0) return _PMF.empty(eps);
     if (pmfList.length === 1) return pmfList[0];
     return _PMF.reduceConvolveLeft(pmfList, eps);
@@ -1902,7 +1900,7 @@ var _PMF = class _PMF {
   static fromJSON(jsonData) {
     return new _PMF(
       new Map(jsonData.bins),
-      EPSILON,
+      EPS,
       !!jsonData.normalized,
       jsonData.identifier || "fromJSON"
     );
@@ -2048,6 +2046,21 @@ var _PMF = class _PMF {
     }
     return false;
   }
+  tailProbGE(t) {
+    let s = 0;
+    for (const [x, rec] of this) {
+      const p = typeof rec === "number" ? rec : rec.p;
+      if (p > 0 && x >= t) s += p;
+    }
+    return s;
+  }
+  tailProbGT(t) {
+    let s = 0;
+    for (const [x, rec] of this) {
+      if (x > t) s += rec.p;
+    }
+    return s;
+  }
   /**
    * Returns a new PMF containing only bins where the specified outcome has non-zero probability.
    * This creates a marginal distribution for the given outcome type, with probabilities
@@ -2107,6 +2120,66 @@ var _PMF = class _PMF {
     const pNone = 1 - pSpecificSuccess - pGeneralSuccess;
     return { pSpecificSuccess, pGeneralSuccess, pNone, pAny };
   }
+  mapValues(f, eps = EPS, opts) {
+    const rounding = opts?.rounding ?? "none";
+    const preserveCounts = opts?.preserveCounts ?? true;
+    const round = (x) => rounding === "floor" ? Math.floor(x) : rounding === "ceil" ? Math.ceil(x) : rounding === "round" ? Math.round(x) : x;
+    const probs = /* @__PURE__ */ new Map();
+    const counts = /* @__PURE__ */ new Map();
+    for (const [v, rec] of this) {
+      if (Math.abs(rec.p) < eps) continue;
+      const u = round(f(v));
+      probs.set(u, (probs.get(u) ?? 0) + rec.p);
+      if (preserveCounts) {
+        const rec2 = this.map.get(v);
+        const src = typeof rec2 === "number" ? void 0 : rec2?.count;
+        if (src) {
+          const dest = counts.get(u) ?? {};
+          for (const k in src) {
+            dest[k] = (dest[k] ?? 0) + src[k];
+          }
+          counts.set(u, dest);
+        }
+      }
+    }
+    const internal = /* @__PURE__ */ new Map();
+    for (const [u, p] of probs) {
+      internal.set(u, { p, count: counts.get(u) ?? {} });
+    }
+    return _PMF.fromMap(
+      new Map(Array.from(internal, ([u, b]) => [u, b.p])),
+      eps
+    );
+  }
+  static fromMap(m, eps = EPS, { requireIntegerValues = true } = {}) {
+    const filtered = [];
+    for (const [v, p] of m) {
+      if (!Number.isFinite(v) || !Number.isFinite(p)) continue;
+      if (p <= 0 || Math.abs(p) < eps) continue;
+      if (requireIntegerValues && !Number.isInteger(v)) {
+        throw new Error(`fromMap: non-integer outcome ${v}`);
+      }
+      filtered.push([v, p]);
+    }
+    if (filtered.length === 0) {
+      throw new Error("fromMap: empty or invalid input map");
+    }
+    let sum = 0;
+    let c = 0;
+    for (const [, p] of filtered) {
+      const y = p - c;
+      const t = sum + y;
+      c = t - sum - y;
+      sum = t;
+    }
+    if (sum <= 0) throw new Error("pmfFromMap: probabilities sum to 0");
+    filtered.sort((a, b) => a[0] - b[0]);
+    const internal = /* @__PURE__ */ new Map();
+    for (const [v, p] of filtered) {
+      internal.set(v, { p: p / sum, count: {} });
+    }
+    return new _PMF(internal, eps);
+  }
   query() {
     return new DiceQuery(this);
   }
@@ -2114,12 +2187,127 @@ var _PMF = class _PMF {
 // Unique ID generator for anonymous PMFs to avoid cache key collisions
 __publicField(_PMF, "__anonIdCounter", 1);
 var PMF = _PMF;
-function getPowerCacheKey(base, n, eps) {
-  const id = base.identifier;
-  let key = `${id}`;
-  for (let i = 1; i < n; i++) key += `+${id}`;
-  return `${key}@${eps}`;
-}
+
+// src/mixture.ts
+var Mixture = class _Mixture {
+  constructor(eps = EPS) {
+    __publicField(this, "totals", /* @__PURE__ */ new Map());
+    // raw mass per outcome (pre-normalization)
+    __publicField(this, "labelMass", /* @__PURE__ */ new Map());
+    // raw mass per outcome per label
+    __publicField(this, "eps");
+    this.eps = Number.isFinite(eps) ? eps : EPS;
+  }
+  /** Remove all accumulated state. */
+  clear() {
+    this.totals.clear();
+    this.labelMass.clear();
+    return this;
+  }
+  /** Number of distinct outcome values currently accumulated. */
+  size() {
+    return this.totals.size;
+  }
+  /** Whether a label was ever added. */
+  hasLabel(label) {
+    for (const bag of this.labelMass.values()) if (bag[label]) return true;
+    return false;
+  }
+  /**
+   * Add a labeled component with a mixture weight.
+   * Weight can be any positive finite number. Very small contributions are pruned by eps.
+   */
+  add(label, pmf, weight = 1) {
+    if (!Number.isFinite(weight) || weight <= 0) return this;
+    for (const [v, binOrNumber] of pmf) {
+      const isNumber = typeof binOrNumber === "number";
+      const p = isNumber ? binOrNumber : binOrNumber?.p ?? 0;
+      if (p <= 0) continue;
+      const add = weight * p;
+      if (!Number.isFinite(add) || Math.abs(add) < this.eps) continue;
+      this.totals.set(v, (this.totals.get(v) ?? 0) + add);
+      const bag = this.labelMass.get(v) ?? {};
+      bag[label] = (bag[label] ?? 0) + add;
+      this.labelMass.set(v, bag);
+    }
+    return this;
+  }
+  buildPMF(eps = EPS) {
+    let grand = 0;
+    let c = 0;
+    for (const m of this.totals.values()) {
+      const y = m - c;
+      const t = grand + y;
+      c = t - grand - y;
+      grand = t;
+    }
+    if (!(grand > 0)) throw new Error("LabeledMixture: zero total mass");
+    const internal = /* @__PURE__ */ new Map();
+    for (const [v, m] of this.totals) {
+      if (m <= 0 || Math.abs(m) < this.eps) continue;
+      const count = this.labelMass.get(v) ?? {};
+      internal.set(v, { p: m / grand, count });
+    }
+    return new PMF(internal, eps);
+  }
+  /**
+   * Produce normalized *per-label* PMFs (labels independent).
+   * These are unlabeled PMFs built from the raw mass of that label alone.
+   */
+  byOutcome() {
+    const labels = /* @__PURE__ */ new Set();
+    for (const bag of this.labelMass.values()) {
+      for (const k of Object.keys(bag)) labels.add(k);
+    }
+    const out = {};
+    for (const label of labels) {
+      const m = /* @__PURE__ */ new Map();
+      for (const [v, bag] of this.labelMass) {
+        const w = bag[label];
+        if (w && Math.abs(w) >= this.eps) m.set(v, w);
+      }
+      if (m.size > 0) out[label] = PMF.fromMap(m, this.eps);
+    }
+    return out;
+  }
+  /**
+   * Mixture weights per label, normalized to sum to 1 over labels that appeared.
+   * Uses raw mass before per-outcome normalization.
+   */
+  weights() {
+    const res = {};
+    for (const [, bag] of this.labelMass) {
+      for (const [lab, w] of Object.entries(bag)) {
+        if (!Number.isFinite(w) || w <= 0) continue;
+        res[lab] = (res[lab] ?? 0) + w;
+      }
+    }
+    let total = 0;
+    let c = 0;
+    for (const v of Object.values(res)) {
+      const y = v - c;
+      const t = total + y;
+      c = t - total - y;
+      total = t;
+    }
+    if (total > 0) {
+      for (const k in res) res[k] = res[k] / total;
+    }
+    return res;
+  }
+  toJSON() {
+    return {
+      totals: Array.from(this.totals.entries()).sort((a, b) => a[0] - b[0]),
+      labels: Array.from(this.labelMass.entries()).sort((a, b) => a[0] - b[0]),
+      eps: this.eps
+    };
+  }
+  static mix(items, eps = EPS) {
+    const mix = new _Mixture(eps);
+    for (const [lab, pmf, w] of items) mix.add(lab, pmf, w);
+    return mix.buildPMF();
+  }
+};
 
 // src/dice.ts
 var Dice = class _Dice {
@@ -2435,7 +2623,7 @@ var Dice = class _Dice {
    * Convert dice to PMF using OutcomeType labels directly from damage distribution.
    * This is much cleaner than the original complex distribution conversion.
    */
-  toPMF(numEpsilon = COMPUTATIONAL_EPS) {
+  toPMF(numEpsilon = EPS) {
     const total = this.total();
     if (total === 0) return PMF.empty(numEpsilon);
     this.ensureHitDistribution();
@@ -2614,7 +2802,7 @@ function parseExpression(arr, n) {
       }
       critNorm = crit.total();
       crit = op.call(crit, parseBinaryArgument(arg, arr, n));
-      critNorm = critNorm ? crit.total() / critNorm : 1;
+      critNorm = crit && critNorm ? crit.total() / critNorm : 1;
     }
     let save;
     let saveNorm = 1;
@@ -2629,7 +2817,7 @@ function parseExpression(arr, n) {
       saveNorm = save.total();
       finalResult = finalResult.deleteFace(min);
       save = op.call(save, parseBinaryArgument(arg, arr, n));
-      saveNorm = saveNorm ? save.total() / saveNorm : 1;
+      saveNorm = save && saveNorm ? save.total() / saveNorm : 1;
     }
     let pc;
     let pcNorm = 1;
@@ -2642,7 +2830,7 @@ function parseExpression(arr, n) {
       const missBefore = pc.total();
       finalResult = finalResult.deleteFace(min);
       pc = op.call(pc, parseBinaryArgument(arg, arr, n)).divideRoundDown(2);
-      const missAfter = pc.total();
+      const missAfter = pc ? pc.total() : 0;
       pcNorm = missBefore ? missAfter / missBefore : 1;
     }
     let miss;
@@ -2658,7 +2846,7 @@ function parseExpression(arr, n) {
       missNorm = miss.total();
       finalResult = finalResult.deleteFace(min);
       miss = op.call(miss, parseBinaryArgument(arg, arr, n));
-      missNorm = missNorm ? miss.total() / missNorm : 1;
+      missNorm = miss && missNorm ? miss.total() / missNorm : 1;
     }
     let norm = finalResult.total();
     finalResult = op.call(finalResult, arg);
@@ -2948,16 +3136,15 @@ function parseOperation(s) {
   return;
 }
 
-exports.COMPUTATIONAL_EPS = COMPUTATIONAL_EPS;
-exports.Dice = Dice;
 exports.DiceQuery = DiceQuery;
+exports.EPS = EPS;
 exports.LRUCache = LRUCache;
+exports.Mixture = Mixture;
 exports.PMF = PMF;
-exports.TEST_EPS = TEST_EPS;
 exports.clearParserCache = clearParserCache;
 exports.getCachingEnabled = getCachingEnabled;
-exports.getPowerCacheKey = getPowerCacheKey;
 exports.parse = parse;
+exports.pmfCache = pmfCache;
 exports.setCachingEnabled = setCachingEnabled;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map