tessl/npm-ulid

A universally-unique, lexicographically-sortable, identifier generator

1.34x

Overview

Eval results

Files

UUID Conversion

Name: tessl/npm-ulid
Rating: 0.78 (1 reviews)
Author: tessl

Bidirectional conversion utilities between ULIDs and standard UUIDs, enabling interoperability with existing systems that use UUID formats.

Capabilities

ULID to UUID Conversion

Converts a ULID to a standard UUID format (8-4-4-4-12 hexadecimal pattern).

/**
 * Convert a ULID to a UUID
 * @param ulid - The ULID to convert
 * @returns A UUID string in standard format
 * @throws ULIDError if the ULID is invalid
 */
function ulidToUUID(ulid: ULID): UUID;

Usage Examples:

import { ulidToUUID, ulid } from "ulid";

// Convert generated ULID to UUID
const id = ulid(); // "01HNZX8JGFACFA36RBXDHEQN6E"
const uuid = ulidToUUID(id); // "0191E9A4-8F21-7516-B3F1-4D6C5E7F8A9B"

// Convert existing ULID
const existingUlid = "01ARYZ6S41TSV4RRFFQ69G5FAV";
const convertedUuid = ulidToUUID(existingUlid); // "0158AFDC-C3E3-7A3A-FFFB-1A5C9E5FAF5F"

// Use in database operations
function storeInLegacySystem(ulidString: string) {
  try {
    const uuidFormat = ulidToUUID(ulidString);
    // Store in system that expects UUID format
    return database.insert({ id: uuidFormat, ...data });
  } catch (error) {
    console.error("Invalid ULID for conversion:", error.message);
  }
}

// Batch conversion
const ulids = ["01HNZX8JGFACFA36RBXDHEQN6E", "01ARYZ6S41TSV4RRFFQ69G5FAV"];
const uuids = ulids.map(ulidToUUID);

Error Conditions:

Throws ULIDError with code ULIDInvalid if the input ULID is malformed
Performs validation before conversion to ensure data integrity

UUID to ULID Conversion

Converts a standard UUID to ULID format.

/**
 * Convert a UUID to a ULID
 * @param uuid - The UUID to convert (with or without hyphens)
 * @returns A ULID string
 * @throws ULIDError if the UUID is invalid
 */
function uuidToULID(uuid: string): ULID;

Usage Examples:

import { uuidToULID } from "ulid";

// Convert standard UUID to ULID
const uuid = "0191E9A4-8F21-7516-B3F1-4D6C5E7F8A9B";
const ulid = uuidToULID(uuid); // "01HNZX8JGFACFA36RBXDHEQN6E"

// Convert UUID without hyphens
const uuidWithoutHyphens = "0191E9A48F217516B3F14D6C5E7F8A9B";
const ulidFromPlain = uuidToULID(uuidWithoutHyphens); // Same result

// Migrate legacy data
async function migrateToULID(legacyRecords: { id: string }[]) {
  return legacyRecords.map(record => ({
    ...record,
    id: uuidToULID(record.id)
  }));
}

// Handle mixed case UUIDs
const mixedCaseUuid = "0191e9a4-8f21-7516-b3f1-4d6c5e7f8a9b";
const convertedUlid = uuidToULID(mixedCaseUuid); // Works with any case

Error Conditions:

Throws ULIDError with code UUIDInvalid if the input UUID format is invalid
Throws ULIDError with code Unexpected if UUID parsing fails unexpectedly

UUID Format Support:

The conversion functions support standard UUID formats:

Standard format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
Case insensitive: Both uppercase and lowercase hexadecimal digits
With hyphens: Standard UUID format with separating hyphens
Without hyphens: Plain 32-character hexadecimal string (for uuidToULID only)

Conversion Properties:

Bijective: Converting ULID→UUID→ULID preserves the original value
Deterministic: Same input always produces same output
128-bit preservation: Full bit precision maintained during conversion
Lexicographic ordering: ULIDs maintain chronological ordering, UUIDs do not

Interoperability Examples:

import { ulid, ulidToUUID, uuidToULID, isValid } from "ulid";

// Round-trip conversion verification
const originalUlid = ulid();
const uuid = ulidToUUID(originalUlid);
const backToUlid = uuidToULID(uuid);

console.log(originalUlid === backToUlid); // true - perfect round-trip

// Integration with existing UUID-based systems
class LegacyAdapter {
  // Store as ULID, expose as UUID for legacy compatibility
  store(data: any) {
    const id = ulid();
    const legacyId = ulidToUUID(id);
    return { ...data, id, legacyId };
  }
  
  // Accept UUID from legacy system, convert to ULID internally
  retrieve(legacyId: string) {
    const internalId = uuidToULID(legacyId);
    return database.findByULID(internalId);
  }
}

Types

type UUID = string;
type ULID = string;

Install with Tessl CLI

npx tessl i tessl/npm-ulid