$id

The $id tool provides secure, URL-friendly unique ID generation using the nanoid library. It offers multiple generation strategies including standard nanoids and custom alphabet-based IDs.

Features

• URL-friendly IDs - Safe for use in URLs and filenames
• High collision resistance - 21-symbol default length for UUID v4-level safety
• Custom alphabets - Define your own character sets
• Variable length - Specify exact ID length requirements
• TypeScript overloads - Type-safe parameter combinations

API Reference

$id()

Generate a standard nanoid with default 21-character length.

Returns: string - A 21-character nanoid

import { $id } from "#appkit/tools"

const id = $id()
console.log(id) // → 'Y5G9o8Wn_ZyB0Kxtv3NMu'

$id(type, length?)

Generate a nanoid with custom length.

Parameters:

• type: "nano" - ID generation strategy
• length?: number - Desired length (optional, defaults to 21)

Returns: string - A nanoid of specified length

import { $id } from "#appkit/tools"

// Short ID for UI components
const shortId = $id("nano", 8)
console.log(shortId) // → 'AbCd3fGh'

// Longer ID for extra security
const longId = $id("nano", 32)
console.log(longId) // → 'mX9kP2vN8qR5tY7wE3uI6oA1sD4fG9hJ'

$id(type, alphabet, length)

Generate a custom ID using specific characters.

Parameters:

• type: "custom" - ID generation strategy
• alphabet: string - Characters to use for ID generation
• length: number - Desired ID length

Returns: string - A custom ID using the provided alphabet

import { $id } from "#appkit/tools"

// Numeric only ID
const numericId = $id("custom", "0123456789", 8)
console.log(numericId) // → '47192638'

// Lowercase letters only
const lowercaseId = $id("custom", "abcdefghijklmnopqrstuvwxyz", 10)
console.log(lowercaseId) // → 'xvqpkmnjzr'

// Custom business alphabet
const businessId = $id("custom", "ABCDEFGHKMNPQRSTUVWXYZ23456789", 6)
console.log(businessId) // → 'A3K9MZ'

Usage Examples

Component IDs

import { $id } from "#appkit/tools"

// Generate unique IDs for Vue components
const componentId = $id("nano", 12)

// Use in template
const formId = `form-${$id("nano", 8)}`
const inputId = `input-${$id("nano", 8)}`

Database Keys

import { $id } from "#appkit/tools"

// Generate document IDs
const documentId = $id() // Full 21-character for database
const sessionId = $id("nano", 16) // Shorter for sessions

// Custom format for specific use cases
const orderId = `ORD-${$id("custom", "0123456789ABCDEF", 8)}`
const userId = `user_${$id("nano", 10)}`

File Names

import { $id } from "#appkit/tools"

// Generate safe filenames
const tempFile = `temp_${$id("nano", 12)}.json`
const uploadId = `upload-${$id()}.jpg`

// Using custom alphabet for cleaner filenames
const cleanName = $id("custom", "abcdefghijklmnopqrstuvwxyz0123456789", 8)

Collision Probability

The default 21-character nanoid provides excellent collision resistance:

• 21 chars: ~1 billion years to have 1% probability of collision when generating 1000 IDs per hour
• 16 chars: ~1 year to have 1% probability of collision when generating 1000 IDs per hour
• 8 chars: ~2 hours to have 1% probability of collision when generating 1000 IDs per hour

Choose length based on your collision tolerance and generation frequency.

Alphabet Guidelines

Safe Characters

// URL-safe (default nanoid alphabet)
const urlSafe = "_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"

// Numbers only
const numeric = "0123456789"

// Lowercase letters + numbers
const alphanumeric = "0123456789abcdefghijklmnopqrstuvwxyz"

Avoid Characters

• Similar looking: 0O, 1lI, 2Z
• Special chars that need encoding: &, =, +, /
• Whitespace or control characters

Performance

• nanoid is 2x faster than UUID
• No dependencies on crypto.getRandomValues in browsers
• Optimized for both Node.js and browser environments
• Can generate millions of IDs per second

Integration Examples

With Database Models

import { $id } from "#appkit/tools"

interface User {
    id: string
    name: string
    email: string
}

function createUser(name: string, email: string): User {
    return {
        id: $id(), // 21-char nanoid for primary key
        name,
        email,
    }
}

With Toast Notifications

import { $id } from "#appkit/tools"

function showToast(message: string) {
    const toastId = $id("nano", 8) // Short ID for UI

    // Use with toast system
    return {
        id: toastId,
        message,
        timestamp: Date.now(),
    }
}

With File Upload

import { $id } from "#appkit/tools"

async function uploadFile(file: File) {
    const fileId = $id() // Unique file identifier
    const fileName = `${$id("nano", 8)}_${file.name}` // Prefix original name

    // Upload logic...
    return { fileId, fileName }
}

Best Practices

1. Use default length (21) for primary keys and important identifiers
2. Use shorter lengths (8-12) for temporary or UI-only IDs
3. Use custom alphabets when you need specific character constraints
4. Avoid similar characters in custom alphabets to prevent confusion
5. Document ID format when using custom generation strategies

Related Tools

• $toasts - Uses $id internally for toast management
• nanoid - Underlying library for ID generation
• UUID - Alternative ID generation strategy