npm package: @fast.one/random
Description: `@fast.one/random` is a library that provides a random number generator with various functionalities. It offers the ability to generate random unsigned integers, random numbers between 0 and 2, retrieve random elements from an array, generate arrays of ra
Latest version: 1.0.9

# @fast.one/random

`@fast.one/random` is a library that provides a random number generator with various functionalities. It offers the ability to generate random unsigned integers, random numbers between 0 and 2, retrieve random elements from an array, generate arrays of random values, and more.

## Installation

You can install `@fast.one/random` using npm or yarn:

```shell
npm install @fast.one/random
```

or

```shell
yarn add @fast.one/random
```

## Usage

To use the `@fast.one/random` library, import the `Random` object from the library:

```typescript
import { Random } from '@fast.one/random';
```

The `Random` object provides the following methods:

### uint

```typescript
uint(size?: number): number;
```

Generates a random unsigned integer between 0 and the specified size (inclusive). If no size is provided, the default upper bound is 1000.

### three

```typescript
three(): 0 | 1 | 2;
```

Generates a random number between 0 and 2 (inclusive), representing one of three possible values: 0, 1, or 2.

### element

```typescript
element<T>(array: T[]): T;
```

Retrieves a random element from the provided array.

### arrayOf

```typescript
arrayOf<T>(min: number, max: number, value: () => T): T[];
```

Generates an array of random values using the specified value generator function. The `min` parameter determines the minimum length of the array, and the `max` parameter determines the maximum length of the array.

### asyncArrayOf

```typescript
asyncArrayOf<T>(min: number, max: number, value: () => Promise<T>): Promise<T[]>;
```

Generates an array of asynchronously generated random values using the specified promise-based value generator function. The `min` parameter determines the minimum length of the array, and the `max` parameter determines the maximum length of the array.

### coin

```typescript
coin(): boolean;
coin<T>(value: () => T): T | undefined;
coin<T>(value: () => Promise<T>): Promise<T | undefined>;
```

Simulates a coin toss with a 50% probability of returning true for heads and false for tails. The `coin` method can also accept a value generator function as a parameter. If the coin lands on heads, it will return the generated value; otherwise, it will return `undefined`. This method can also handle promise-based value generation.

### outOf

```typescript
outOf(n: number): boolean;
outOf<T>(n: number, value: () => T): T | undefined;
outOf<T>(n: number, value: () => Promise<T>): Promise<T | undefined>;
```

Generates a random number between 1 and the specified number (inclusive) and returns true if it equals 1. The `outOf` method can also accept a value generator function as a parameter. If the generated number equals 1, it will return the generated value; otherwise, it will return `undefined`. This method can also handle promise-based value generation.

## Example

Here's an example of how to use the `@fast.one/random` library:

```typescript
import { Random } from '@fast.one/random';

const randomValue = Random.uint(100); // Generate a random unsigned integer between 0 and 100

const randomElement = Random.element([1, 2, 3, 4, 5]); // Get a random element from the array

const randomArray = Random.arrayOf(5, 10, () => Random.uint()); // Generate an

 array of random unsigned integers

const asyncRandomArray = await Random.asyncArrayOf(5, 10, async () => {
  // Generate asynchronously a random value
  return new Promise<number>((resolve) => {
    setTimeout(() => {
      resolve(Random.uint());
    }, 1000);
  });
});

const coinResult = Random.coin(); // Simulate a coin toss

const coinResultWithValue = Random.coin(() => 'Heads'); // Simulate a coin toss with a specific value

const outOfResult = Random.outOf(10); // Check if a random number is equal to 1

const outOfResultWithValue = Random.outOf(10, () => 'Value'); // Check if a random number is equal to 1 and return a specific value
```

## License

This library is released under the MIT License.