Time Utilities

/**
 * Decode time from a ULID
 * @param id - The ULID string to decode
 * @returns The decoded timestamp in milliseconds since Unix epoch
 * @throws ULIDError if the ULID is malformed or contains invalid characters
 */
function decodeTime(id: ULID): number;

import { decodeTime, ulid } from "ulid";

// Generate a ULID and extract its timestamp
const id = ulid();
const timestamp = decodeTime(id);
const createdAt = new Date(timestamp);

console.log(`ULID ${id} was created at ${createdAt.toISOString()}`);

// Decode timestamp from existing ULID
const existingId = "01HNZX8JGFACFA36RBXDHEQN6E";
const originalTime = decodeTime(existingId); // 1469918176385

// Use with specific ULID
try {
  const time = decodeTime("01ARYZ6S41TSV4RRFFQ69G5FAV");
  console.log(new Date(time)); // Original creation date
} catch (error) {
  console.error("Invalid ULID:", error.message);
}

/**
 * Encode the time portion of a ULID
 * @param now - The timestamp to encode (milliseconds since Unix epoch)
 * @param len - Length to generate (default: TIME_LEN = 10)
 * @returns The encoded time string
 * @throws ULIDError for invalid timestamp values
 */
function encodeTime(now: number, len?: number): string;

import { encodeTime, TIME_LEN } from "ulid";

// Encode current timestamp
const now = Date.now();
const encoded = encodeTime(now); // "01HNZXD07M"

// Encode specific timestamp
const specificTime = 1469918176385;
const timeStr = encodeTime(specificTime); // "01ARYZ6S41"

// Encode with custom length (advanced usage)
const shortTime = encodeTime(now, 8); // Shorter time encoding

// Use with Date objects
const futureDate = new Date("2030-01-01T00:00:00Z");
const futureEncoded = encodeTime(futureDate.getTime());

const TIME_LEN: number; // 10 - Standard length of time portion
const TIME_MAX: number; // 281474976710655 - Maximum timestamp value (2^48 - 1)