@bboss/uuid32

A lightweight TypeScript library for encoding and decoding UUIDs to/from Crockford Base32 strings.

Features

• 🚀 Fast & Lightweight: Zero dependencies, optimized for performance
• 🌐 Universal: Works in Node.js and modern browsers
• 📦 TypeScript Native: Full TypeScript support with type definitions
• 🧪 Well Tested: Comprehensive test suite with high coverage
• 🔧 Simple API: Easy-to-use functions for encoding, decoding, and validation
• 🛡️ User-Friendly: Case-insensitive with automatic correction of confusable characters
• ✨ Crockford Standard: Full compliance with Crockford Base32 specification

Use Cases

• Product Key Generation: Software license keys, serial numbers
• API Key Generation: Service authentication tokens, access keys
• Short IDs: URL shortening, reference codes, tracking IDs
• Manual Input: Reduced errors when users need to type keys manually

Installation

# npm
npm install @bboss/uuid32

# yarn
yarn add @bboss/uuid32

Requirements

• Requires an environment with crypto.randomUUID() support (e.g., Node.js 16+ or modern browsers).

Usage

import uuid32 from '@bboss/uuid32';
// const uuid32 = require('@bboss/uuid32'); // legacy way

// Generate a new Base32 UUID
const shortId = uuid32.generateBase32();
console.log(shortId); // → "29STNWYQG28H4VWA59PD0XYJR8" (random)

// Encode existing UUID to Base32
const encoded = uuid32.encode('49ceabcf-5e02-4449-be28-a9b341df4b08');
console.log(encoded); // → "29STNWYQG28H4VWA59PD0XYJR8"

// Decode Base32 back to standard UUID
const decoded = uuid32.decode('29STNWYQG28H4VWA59PD0XYJR8');
console.log(decoded); // → "49ceabcf-5e02-4449-be28-a9b341df4b08"

// Case-insensitive decoding (NEW in v1.2.0)
uuid32.decode('29stnwyqg28h4vwa59pd0xyjr8');  // ✅ Works (lowercase)
uuid32.decode('29StNwYqG28h4VwA59Pd0XyJr8');  // ✅ Works (mixed case)

// Auto-correction of confusable characters (NEW in v1.2.0)
uuid32.decode('29STNWYQG28H4VWA59PD0XYJRl');  // ✅ 'l' → '1' auto-corrected
uuid32.decode('2OSTNWYQG28H4VWA59PD0XYJR8');  // ✅ 'O' → '0' auto-corrected

// Validation
console.log(uuid32.isValidBase32('29STNWYQG28H4VWA59PD0XYJR8')); // → true
console.log(uuid32.isValidBase32('abc123'));  // → true (accepts lowercase)

API Reference

generateBase32(): string

Generates a new UUID v4 using crypto.randomUUID() and encodes it to Crockford Base32.

Returns: Base32 encoded UUID string

encode(uuid: string): string

Encodes a standard UUID to Crockford Base32 format.

Parameters:

• uuid - Standard UUID string (with or without hyphens)

Returns: Base32 encoded string

Throws: Error if UUID format is invalid

decode(base32: string): string

Decodes a Crockford Base32 string back to standard UUID format.

Supports case-insensitive input and automatically corrects confusable characters according to the Crockford Base32 standard:

• Case-insensitive: ABC and abc are treated the same
• I or i → 1
• L or l → 1
• O or o → 0

Parameters:

• base32 - Base32 encoded string (case-insensitive)

Returns: Standard UUID string with hyphens

Throws: Error if Base32 format is invalid

isValidBase32(str: string): boolean

Validates if a string is a valid Crockford Base32 format.

Accepts both uppercase and lowercase characters, as well as confusable characters that can be auto-corrected.

Parameters:

• str - String to validate (case-insensitive)

Returns: true if valid Base32, false otherwise

Error Handling

The library throws descriptive errors for invalid inputs:

try {
    uuid32.encode('invalid-uuid');
} catch (error) {
    console.log(error.message); // → "Invalid UUID format"
}

try {
    uuid32.decode('invalid@base32!');
} catch (error) {
    console.log(error.message); // → "Invalid Base32 format"
}

Crockford Base32 Character Set

Uses the following 32 characters: 0123456789ABCDEFGHJKMNPQRSTVWXYZ

Encoding

Encoded strings will only contain valid Base32 characters, excluding confusable ones:

• Excluded: I, L, O, U (never appear in encoded output)
• Used: 0-9, A-H, J, K, M, N, P-Z

Decoding (Flexible Input)

Supports case-insensitive decoding and automatic correction of confusable characters:

• Case-insensitive: ABC = abc = AbC
• Auto-correction:
  • I or i → 1
  • L or l → 1
  • O or o → 0
  • U remains as U (not confusable in this context)

This flexible decoding makes the library more user-friendly for manual input scenarios like product keys and API keys, while maintaining full compliance with the Crockford Base32 specification.

License

MIT License - see LICENSE file for details.