draw

Randomly select an element from an array.

Syntax

draw<T>(
  array: T[]
): T | undefined

Parameters

• array (T[]): The array to select from

Return Value

• T | undefined: The randomly selected element, or undefined if the array is empty

Examples

Basic Usage

import { draw } from 'radash'

const fruits = ['apple', 'banana', 'cherry', 'date']
const randomFruit = draw(fruits)
// Might return: 'apple', 'banana', 'cherry', or 'date'

Handling Empty Array

import { draw } from 'radash'

const emptyArray: string[] = []
const result = draw(emptyArray)
// undefined

Handling Single Element Array

import { draw } from 'radash'

const singleElement = ['hello']
const result = draw(singleElement)
// 'hello'

Handling Number Array

import { draw } from 'radash'

const numbers = [1, 2, 3, 4, 5, 6]
const randomNumber = draw(numbers)
// Might return: 1, 2, 3, 4, 5, or 6

Handling Object Array

import { draw } from 'radash'

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

const randomUser = draw(users)
// Might return: { id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }, or { id: 3, name: 'Charlie' }

Handling Mixed Type Array

import { draw } from 'radash'

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

Game Application

import { draw } 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♣'
  ]

  drawCard(): string | undefined {
    return draw(this.deck)
  }
}

const game = new CardGame()
const card = game.drawCard()
// Might return: 'A♠', '2♥', 'K♦', etc.

Random Selector

import { draw } from 'radash'

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

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

  select(): T | undefined {
    return draw(this.items)
  }

  selectMultiple(count: number): T[] {
    const result: T[] = []
    for (let i = 0; i < count && this.items.length > 0; i++) {
      const item = draw(this.items)
      if (item !== undefined) {
        result.push(item)
        // Remove the selected item from the array
        const index = this.items.indexOf(item)
        if (index > -1) {
          this.items.splice(index, 1)
        }
      }
    }
    return result
  }
}

const selector = new RandomSelector(['red', 'green', 'blue', 'yellow'])
const color = selector.select()
// Might return: 'red', 'green', 'blue', or 'yellow'

Random Task Assignment

import { draw } 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 assignRandomTask(): Task | undefined {
  return draw(tasks)
}

const assignedTask = assignRandomTask()
// Might return any task

Random Color Generator

import { draw } from 'radash'

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

function getRandomColor(): string | undefined {
  return draw(colors)
}

const color = getRandomColor()
// Might return any color value

Random Greeting

import { draw } from 'radash'

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

function getRandomGreeting(): string | undefined {
  return draw(greetings)
}

const greeting = getRandomGreeting()
// Might return any greeting

Random Joke

import { draw } 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 | undefined {
  return draw(jokes)
}

const joke = getRandomJoke()
// Might return any joke

Random Password Generator

import { draw } from 'radash'

const letters = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
const numbers = '0123456789'
const symbols = '!@#$%^&*()_+-=[]{}|;:,.<>?'

function generatePassword(length: number): string {
  const allChars = letters + numbers + symbols
  let password = ''
  
  for (let i = 0; i < length; i++) {
    const char = draw(allChars.split(''))
    if (char !== undefined) {
      password += char
    }
  }
  
  return password
}

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

Notes

1. Randomness: Each call might return a different result
2. Empty Array: If the array is empty, it returns undefined
3. No Modification: Does not modify the original array
4. Type Safety: Supports full TypeScript type inference

Differences from Other Functions

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

Performance

• Time Complexity: O(1)
• Space Complexity: O(1)
• Use Cases: Random selection, game logic, randomization