tinyuuid

Fast and lightweight TypeScript library for UUID generation, compression, and expansion. Compress UUIDs from 36 to 22 characters (base62) or 20 characters (base91) with zero dependencies.

Features

• 🚀 Fast: Optimized for performance with minimal overhead
• 📦 Lightweight: Zero dependencies, uses only built-in Node.js modules
• 🔧 TypeScript: Full TypeScript support with type definitions
• ✨ Simple API: Easy to use functions for all operations

Installation

npm install @erlqq/tinyuuid

yarn add @erlqq/tinyuuid

pnpm add @erlqq/tinyuuid

Usage

import { generate, generateShort, shorten, expand, shorten91, expand91 } from '@erlqq/tinyuuid'

// Generate a standard UUID
const uuid = generate()
// Output: "550e8400-e29b-41d4-a716-446655440000"

// Generate a shortened UUID directly
const shortUuid = generateShort()
// Output: "1CGCiUZq18xdRy5IL1oQWC"

// Shorten an existing UUID
const shortened = shorten("355bf501-ffea-4f5a-a9e2-16074de6fcf2")
// Output: "1CGCiUZq18xdRy5IL1oQWC"

// Expand a shortened UUID back to full format
const expanded = expand("1CGCiUZq18xdRy5IL1oQWC")
// Output: "355bf501-ffea-4f5a-a9e2-16074de6fcf2"

// Base91 encoding for maximum compression (20 characters)
const short91 = shorten91("355bf501-ffea-4f5a-a9e2-16074de6fcf2")
// Output: "4nsUS$C5LWA5l[xw=gl~"
const expanded91 = expand91(short91)
// Output: "355bf501-ffea-4f5a-a9e2-16074de6fcf2"

API

generate(): string

Generates a new UUID v4 (random UUID).

Returns: A standard UUID string in format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

generateShort(): string

Generates a new UUID and returns it in shortened format.

Returns: A base62-encoded shortened UUID string (typically 22 characters)

shorten(uuid: string): string

Converts a standard UUID to a shortened base62 representation.

Parameters:

• uuid - A valid UUID string

Returns: A shortened UUID string

Throws: Error if the UUID format is invalid

expand(shortUuid: string): string

Converts a shortened UUID back to standard UUID format.

Parameters:

• shortUuid - A shortened UUID string

Returns: A standard UUID string

Throws: Error if the short UUID is invalid

shorten91(uuid: string): string

Converts a standard UUID to a shortened base91 representation (maximum compression, ~20 characters).

Parameters:

• uuid - A valid UUID string

Returns: A shortened UUID string (typically 20 characters)

Throws: Error if the UUID format is invalid

Note: Base91 contains special characters that may require URL encoding in some contexts.

expand91(shortUuid: string): string

Converts a shortened base91 UUID back to standard UUID format.

Parameters:

• shortUuid - A shortened base91 UUID string

Returns: A standard UUID string

Throws: Error if the short UUID is invalid

How It Works

The library provides two encoding methods for UUID compression:

Base62 Encoding (Default)

• Uses 62 characters: 0-9, a-z, A-Z
• Produces ~22 character shortened UUIDs (39% size reduction)
• Fully URL-safe - no special characters, perfect for URLs and identifiers
• Recommended for most use cases

Base91 Encoding (Maximum Compression)

• Uses 91 characters including special symbols
• Produces ~20 character shortened UUIDs (44% size reduction)
• Contains special characters that may require URL encoding
• Use when size is critical and URL encoding is acceptable

Both methods are lossless - any shortened UUID can be perfectly restored to its original form. The algorithm converts the UUID hex string to a BigInt, then encodes it using the selected base. The compression is mathematically optimal for the chosen alphabet size.

Performance

• UUID generation uses crypto.randomUUID() when available (Node.js 14.17.0+), falling back to crypto.randomBytes() or crypto.getRandomValues() for compatibility
• Base62 encoding/decoding uses optimized BigInt operations with a precomputed alphabet hash for fast character lookup
• Zero external dependencies for minimal bundle size

Testing

Run tests with:

npm test

Watch mode:

npm run test:watch

Coverage report:

npm run test:coverage

License

MIT