Quick Start

Generate your first ID with uniku in under 5 minutes.

This guide will walk you through generating your first ID, validating it, and converting it to bytes. We’ll use UUID v7 as it’s the most common use case for database primary keys.

1. Import the generator

   Import the uuidv7 function from the dedicated entry point:

   import { uuidv7 } from 'uniku/uuid/v7'
   

   Each ID format has its own entry point (e.g., uniku/uuid/v4, uniku/ulid, uniku/nanoid). This ensures optimal tree-shaking.

2. Generate your first ID

   Call the function to generate a UUID v7 string:

   const id = uuidv7()
   console.log(id)
   // => "018e5e5c-7c8a-7000-8000-000000000000"
   

   UUID v7 IDs are time-ordered and lexicographically sortable:

   const ids = [uuidv7(), uuidv7(), uuidv7()]
   console.log(ids[0] < ids[1] && ids[1] < ids[2]) // true
   

   Time-ordered IDs are ideal for database indexes because they maintain insertion order, reducing index fragmentation.

3. Validate an ID

   Use the isValid() method to check if a string is a valid UUID v7:

   const id = uuidv7()
   
   if (uuidv7.isValid(id)) {
     console.log('Valid UUID v7!')
   }
   
   // TypeScript type guard
   const maybeId: unknown = getUserInput()
   if (uuidv7.isValid(maybeId)) {
     // TypeScript now knows maybeId is a string
     console.log(maybeId.toUpperCase())
   }
   

   The isValid() method is a TypeScript type guard, which means it narrows the type from unknown to string.

4. Convert to bytes

   Convert the ID string to a Uint8Array for binary storage:

   const id = uuidv7()
   // => "018e5e5c-7c8a-7000-8000-000000000000"
   
   const bytes = uuidv7.toBytes(id)
   console.log(bytes)
   // => Uint8Array(16) [1, 142, 94, 92, 124, 138, 112, 0, ...]
   
   console.log(bytes.length)
   // => 16
   

   UUIDs are always 16 bytes (128 bits). Storing them as bytes instead of strings saves 20 bytes per ID in your database.

5. Convert from bytes

   Convert a Uint8Array back to a UUID string:

   const bytes = new Uint8Array([
     1, 142, 94, 92, 124, 138, 112, 0,
     128, 0, 0, 0, 0, 0, 0, 0
   ])
   
   const id = uuidv7.fromBytes(bytes)
   console.log(id)
   // => "018e5e5c-7c8a-7000-8000-000000000000"
   

   This is useful when reading binary-encoded IDs from a database.

6. Extract timestamp (optional)

   UUID v7 embeds a timestamp. Extract it with the timestamp() method:

   const id = uuidv7()
   const timestamp = uuidv7.timestamp(id)
   
   console.log(new Date(timestamp))
   // => 2024-03-15T10:30:45.123Z
   
   console.log(timestamp)
   // => 1710500445123 (milliseconds since Unix epoch)
   

   This is useful for debugging or auditing when an ID was created without storing a separate timestamp column.

Complete Example

Here’s a complete example combining everything:

import { uuidv7 } from 'uniku/uuid/v7'

// Generate an ID
const id = uuidv7()
console.log('Generated ID:', id)

// Validate
if (uuidv7.isValid(id)) {
  console.log('✓ Valid UUID v7')
}

// Extract timestamp
const createdAt = new Date(uuidv7.timestamp(id))
console.log('Created at:', createdAt.toISOString())

// Convert to bytes for storage
const bytes = uuidv7.toBytes(id)
console.log('Bytes:', bytes)
console.log('Size:', bytes.length, 'bytes')

// Convert back to string
const restored = uuidv7.fromBytes(bytes)
console.log('Restored ID:', restored)
console.log('Match:', id === restored) // true

Database Integration

Here’s how to use uniku with a database:

import { uuidv7 } from 'uniku/uuid/v7'

// PostgreSQL example with binary storage
const id = uuidv7()
const bytes = uuidv7.toBytes(id)

await db.execute(
  'INSERT INTO users (id, name) VALUES ($1, $2)',
  [bytes, 'Alice']
)

// Retrieve and convert back
const result = await db.query('SELECT id FROM users WHERE name = $1', ['Alice'])
const retrievedId = uuidv7.fromBytes(result.rows[0].id)
console.log(retrievedId) // Same as original ID

When storing UUIDs as binary in PostgreSQL, use the BYTEA type, not the UUID type. The UUID type expects hyphenated strings.

Advanced Usage

Custom Timestamp

For testing or specific use cases, provide a custom timestamp:

import { uuidv7 } from 'uniku/uuid/v7'

const id = uuidv7({
  msecs: 1710500445123, // March 15, 2024
  seq: 0
})

Write to Buffer

Write UUID bytes directly to an existing buffer:

import { uuidv7 } from 'uniku/uuid/v7'

const buffer = new Uint8Array(32)
uuidv7(undefined, buffer, 8) // Write 16 bytes starting at offset 8

console.log(buffer.subarray(8, 24)) // UUID bytes

Nil and Max Constants

Access special UUID constants:

import { uuidv7 } from 'uniku/uuid/v7'

console.log(uuidv7.NIL)
// => "00000000-0000-0000-0000-000000000000"

console.log(uuidv7.MAX)
// => "ffffffff-ffff-ffff-ffff-ffffffffffff"

Try Other ID Formats

Now that you know the basics, try other ID formats:

UUID v4 (Random)

import { uuidv4 } from 'uniku/uuid/v4'

const id = uuidv4()
// => "550e8400-e29b-41d4-a716-446655440000"

Next Steps

API Reference

Explore the complete API for all ID formats

Migration Guide

Migrate from uuid, nanoid, ulid, or other libraries

Choosing an ID

Learn how to choose the right ID format

CLI Tool

Generate and validate IDs from the command line