or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

base32-utilities.mdgeneration.mdindex.mdtime-utilities.mduuid-conversion.mdvalidation.md
tile.json

tessl/npm-ulid

A universally-unique, lexicographically-sortable, identifier generator

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/ulid@3.0.x

To install, run

npx @tessl/cli install tessl/npm-ulid@3.0.0

index.mddocs/

ULID

ULID provides a high-performance generator for Universally Unique Lexicographically Sortable Identifiers. ULIDs are 26-character identifiers that offer lexicographic sortability, case insensitivity, URL safety, and 128-bit UUID compatibility, making them ideal for distributed systems where chronological ordering is important.

Package Information

  • Package Name: ulid
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install ulid

Core Imports

import { 
  ulid, 
  monotonicFactory, 
  isValid, 
  decodeTime, 
  encodeTime,
  ulidToUUID,
  uuidToULID,
  fixULIDBase32,
  incrementBase32,
  ULIDError,
  ULIDErrorCode,
  MAX_ULID,
  MIN_ULID,
  TIME_LEN,
  TIME_MAX
} from "ulid";

For CommonJS:

const { 
  ulid, 
  monotonicFactory, 
  isValid, 
  decodeTime, 
  encodeTime,
  ulidToUUID,
  uuidToULID,
  fixULIDBase32,
  incrementBase32,
  ULIDError,
  ULIDErrorCode,
  MAX_ULID,
  MIN_ULID,
  TIME_LEN,
  TIME_MAX
} = require("ulid");

Basic Usage

import { ulid, monotonicFactory, isValid } from "ulid";

// Generate a single ULID
const id = ulid(); // "01HNZXD07M5CEN5XA66EMZSRZW"

// Create a monotonic factory for ordering within the same millisecond
const factory = monotonicFactory();
const id1 = factory(); // "01HNZXD07M5CEN5XA66EMZSRZA"  
const id2 = factory(); // "01HNZXD07M5CEN5XA66EMZSRZB"

// Validate a ULID
if (isValid(id)) {
  console.log("Valid ULID");
}

// Extract timestamp from ULID
const timestamp = decodeTime(id);
console.log(new Date(timestamp));

Architecture

ULID is built around several core components:

  • ID Generation: Core ulid() function and monotonicFactory() for ordered generation
  • Time Encoding: Timestamp encoding/decoding utilities with millisecond precision
  • Validation: ULID format validation and error handling
  • UUID Interop: Bidirectional conversion between ULIDs and UUIDs
  • Base32 Utilities: Crockford Base32 encoding with error correction
  • PRNG Detection: Automatic detection of cryptographically-secure random number generators

Capabilities

ULID Generation

Core functionality for generating ULIDs with optional monotonic ordering to ensure lexicographic sortability within the same millisecond.

function ulid(seedTime?: number, prng?: PRNG): ULID;
function monotonicFactory(prng?: PRNG): ULIDFactory;

type ULID = string;
type ULIDFactory = (seedTime?: number) => ULID;
type PRNG = () => number;

ULID Generation

Time Utilities

Functions for encoding and decoding timestamps in ULID format, allowing extraction of creation time from any ULID.

function encodeTime(now: number, len?: number): string;
function decodeTime(id: ULID): number;

Time Utilities

Validation

ULID format validation to ensure proper structure and encoding.

function isValid(id: string): boolean;

Validation

UUID Conversion

Bidirectional conversion utilities between ULIDs and standard UUIDs for interoperability with existing systems.

function ulidToUUID(ulid: ULID): UUID;
function uuidToULID(uuid: string): ULID;

type UUID = string;

UUID Conversion

Base32 Utilities

Utilities for working with Crockford Base32 encoding, including error correction and string manipulation for ULID components.

function fixULIDBase32(id: string): string;
function incrementBase32(str: string): string;

Base32 Utilities

Constants

const MAX_ULID: string; // "7ZZZZZZZZZZZZZZZZZZZZZZZZZ"
const MIN_ULID: string; // "00000000000000000000000000"
const TIME_LEN: number; // 10
const TIME_MAX: number; // 281474976710655 (2^48 - 1)

Error Handling

class ULIDError extends Error {
  code: ULIDErrorCode;
  constructor(errorCode: ULIDErrorCode, message: string);
}

enum ULIDErrorCode {
  Base32IncorrectEncoding = "B32_ENC_INVALID",
  DecodeTimeInvalidCharacter = "DEC_TIME_CHAR",
  DecodeTimeValueMalformed = "DEC_TIME_MALFORMED", 
  EncodeTimeNegative = "ENC_TIME_NEG",
  EncodeTimeSizeExceeded = "ENC_TIME_SIZE_EXCEED",
  EncodeTimeValueMalformed = "ENC_TIME_MALFORMED",
  PRNGDetectFailure = "PRNG_DETECT",
  ULIDInvalid = "ULID_INVALID",
  Unexpected = "UNEXPECTED",
  UUIDInvalid = "UUID_INVALID"
}

CLI Tool

The package includes a command-line tool for generating ULIDs:

# Install globally for CLI usage
npm install -g ulid

# Generate a single ULID
ulid

# Generate multiple ULIDs
ulid --count=5

The CLI uses the monotonic factory to ensure proper ordering when generating multiple ULIDs in sequence.