Timestamp to Lexicographic String Converter

Build a utility that converts Unix timestamps (in milliseconds) into lexicographically sortable string representations. This is useful for creating time-based identifiers that maintain natural sort order.

Requirements

Your implementation should:

1. Convert timestamps to fixed-length string representations that preserve chronological ordering
2. Handle edge cases including very old dates (timestamp 0) and far future dates
3. Validate input to ensure only valid timestamp values are processed
4. Use efficient encoding to keep string length reasonable

Implementation Details

Create a module that exports a function to encode timestamps. The function should:

• Accept a timestamp in milliseconds as input
• Return a fixed-length string representation
• Throw descriptive errors for invalid inputs (negative values, non-numeric values, or values exceeding the maximum supported timestamp)

Test Cases

The following test cases should pass:

• Encoding timestamp 1609459200000 (2021-01-01 00:00:00 UTC) produces a valid 10-character string @test
• Encoding timestamp 0 produces a valid 10-character string @test
• Encoding a negative timestamp throws an error @test
• Encoding a non-numeric value (such as NaN) throws an error @test
• Multiple timestamps encoded in chronological order produce strings that sort lexicographically in the same order @test

Implementation

@generates

API

/**
 * Encodes a timestamp into a lexicographically sortable string representation.
 *
 * @param timestamp - The timestamp in milliseconds to encode
 * @param length - The desired length of the encoded string (default: 10)
 * @returns A string representation of the timestamp
 * @throws Error if the timestamp is invalid (negative, NaN, or too large)
 */
export function encodeTimestamp(timestamp: number, length?: number): string;

Dependencies { .dependencies }

ulid { .dependency }

Provides unique identifier generation with lexicographic sorting capabilities.

@satisfied-by