@bboss/uuid32 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 bigboss.dev (https://github.com/bigbossdev/uuid32)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# @bboss/uuid32
+
+A lightweight TypeScript library for encoding and decoding UUIDs to/from Crockford Base32 strings, designed exclusively for Node.js environments.
+
+## Features
+
+- 🚀 **Fast & Lightweight**: Zero dependencies, optimized for performance
+- 🔒 **Node.js Only**: Built specifically for server-side applications
+- 📦 **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**: Excludes confusing characters (I, L, O, U) to prevent input errors
+
+## 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
+
+- Node.js 16.0.0 or higher (requires `crypto.randomUUID()`)
+- **Node.js only** - not compatible with browser environments
+
+## 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"
+
+// Validation
+console.log(uuid32.isValidBase32('29STNWYQG28H4VWA59PD0XYJR8')); // → true
+```
+
+## 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.
+
+**Parameters:**
+- `base32` - Base32 encoded string
+
+**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.
+
+**Parameters:**
+- `str` - String to validate
+
+**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`
+
+**Excluded characters for clarity:**
+- `I` (can be confused with `1`)
+- `L` (can be confused with `1`) 
+- `O` (can be confused with `0`)
+- `U` (can be confused with `V`)
+
+This makes the encoded strings more reliable for manual input and reduces transcription errors.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { isValidBase32 } from './utils';
+/**
+ * Encodes a UUID to Crockford Base32 string
+ */
+export declare function encode(uuid: string): string;
+/**
+ * Decodes a Crockford Base32 string to UUID
+ */
+export declare function decode(base32: string): string;
+/**
+ * Generates a new UUID v4 and encodes it to Crockford Base32
+ */
+export declare function generateBase32(): string;
+export { isValidBase32 };
+declare const _default: {
+    generateBase32: typeof generateBase32;
+    encode: typeof encode;
+    decode: typeof decode;
+    isValidBase32: typeof isValidBase32;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAGH,aAAa,EAIhB,MAAM,SAAS,CAAC;AAKjB;;GAEG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmB3C;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAuB7C;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAGvC;AAGD,OAAO,EAAE,aAAa,EAAE,CAAC;;;;;;;AAGzB,wBAKE"}

package/dist/index.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidBase32 = void 0;
+exports.encode = encode;
+exports.decode = decode;
+exports.generateBase32 = generateBase32;
+const crypto_1 = require("crypto");
+const utils_1 = require("./utils");
+Object.defineProperty(exports, "isValidBase32", { enumerable: true, get: function () { return utils_1.isValidBase32; } });
+// Check environment on module load
+(0, utils_1.checkNodeEnvironment)();
+/**
+ * Encodes a UUID to Crockford Base32 string
+ */
+function encode(uuid) {
+    if (!(0, utils_1.isValidUuid)(uuid)) {
+        throw new Error('Invalid UUID format');
+    }
+    const normalized = (0, utils_1.normalizeUuid)(uuid);
+    const hex = BigInt('0x' + normalized);
+    if (hex === 0n)
+        return '0'.padStart(26, '0');
+    let result = '';
+    let num = hex;
+    while (num > 0n) {
+        result = utils_1.BASE32_CHARS[Number(num % 32n)] + result;
+        num = num / 32n;
+    }
+    return result.padStart(26, '0');
+}
+/**
+ * Decodes a Crockford Base32 string to UUID
+ */
+function decode(base32) {
+    if (!(0, utils_1.isValidBase32)(base32)) {
+        throw new Error('Invalid Base32 format');
+    }
+    let num = 0n;
+    for (let i = 0; i < base32.length; i++) {
+        const char = base32[i];
+        const index = utils_1.BASE32_CHARS.indexOf(char);
+        if (index === -1) {
+            throw new Error('Invalid Base32 character');
+        }
+        num = num * 32n + BigInt(index);
+    }
+    let hex = num.toString(16).padStart(32, '0');
+    if (hex.length > 32) {
+        throw new Error('Invalid Base32 value: too large for UUID');
+    }
+    return (0, utils_1.formatUuid)(hex);
+}
+/**
+ * Generates a new UUID v4 and encodes it to Crockford Base32
+ */
+function generateBase32() {
+    const uuid = (0, crypto_1.randomUUID)();
+    return encode(uuid);
+}
+// Default export for CommonJS compatibility
+exports.default = {
+    generateBase32,
+    encode,
+    decode,
+    isValidBase32: utils_1.isValidBase32
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAgBA,wBAmBC;AAKD,wBAuBC;AAKD,wCAGC;AAvED,mCAAoC;AACpC,mCAOiB;AAkER,8FAtEL,qBAAa,OAsEK;AAhEtB,mCAAmC;AACnC,IAAA,4BAAoB,GAAE,CAAC;AAEvB;;GAEG;AACH,SAAgB,MAAM,CAAC,IAAY;IAC/B,IAAI,CAAC,IAAA,mBAAW,EAAC,IAAI,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAC3C,CAAC;IAED,MAAM,UAAU,GAAG,IAAA,qBAAa,EAAC,IAAI,CAAC,CAAC;IACvC,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,GAAG,UAAU,CAAC,CAAC;IAEtC,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,GAAG,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAE7C,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,GAAG,GAAG,GAAG,CAAC;IAEd,OAAO,GAAG,GAAG,EAAE,EAAE,CAAC;QACd,MAAM,GAAG,oBAAY,CAAC,MAAM,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC;QAClD,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACpB,CAAC;IAED,OAAO,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,SAAgB,MAAM,CAAC,MAAc;IACjC,IAAI,CAAC,IAAA,qBAAa,EAAC,MAAM,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAC7C,CAAC;IAED,IAAI,GAAG,GAAG,EAAE,CAAC;IAEb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACvB,MAAM,KAAK,GAAG,oBAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;QAChD,CAAC;QACD,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;IAED,IAAI,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAE7C,IAAI,GAAG,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAChE,CAAC;IAED,OAAO,IAAA,kBAAU,EAAC,GAAG,CAAC,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,SAAgB,cAAc;IAC1B,MAAM,IAAI,GAAG,IAAA,mBAAU,GAAE,CAAC;IAC1B,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC;AAKD,4CAA4C;AAC5C,kBAAe;IACX,cAAc;IACd,MAAM;IACN,MAAM;IACN,aAAa,EAAb,qBAAa;CAChB,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Crockford Base32 character set (excludes I, L, O, U to avoid confusion)
+ */
+export declare const BASE32_CHARS = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/**
+ * Validates if a string is a valid UUID format
+ */
+export declare function isValidUuid(str: string): boolean;
+/**
+ * Validates if a string is a valid Crockford Base32 format
+ */
+export declare function isValidBase32(str: string): boolean;
+/**
+ * Normalizes UUID by removing hyphens
+ */
+export declare function normalizeUuid(uuid: string): string;
+/**
+ * Formats UUID by adding hyphens
+ */
+export declare function formatUuid(uuid: string): string;
+/**
+ * Checks if running in browser environment
+ */
+export declare function checkNodeEnvironment(): void;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,YAAY,qCAAqC,CAAC;AAY/D;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGhD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGlD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAI3C"}

package/dist/utils.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASE32_CHARS = void 0;
+exports.isValidUuid = isValidUuid;
+exports.isValidBase32 = isValidBase32;
+exports.normalizeUuid = normalizeUuid;
+exports.formatUuid = formatUuid;
+exports.checkNodeEnvironment = checkNodeEnvironment;
+/**
+ * Crockford Base32 character set (excludes I, L, O, U to avoid confusion)
+ */
+exports.BASE32_CHARS = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/**
+ * UUID validation regex (with or without hyphens)
+ */
+const UUID_REGEX = /^[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}$/i;
+/**
+ * Crockford Base32 validation regex
+ */
+const BASE32_REGEX = /^[0-9ABCDEFGHJKMNPQRSTVWXYZ]+$/;
+/**
+ * Validates if a string is a valid UUID format
+ */
+function isValidUuid(str) {
+    if (typeof str !== 'string')
+        return false;
+    return UUID_REGEX.test(str);
+}
+/**
+ * Validates if a string is a valid Crockford Base32 format
+ */
+function isValidBase32(str) {
+    if (typeof str !== 'string')
+        return false;
+    return BASE32_REGEX.test(str) && str.length > 0;
+}
+/**
+ * Normalizes UUID by removing hyphens
+ */
+function normalizeUuid(uuid) {
+    return uuid.replace(/-/g, '');
+}
+/**
+ * Formats UUID by adding hyphens
+ */
+function formatUuid(uuid) {
+    return `${uuid.slice(0, 8)}-${uuid.slice(8, 12)}-${uuid.slice(12, 16)}-${uuid.slice(16, 20)}-${uuid.slice(20, 32)}`;
+}
+/**
+ * Checks if running in browser environment
+ */
+function checkNodeEnvironment() {
+    if (typeof globalThis.window !== 'undefined' || typeof globalThis.document !== 'undefined') {
+        throw new Error('@bboss/uuid32 is Node.js only and cannot run in browser environments');
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":";;;AAkBA,kCAGC;AAKD,sCAGC;AAKD,sCAEC;AAKD,gCAEC;AAKD,oDAIC;AApDD;;GAEG;AACU,QAAA,YAAY,GAAG,kCAAkC,CAAC;AAE/D;;GAEG;AACH,MAAM,UAAU,GAAG,qEAAqE,CAAC;AAEzF;;GAEG;AACH,MAAM,YAAY,GAAG,gCAAgC,CAAC;AAEtD;;GAEG;AACH,SAAgB,WAAW,CAAC,GAAW;IACnC,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,GAAW;IACrC,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;AACpD,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,IAAY;IACtC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,SAAgB,UAAU,CAAC,IAAY;IACnC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;AACxH,CAAC;AAED;;GAEG;AACH,SAAgB,oBAAoB;IAChC,IAAI,OAAQ,UAAkB,CAAC,MAAM,KAAK,WAAW,IAAI,OAAQ,UAAkB,CAAC,QAAQ,KAAK,WAAW,EAAE,CAAC;QAC3G,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;IAC5F,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+    "name": "@bboss/uuid32",
+    "version": "0.1.0",
+    "description": "UUID to Crockford Base32 encoding/decoding library for Node.js",
+    "keywords": [
+        "uuid",
+        "base32",
+        "crockford",
+        "encoding",
+        "decoding",
+        "product-key",
+        "api-key",
+        "typescript",
+        "nodejs"
+    ],
+    "author": "bigboss.dev",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/bigbossdev/uuid32.git"
+    },
+    "bugs": {
+        "url": "https://github.com/bigbossdev/uuid32/issues"
+    },
+    "homepage": "https://github.com/bigbossdev/uuid32#readme",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist/**/*",
+        "README.md",
+        "LICENSE"
+    ],
+    "engines": {
+        "node": ">=16.0.0"
+    },
+    "scripts": {
+        "build": "rimraf dist && tsc",
+        "test": "jest",
+        "test:watch": "jest --watch",
+        "test:coverage": "jest --coverage",
+        "prepublishOnly": "npm run build"
+    },
+    "devDependencies": {
+        "@types/jest": "^29.5.14",
+        "@types/node": "^22.0.0",
+        "jest": "^29.7.0",
+        "rimraf": "^6.0.1",
+        "ts-jest": "^29.4.5",
+        "typescript": "^5.9.3"
+    },
+    "packageManager": "yarn@4.10.3"
+}