Ordered ID Generator

Build a function that generates sequential, ordered identifiers for a high-frequency event logging system. The identifiers must maintain strict lexicographic ordering even when multiple events occur within the same millisecond.

Requirements

Your implementation must:

1. Generate unique identifiers that are lexicographically sortable by creation time
2. Ensure that identifiers created within the same millisecond maintain strict sequential order (no two identifiers should be equal, and later-generated identifiers should always sort after earlier ones)
3. Support generating identifiers with custom timestamps for historical event recording
4. Return identifiers as strings in a format suitable for database indexing

Implementation

@generates

API

/**
 * Creates an ordered ID generator
 * @returns A generator function that produces ordered IDs
 */
export function createOrderedIdGenerator(): IdGenerator;

/**
 * ID generator function type
 * @param timestamp - Optional timestamp in milliseconds (default: current time)
 * @returns A unique, ordered identifier string
 */
export type IdGenerator = (timestamp?: number) => string;

Test Cases

Ordering within same millisecond

• When generating 3 IDs with the same timestamp (150000), each subsequent ID should be lexicographically greater than the previous one @test

Ordering with different timestamps

• When generating IDs with increasing timestamps (100000, 200000, 300000), each ID should be lexicographically greater than the previous one @test

Maintaining monotonicity with past timestamps

• When generating an ID with timestamp 200000, then another with timestamp 150000, the second ID should still be lexicographically greater than the first (maintaining monotonic ordering) @test

Default timestamp behavior

• When generating an ID without specifying a timestamp, it should use the current time @test

Dependencies { .dependencies }

ulid { .dependency }

Provides identifier generation with sortable properties.

@satisfied-by