https://github.com/alvarocastro/pick-random-weighted

Ultra fast and lightweight function to pick a random item from a weighted list.
https://github.com/alvarocastro/pick-random-weighted

array arrays choose decision-making javascript random weighted weighted-random

Last synced: 4 months ago
JSON representation

Ultra fast and lightweight function to pick a random item from a weighted list.

• Host: GitHub
• URL: https://github.com/alvarocastro/pick-random-weighted
• Owner: alvarocastro
• License: mit
• Created: 2019-07-18T18:39:13.000Z (over 6 years ago)
• Default Branch: master
• Last Pushed: 2023-04-05T21:57:37.000Z (over 2 years ago)
• Last Synced: 2025-06-17T21:54:07.094Z (5 months ago)
• Topics: array, arrays, choose, decision-making, javascript, random, weighted, weighted-random
• Language: JavaScript
• Homepage: https://www.npmjs.com/package/pick-random-weighted
• Size: 1.04 MB
• Stars: 7
• Watchers: 1
• Forks: 1
• Open Issues: 9
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# pick-random-weighted

[![NPM](https://img.shields.io/npm/v/pick-random-weighted)](https://www.npmjs.com/package/pick-random-weighted)

[![Build status](https://img.shields.io/github/workflow/status/alvarocastro/pick-random-weighted/build)](https://github.com/alvarocastro/pick-random-weighted/actions?query=workflow%3Abuild)

[![Maintainability status](https://img.shields.io/codeclimate/maintainability/alvarocastro/pick-random-weighted)](https://codeclimate.com/github/alvarocastro/pick-random-weighted/maintainability)

[![Coverage status](https://img.shields.io/coveralls/github/alvarocastro/pick-random-weighted)](https://coveralls.io/github/alvarocastro/pick-random-weighted?branch=master)

[![Bundle size](https://img.shields.io/bundlephobia/min/pick-random-weighted)](https://bundlephobia.com/result?p=pick-random-weighted)

[![Code style: XO](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/xojs/xo)

[![Release: Semantic](https://img.shields.io/badge/%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)

Simple, fast and lightweight function to pick a random element from a weighted array.

- [Install](#install)

- [Usage](#usage)

- [Randomness](#random-number-generation)

- [Contributing](#contributing)

- [Support](#support)

## Install

```bash

npm install pick-random-weighted

```

## Usage

The package contains a `pick` function that just works out-of-the box.

```js

import pick from 'pick-random-weighted';

const colors = [

	['Red', 30],

	['Green', 20],

	['Blue', 40]

];

const color = pick(colors);

```

It also contains a `Picker` class that can be instantiated to create a custom picker.

```js

import { Picker } from 'pick-random-weighted';

const picker = new Picker();

const colors = [

	['Red', 30],

	['Green', 20],

	['Blue', 40]

];

const color = Picker.pick(colors);

```

### pick(values)

Returns a random value from the `values` array.

##### values

Type: `Array`

List of values to pick from.

Each element should be provided in the format `[value, weight]`.

## Random number generation

By default, and to keep a small footprint, the library uses `Math.random()` to generate the random number to pick the value.

If you need you can define a custom function to generate random values, you can create a function that returns fixed values to use on your unit tests or implement a more specialized library like [random-js](https://www.npmjs.com/package/random-js).

### Using a custom random generator

By overwriting `pick.random` you can define your custom function.

> Remember the returned value should be a number within the [0,1) range.

```js

import { Picker } from 'pick-random-weighted';

const picker = new Picker(function () {

	return 0.3;

});

const colors = [

	['Red', 30],

	['Green', 20],

	['Blue', 40]

];

const color = Picker.pick(colors);

// Will always return 'Green' since our custom random generator function always returns the same value.

```

## Contributing

Contributions are always welcome! Please run `npm test` beforehand to ensure everything is ok.

## Support

If you use this package please consider starring it :)