@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

``bash


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

`javascript
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

$3


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

Returns: Base32 encoded UUID string

$3

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

$3

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

$3

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:

`javascript
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

$3


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

$3

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.