Probability Branch

A lightweight TypeScript library for probabilistic branching and random selection, powered by the Mersenne Twister algorithm. 🎲✨

For more awesome packages, check out my homepage💛

Features

• Define multiple branches with custom probabilities and handlers
• Select a branch randomly or deterministically
• Limit the number of times a branch can be executed
• Pluggable random number generator (default: Mersenne Twister)
• Global control of random seed and generator

Installation

pnpm add probability-branch
# or
npm install probability-branch

Usage

import { pb } from 'probability-branch';

// Create a probability branch instance
pb()
  .br(70, () => console.log('Branch A'))
  .br(30, () => console.log('Branch B'))
  .br(23.3, () => console.log('Branch C'))
  .br(103.6, () => console.log('Branch D'))
  .run(); // Randomly runs one branch based on weights

API Reference

pb(options?: Partial<ProbabilityBranchOptions>): ProbabilityBranch

Create a new probability branch instance.

• options.limit: Maximum number of times the branch can be run (default: 1, set to 0 for unlimited).
• Returns An ProbabilityBranch instance.

instance.br(weight: number, handler: Fn)

Add a branch with a given probability and handler.

• weight: Non-negative number, probability weight for this branch.
• handler: Function to execute if this branch is selected.

instance.run(probability?: number): ProbabilityBranchResult

Run the probability branch. If probability is not provided, a random value is generated.

• Default random number generator is Mersenne Twister.

• Returns an object below:

interface ProbabilityBranchResult {
  /**
   * The probability value used for this run
   */
  probability: number;

  /**
   * The total sum of all branch weights
   */
  sum: number;

  /**
   * How many times this branch has been run
   */
  count: number;

  /**
   * The maximum number of times this branch can be run
   * - `0` means unlimited runs
   */
  limit: number;

  /**
   * All branches in this instance
   * - this is a reference to the real executed branches, be careful when modifying it
   */
  branches: Branch[];

  /**
   * Whether `branches.length` is `0`
   */
  readonly empty: boolean;

  /**
   * The index of the entered branch
   */
  index: number;

  /**
   * The value returned by the entered handler
   * - if `branches.length` is `0`, this will be `undefined`
   */
  returned: unknown;
}

instance.getCount(): number

Get how many times this instance has been run.

Random Generator Control (Global)

pb.setSeed(seed: number): ProbabilityBranchCreator

Set the seed for the global random number generator.

pb.getSeed(): number

Get the current seed.

pb.getCount(): number

Get how many random numbers have been generated since initialization.

pb.setGenerator(generator: RandomGenerator): ProbabilityBranchCreator

Replace the global random number generator.

• The generator must implement the RandomGenerator interface. See example below

pb.restoreDefaultGenerator(): ProbabilityBranchCreator

Restore the default Mersenne Twister generator.

Example: Custom Random Generator

In this interface, only random method is strictly required.

Other methods will fallback to a default implementation that does nothing.

class MyRandom implements RandomGenerator {
  private seed = 42;
  private count = 0;
  random() {
    this.count++;
    return Math.random();
  }
  setSeed(seed: number) {
    this.seed = seed;
  }
  getSeed() {
    return this.seed;
  }
  getCount() {
    return this.count;
  }
}

pb.setGenerator(new MyRandom());
pb.setSeed(123);

Bonus: Mersenne Twister

You can import the Mersenne Twister directly if you want to use it as a custom random generator:

import { MersenneTwister } from 'probability-branch';

new MersenneTwister(); // equivalent to `new MersenneTwister(0)`
const mt = new MersenneTwister(23);
mt.random(); // generates a random [0,1) number

License

MIT

Author

KasukabeTsumugi
Email: [email protected]