lodash.shuffle

The lodash method _.shuffle exported as a module for randomizing array elements using the Fisher-Yates shuffle algorithm. This modular package provides efficient random shuffling of collections with uniform distribution of all possible permutations.

Package Information

• Package Name: lodash.shuffle
• Package Type: npm
• Language: JavaScript
• Installation: npm install lodash.shuffle

Core Imports

const shuffle = require('lodash.shuffle');

For ES modules:

import shuffle from 'lodash.shuffle';

Note: This is the modular lodash package - install lodash.shuffle specifically, not the full lodash library.

Basic Usage

const shuffle = require('lodash.shuffle');

// Shuffle an array
const numbers = [1, 2, 3, 4, 5];
const shuffled = shuffle(numbers);
console.log(shuffled); // [3, 1, 5, 2, 4] (random order)

// Shuffle object values
const obj = { a: 1, b: 2, c: 3 };
const shuffledValues = shuffle(obj);
console.log(shuffledValues); // [2, 3, 1] (random order of values)

// Shuffle string characters
const text = "hello";
const shuffledChars = shuffle(text);
console.log(shuffledChars); // ['e', 'l', 'o', 'h', 'l'] (random order)

Capabilities

Array Shuffling

Creates an array of shuffled values using a version of the Fisher-Yates shuffle algorithm, ensuring uniform distribution of all possible permutations.

/**
 * Creates an array of shuffled values, using a version of the Fisher-Yates shuffle
 * @param {Array|Object|string} collection - The collection to shuffle
 * @returns {Array} Returns the new shuffled array
 */
function shuffle(collection);

Parameters:

• collection (Array|Object|string): The collection to shuffle
  • Arrays: Elements are shuffled randomly
  • Objects: Object values (not keys) are shuffled into an array
  • Strings: Characters are shuffled into an array
  • Array-like objects: Converted to array and shuffled
  • Numbers: Treated as empty, returns []
  • null/undefined: Returns []

Returns:

• (Array): Returns the new shuffled array containing the same elements in random order

Algorithm:

• Uses Fisher-Yates shuffle algorithm for uniform randomization
• Time complexity: O(n)
• Space complexity: O(n) (creates new array, doesn't mutate input)
• Cryptographic security depends on Math.random() implementation

Behavior:

• Always returns a new array (never mutates the input collection)
• For objects, returns array of values only (keys are not included)
• Empty collections return empty arrays
• Single-element collections return arrays with that single element
• All original elements are preserved, only order changes

Usage Examples:

// Array shuffling
const deck = ['♠A', '♠K', '♠Q', '♠J'];
const shuffledDeck = shuffle(deck);
console.log(deck);         // ['♠A', '♠K', '♠Q', '♠J'] (original unchanged)
console.log(shuffledDeck); // ['♠Q', '♠A', '♠J', '♠K'] (random order)

// Object value shuffling
const colors = { primary: 'red', secondary: 'blue', accent: 'green' };
const shuffledColors = shuffle(colors);
console.log(shuffledColors); // ['blue', 'green', 'red'] (values only, random order)

// String character shuffling
const word = "shuffle";
const shuffledLetters = shuffle(word);
console.log(shuffledLetters); // ['u', 's', 'l', 'f', 'e', 'h', 'f'] (characters in random order)

// Edge cases
shuffle([]);        // []
shuffle({});       // []
shuffle(42);       // []
shuffle(null);     // []
shuffle([1]);      // [1] (single element)