@nakanoaas/uuid58 1.0.5 → 1.1.0

package/README.md

@@ -165,6 +165,62 @@ function uuid58DecodeSafe(uuid58: string): string | Uuid58DecodeError;
   `Uuid58DecodeError` if the input is not a valid 22-character Base58 string
 - **Note:** This function does not throw; it returns the error object instead.
 
+### Error Classes
+
+#### `Uuid58EncodeError`
+
+Error thrown when an invalid UUID string is provided for encoding. This includes
+strings that don't match the standard UUID format (32 hexadecimal characters
+with optional hyphens).
+
+```typescript
+class Uuid58EncodeError extends Error;
+```
+
+#### `Uuid58DecodeError`
+
+Error thrown when an invalid Base58 string is provided for decoding. This
+includes strings containing characters not in the Base58 alphabet or strings
+that are not exactly 22 characters long.
+
+```typescript
+class Uuid58DecodeError extends Error;
+```
+
+### Alphabet and Utilities
+
+#### `UUID58_ALPHABET`
+
+Character set for Base58 encoding (Bitcoin compatible). This alphabet excludes
+characters that can be easily confused: `0` (zero) and `O` (capital O), `I`
+(capital i) and `l` (lowercase L). The alphabet consists of 58 characters:
+digits 1-9 and letters A-Z, a-z (excluding the ambiguous characters mentioned
+above).
+
+```typescript
+const UUID58_ALPHABET: string; // "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+```
+
+#### `UUID58_REGEX`
+
+Regular expression pattern for validating UUID58 strings. This regex ensures
+that a string contains exactly 22 characters and uses only characters from the
+Base58 alphabet.
+
+```typescript
+const UUID58_REGEX: RegExp; // /^[1-9A-HJ-NP-Za-km-z]{22}$/
+```
+
+**Example:**
+
+```typescript
+import { UUID58_REGEX } from "@nakanoaas/uuid58";
+
+const isValid = UUID58_REGEX.test("XDY9dmBbcMBXqcRvYw8xJ2"); // true
+const isValid = UUID58_REGEX.test("invalid"); // false
+const isValid = UUID58_REGEX.test("123"); // false (too short)
+```
+
 ## Why uuid58?
 
 Standard UUIDs are 36 characters long (including hyphens), which can be

package/esm/alphabet.d.ts

@@ -1,3 +1,40 @@
-export declare const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
-export declare const ALPHABET_LENGTH: bigint;
+/**
+ * Character set for Base58 encoding (Bitcoin compatible).
+ *
+ * This alphabet excludes characters that can be easily confused:
+ * - `0` (zero) and `O` (capital O)
+ * - `I` (capital i) and `l` (lowercase L)
+ *
+ * The alphabet consists of 58 characters: digits 1-9 and letters A-Z, a-z
+ * (excluding the ambiguous characters mentioned above).
+ *
+ * @example
+ * ```typescript
+ * const char = UUID58_ALPHABET[0]; // "1"
+ * const char = UUID58_ALPHABET[9]; // "A"
+ * ```
+ */
+export declare const UUID58_ALPHABET: string;
+/**
+ * @internal
+ * The length of the Base58 alphabet as BigInt for encoding/decoding operations.
+ * This is exported for internal use but not part of the public API.
+ */
+export declare const UUID58_LENGTH: bigint;
+/**
+ * Regular expression pattern for validating UUID58 strings.
+ *
+ * This regex ensures that a string:
+ * - Contains exactly 22 characters
+ * - Uses only characters from the Base58 alphabet
+ * - Does not start with leading zeros (represented as "1" in Base58)
+ *
+ * @example
+ * ```typescript
+ * const isValid = UUID58_REGEX.test("XDY9dmBbcMBXqcRvYw8xJ2"); // true
+ * const isValid = UUID58_REGEX.test("invalid"); // false
+ * const isValid = UUID58_REGEX.test("123"); // false (too short)
+ * ```
+ */
+export declare const UUID58_REGEX: RegExp;
 //# sourceMappingURL=alphabet.d.ts.map

package/esm/alphabet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alphabet.d.ts","sourceRoot":"","sources":["../src/alphabet.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,eAAe,+DACkC,CAAC;AAC/D,eAAO,MAAM,eAAe,QAAiC,CAAC"}
+{"version":3,"file":"alphabet.d.ts","sourceRoot":"","sources":["../src/alphabet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,EAAE,MACgC,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,MAAuC,CAAC;AAEpE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,MAAsC,CAAC"}

package/esm/alphabet.js

@@ -1,3 +1,39 @@
-// Character set for Base58 (Bitcoin compatible)
-export const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"; // cspell:disable-line
-export const ALPHABET_LENGTH = BigInt(BASE58_ALPHABET.length);
+/**
+ * Character set for Base58 encoding (Bitcoin compatible).
+ *
+ * This alphabet excludes characters that can be easily confused:
+ * - `0` (zero) and `O` (capital O)
+ * - `I` (capital i) and `l` (lowercase L)
+ *
+ * The alphabet consists of 58 characters: digits 1-9 and letters A-Z, a-z
+ * (excluding the ambiguous characters mentioned above).
+ *
+ * @example
+ * ```typescript
+ * const char = UUID58_ALPHABET[0]; // "1"
+ * const char = UUID58_ALPHABET[9]; // "A"
+ * ```
+ */
+export const UUID58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+/**
+ * @internal
+ * The length of the Base58 alphabet as BigInt for encoding/decoding operations.
+ * This is exported for internal use but not part of the public API.
+ */
+export const UUID58_LENGTH = BigInt(UUID58_ALPHABET.length);
+/**
+ * Regular expression pattern for validating UUID58 strings.
+ *
+ * This regex ensures that a string:
+ * - Contains exactly 22 characters
+ * - Uses only characters from the Base58 alphabet
+ * - Does not start with leading zeros (represented as "1" in Base58)
+ *
+ * @example
+ * ```typescript
+ * const isValid = UUID58_REGEX.test("XDY9dmBbcMBXqcRvYw8xJ2"); // true
+ * const isValid = UUID58_REGEX.test("invalid"); // false
+ * const isValid = UUID58_REGEX.test("123"); // false (too short)
+ * ```
+ */
+export const UUID58_REGEX = /^[1-9A-HJ-NP-Za-km-z]{22}$/u;

package/esm/decode.js

@@ -1,9 +1,9 @@
 var _a;
-import { ALPHABET_LENGTH, BASE58_ALPHABET } from "./alphabet.js";
+import { UUID58_ALPHABET, UUID58_LENGTH } from "./alphabet.js";
 // Fast lookup map from alphabet characters to their indices
 const BASE58_MAP = {};
-for (let i = 0; i < BASE58_ALPHABET.length; i++) {
-    BASE58_MAP[BASE58_ALPHABET[i]] = BigInt(i);
+for (let i = 0; i < UUID58_ALPHABET.length; i++) {
+    BASE58_MAP[UUID58_ALPHABET[i]] = BigInt(i);
 }
 /**
  * Error thrown when an invalid Base58 string is provided for decoding.
@@ -41,7 +41,7 @@ export function uuid58DecodeSafe(uuid58) {
         if (index === undefined) {
             return new Uuid58DecodeError(`Invalid Base58 character '${char}' found in input: ${uuid58}`);
         }
-        num = num * ALPHABET_LENGTH + index;
+        num = num * UUID58_LENGTH + index;
     }
     const hex = num.toString(16).padStart(32, "0");
     if (hex.length !== 32) {

package/esm/encode.js

@@ -1,5 +1,5 @@
 var _a;
-import { ALPHABET_LENGTH, BASE58_ALPHABET } from "./alphabet.js";
+import { UUID58_ALPHABET, UUID58_LENGTH } from "./alphabet.js";
 /**
  * Error thrown when an invalid UUID string is provided for encoding.
  * This includes strings that don't match the standard UUID format (32 hexadecimal characters with optional hyphens).
@@ -45,10 +45,10 @@ export function uuid58EncodeSafe(uuid) {
     }
     let encoded = "";
     do {
-        encoded = BASE58_ALPHABET[Number(num % ALPHABET_LENGTH)] + encoded;
-        num /= ALPHABET_LENGTH;
+        encoded = UUID58_ALPHABET[Number(num % UUID58_LENGTH)] + encoded;
+        num /= UUID58_LENGTH;
     } while (num > 0n);
-    return encoded.padStart(22, BASE58_ALPHABET[0]);
+    return encoded.padStart(22, UUID58_ALPHABET[0]);
 }
 /**
  * Converts a standard UUID string to a 22-character Base58-encoded format.

package/esm/{uuid58.d.ts → generate.d.ts}

@@ -12,4 +12,4 @@
  * ```
  */
 export declare function uuid58(): string;
-//# sourceMappingURL=uuid58.d.ts.map
+//# sourceMappingURL=generate.d.ts.map

package/esm/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAe/B"}

package/esm/{uuid58.js → generate.js}

@@ -1,4 +1,4 @@
-import { ALPHABET_LENGTH, BASE58_ALPHABET } from "./alphabet.js";
+import { UUID58_ALPHABET, UUID58_LENGTH } from "./alphabet.js";
 /**
  * Generates a new Base58-encoded UUID (always 22 characters).
  *
@@ -19,8 +19,8 @@ export function uuid58() {
     let num = bytes[0] << 64n | bytes[1];
     let encoded = "";
     do {
-        encoded = BASE58_ALPHABET[Number(num % ALPHABET_LENGTH)] + encoded;
-        num /= ALPHABET_LENGTH;
+        encoded = UUID58_ALPHABET[Number(num % UUID58_LENGTH)] + encoded;
+        num /= UUID58_LENGTH;
     } while (num > 0n);
-    return encoded.padStart(22, BASE58_ALPHABET[0]);
+    return encoded.padStart(22, UUID58_ALPHABET[0]);
 }

package/esm/index.d.ts

@@ -1,4 +1,5 @@
+export { UUID58_ALPHABET, UUID58_REGEX } from "./alphabet.js";
 export * from "./decode.js";
 export * from "./encode.js";
-export * from "./uuid58.js";
+export * from "./generate.js";
 //# sourceMappingURL=index.d.ts.map

package/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC9D,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}

package/esm/index.js

@@ -1,3 +1,4 @@
+export { UUID58_ALPHABET, UUID58_REGEX } from "./alphabet.js";
 export * from "./decode.js";
 export * from "./encode.js";
-export * from "./uuid58.js";
+export * from "./generate.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nakanoaas/uuid58",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "A tiny, zero-dependency library for generating and converting UUIDs to Base58-encoded strings.",
   "repository": {
     "type": "git",

package/script/alphabet.d.ts

@@ -1,3 +1,40 @@
-export declare const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
-export declare const ALPHABET_LENGTH: bigint;
+/**
+ * Character set for Base58 encoding (Bitcoin compatible).
+ *
+ * This alphabet excludes characters that can be easily confused:
+ * - `0` (zero) and `O` (capital O)
+ * - `I` (capital i) and `l` (lowercase L)
+ *
+ * The alphabet consists of 58 characters: digits 1-9 and letters A-Z, a-z
+ * (excluding the ambiguous characters mentioned above).
+ *
+ * @example
+ * ```typescript
+ * const char = UUID58_ALPHABET[0]; // "1"
+ * const char = UUID58_ALPHABET[9]; // "A"
+ * ```
+ */
+export declare const UUID58_ALPHABET: string;
+/**
+ * @internal
+ * The length of the Base58 alphabet as BigInt for encoding/decoding operations.
+ * This is exported for internal use but not part of the public API.
+ */
+export declare const UUID58_LENGTH: bigint;
+/**
+ * Regular expression pattern for validating UUID58 strings.
+ *
+ * This regex ensures that a string:
+ * - Contains exactly 22 characters
+ * - Uses only characters from the Base58 alphabet
+ * - Does not start with leading zeros (represented as "1" in Base58)
+ *
+ * @example
+ * ```typescript
+ * const isValid = UUID58_REGEX.test("XDY9dmBbcMBXqcRvYw8xJ2"); // true
+ * const isValid = UUID58_REGEX.test("invalid"); // false
+ * const isValid = UUID58_REGEX.test("123"); // false (too short)
+ * ```
+ */
+export declare const UUID58_REGEX: RegExp;
 //# sourceMappingURL=alphabet.d.ts.map

package/script/alphabet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alphabet.d.ts","sourceRoot":"","sources":["../src/alphabet.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,eAAe,+DACkC,CAAC;AAC/D,eAAO,MAAM,eAAe,QAAiC,CAAC"}
+{"version":3,"file":"alphabet.d.ts","sourceRoot":"","sources":["../src/alphabet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,EAAE,MACgC,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,MAAuC,CAAC;AAEpE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,MAAsC,CAAC"}

package/script/alphabet.js

@@ -1,6 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ALPHABET_LENGTH = exports.BASE58_ALPHABET = void 0;
-// Character set for Base58 (Bitcoin compatible)
-exports.BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"; // cspell:disable-line
-exports.ALPHABET_LENGTH = BigInt(exports.BASE58_ALPHABET.length);
+exports.UUID58_REGEX = exports.UUID58_LENGTH = exports.UUID58_ALPHABET = void 0;
+/**
+ * Character set for Base58 encoding (Bitcoin compatible).
+ *
+ * This alphabet excludes characters that can be easily confused:
+ * - `0` (zero) and `O` (capital O)
+ * - `I` (capital i) and `l` (lowercase L)
+ *
+ * The alphabet consists of 58 characters: digits 1-9 and letters A-Z, a-z
+ * (excluding the ambiguous characters mentioned above).
+ *
+ * @example
+ * ```typescript
+ * const char = UUID58_ALPHABET[0]; // "1"
+ * const char = UUID58_ALPHABET[9]; // "A"
+ * ```
+ */
+exports.UUID58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+/**
+ * @internal
+ * The length of the Base58 alphabet as BigInt for encoding/decoding operations.
+ * This is exported for internal use but not part of the public API.
+ */
+exports.UUID58_LENGTH = BigInt(exports.UUID58_ALPHABET.length);
+/**
+ * Regular expression pattern for validating UUID58 strings.
+ *
+ * This regex ensures that a string:
+ * - Contains exactly 22 characters
+ * - Uses only characters from the Base58 alphabet
+ * - Does not start with leading zeros (represented as "1" in Base58)
+ *
+ * @example
+ * ```typescript
+ * const isValid = UUID58_REGEX.test("XDY9dmBbcMBXqcRvYw8xJ2"); // true
+ * const isValid = UUID58_REGEX.test("invalid"); // false
+ * const isValid = UUID58_REGEX.test("123"); // false (too short)
+ * ```
+ */
+exports.UUID58_REGEX = /^[1-9A-HJ-NP-Za-km-z]{22}$/u;

package/script/decode.js

@@ -7,8 +7,8 @@ exports.uuid58Decode = uuid58Decode;
 const alphabet_js_1 = require("./alphabet.js");
 // Fast lookup map from alphabet characters to their indices
 const BASE58_MAP = {};
-for (let i = 0; i < alphabet_js_1.BASE58_ALPHABET.length; i++) {
-    BASE58_MAP[alphabet_js_1.BASE58_ALPHABET[i]] = BigInt(i);
+for (let i = 0; i < alphabet_js_1.UUID58_ALPHABET.length; i++) {
+    BASE58_MAP[alphabet_js_1.UUID58_ALPHABET[i]] = BigInt(i);
 }
 /**
  * Error thrown when an invalid Base58 string is provided for decoding.
@@ -47,7 +47,7 @@ function uuid58DecodeSafe(uuid58) {
         if (index === undefined) {
             return new Uuid58DecodeError(`Invalid Base58 character '${char}' found in input: ${uuid58}`);
         }
-        num = num * alphabet_js_1.ALPHABET_LENGTH + index;
+        num = num * alphabet_js_1.UUID58_LENGTH + index;
     }
     const hex = num.toString(16).padStart(32, "0");
     if (hex.length !== 32) {

package/script/encode.js

@@ -51,10 +51,10 @@ function uuid58EncodeSafe(uuid) {
     }
     let encoded = "";
     do {
-        encoded = alphabet_js_1.BASE58_ALPHABET[Number(num % alphabet_js_1.ALPHABET_LENGTH)] + encoded;
-        num /= alphabet_js_1.ALPHABET_LENGTH;
+        encoded = alphabet_js_1.UUID58_ALPHABET[Number(num % alphabet_js_1.UUID58_LENGTH)] + encoded;
+        num /= alphabet_js_1.UUID58_LENGTH;
     } while (num > 0n);
-    return encoded.padStart(22, alphabet_js_1.BASE58_ALPHABET[0]);
+    return encoded.padStart(22, alphabet_js_1.UUID58_ALPHABET[0]);
 }
 /**
  * Converts a standard UUID string to a 22-character Base58-encoded format.

package/script/{uuid58.d.ts → generate.d.ts}

@@ -12,4 +12,4 @@
  * ```
  */
 export declare function uuid58(): string;
-//# sourceMappingURL=uuid58.d.ts.map
+//# sourceMappingURL=generate.d.ts.map

package/script/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAe/B"}

package/script/{uuid58.js → generate.js}

@@ -22,8 +22,8 @@ function uuid58() {
     let num = bytes[0] << 64n | bytes[1];
     let encoded = "";
     do {
-        encoded = alphabet_js_1.BASE58_ALPHABET[Number(num % alphabet_js_1.ALPHABET_LENGTH)] + encoded;
-        num /= alphabet_js_1.ALPHABET_LENGTH;
+        encoded = alphabet_js_1.UUID58_ALPHABET[Number(num % alphabet_js_1.UUID58_LENGTH)] + encoded;
+        num /= alphabet_js_1.UUID58_LENGTH;
     } while (num > 0n);
-    return encoded.padStart(22, alphabet_js_1.BASE58_ALPHABET[0]);
+    return encoded.padStart(22, alphabet_js_1.UUID58_ALPHABET[0]);
 }

package/script/index.d.ts

@@ -1,4 +1,5 @@
+export { UUID58_ALPHABET, UUID58_REGEX } from "./alphabet.js";
 export * from "./decode.js";
 export * from "./encode.js";
-export * from "./uuid58.js";
+export * from "./generate.js";
 //# sourceMappingURL=index.d.ts.map

package/script/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC9D,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}

package/script/index.js

@@ -14,6 +14,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.UUID58_REGEX = exports.UUID58_ALPHABET = void 0;
+var alphabet_js_1 = require("./alphabet.js");
+Object.defineProperty(exports, "UUID58_ALPHABET", { enumerable: true, get: function () { return alphabet_js_1.UUID58_ALPHABET; } });
+Object.defineProperty(exports, "UUID58_REGEX", { enumerable: true, get: function () { return alphabet_js_1.UUID58_REGEX; } });
 __exportStar(require("./decode.js"), exports);
 __exportStar(require("./encode.js"), exports);
-__exportStar(require("./uuid58.js"), exports);
+__exportStar(require("./generate.js"), exports);

package/esm/uuid58.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"uuid58.d.ts","sourceRoot":"","sources":["../src/uuid58.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAe/B"}

package/script/uuid58.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"uuid58.d.ts","sourceRoot":"","sources":["../src/uuid58.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAe/B"}