@temelj/id

Generate and validate globally unique identifiers including UUID v4 and ULID (Universally Unique Lexicographically Sortable Identifier).

Installation

npm install @temelj/id

UUID v4

Generate and work with UUID version 4 identifiers.

generateUuid4

Generates a new UUID v4 string.

function generateUuid4(): string

import { generateUuid4 } from "@temelj/id";

const id = generateUuid4();
// "a3bb189e-8bf9-3888-9912-ace4e6543002"

isUuid4Valid

Checks if a string is a valid UUID v4.

function isUuid4Valid(id: string): boolean

import { isUuid4Valid } from "@temelj/id";

isUuid4Valid("a3bb189e-8bf9-3888-9912-ace4e6543002"); // true
isUuid4Valid("not-a-uuid");                          // false
isUuid4Valid("");                                    // false

getUuid4Bytes

Returns the byte array representation of a UUID v4 string.

function getUuid4Bytes(id: string): Uint8Array

import { getUuid4Bytes } from "@temelj/id";

const id = "a3bb189e-8bf9-3888-9912-ace4e6543002";
const bytes = getUuid4Bytes(id);
// Uint8Array(16) [163, 177, 24, 158, ...]

makeUuid4FromBytes

Constructs a UUID v4 string from a byte array.

function makeUuid4FromBytes(bytes: Uint8Array): string

import { makeUuid4FromBytes, getUuid4Bytes } from "@temelj/id";

const original = "a3bb189e-8bf9-3888-9912-ace4e6543002";
const bytes = getUuid4Bytes(original);
const reconstructed = makeUuid4FromBytes(bytes);
// "a3bb189e-8bf9-3888-9912-ace4e6543002"

UUID constants

const UUID4_MIN: string      // "00000000-0000-4000-8000-000000000000"
const UUID4_MAX: string      // "ffffffff-ffff-4fff-bfff-ffffffffffff"
const UUID4_LENGTH: number   // 36

import { UUID4_MIN, UUID4_MAX, UUID4_LENGTH } from "@temelj/id";

console.log(UUID4_LENGTH); // 36

ULID

ULID (Universally Unique Lexicographically Sortable Identifier) combines the benefits of UUIDs with lexicographical sorting.

ULIDs are 26 characters long and encode a timestamp, making them naturally sortable by creation time.

generateUlid

Generates a new ULID string.

function generateUlid(options?: UlidOptions): string

import { generateUlid } from "@temelj/id";

const id = generateUlid();
// "01ARZ3NDEKTSV4RRFFQ69G5FAV"
console.log(id.length); // 26

import { generateUlid } from "@temelj/id";

const id = generateUlid({
  time: new Date('2024-01-01T00:00:00Z')
});
// ULID with specific timestamp

import { generateUlid } from "@temelj/id";

const id = generateUlid({
  time: new Date(42),
  random: Uint8Array.from([
    0x00, 0x01, 0x02, 0x03, 0x04,
    0x05, 0x06, 0x07, 0x08, 0x09
  ])
});
// "005800001A000G40R40M30E209"

generateUlidList

Generates multiple ULIDs in a monotonically increasing sequence.

function generateUlidList(count: number, options?: UlidOptions): string[]

import { generateUlidList } from "@temelj/id";

const ids = generateUlidList(5);
// [
//   "01ARZ3NDEKTSV4RRFFQ69G5FAV",
//   "01ARZ3NDEKTSV4RRFFQ69G5FAW",
//   "01ARZ3NDEKTSV4RRFFQ69G5FAX",
//   "01ARZ3NDEKTSV4RRFFQ69G5FAY",
//   "01ARZ3NDEKTSV4RRFFQ69G5FAZ"
// ]

When generating ULIDs within the same millisecond, the random component is incremented to ensure strict monotonicity. If more than 2^80 ULIDs are generated within the same millisecond, generation will fail.

isUlidValid

Checks if a string is a valid ULID.

function isUlidValid(id: string): boolean

import { isUlidValid, generateUlid } from "@temelj/id";

const id = generateUlid();
isUlidValid(id);              // true
isUlidValid("not-a-ulid");    // false
isUlidValid("");              // false
isUlidValid("1234567890");    // false

getUlidBytes

Returns the byte array representation of a ULID string.

function getUlidBytes(id: string): Uint8Array

import { getUlidBytes } from "@temelj/id";

const id = "01BXZ26W400000000000000000";
const bytes = getUlidBytes(id);
// Uint8Array(16) [...]
console.log(bytes.length); // 16

makeUlidFromBytes

Constructs a ULID string from a byte array.

function makeUlidFromBytes(bytes: Uint8Array): string

import { makeUlidFromBytes, getUlidBytes } from "@temelj/id";

const original = "01BXZ26W400000000000000000";
const bytes = getUlidBytes(original);
const reconstructed = makeUlidFromBytes(bytes);
// "01BXZ26W400000000000000000"

Types

UlidOptions

Options for generating ULIDs.

interface UlidOptions {
  /**
   * The time to use for generating the ULID.
   */
  time?: Date;
  /**
   * The random bytes to use for generating the ULID.
   * Must be exactly 10 bytes.
   */
  random?: Uint8Array;
}

Comparison: UUID vs ULID

Features
When to use UUID v4
When to use ULID

Feature	UUID v4	ULID
Length	36 chars (with hyphens)	26 chars
Sortable	No	Yes (by timestamp)
Timestamp	No	Yes (millisecond precision)
Randomness	122 bits	80 bits
Case-sensitive	No (hex)	Yes (base32)

Use UUID v4 when:

You need maximum randomness (122 bits)
You’re working with systems that expect standard UUIDs
Sorting by creation time is not important
Case-insensitive identifiers are preferred

import { generateUuid4 } from "@temelj/id";

// User IDs that don't need ordering
const userId = generateUuid4();

// Primary keys in relational databases
const recordId = generateUuid4();

Use ULID when:

You need lexicographically sortable IDs
Timestamp information is valuable
Shorter string representation is preferred
You want to maintain insertion order

import { generateUlid } from "@temelj/id";

// Event IDs that should be sortable by time
const eventId = generateUlid();

// Log entries
const logId = generateUlid();

// Time-series data
const dataPointId = generateUlid();

Examples

Database records
Ordered events
Batch generation
Validation

import { generateUuid4 } from "@temelj/id";

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

function createUser(name: string, email: string): User {
  return {
    id: generateUuid4(),
    name,
    email
  };
}

const user = createUser("John Doe", "john@example.com");
// {
//   id: "a3bb189e-8bf9-3888-9912-ace4e6543002",
//   name: "John Doe",
//   email: "john@example.com"
// }

import { generateUlid } from "@temelj/id";

interface Event {
  id: string;
  type: string;
  timestamp: Date;
  data: any;
}

function createEvent(type: string, data: any): Event {
  const now = new Date();
  return {
    id: generateUlid({ time: now }),
    type,
    timestamp: now,
    data
  };
}

const events = [
  createEvent('user.login', { userId: '123' }),
  createEvent('user.logout', { userId: '123' })
];

// Events are naturally sorted by their ID
events.sort((a, b) => a.id.localeCompare(b.id));

import { generateUlidList } from "@temelj/id";

// Generate multiple IDs efficiently
const orderIds = generateUlidList(100);

// All IDs are monotonically increasing
console.log(orderIds[0] < orderIds[1]);   // true
console.log(orderIds[98] < orderIds[99]); // true

// Use for bulk insert operations
const orders = orderIds.map((id, index) => ({
  id,
  orderNumber: index + 1,
  status: 'pending'
}));

import { isUuid4Valid, isUlidValid } from "@temelj/id";

function validateId(id: string, type: 'uuid' | 'ulid'): boolean {
  if (type === 'uuid') {
    return isUuid4Valid(id);
  }
  return isUlidValid(id);
}

// API route handler
function getUserById(id: string) {
  if (!isUuid4Valid(id)) {
    throw new Error('Invalid user ID format');
  }
  // Fetch user...
}

For new projects, consider using ULIDs for primary keys if you benefit from time-based sorting. For compatibility with existing systems or maximum randomness, use UUID v4.

Getting Started

Core Packages

Data & Utilities

Web & Templating

Guides

Installation

UUID v4

generateUuid4

isUuid4Valid

getUuid4Bytes

makeUuid4FromBytes

UUID constants

ULID

generateUlid

generateUlidList

isUlidValid

getUlidBytes

makeUlidFromBytes

Types

UlidOptions

Comparison: UUID vs ULID

Examples

​Installation

​UUID v4

​generateUuid4

​isUuid4Valid

​getUuid4Bytes

​makeUuid4FromBytes

​UUID constants

​ULID

​generateUlid

​generateUlidList

​isUlidValid

​getUlidBytes

​makeUlidFromBytes

​Types

​UlidOptions

​Comparison: UUID vs ULID

​Examples

Installation

UUID v4

generateUuid4

isUuid4Valid

getUuid4Bytes

makeUuid4FromBytes

UUID constants

ULID

generateUlid

generateUlidList

isUlidValid

getUlidBytes

makeUlidFromBytes

Types

UlidOptions

Comparison: UUID vs ULID

Examples