@santi100/array-shuffle

Santi's Array Shuffling Library

• 🚀 Lightweight and fast^
• 👴 ES3-compliant*
• 💻 Portable between the browser and Node.js

What's this?

This library exports a function that shuffles the values in any array. It is implemented using the Fisher-Yates shuffle algorithm to shuffle the array elements.

Installation

• Via NPM: npm install @santi100/array-shuffle
• Via Yarn: yarn add @santi100/array-shuffle
• Via PNPM: pnpm install @santi100/array-shuffle

API

• function shuffle<T = unknown>(array: T[]): T[];

  Name	Type	Description	Optional?	Default
  array	T[]	The array to be shuffled.	No	N/A

  Returns the shuffled array.

• function shuffle<T = unknown>(array: T[], opts: { inPlace: boolean; }): T[];

  Name	Type	Description	Optional?	Default
  array	T[]	The array to be shuffled.	No	N/A
  opts	object	Optional parameters for shuffling.	Yes	{ inPlace: false }
  opts.inPlace	boolean	If true, shuffles the array in place.	Yes	false

  Returns the shuffled array.

Usage

// Import the shuffle function
const shuffle = require('@santi100/array-shuffle'); // CJS
import shuffle from '@santi100/array-shuffle'; // ESM
import shuffle = require('@santi100/array-shuffle'); // TypeScript

// Create an array of numbers
const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

// Shuffle the array and get a new shuffled array
const shuffledArray = shuffle(numbers);

console.log('Shuffled Array:', shuffledArray);

// Shuffle the array in-place
const originalArray = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
shuffle(originalArray, { inPlace: true });

console.log('Original Array (Shuffled In-Place):', originalArray);

Contribute

Wanna contribute? File an issue or pull request! Look at the contribution instructions and make sure you follow the contribution Code of Conduct.

**Hasn't been tested in an actual ES3 environment. Feel free to open an issue or pull request if you find any non-ES3 thing. See "Contribute" for instructions on how to do so.*

^The source code is just a few kilobytes in size.