Utility Functions

1import { type ClassValue, clsx } from "clsx"
2import { twMerge } from "tailwind-merge"
3
4export function cn(...inputs: ClassValue[]) {
5  return twMerge(clsx(inputs))
6}

1/**
2 * Formats a Date object into a readable string.
3 * @param date The Date object to format.
4 * @param options Optional Intl.DateTimeFormatOptions for customization.
5 * @returns The formatted date string.
6 */
7export function formatDate(date: Date, options?: Intl.DateTimeFormatOptions): string {
8  const defaultOptions: Intl.DateTimeFormatOptions = {
9    year: "numeric",
10    month: "long",
11    day: "numeric",
12  }
13  return new Intl.DateTimeFormat("en-US", options || defaultOptions).format(date)
14}

1/**
2 * Capitalizes the first letter of a string.
3 * @param str The input string.
4 * @returns The string with its first letter capitalized.
5 */
6export function capitalize(str: string): string {
7  if (!str) return ""
8  return str.charAt(0).toUpperCase() + str.slice(1)
9}

1/**
2 * Truncates a string to a specified length, adding an ellipsis if truncated.
3 * @param str The input string.
4 * @param maxLength The maximum length of the string before truncation.
5 * @returns The truncated string.
6 */
7export function truncateString(str: string, maxLength: number): string {
8  if (str.length <= maxLength) {
9    return str
10  }
11  return str.slice(0, maxLength) + "..."
12}

1/**
2 * Creates a debounced function that delays invoking `func` until after `wait` milliseconds
3 * have passed since the last time the debounced function was invoked.
4 * @param func The function to debounce.
5 * @param wait The number of milliseconds to delay.
6 * @returns The new debounced function.
7 */
8export function debounce<T extends (...args: any[]) => void>(func: T, wait: number): (...args: Parameters<T>) => void {
9  let timeout: NodeJS.Timeout | null = null
10
11  return function (this: ThisParameterType<T>, ...args: Parameters<T>) {
12    const context = this
13    const later = () => {
14      timeout = null
15      func.apply(context, args)
16    }
17    if (timeout) {
18      clearTimeout(timeout)
19    }
20    timeout = setTimeout(later, wait)
21  }
22}

1/**
2 * Creates a throttled function that only invokes `func` at most once per `wait` milliseconds.
3 * @param func The function to throttle.
4 * @param wait The number of milliseconds to throttle invocations to.
5 * @returns The new throttled function.
6 */
7export function throttle<T extends (...args: any[]) => void>(func: T, wait: number): (...args: Parameters<T>) => void {
8  let inThrottle: boolean
9  let lastFn: NodeJS.Timeout | null
10  let lastTime: number
11
12  return function (this: ThisParameterType<T>, ...args: Parameters<T>) {
13    const context = this
14    if (!inThrottle) {
15      func.apply(context, args)
16      lastTime = Date.now()
17      inThrottle = true
18    } else {
19      if (lastFn) {
20        clearTimeout(lastFn)
21      }
22      lastFn = setTimeout(
23        function () {
24          if (Date.now() - lastTime >= wait) {
25            func.apply(context, args)
26            lastTime = Date.now()
27          }
28        },
29        Math.max(wait - (Date.now() - lastTime), 0),
30      )
31    }
32  }
33}

1/**
2 * Checks if a string is a valid email address using a simple regex.
3 * @param email The email string to validate.
4 * @returns True if the email is valid, false otherwise.
5 */
6export function isValidEmail(email: string): boolean {
7  const emailRegex = /^[^s@]+@[^s@]+.[^s@]+$/
8  return emailRegex.test(email)
9}

1/**
2 * Generates a simple unique ID string.
3 * @param prefix An optional prefix for the ID.
4 * @returns A unique ID string.
5 */
6export function generateRandomId(prefix: string = "id_"): string {
7  return prefix + Math.random().toString(36).substring(2, 9)
8}

1/**
2 * Clamps a number between an upper and lower bound.
3 * @param num The number to clamp.
4 * @param min The lower bound.
5 * @param max The upper bound.
6 * @returns The clamped number.
7 */
8export function clamp(num: number, min: number, max: number): number {
9  return Math.min(Math.max(num, min), max)
10}

1/**
2 * Converts a hexadecimal color string to an RGBA color string.
3 * @param hex The hexadecimal color string (e.g., "#RRGGBB" or "#RGB").
4 * @param alpha The alpha transparency value (0-1).
5 * @returns The RGBA color string (e.g., "rgba(255, 0, 0, 0.5)").
6 */
7export function hexToRgba(hex: string, alpha: number = 1): string | null {
8  let r = 0,
9    g = 0,
10    b = 0
11  // Handle #RGB format
12  if (hex.length === 4) {
13    r = parseInt(hex[1] + hex[1], 16)
14    g = parseInt(hex[2] + hex[2], 16)
15    b = parseInt(hex[3] + hex[3], 16)
16  }
17  // Handle #RRGGBB format
18  else if (hex.length === 7) {
19    r = parseInt(hex.substring(1, 3), 16)
20    g = parseInt(hex.substring(3, 5), 16)
21    b = parseInt(hex.substring(5, 7), 16)
22  } else {
23    return null // Invalid hex format
24  }
25  return `rgba(${r}, ${g}, ${b}, ${alpha})`
26}

1/**
2 * Returns a random item from an array.
3 * @param arr The input array.
4 * @returns A random item from the array, or undefined if the array is empty.
5 */
6export function getRandomItem<T>(arr: T[]): T | undefined {
7  if (arr.length === 0) {
8    return undefined
9  }
10  const randomIndex = Math.floor(Math.random() * arr.length)
11  return arr[randomIndex]
12}