@yipe/dice 0.1.1 → 0.1.3

package/dist/index.d.cts

@@ -1,9 +1,24 @@
+/**
+ * Simple LRU cache implementation
+ */
+declare class LRUCache<K, V> {
+    private readonly maxSize;
+    private cache;
+    constructor(maxSize?: number);
+    get(key: K): V | undefined;
+    delete(key: K): void;
+    set(key: K, value: V): this;
+    clear(): void;
+    get size(): number;
+    has(key: K): boolean;
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V>;
+}
+
 /** Mapping from outcome label to probability mass or damage attribution. */
 type OutcomeLabelMap = Partial<Record<string, number>>;
 /** Computational epsilon for pruning negligible probabilities. */
-declare const COMPUTATIONAL_EPS = 1e-40;
-/** Test tolerance for floating-point precision errors. */
-declare const TEST_EPS = 1e-10;
+declare const EPS = 1e-12;
 /** A probability bin for a specific damage value. */
 interface Bin {
     /** Total probability mass at this damage value. */
@@ -17,6 +32,7 @@ interface Bin {
 type DamageDistribution = Record<number, number>;
 /** Canonical outcome labels supported by the query helpers. */
 type OutcomeType = "crit" | "hit" | "missNone" | "missDamage" | "saveHalf" | "saveFail" | "pc";
+type Rounding = "none" | "floor" | "round" | "ceil";
 
 /**
  * Query interface for analyzing dice roll probability distributions.
@@ -31,7 +47,7 @@ type OutcomeType = "crit" | "hit" | "missNone" | "missDamage" | "saveHalf" | "sa
 declare class DiceQuery {
     readonly singles: PMF[];
     readonly combined: PMF;
-    constructor(singles: PMF | PMF[], combined?: PMF);
+    constructor(singles: PMF | PMF[], combined?: PMF, eps?: number);
     private static readonly DEFAULT_OUTCOMES;
     /**
      * Returns the expected damage across all possible outcomes.
@@ -191,7 +207,6 @@ declare class DiceQuery {
      * - "How much damage comes from miss effects (like save-for-half spells)?"
      */
     expectedDamageFrom(labels: OutcomeType | OutcomeType[]): number;
-    private _expectedDamageFromSingle;
     /**
      * Returns damage statistics for scenarios where AT LEAST ONE attack results in
      * the specified outcome(s).
@@ -604,26 +619,16 @@ type Snapshot = {
     outcomes: Map<OutcomeType, OutcomeSnapshot>;
 };
 
+declare const pmfCache: LRUCache<string, PMF>;
 /**
  * Probability Mass Function for discrete damage distributions.
- *
- * Represents the probability distribution of dice roll outcomes with support for:
- * - Damage values and their probabilities
- * - Outcome type tracking (hit, miss, crit, etc)
- * - Damage attribution by outcome type
- *
- * Core operations:
- * - convolve(): Convolve two PMFs to represent multiple dice/attacks
- * - addScaled(): Add a scaled PMF branch (for conditional outcomes)
- * - mapDamage(): Transform damage values (for modifiers, resistances)
- * - normalize(): Ensure probabilities sum to 1.0
  */
 declare class PMF {
     readonly map: Map<number, Bin>;
     readonly epsilon: number;
     readonly normalized: boolean;
     readonly identifier: string;
-    private _preservedProvidence;
+    private _preservedProvenance;
     private static __anonIdCounter;
     private _support?;
     private _min?;
@@ -632,9 +637,10 @@ declare class PMF {
     private _mean?;
     private _variance?;
     private _stdev?;
-    constructor(map?: Map<number, Bin>, epsilon?: number, normalized?: boolean, identifier?: string, _preservedProvidence?: boolean);
+    constructor(map?: Map<number, Bin>, epsilon?: number, normalized?: boolean, identifier?: string, _preservedProvenance?: boolean);
     static empty(epsilon?: number, identifier?: string): PMF;
     static zero(epsilon?: number): PMF;
+    static delta(value: number, epsilon?: number): PMF;
     static emptyMass(): PMF;
     [Symbol.iterator](): IterableIterator<[number, Bin]>;
     static clearCache(): void;
@@ -727,9 +733,10 @@ declare class PMF {
      *   [pCrit, critPMF],
      * ]);
      */
-    static mixN(weights: [number, PMF][]): PMF;
-    private setPreservedProvidence;
-    preservedProvidence(): boolean;
+    static mixN(weights: [number, PMF][], eps?: number): PMF;
+    private setPreservedProvenance;
+    preservedProvenance(): boolean;
+    private getPowerCacheKey;
     /**
      * Efficiently computes this PMF convolved with itself `n` times.
      * Uses exponentiation by squaring to reduce total convolutions.
@@ -837,6 +844,8 @@ declare class PMF {
     } | null;
     /** Check if outcome exists in this PMF. */
     hasOutcome(outcome: string): boolean;
+    tailProbGE(t: number): number;
+    tailProbGT(t: number): number;
     /**
      * 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
@@ -862,84 +871,50 @@ declare class PMF {
         pNone: number;
         pAny: number;
     };
+    mapValues(f: (v: number) => number, eps?: number, opts?: {
+        rounding?: Rounding;
+        preserveCounts?: boolean;
+    }): PMF;
+    static fromMap(m: Map<number, number>, eps?: number, { requireIntegerValues }?: {
+        requireIntegerValues?: boolean;
+    }): PMF;
     query(): DiceQuery;
 }
-declare function getPowerCacheKey(base: PMF, n: number, eps: number): string;
 
-/**
- * @internal
- */
-declare class Dice {
-    private readonly faces;
-    privateData: Record<string, any>;
-    private outcomeData;
-    private hasHitDistributionCalculated;
-    identifier?: string;
-    constructor(x?: number);
-    getOutcomeDistribution(key: OutcomeType): DamageDistribution | undefined;
-    getFullOutcomeDistribution(): Record<OutcomeType, DamageDistribution | undefined>;
-    setOutcomeDistribution(key: OutcomeType, data: DamageDistribution | undefined): void;
-    hasOutcomeData(key: OutcomeType): boolean;
-    getOutcomeCount(key: OutcomeType, face: number): number;
-    getAverage(key: OutcomeType): number;
-    calculateHitDistribution(): DamageDistribution;
-    private ensureHitDistribution;
-    private binaryOp;
-    private removeFaces;
-    getFaceEntries(): [number, number][];
-    getFaceMap(): DamageDistribution;
-    get(face: number): number;
-    keys(): number[];
-    values(): number[];
-    total(): number;
-    setFace(key: number, value: number): void;
-    static scalar(value: number): Dice;
-    maxFace(): number;
-    minFace(): number;
-    increment(face: number, count: number): void;
-    normalize(scalar: number): Dice;
-    add(other: Dice | number): Dice;
-    subtract(other: Dice | number): Dice;
-    conditionalApply(other: Dice | number): Dice;
-    multiply(other: Dice | number): Dice;
-    addNonZero(other: Dice | number): Dice;
-    eq(other: Dice | number): Dice;
-    max(other: Dice | number): Dice;
-    min(other: Dice | number): Dice;
-    advantage(): Dice;
-    ge(other: Dice | number): Dice;
-    divide(other: Dice | number): Dice;
-    divideRoundUp(other: Dice | number): Dice;
-    divideRoundDown(other: Dice | number): Dice;
-    and(other: Dice | number): Dice;
-    private checkTarget;
-    dc(other: Dice | number): Dice;
-    ac(other: Dice | number): Dice;
-    deleteFace(face: number): Dice;
-    reroll(toReroll: Dice | number): Dice;
-    combine(other: Dice | number): Dice;
-    combineInPlace(other: Dice): void;
-    percent(): DamageDistribution;
-    average(): number;
-    toPMF(numEpsilon?: number): PMF;
-}
-type _DiceInternal = never;
-
-/**
- * Simple LRU cache implementation
- */
-declare class LRUCache<K, V> {
-    private readonly maxSize;
-    private cache;
-    constructor(maxSize?: number);
-    get(key: K): V | undefined;
-    delete(key: K): void;
-    set(key: K, value: V): this;
-    clear(): void;
-    get size(): number;
-    has(key: K): boolean;
-    keys(): IterableIterator<K>;
-    values(): IterableIterator<V>;
+/** A labeled mixture builder that preserves provenance in Bin.count. */
+declare class Mixture<L extends string = string> {
+    private readonly totals;
+    private readonly labelMass;
+    private readonly eps;
+    constructor(eps?: number);
+    /** Remove all accumulated state. */
+    clear(): this;
+    /** Number of distinct outcome values currently accumulated. */
+    size(): number;
+    /** Whether a label was ever added. */
+    hasLabel(label: L): boolean;
+    /**
+     * Add a labeled component with a mixture weight.
+     * Weight can be any positive finite number. Very small contributions are pruned by eps.
+     */
+    add(label: L, pmf: PMF, weight?: number): this;
+    buildPMF(eps?: number): PMF;
+    /**
+     * Produce normalized *per-label* PMFs (labels independent).
+     * These are unlabeled PMFs built from the raw mass of that label alone.
+     */
+    byOutcome(): Record<L, PMF>;
+    /**
+     * Mixture weights per label, normalized to sum to 1 over labels that appeared.
+     * Uses raw mass before per-outcome normalization.
+     */
+    weights(): Record<L, number>;
+    toJSON(): {
+        totals: Array<[number, number]>;
+        labels: Array<[number, Record<L, number>]>;
+        eps: number;
+    };
+    static mix<L extends string = string>(items: Array<[label: L, pmf: PMF, weight: number]>, eps?: number): PMF;
 }
 
 /** Enable or disable the internal parse cache. */
@@ -955,4 +930,4 @@ declare function clearParserCache(): void;
  */
 declare function parse(expression: string, n?: number): PMF;
 
-export { type Bin, COMPUTATIONAL_EPS, type DamageDistribution, Dice, DiceQuery, LRUCache, type OutcomeLabelMap, type OutcomeSnapshot, type OutcomeType, PMF, type Snapshot, TEST_EPS, type _DiceInternal, clearParserCache, getCachingEnabled, getPowerCacheKey, parse, setCachingEnabled };
+export { type Bin, type DamageDistribution, DiceQuery, EPS, LRUCache, Mixture, type OutcomeLabelMap, type OutcomeSnapshot, type OutcomeType, PMF, type Rounding, type Snapshot, clearParserCache, getCachingEnabled, parse, pmfCache, setCachingEnabled };

package/dist/index.d.ts

@@ -1,9 +1,24 @@
+/**
+ * Simple LRU cache implementation
+ */
+declare class LRUCache<K, V> {
+    private readonly maxSize;
+    private cache;
+    constructor(maxSize?: number);
+    get(key: K): V | undefined;
+    delete(key: K): void;
+    set(key: K, value: V): this;
+    clear(): void;
+    get size(): number;
+    has(key: K): boolean;
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V>;
+}
+
 /** Mapping from outcome label to probability mass or damage attribution. */
 type OutcomeLabelMap = Partial<Record<string, number>>;
 /** Computational epsilon for pruning negligible probabilities. */
-declare const COMPUTATIONAL_EPS = 1e-40;
-/** Test tolerance for floating-point precision errors. */
-declare const TEST_EPS = 1e-10;
+declare const EPS = 1e-12;
 /** A probability bin for a specific damage value. */
 interface Bin {
     /** Total probability mass at this damage value. */
@@ -17,6 +32,7 @@ interface Bin {
 type DamageDistribution = Record<number, number>;
 /** Canonical outcome labels supported by the query helpers. */
 type OutcomeType = "crit" | "hit" | "missNone" | "missDamage" | "saveHalf" | "saveFail" | "pc";
+type Rounding = "none" | "floor" | "round" | "ceil";
 
 /**
  * Query interface for analyzing dice roll probability distributions.
@@ -31,7 +47,7 @@ type OutcomeType = "crit" | "hit" | "missNone" | "missDamage" | "saveHalf" | "sa
 declare class DiceQuery {
     readonly singles: PMF[];
     readonly combined: PMF;
-    constructor(singles: PMF | PMF[], combined?: PMF);
+    constructor(singles: PMF | PMF[], combined?: PMF, eps?: number);
     private static readonly DEFAULT_OUTCOMES;
     /**
      * Returns the expected damage across all possible outcomes.
@@ -191,7 +207,6 @@ declare class DiceQuery {
      * - "How much damage comes from miss effects (like save-for-half spells)?"
      */
     expectedDamageFrom(labels: OutcomeType | OutcomeType[]): number;
-    private _expectedDamageFromSingle;
     /**
      * Returns damage statistics for scenarios where AT LEAST ONE attack results in
      * the specified outcome(s).
@@ -604,26 +619,16 @@ type Snapshot = {
     outcomes: Map<OutcomeType, OutcomeSnapshot>;
 };
 
+declare const pmfCache: LRUCache<string, PMF>;
 /**
  * Probability Mass Function for discrete damage distributions.
- *
- * Represents the probability distribution of dice roll outcomes with support for:
- * - Damage values and their probabilities
- * - Outcome type tracking (hit, miss, crit, etc)
- * - Damage attribution by outcome type
- *
- * Core operations:
- * - convolve(): Convolve two PMFs to represent multiple dice/attacks
- * - addScaled(): Add a scaled PMF branch (for conditional outcomes)
- * - mapDamage(): Transform damage values (for modifiers, resistances)
- * - normalize(): Ensure probabilities sum to 1.0
  */
 declare class PMF {
     readonly map: Map<number, Bin>;
     readonly epsilon: number;
     readonly normalized: boolean;
     readonly identifier: string;
-    private _preservedProvidence;
+    private _preservedProvenance;
     private static __anonIdCounter;
     private _support?;
     private _min?;
@@ -632,9 +637,10 @@ declare class PMF {
     private _mean?;
     private _variance?;
     private _stdev?;
-    constructor(map?: Map<number, Bin>, epsilon?: number, normalized?: boolean, identifier?: string, _preservedProvidence?: boolean);
+    constructor(map?: Map<number, Bin>, epsilon?: number, normalized?: boolean, identifier?: string, _preservedProvenance?: boolean);
     static empty(epsilon?: number, identifier?: string): PMF;
     static zero(epsilon?: number): PMF;
+    static delta(value: number, epsilon?: number): PMF;
     static emptyMass(): PMF;
     [Symbol.iterator](): IterableIterator<[number, Bin]>;
     static clearCache(): void;
@@ -727,9 +733,10 @@ declare class PMF {
      *   [pCrit, critPMF],
      * ]);
      */
-    static mixN(weights: [number, PMF][]): PMF;
-    private setPreservedProvidence;
-    preservedProvidence(): boolean;
+    static mixN(weights: [number, PMF][], eps?: number): PMF;
+    private setPreservedProvenance;
+    preservedProvenance(): boolean;
+    private getPowerCacheKey;
     /**
      * Efficiently computes this PMF convolved with itself `n` times.
      * Uses exponentiation by squaring to reduce total convolutions.
@@ -837,6 +844,8 @@ declare class PMF {
     } | null;
     /** Check if outcome exists in this PMF. */
     hasOutcome(outcome: string): boolean;
+    tailProbGE(t: number): number;
+    tailProbGT(t: number): number;
     /**
      * 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
@@ -862,84 +871,50 @@ declare class PMF {
         pNone: number;
         pAny: number;
     };
+    mapValues(f: (v: number) => number, eps?: number, opts?: {
+        rounding?: Rounding;
+        preserveCounts?: boolean;
+    }): PMF;
+    static fromMap(m: Map<number, number>, eps?: number, { requireIntegerValues }?: {
+        requireIntegerValues?: boolean;
+    }): PMF;
     query(): DiceQuery;
 }
-declare function getPowerCacheKey(base: PMF, n: number, eps: number): string;
 
-/**
- * @internal
- */
-declare class Dice {
-    private readonly faces;
-    privateData: Record<string, any>;
-    private outcomeData;
-    private hasHitDistributionCalculated;
-    identifier?: string;
-    constructor(x?: number);
-    getOutcomeDistribution(key: OutcomeType): DamageDistribution | undefined;
-    getFullOutcomeDistribution(): Record<OutcomeType, DamageDistribution | undefined>;
-    setOutcomeDistribution(key: OutcomeType, data: DamageDistribution | undefined): void;
-    hasOutcomeData(key: OutcomeType): boolean;
-    getOutcomeCount(key: OutcomeType, face: number): number;
-    getAverage(key: OutcomeType): number;
-    calculateHitDistribution(): DamageDistribution;
-    private ensureHitDistribution;
-    private binaryOp;
-    private removeFaces;
-    getFaceEntries(): [number, number][];
-    getFaceMap(): DamageDistribution;
-    get(face: number): number;
-    keys(): number[];
-    values(): number[];
-    total(): number;
-    setFace(key: number, value: number): void;
-    static scalar(value: number): Dice;
-    maxFace(): number;
-    minFace(): number;
-    increment(face: number, count: number): void;
-    normalize(scalar: number): Dice;
-    add(other: Dice | number): Dice;
-    subtract(other: Dice | number): Dice;
-    conditionalApply(other: Dice | number): Dice;
-    multiply(other: Dice | number): Dice;
-    addNonZero(other: Dice | number): Dice;
-    eq(other: Dice | number): Dice;
-    max(other: Dice | number): Dice;
-    min(other: Dice | number): Dice;
-    advantage(): Dice;
-    ge(other: Dice | number): Dice;
-    divide(other: Dice | number): Dice;
-    divideRoundUp(other: Dice | number): Dice;
-    divideRoundDown(other: Dice | number): Dice;
-    and(other: Dice | number): Dice;
-    private checkTarget;
-    dc(other: Dice | number): Dice;
-    ac(other: Dice | number): Dice;
-    deleteFace(face: number): Dice;
-    reroll(toReroll: Dice | number): Dice;
-    combine(other: Dice | number): Dice;
-    combineInPlace(other: Dice): void;
-    percent(): DamageDistribution;
-    average(): number;
-    toPMF(numEpsilon?: number): PMF;
-}
-type _DiceInternal = never;
-
-/**
- * Simple LRU cache implementation
- */
-declare class LRUCache<K, V> {
-    private readonly maxSize;
-    private cache;
-    constructor(maxSize?: number);
-    get(key: K): V | undefined;
-    delete(key: K): void;
-    set(key: K, value: V): this;
-    clear(): void;
-    get size(): number;
-    has(key: K): boolean;
-    keys(): IterableIterator<K>;
-    values(): IterableIterator<V>;
+/** A labeled mixture builder that preserves provenance in Bin.count. */
+declare class Mixture<L extends string = string> {
+    private readonly totals;
+    private readonly labelMass;
+    private readonly eps;
+    constructor(eps?: number);
+    /** Remove all accumulated state. */
+    clear(): this;
+    /** Number of distinct outcome values currently accumulated. */
+    size(): number;
+    /** Whether a label was ever added. */
+    hasLabel(label: L): boolean;
+    /**
+     * Add a labeled component with a mixture weight.
+     * Weight can be any positive finite number. Very small contributions are pruned by eps.
+     */
+    add(label: L, pmf: PMF, weight?: number): this;
+    buildPMF(eps?: number): PMF;
+    /**
+     * Produce normalized *per-label* PMFs (labels independent).
+     * These are unlabeled PMFs built from the raw mass of that label alone.
+     */
+    byOutcome(): Record<L, PMF>;
+    /**
+     * Mixture weights per label, normalized to sum to 1 over labels that appeared.
+     * Uses raw mass before per-outcome normalization.
+     */
+    weights(): Record<L, number>;
+    toJSON(): {
+        totals: Array<[number, number]>;
+        labels: Array<[number, Record<L, number>]>;
+        eps: number;
+    };
+    static mix<L extends string = string>(items: Array<[label: L, pmf: PMF, weight: number]>, eps?: number): PMF;
 }
 
 /** Enable or disable the internal parse cache. */
@@ -955,4 +930,4 @@ declare function clearParserCache(): void;
  */
 declare function parse(expression: string, n?: number): PMF;
 
-export { type Bin, COMPUTATIONAL_EPS, type DamageDistribution, Dice, DiceQuery, LRUCache, type OutcomeLabelMap, type OutcomeSnapshot, type OutcomeType, PMF, type Snapshot, TEST_EPS, type _DiceInternal, clearParserCache, getCachingEnabled, getPowerCacheKey, parse, setCachingEnabled };
+export { type Bin, type DamageDistribution, DiceQuery, EPS, LRUCache, Mixture, type OutcomeLabelMap, type OutcomeSnapshot, type OutcomeType, PMF, type Rounding, type Snapshot, clearParserCache, getCachingEnabled, parse, pmfCache, setCachingEnabled };