npm package: @if25b206/shuffle-array
Description: A small library that takes an array as input and returns a new array that is shuffled.
Author: if25b206
Latest version: 0.2.0

# @if25b206/shuffle-array

> A small library that takes an array as input and returns a new shuffled array. Supports both standard (`Math.random`) and cryptographically secure (`crypto.randomInt`) shuffling.

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
  - [Standard Shuffle](#standard-shuffle)
  - [Cryptographic Shuffle](#cryptographic-shuffle)
  - [Examples](#examples)
- [API](#api)
- [Contribution](#contribution)
- [Security](#security)
- [License](#license)

## Installation

Install via npm:

```bash
npm install @if25b206/shuffle-array
```

Install via yarn:

```bash
yarn add @if25b206/shuffle-array
```

## Usage

### Standard Shuffle

Uses `Math.random()` — fast, suitable for non-security-critical use cases.

```js
import shuffleArray from '@if25b206/shuffle-array';

const startArray = [1, 2, 3, 4, 5];
const newShuffledArray = shuffleArray(startArray);

console.log(startArray);       // [1, 2, 3, 4, 5] (unchanged)
console.log(newShuffledArray); // e.g., [3, 1, 5, 2, 4]
```

### Cryptographic Shuffle

Uses Node.js `crypto.randomInt()` — cryptographically secure, suitable for security-sensitive shuffling such as key generation, token ordering, or lottery systems.

```js
import { cryptoShuffleArray } from '@if25b206/shuffle-array';

const startArray = [1, 2, 3, 4, 5];
const secureShuffled = cryptoShuffleArray(startArray);

console.log(startArray);      // [1, 2, 3, 4, 5] (unchanged)
console.log(secureShuffled);  // e.g., [4, 2, 1, 5, 3]
```

### Examples

Shuffle a list of user IDs:

```js
import shuffleArray from '@if25b206/shuffle-array';

const userIds = ['u1', 'u2', 'u3', 'u4'];
const randomizedOrderOfUserIds = shuffleArray(userIds);

console.log(randomizedOrderOfUserIds); // e.g., ['u1', 'u3', 'u4', 'u2']
```

Securely shuffle a deck of cards:

```js
import { cryptoShuffleArray } from '@if25b206/shuffle-array';

const deck = ['Ace of Spades', 'Two of Hearts', 'Three of Clubs'];
const shuffledDeck = cryptoShuffleArray(deck);

console.log(shuffledDeck); // e.g., ['Two of Hearts', 'Ace of Spades', 'Three of Clubs']
```

## API

### `shuffleArray(array)` _(default export)_

| Parameter | Type    | Description             |
|-----------|---------|-------------------------|
| `array`   | `Array` | The array to shuffle    |

Returns a new shuffled array. Does not mutate the input. Uses `Math.random()`.

---

### `cryptoShuffleArray(array)` _(named export)_

| Parameter | Type    | Description             |
|-----------|---------|-------------------------|
| `array`   | `Array` | The array to shuffle    |

Returns a new shuffled array. Does not mutate the input. Uses `crypto.randomInt()` for cryptographically secure randomness. **Node.js only.**

## Contribution

Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for more details.

## Security

Please refer to our [SECURITY.md](./SECURITY.md) for information about our security policies, how to report vulnerabilities, and our approach to handling security concerns.

**Note on randomness:**
- `shuffleArray` uses `Math.random()` — **not** cryptographically secure. Do not use for security-critical purposes.
- `cryptoShuffleArray` uses `crypto.randomInt()` — cryptographically secure and suitable for security-sensitive applications.

## License

This project is licensed under the [MIT License](./LICENSE.md).