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.

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