@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
• Usage
  • Standard Shuffle
  • Cryptographic Shuffle
  • Examples
• API
• Contribution
• Security
• License

Installation

Install via npm:

npm install @if25b206/shuffle-array

Install via yarn:

yarn add @if25b206/shuffle-array

Usage

Standard Shuffle

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

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.

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:

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:

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 for more details.

Security

Please refer to our 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.