0
# lodash.shuffle
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: lodash.shuffle
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install lodash.shuffle`
10

11
## Core Imports
12

13
```javascript
14
const shuffle = require('lodash.shuffle');
15
```
16

17
For ES modules:
18

19
```javascript
20
import shuffle from 'lodash.shuffle';
21
```
22

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

25
## Basic Usage
26

27
```javascript
28
const shuffle = require('lodash.shuffle');
29

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

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

40
// Shuffle string characters
41
const text = "hello";
42
const shuffledChars = shuffle(text);
43
console.log(shuffledChars); // ['e', 'l', 'o', 'h', 'l'] (random order)
44
```
45

46
## Capabilities
47

48
### Array Shuffling
49

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

52
```javascript { .api }
53
/**
54
 * Creates an array of shuffled values, using a version of the Fisher-Yates shuffle
55
 * @param {Array|Object|string} collection - The collection to shuffle
56
 * @returns {Array} Returns the new shuffled array
57
 */
58
function shuffle(collection);
59
```
60

61
**Parameters:**
62
- `collection` *(Array|Object|string)*: The collection to shuffle
63
  - **Arrays**: Elements are shuffled randomly
64
  - **Objects**: Object values (not keys) are shuffled into an array
65
  - **Strings**: Characters are shuffled into an array
66
  - **Array-like objects**: Converted to array and shuffled
67
  - **Numbers**: Treated as empty, returns `[]`
68
  - **null/undefined**: Returns `[]`
69

70
**Returns:**
71
- *(Array)*: Returns the new shuffled array containing the same elements in random order
72

73
**Algorithm:**
74
- Uses Fisher-Yates shuffle algorithm for uniform randomization
75
- Time complexity: O(n)
76
- Space complexity: O(n) (creates new array, doesn't mutate input)
77
- Cryptographic security depends on `Math.random()` implementation
78

79
**Behavior:**
80
- Always returns a new array (never mutates the input collection)  
81
- For objects, returns array of values only (keys are not included)
82
- Empty collections return empty arrays
83
- Single-element collections return arrays with that single element
84
- All original elements are preserved, only order changes
85

86
**Usage Examples:**
87

88
```javascript
89
// Array shuffling
90
const deck = ['♠A', '♠K', '♠Q', '♠J'];
91
const shuffledDeck = shuffle(deck);
92
console.log(deck);         // ['♠A', '♠K', '♠Q', '♠J'] (original unchanged)
93
console.log(shuffledDeck); // ['♠Q', '♠A', '♠J', '♠K'] (random order)
94

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

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

105
// Edge cases
106
shuffle([]);        // []
107
shuffle({});       // []
108
shuffle(42);       // []
109
shuffle(null);     // []
110
shuffle([1]);      // [1] (single element)
111
```