Overview
The ID module provides functions for generating and validating ULIDs (Universally Unique Lexicographically Sortable Identifiers) and UUID v4 identifiers.
ULID
generateUlid
Generates a new ULID string.
function generateUlid(options?: UlidOptions): string
Optional configuration for ULID generation
A 26-character ULID string (Crockford’s base32 encoded)
import { generateUlid } from "@temelj/id";
const id = generateUlid();
console.log(id); // "01ARZ3NDEKTSV4RRFFQ69G5FAV"
// Generate with specific timestamp
const id2 = generateUlid({ time: new Date("2024-01-01") });
generateUlidList
Generates multiple ULIDs in a monotonically increasing sequence.
function generateUlidList(count: number, options?: UlidOptions): string[]
The number of ULIDs to generate
Optional configuration (cannot include custom random bytes)
Array of ULID strings in monotonically increasing order
import { generateUlidList } from "@temelj/id";
const ids = generateUlidList(5);
console.log(ids);
// [
// "01BX5ZZKBKACTAV9WEVGEMMVRZ",
// "01BX5ZZKBKACTAV9WEVGEMMVS0",
// "01BX5ZZKBKACTAV9WEVGEMMVS1",
// ...
// ]
isUlidValid
Checks if a string is a valid ULID.
function isUlidValid(id: string): boolean
True if the string is a valid ULID, false otherwise
import { isUlidValid } from "@temelj/id";
console.log(isUlidValid("01ARZ3NDEKTSV4RRFFQ69G5FAV")); // true
console.log(isUlidValid("invalid-id")); // false
console.log(isUlidValid("")); // false
getUlidBytes
Converts a ULID string to its byte array representation.
function getUlidBytes(id: string): Uint8Array
The ULID string to convert
16-byte array representation of the ULID
import { getUlidBytes } from "@temelj/id";
const id = "01ARZ3NDEKTSV4RRFFQ69G5FAV";
const bytes = getUlidBytes(id);
console.log(bytes); // Uint8Array(16) [ ... ]
makeUlidFromBytes
Constructs a ULID string from a byte array.
function makeUlidFromBytes(bytes: Uint8Array): string
16-byte array to convert to ULID
The ULID string representation
import { makeUlidFromBytes, getUlidBytes } from "@temelj/id";
const originalId = "01ARZ3NDEKTSV4RRFFQ69G5FAV";
const bytes = getUlidBytes(originalId);
const reconstructedId = makeUlidFromBytes(bytes);
console.log(reconstructedId === originalId); // true
UlidOptions
Options for ULID generation.
interface UlidOptions {
time?: Date;
random?: Uint8Array;
}
The timestamp to use for generating the ULID. Defaults to current time.
Custom random bytes (must be exactly 10 bytes). Cannot be used with generateUlidList.
UUID v4
generateUuid4
Generates a new UUID v4 string.
function generateUuid4(): string
A 36-character UUID v4 string in lowercase
import { generateUuid4 } from "@temelj/id";
const id = generateUuid4();
console.log(id); // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
isUuid4Valid
Checks if a string is a valid UUID v4.
function isUuid4Valid(id: string): boolean
True if the string is a valid UUID v4, false otherwise
import { isUuid4Valid } from "@temelj/id";
console.log(isUuid4Valid("f47ac10b-58cc-4372-a567-0e02b2c3d479")); // true
console.log(isUuid4Valid("invalid-uuid")); // false
getUuid4Bytes
Converts a UUID v4 string to its byte array representation.
function getUuid4Bytes(id: string): Uint8Array
The UUID v4 string to convert
16-byte array representation of the UUID
import { getUuid4Bytes } from "@temelj/id";
const id = "f47ac10b-58cc-4372-a567-0e02b2c3d479";
const bytes = getUuid4Bytes(id);
console.log(bytes); // Uint8Array(16) [ ... ]
makeUuid4FromBytes
Constructs a UUID v4 string from a byte array.
function makeUuid4FromBytes(bytes: Uint8Array): string
16-byte array to convert to UUID v4
The UUID v4 string representation in lowercase
import { makeUuid4FromBytes, getUuid4Bytes } from "@temelj/id";
const originalId = "f47ac10b-58cc-4372-a567-0e02b2c3d479";
const bytes = getUuid4Bytes(originalId);
const reconstructedId = makeUuid4FromBytes(bytes);
console.log(reconstructedId === originalId); // true
Constants
UUID4_MIN
Minimum valid UUID v4 value.
const UUID4_MIN: string = "00000000-0000-4000-8000-000000000000";
UUID4_MAX
Maximum valid UUID v4 value.
const UUID4_MAX: string = "ffffffff-ffff-4fff-bfff-ffffffffffff";
UUID4_LENGTH
Length of a UUID v4 string including hyphens.
const UUID4_LENGTH: number = 36;
ULID vs UUID v4
Use ULID when:
- You need sortable IDs by creation time
- You want better database index performance
- You need shorter string representation (26 vs 36 characters)
- You want monotonic ordering within the same millisecond
Use UUID v4 when:
- You need compatibility with existing systems expecting UUIDs
- Random distribution is preferred over sortability
- Standards compliance is required
Common use cases
Database primary keys
import { generateUlid } from "@temelj/id";
interface User {
id: string;
name: string;
}
function createUser(name: string): User {
return {
id: generateUlid(),
name
};
}
Request tracing
import { generateUuid4 } from "@temelj/id";
function traceRequest(handler: () => void) {
const requestId = generateUuid4();
console.log(`[${requestId}] Starting request`);
try {
handler();
console.log(`[${requestId}] Request completed`);
} catch (error) {
console.error(`[${requestId}] Request failed:`, error);
}
}
Batch ID generation
import { generateUlidList } from "@temelj/id";
function createBatchRecords(count: number) {
const ids = generateUlidList(count);
return ids.map((id, index) => ({
id,
position: index
}));
}