shuffle

Randomly shuffle the order of elements in an array.

Syntax

shuffle<T>(array: T[]): T[]

Parameters

• array (T[]): The array to shuffle

Return Value

• T[]: A new array with the elements in shuffled order

Examples

Basic Usage

import { shuffle } from 'radash'

const numbers = [1, 2, 3, 4, 5]
const shuffled = shuffle(numbers)
// Might return: [3, 1, 5, 2, 4]

Handling String Array

import { shuffle } from 'radash'

const fruits = ['apple', 'banana', 'cherry', 'date', 'elderberry']
const shuffledFruits = shuffle(fruits)
// Might return: ['cherry', 'apple', 'elderberry', 'banana', 'date']

Handling Object Array

import { shuffle } from 'radash'

const users = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
  { id: 3, name: 'Charlie' },
  { id: 4, name: 'Diana' }
]

const shuffledUsers = shuffle(users)
// Might return: [
//   { id: 3, name: 'Charlie' },
//   { id: 1, name: 'Alice' },
//   { id: 4, name: 'Diana' },
//   { id: 2, name: 'Bob' }
// ]

Handling Empty Array

import { shuffle } from 'radash'

const emptyArray: number[] = []
const shuffled = shuffle(emptyArray)
// []

Handling Single Element Array

import { shuffle } from 'radash'

const singleElement = ['hello']
const shuffled = shuffle(singleElement)
// ['hello'] (order unchanged)

Handling Mixed Type Array

import { shuffle } from 'radash'

const mixed = ['hello', 42, true, { key: 'value' }]
const shuffled = shuffle(mixed)
// Might return: [42, { key: 'value' }, 'hello', true]

Game Application

import { shuffle } from 'radash'

class CardGame {
  private deck = [
    'A♠', '2♠', '3♠', '4♠', '5♠', '6♠', '7♠', '8♠', '9♠', '10♠', 'J♠', 'Q♠', 'K♠',
    'A♥', '2♥', '3♥', '4♥', '5♥', '6♥', '7♥', '8♥', '9♥', '10♥', 'J♥', 'Q♥', 'K♥',
    'A♦', '2♦', '3♦', '4♦', '5♦', '6♦', '7♦', '8♦', '9♦', '10♦', 'J♦', 'Q♦', 'K♦',
    'A♣', '2♣', '3♣', '4♣', '5♣', '6♣', '7♣', '8♣', '9♣', '10♣', 'J♣', 'Q♣', 'K♣'
  ]

  shuffleDeck() {
    this.deck = shuffle(this.deck)
  }

  dealCards(count: number) {
    return this.deck.slice(0, count)
  }
}

const game = new CardGame()
game.shuffleDeck()
const hand = game.dealCards(5)
// Returns 5 random cards

Random Selector

import { shuffle } from 'radash'

class RandomSelector<T> {
  private items: T[]

  constructor(items: T[]) {
    this.items = [...items]
  }

  shuffle() {
    this.items = shuffle(this.items)
  }

  select(count: number): T[] {
    return this.items.slice(0, count)
  }

  selectAll(): T[] {
    return shuffle(this.items)
  }
}

const selector = new RandomSelector(['red', 'green', 'blue', 'yellow', 'purple'])
const colors = selector.select(3)
// Returns 3 random colors

Random Task Assignment

import { shuffle } from 'radash'

interface Task {
  id: number
  name: string
  priority: 'low' | 'medium' | 'high'
}

const tasks: Task[] = [
  { id: 1, name: 'Write documentation', priority: 'high' },
  { id: 2, name: 'Fix bug', priority: 'high' },
  { id: 3, name: 'Add tests', priority: 'medium' },
  { id: 4, name: 'Refactor code', priority: 'medium' },
  { id: 5, name: 'Update dependencies', priority: 'low' }
]

function assignRandomTasks(taskCount: number): Task[] {
  const shuffledTasks = shuffle(tasks)
  return shuffledTasks.slice(0, taskCount)
}

const assignedTasks = assignRandomTasks(3)
// Returns 3 random tasks

Random Color Generator

import { shuffle } from 'radash'

const colors = [
  '#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4', '#FFEAA7',
  '#DDA0DD', '#98D8C8', '#F7DC6F', '#BB8FCE', '#85C1E9'
]

function getRandomColors(count: number): string[] {
  return shuffle(colors).slice(0, count)
}

const randomColors = getRandomColors(5)
// Returns 5 random colors

Random Greeting

import { shuffle } from 'radash'

const greetings = [
  'Hello!',
  'Hi there!',
  'Good morning!',
  'Good afternoon!',
  'Good evening!',
  'Hey!',
  'Greetings!',
  'Welcome!'
]

function getRandomGreeting(): string {
  return shuffle(greetings)[0]
}

const greeting = getRandomGreeting()
// Returns a random greeting

Random Joke

import { shuffle } from 'radash'

const jokes = [
  "Why don't scientists trust atoms? Because they make up everything!",
  'Why did the scarecrow win an award? Because he was outstanding in his field!',
  "Why don't eggs tell jokes? They'd crack each other up!",
  'What do you call a fake noodle? An impasta!',
  'Why did the math book look so sad? Because it had too many problems!'
]

function getRandomJoke(): string {
  return shuffle(jokes)[0]
}

const joke = getRandomJoke()
// Returns a random joke

Random Password Generator

import { shuffle } from 'radash'

function generatePassword(length: number): string {
  const letters = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
  const numbers = '0123456789'
  const symbols = '!@#$%^&*()_+-=[]{}|;:,.<>?'
  
  const allChars = letters + numbers + symbols
  const shuffledChars = shuffle(allChars.split(''))
  
  return shuffledChars.slice(0, length).join('')
}

const password = generatePassword(8)
// Generates an 8-character random password

Random Test Data

import { shuffle } from 'radash'

const testData = [
  { id: 1, value: 'test1' },
  { id: 2, value: 'test2' },
  { id: 3, value: 'test3' },
  { id: 4, value: 'test4' },
  { id: 5, value: 'test5' }
]

function getRandomTestData(count: number) {
  return shuffle(testData).slice(0, count)
}

const randomData = getRandomTestData(3)
// Returns 3 random test data

Random Sorting

import { shuffle } from 'radash'

const students = [
  { name: 'Alice', grade: 85 },
  { name: 'Bob', grade: 92 },
  { name: 'Charlie', grade: 78 },
  { name: 'Diana', grade: 95 },
  { name: 'Eve', grade: 88 }
]

function randomizePresentationOrder() {
  return shuffle(students)
}

const presentationOrder = randomizePresentationOrder()
// Returns a randomly sorted list of students

Notes

1. Immutability: Does not modify the original array
2. Randomness: Each call might return a different result
3. Performance: Uses the Fisher-Yates shuffle algorithm
4. Type Safety: Supports full TypeScript type inference

Differences from Other Functions

• shuffle: Randomly shuffles the array order
• draw: Randomly selects a single element
• random: Generates random numbers
• sample: Randomly selects multiple elements

Performance

• Time Complexity: O(n), where n is the array length
• Space Complexity: O(n)
• Use Cases: Games, randomization, test data generation