UUID to Crockford Base32 encoding/decoding library for Node.js
npm install @bboss/uuid32A lightweight TypeScript library for encoding and decoding UUIDs to/from Crockford Base32 strings.
- ๐ 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
- 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
``bashnpm
npm install @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 โ 0Parameters:
-
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 otherwiseError 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.
MIT License - see LICENSE file for details.