Skip to content

draw ​

Randomly select an element from an array.

Syntax ​

typescript
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 ​

typescript
import { draw } from 'radash'

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

Handling Empty Array ​

typescript
import { draw } from 'radash'

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

Handling Single Element Array ​

typescript
import { draw } from 'radash'

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

Handling Number Array ​

typescript
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 ​

typescript
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 ​

typescript
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 ​

typescript
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 ​

typescript
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 ​

typescript
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 ​

typescript
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 ​

typescript
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 ​

typescript
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 ​

typescript
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

Released under the MIT License.