rand-picker
TypeScript icon, indicating that this package has built-in type declarations

1.1.0 • Public • Published

rand-picker

NPM version Generic badge CI codecov

A powerful Random Picker of elements with many options. Easy to use.

Read docs.


How to use

Basics

Install (npm):

npm install rand-picker

Import (ES Modules):

import { newPicker } from "rand-picker";

Create a new picker:

const data = [1, 2, 3, 4, 5, 6];
const picker = newPicker(data);

Typing (TypeScript):

import { newPicker, Picker } from "rand-picker";

const data: number[] = [1, 2, 3, 4, 5, 6];
const picker: Picker<number> = newPicker(data);

Pick a random element:

const element1 = picker.pickOne();
const [element2] = picker.pick();

Pick multiple elements:

const elements = picker.pick(40); // Picks 40 random elements

Remove element after to be picked:

const picker = newPicker(data, {
  removeOnPick: true,
});
console.log(picker.length); // 6
picker.pick(2);
console.log(picker.length); // 4
console.log(data.length); // 4

Warning: picker mutates 'data' parameter.

Weighted picker:

const picker = newPicker(["A", "B"], {
  weighted: true,
});
picker.put("A", 25); // Edits weight of 'A' to 25
picker.put("B", 25); // Edits weight of 'B' to 25
picker.put("C", 50); // Adds 'C' and puts its height to 50

Note: it's not necessary to sum up 100, weights are relative about the elements.

Note 2: added weights does nothing if 'weighted' option is not enabled.

Options on pick

  • unique:
picker.pick(5, {
  unique: true,
}); // gets 5 unique elements
console.log(data.length); // 6. Don't modify data array

const elements = picker.pick(10, {
  unique: true,
}); // tries to get 10 unique elements
console.log(elements.length); // 6. 'data' has only 6 unique values
  • sequential:
picker.pick(2, {
  sequential: true,
}); // gets a pair of sequential elements: [1, 2], [2, 3], [3, 4], [4, 5] or [5, 6]

Note: both options can be combined.

Other functions

picker.weight // Returns total picker weights

picker.length // Returns data length

picker.getWeight(obj) // Returns the assigned weight for 'obj'

picker.duplicate(options?) // Returns a picker copy, with a new data and weight arrays

picker.remove(obj) // Removes 'obj' from picker and returns it

picker.throwDart(num); // Gives 'num' between 0 and weight, returns the determinated element for that number.

Note: if weights are not enabled, it takes all them as 1 for weight-related functions.

Secure random

const picker = newPicker(data, {
  randomMode: RandomMode.SECURE,
});

const picked = picker.pick(6);

Picker inside another picker

const innerPicker = newPicker([], {
  weighted: true,
})
  .put("B", 2) //   Prob = 2/5 (inside this picker)
  .put("C", 3); //  Prob = 3/5 (inside this picker)

const innerPicker2 = newPicker([], {
  weighted: true,
})
  .put("D", 3) //   Prob = 3/10 (inside this picker)
  .put("E", 7); //  Prob = 7/10 (inside this picker)

const picker = newPicker([], {
  weighted: true,
})
  .put("A") //                Prob = 1/21
  .put(innerPicker, 10) //    Prob = 10/21
  .put(innerPicker2, 10); //  Prob = 10/21

const darts = Array.from(Array(21).keys()); // 0, 1, ..., 20
const distribution = darts.map((i) => picker.throwDart(i));
console.log(distribution);
// 'A',                                 => Prob(A) = 1/21
// 'B', 'B', 'B', 'B',                  => Prob(B) = 4/21
// 'C', 'C', 'C', 'C', 'C', 'C',        => Prob(C) = 6/21
// 'D', 'D', 'D',                       => Prob(D) = 3/21
// 'E', 'E', 'E', 'E', 'E', 'E', 'E'    => Prob(E) = 7/21

©2021 Daniel Sales Álvarez

Package Sidebar

Install

npm i rand-picker

Weekly Downloads

1

Version

1.1.0

License

GPLv3

Unpacked Size

73 kB

Total Files

31

Last publish

Collaborators

  • danisales