npm package: @shane-butt/randomts
Description: Random numbers for all your random needs.
Author: Shane Butt
Latest version: 1.1.1

# **RandomTS**

## This is a set of random probability generators such as : flip a coin, roll a die, pick a number, and random number generation.

### This project was writen in TypeScript using Node. This project was to test using a npm I create to make an api to call for random events. I have plans later to add different distributions of random values.

---

---

## **Installing**

---

---

> ### Locally to play with the code
>
> - Clone from github using `https://github.com/ShaneButtCodeNL/RandomTS.git`
> - Install dependencies using `npm install`
> - `npm run build` will build the program in a `lib` folder in the current folder.
> - `npm run test` will run the code against the test to ensure the code works
> - you can then add RandomTS to your code using either `const random = require("{PATH}/RandomTS")` or `import * as random from "{PATH}/RandomTS"`. Where **{PATH}** is the path of the lib polder after building.

---

> ### From NPM (**Prefered**)
>
> - Run `npm install @shane-butt/randomts`
> - In your program import it using either `const random = require("@shane-butt/randomts` or `import * as random from "@shane-butt/randomts"`

Congratulations welcome to Random events of mild interest.

---

---

## **Using this Random event generator**

---

---

### Import to your project

- install with `npm i @shane-butt/randomts` import using `const random = require("@shane-butt/RandomTS")` or `import * as random from "@shane-butt/RandomTS"`

### Call Random functions

> #### `random`
>
> - generate a random value in range of [0,1). This can generate 0 but not 1.
> - Can be given a value `precision` that will limit the number of decimal places that will generate
> - Can be given up to two seeds. If two seeds are given it will return same value each call.

```
import * as random from "@shane-butt/randomts";

// Generates a value in range [0,1)
const a = random.random();

// Generates a value in range [0,1) with at most 3 decimal places
const b = random.random(3);

// Generates a value in range [0,1) with at most 3 decimal places
const c = random.random(3,123_123,321_321)

// Generates a value in range [0,1) with at most 3 decimal places
const d = random.random(3,123_123,321_321)

//Because both seeds are the same
d===c
```

> #### `flipACoin`
>
> - Generate a vaue of "H" for heads or "T" for tails
> - Can be given a seed. The result will be the same for the same seed.

```
import * as random from "@shane-butt/randomts";

// Will either be "H" or "T"
const flip1 = random.flipACoin();

// Will either be "H" or "T"
const flip2 = random.flipACoin(123_123);

// Will either be "H" or "T"
const flip3 = random.flipACoin(123_123);

// Will either be "H" or "T" may be different than flip2 and flip3
const flip4 = random.flipACoin(123_456);

//Same Seed
flip2===flip3

```

> #### `rollASixSidedDie`
>
> - Generate a number in range [ 0 , 6 ]. Can generate 1 and 6.
> - Can be given a seed. Calls with the same seed will have the same result.

```
import * as random from "@shane-butt/randomts";

// Will generate a value in range of [ 1 , 6 ]
const roll1 = random.rollASixSidefDie();

// Will generate a value in range of [ 1 , 6 ]
const roll2 = random.rollASixSidefDie(123);

// Will generate a value in range of [ 1 , 6 ]
const roll3 = random.rollASixSidefDie(123);

roll2===roll3
```

> #### `rollANSidedDie`
>
> - Needs a value of n which is how many sides the die has
> - Generate a value in range of [ 1 , n ]
> - Can be given a seed. Calls with the same seed will have the same result.

```
import * as random from "@shane-butt/randomts";

// Will generate a value between [ 1 , 20 ]
const roll1 = random.rollNSidedDie(20);

// Will generate a value between [ 1 , 20 ]
const roll2 = random.rollNSidedDie(20,1234);

// Will generate a value between [ 1 , 20 ]
const roll3 = random.rollNSidedDie(20,1234);

roll2===roll3
```

> #### `shuffleArray`
>
> - Pass an array to the function and it will return a copy that is shuffled
> - Can be given two seeds. Calls with both seeds the same will have the same result.

```
import * as random from "@shane-butt/randomts";

const a= [1,2,3]

// Shuffle a. shuffled can be any permutation of [1,2,3]
const shuffled1 = random.shuffleArray(a)

// Shuffle a. shuffled can be any permutation of [1,2,3]
const shuffled2 = random.shuffleArray(a)

// Shuffle a. shuffled can be any permutation of [1,2,3]
const shuffled3 = random.shuffleArray(a)

for(let i=0;i<3;i++){
   shuffled2[i]===shuffled3[i]
}
```

> #### `shuffleArrayInPlace`
>
> - Pass an array to the function and it will shuffle it and alter the values in the original array.
> - Please use `shuffleArray` instead of this. It is better to return a copy than mutate the original.
> - Can be given two seeds. Calls with both seeds the same will have the same result.

```
import * as random from "@shane-butt/randomts";

let a = [1,2,3]

//Shuffle a. a now can be any permutation of [1,2,3]
random.shuffleArrayInPlace(a)
```

> #### `pickRandomFromArray`
>
> - Pass an array to the function and get a random value from the array.
> - Can be given a seed. Calls with the same seed will have the same result.
> - Can be given two seeds. Calls with both seeds the same will have the same result.

```
import * as random from "@shane-butt/randomts";

const a= [1,2,3]

// A value from a. Either 1 , 2 or 3
const value1 = random.pickRandomFromArray(a)

// A value from a. Either 1 , 2 or 3
const value2 = random.pickRandomFromArray(a, 123, 321)

// A value from a. Either 1 , 2 or 3
const value3 = random.pickRandomFromArray(a, 123, 321)

value2 === value3;
```

> #### `pickNRandomFromArray`
>
> - Pass an array and a value and get a number of values from the array.
> - You may also pass a third boolean value to dictate whether you would like duplicates. If you pass true it will pick duplicates. By default it will not pick duplicates.
> - If you choose not to allow duplicates the value passed must be less than or equal to the length of the array.
> - Can be given a seed. Calls with the same seed will have the same result.

```
import * as random from "@shane-butt/randomts";

const a= [1,2,3,4,5,6,7,8,9]

// Will get 5 unique values from a.
const values1 = random.pickRandomNFromArray(a,5)

// Will get 5 values from a with a possibility of duplicates.
const values2 = random.pickRandomNFromArray(a,5,true)

// Will get 5 unique values from a.
const values3 = random.pickRandomNFromArray(a,5,false)

// Will throw error as value is larger than array length.
const values1 = random.pickRandomNFromArray(a,100)

// Will get 100 values from a. Will have duplicates.
const values1 = random.pickRandomNFromArray(a,100,true)
```

> #### `randomNumberInRange`
>
> - Pass a lower limit and upper limit to get a value in range [lower,higher).
> - Can be given a seed. Calls with the same seed will have the same result.

```
import * as random from "@shane-butt/randomts";

// A value either 1 , 2 or 3
const value = random.randomNumberInRange(1,4)
```

> #### `nRandomNumbersInRange`
>
> - Pass a lower limit, upper limit, number of values "n" and an optional boolean value to allow duplicates.
> - Will get n values in range [lower,upper).
> - if duplicates are not allowed the value of n must be less than | upper - lower |.Thats the absolute value.
> - duplicates are not allowed by default.
> - Can be given a seed. Calls with the same seed will have the same result.
> - Returns an array of numbers

```
import * as random from "@shane-butt/randomts";

// Will get 10 unique values in range [-10,10).
const values1 = random.nRandomNumbersInRange(-10,10,10)

// Will get 10 values in range [-10,10). May have duplicates.
const values2 = random.nRandomNumbersInRange(-10,10,10,true)

// Will get 10 unique values in range [-10,10).
const values3 = random.nRandomNumbersInRange(-10,10,10,false)

// Will throw an error as 100 > | 10 - -10|=20
const err = random.nRandomNumbersInRange(-10,10,100)

// Will get 100 values in range [-10,10). will have duplicates.
const values4 = random.nRandomNumbersInRange(-10,10,100,true)
```

---

---

### Use The Random Number Generators

---

#### `RandomWholeNumber`

Import To project

```
import {RandomWholeNumber} from "@shane-butt/randomts"
```

Constructor

> `RandomWholeNumber( seed?:number, max=100, min=0 )`
>
> - `seed` [ number ] A number that is used to base the random values are generated from. If undefined it will generate its own seed.
> - `max` [ number ] A number that makes an upper bound for number generation. All Values generated will be strictly less then max. Defaults to 100.
> - `min` [ number ] A number that makes a floor for number generation. All Values will be greater than or equal to min. Defaults to 0.
> - `max` must be greater than `min`. If `min` is grater than or equal to max an error will be thrown.

```
import {RandomWholeNumber} from "@shane-butt/randomts"

const rng1 = new RandomWholeNumber()

const rng2 = new RandomWholeNumber(123_456_789)

const rng3 = new RandomWholeNumber(123_456_789,30,99)

```

Generate values

> `next( offset=0 )` Will generate a value in the range of the generator's min and max values.
>
> - `offset` [ number ] A value to offset the next generated value without affecting future random generations.

```
import {RandomWholeNumber} from "@shane-butt/randomts"

const rng = new RandomWholeNumber()

//Random value in range [0 , 99]
const randomValue= rng.next();
```

> `nextInRange( min:number, max:number, offset=0 )` Will generate a value in the range [ min,max ]
>
> - `min` The floor for generation. Value generated will be greater than or equal to min.
> - `max` The upper bound for number generation. Value generated will be strictly less then max.
> - This function ignores the bound the of the generator allowing generation of different values without affecting future generations.
> - `max` must be greater than `min`. If `min` is grater than or equal to max an error will be thrown.

```
import {RandomWholeNumber} from "@shane-butt/randomts"

const rng = new RandomWholeNumber()

//Random value in range [123 , 321]
const randomValue= rng.nextInRange(123,321);
```

> `reset()` Will reset the the Generator to initial state.

```
import {RandomWholeNumber} from "@shane-butt/randomts"

const rng = new RandomWholeNumber()

const a = rng.next()

rng.reset()

const b = rng.next()

//True
a===b
```

---

#### `Randomprobability`

Import To project

```
import {RandomProbability} from "@shane-butt/randomts"
```

Constructor

> `RandomProbability(seedA?: number, seedB?: number, precision = 2)`
>
> - `seedA` [ number ] a Seed used to generate numbers.
> - `seedB` [ number ] a Seed used to generate numbers.
> - `precision` [ number ] The precision of the number. This states the number of decimal places to use. Must be greater than zero. Defaults value to 2.

```
import {RandomProbability} from "@shane-butt/randomts"

const rng = new RandomProbability()

const rng2 = new RandomProbability(123)

const rng3 = new RandomProbability(123, 456)

const rng4 = new RandomProbability(123, 456, 5)
```

Generate Values

> `next(offset=0)` Generates a value in range [ 0 , 1 )
>
> - `offset` A number that can be given to offset this generated value. Defaults to zero if undefined
> - Returns a string representation of a number in the range [ 0 , 1 ).
> - Value will have `precision` number of decimal points. EX `precision=2` then `value=0.AB` where `A` and `B` are numbers.

```
import {RandomProbability} from "@shane-butt/randomts"

const rng = new RandomProbability()

const a= rng.next()

//True
typeof a === "string"

const numA = parseFloat(a)

//True
numA >= 0
//True
numA < 1
```

> `nextValue(offset=0)`
>
> - `offset` A number that can be given to offset this generated value. Defaults to zero if undefined.
> - Returns a number in the range of [ 0 , 1 ).
> - This is the same as calling `next` but calls parse float on the value automatically.
> - Value will have `precision` number of decimal points. EX `precision=2` then `value=0.AB` where `A` and `B` are numbers.
> - Since this is a number the number of decimal places may be less than `precision` as trailing zeros are ignored.

```
import {RandomProbability} from "@shane-butt/randomts"

const rng = new RandomProbability()

const a = rng.nextValue(100)

//True
typeof a === "number"

//True
a >= 0
//True
a < 1
//True
a !== 1
```

> `nextPrecision(precision:number,offset=0) : string`
>
> - `precision` The precision (number of decimals places) of the next generated value.
> - `offset` A number that can be given to offset this generated value. Defaults to zero if undefined
> - Returns a String representation of a number in range of [ 0 ,1 ). Will have a length of 2 + `precision`. EX 0.ABC

```
import {RandomProbability} from "@shane-butt/randomts"

const rng = new RandomProbability()

// a is like "0.ABCDE"
const a = rng.nextPrecision(5)

//True
typeof a === "string"

//True
a.length === 2+5
```

> `nextValuePrecision(precision:number,offset=0) : number`
>
> - `precision` The precision (number of decimals places) of the next generated value.
> - `offset` A number that can be given to offset this generated value. Defaults to zero if undefined
> - Returns a number in range of [ 0 ,1 ). Will have a length less than or equal to 2 + `precision`. It can be less as trailing zeros will be ignored. EX 0.ABC .

```
import {RandomProbability} from "@shane-butt/randomts"

const rng = new RandomProbability()

// a is like 0.ABCDE
const a = rng.nextValuePrecision(5)

//True
typeof a === "number"

//True. Can be less if trailing zeros Ex 0.12300 === 0.123.
`${a}`.length <= 2+5
```

Reset the generator

> `reset()`
>
> - Resets the generator to initial state

```
import {RandomProbability} from "@shane-butt/randomts"

const rng = new RandomProbability()

const a = rng.next()

rng.reset()

const b = rng.next()

//True
a === b
```