rand-picker
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