@nakanoaas/uuid58 0.0.7 → 1.0.0

package/README.md

@@ -10,12 +10,13 @@ shorter, URL-safe identifiers while maintaining the uniqueness of UUIDs.
 
 ## Features
 
-- 🚀 Generate short, URL-safe identifiers (~22 characters)
+- 🚀 Generate short, URL-safe identifiers (**fixed 22 characters**)
 - 🔄 Bidirectional conversion between UUID and Base58
 - 🪶 Zero dependencies
 - 💪 Type-safe with TypeScript
 - 🔒 Uses native `crypto.randomUUID()` for secure UUID generation
 - 📦 Supports both ESM and CommonJS
+- 🛡️ Provides safe APIs that return error objects instead of throwing exceptions
 
 ## Installation
 
@@ -50,13 +51,13 @@ pnpm add @nakanoaas/uuid58
 ```typescript
 import { uuid58, uuid58Decode, uuid58Encode } from "@nakanoaas/uuid58";
 
-// Generate a new Base58-encoded UUID
+// Generate a new Base58-encoded UUID (always 22 characters)
 const id = uuid58();
-// => "XDY9dmBbcMBXqcRvYw8xJ2"
+// => "XDY9dmBbcMBXqcRvYw8xJ2" (22 characters)
 
-// Convert existing UUID to Base58
+// Convert existing UUID to Base58 (always 22 characters)
 const encoded = uuid58Encode("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf");
-// => "XDY9dmBbcMBXqcRvYw8xJ2"
+// => "XDY9dmBbcMBXqcRvYw8xJ2" (22 characters)
 
 // Convert Base58 back to UUID
 const decoded = uuid58Decode("XDY9dmBbcMBXqcRvYw8xJ2");
@@ -76,7 +77,7 @@ if (encodedSafe instanceof Uuid58EncodeError) {
   console.error(encodedSafe.message);
   return;
 }
-// use encoded string
+// use encoded string (22 characters)
 console.log(encodedSafe);
 
 // Safe decoding: returns error object instead of throwing
@@ -94,74 +95,76 @@ console.log(decodedSafe);
 
 ### `uuid58()`
 
-Generates a new Base58-encoded UUID.
+Generates a new Base58-encoded UUID (always 22 characters).
 
 ```typescript
-function uuid58(): string;
+function uuid58(): string; // always returns a 22-character string
 ```
 
 ### `uuid58Encode(uuid: string)`
 
-Converts a standard UUID string to a Base58-encoded format.
+Converts a standard UUID string to a 22-character Base58-encoded format.
 
 ```typescript
-function uuid58Encode(uuid: string): string;
+function uuid58Encode(uuid: string): string; // always returns a 22-character string
 ```
 
 - **Parameters:**
   - `uuid`: The UUID string to encode (with or without hyphens)
-- **Returns:** A Base58-encoded string
+- **Returns:** A 22-character Base58-encoded string
 - **Throws:** `Uuid58EncodeError` if the input is not a valid UUID
 
 ### `uuid58EncodeSafe(uuid: string)`
 
-Converts a standard UUID string to a Base58-encoded format, but instead of
-throwing an error for invalid input, it returns an `Uuid58EncodeError` instance.
+Converts a standard UUID string to a 22-character Base58-encoded format, but
+instead of throwing an error for invalid input, it returns an
+`Uuid58EncodeError` instance.
 
 ```typescript
-function uuid58EncodeSafe(uuid: string): string | Uuid58EncodeError;
+function uuid58EncodeSafe(uuid: string): string | Uuid58EncodeError; // string is always 22 characters
 ```
 
 - **Parameters:**
   - `uuid`: The UUID string to encode (with or without hyphens)
-- **Returns:** A Base58-encoded string, or an `Uuid58EncodeError` if the input
-  is not a valid UUID
+- **Returns:** A 22-character Base58-encoded string, or an `Uuid58EncodeError`
+  if the input is not a valid UUID
 - **Note:** This function does not throw; it returns the error object instead.
 
 ### `uuid58Decode(encoded: string)`
 
-Converts a Base58-encoded string back to a standard UUID format.
+Converts a 22-character Base58-encoded string back to a standard UUID format.
 
 ```typescript
-function uuid58Decode(encoded: string): string;
+function uuid58Decode(uuid58: string): string;
 ```
 
 - **Parameters:**
-  - `encoded`: The Base58-encoded string to decode
+  - `uuid58`: The 22-character Base58-encoded string to decode
 - **Returns:** A standard UUID string (lowercase, with hyphens)
-- **Throws:** `Uuid58DecodeError` if the input contains invalid Base58
-  characters
+- **Throws:** `Uuid58DecodeError` if the input is not a valid 22-character
+  Base58 string
 
 ### `uuid58DecodeSafe(encoded: string)`
 
-Converts a Base58-encoded string back to a standard UUID format, but instead of
-throwing an error for invalid input, it returns an `Uuid58DecodeError` instance.
+Converts a 22-character Base58-encoded string back to a standard UUID format,
+but instead of throwing an error for invalid input, it returns an
+`Uuid58DecodeError` instance.
 
 ```typescript
-function uuid58DecodeSafe(encoded: string): string | Uuid58DecodeError;
+function uuid58DecodeSafe(uuid58: string): string | Uuid58DecodeError;
 ```
 
 - **Parameters:**
-  - `encoded`: The Base58-encoded string to decode
+  - `uuid58`: The 22-character Base58-encoded string to decode
 - **Returns:** A standard UUID string (lowercase, with hyphens), or an
-  `Uuid58DecodeError` if the input contains invalid Base58 characters
+  `Uuid58DecodeError` if the input is not a valid 22-character Base58 string
 - **Note:** This function does not throw; it returns the error object instead.
 
 ## Why uuid58?
 
 Standard UUIDs are 36 characters long (including hyphens), which can be
-cumbersome in URLs or when space is limited. Base58 encoding reduces this to
-around 22 characters while maintaining uniqueness and using only URL-safe
+cumbersome in URLs or when space is limited. Base58 encoding reduces this to a
+fixed 22 characters while maintaining uniqueness and using only URL-safe
 characters. The Base58 alphabet used in this library is the same as Bitcoin's,
 which excludes similar-looking characters (0, O, I, l) to prevent visual
 ambiguity and confusion.

package/esm/decode.d.ts

@@ -5,13 +5,13 @@
 export declare class Uuid58DecodeError extends Error {
 }
 /**
- * Converts a Base58-encoded string back to a standard UUID format, but instead of
+ * Converts a 22-character Base58-encoded string back to a standard UUID format, but instead of
  * throwing an error for invalid input, it returns an `Uuid58DecodeError`
  * instance.
  *
- * @param base58 - The Base58-encoded string to decode
+ * @param uuid58 - The 22-character Base58-encoded UUID string to decode
  * @returns A standard UUID string (lowercase, with hyphens), or an
- *   `Uuid58DecodeError` if the input contains invalid Base58 characters
+ *   `Uuid58DecodeError` if the input is not a valid 22-character Base58 string
  * @note This function does not throw; it returns the error object instead.
  *
  * @example
@@ -20,18 +20,18 @@ export declare class Uuid58DecodeError extends Error {
  * const error = uuid58DecodeSafe("invalid"); // returns Uuid58DecodeError
  * ```
  */
-export declare function uuid58DecodeSafe(base58: string): string | Uuid58DecodeError;
+export declare function uuid58DecodeSafe(uuid58: string): string | Uuid58DecodeError;
 /**
- * Converts a Base58-encoded string back to a standard UUID string format.
+ * Converts a 22-character Base58-encoded string back to a standard UUID string format.
  *
- * @param base58 - The Base58-encoded string to decode
+ * @param uuid58 - The 22-character Base58-encoded string to decode
  * @returns A standard UUID string in the format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (always in lowercase)
- * @throws {Uuid58DecodeError} If the input string contains characters not in the Base58 alphabet
+ * @throws {Uuid58DecodeError} If the input string is not a valid 22-character Base58 string
  *
  * @example
  * ```typescript
  * const uuid = uuid58Decode("XDY9dmBbcMBXqcRvYw8xJ2"); // returns "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
  * ```
  */
-export declare function uuid58Decode(base58: string): string;
+export declare function uuid58Decode(uuid58: string): string;
 //# sourceMappingURL=decode.d.ts.map

package/esm/decode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../src/decode.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;CAI3C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CA4B3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CA4BnD"}
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../src/decode.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;CAI3C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAoC3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMnD"}

package/esm/decode.js

@@ -16,13 +16,13 @@ _a = Uuid58DecodeError;
     _a.prototype.name = "Uuid58DecodeError";
 })();
 /**
- * Converts a Base58-encoded string back to a standard UUID format, but instead of
+ * Converts a 22-character Base58-encoded string back to a standard UUID format, but instead of
  * throwing an error for invalid input, it returns an `Uuid58DecodeError`
  * instance.
  *
- * @param base58 - The Base58-encoded string to decode
+ * @param uuid58 - The 22-character Base58-encoded UUID string to decode
  * @returns A standard UUID string (lowercase, with hyphens), or an
- *   `Uuid58DecodeError` if the input contains invalid Base58 characters
+ *   `Uuid58DecodeError` if the input is not a valid 22-character Base58 string
  * @note This function does not throw; it returns the error object instead.
  *
  * @example
@@ -31,18 +31,21 @@ _a = Uuid58DecodeError;
  * const error = uuid58DecodeSafe("invalid"); // returns Uuid58DecodeError
  * ```
  */
-export function uuid58DecodeSafe(base58) {
+export function uuid58DecodeSafe(uuid58) {
+    if (uuid58.length !== 22) {
+        return new Uuid58DecodeError(`Base58 string must be exactly 22 characters: ${uuid58}`);
+    }
     let num = 0n;
-    for (const char of base58) {
+    for (const char of uuid58) {
         const index = BASE58_MAP[char];
         if (index === undefined) {
-            return new Uuid58DecodeError(`Character '${char}' is not a valid Base58 character in string: ${base58}`);
+            return new Uuid58DecodeError(`Invalid Base58 character '${char}' found in input: ${uuid58}`);
         }
         num = num * ALPHABET_LENGTH + index;
     }
     const hex = num.toString(16).padStart(32, "0");
     if (hex.length !== 32) {
-        return new Uuid58DecodeError(`length not 32: ${base58}`);
+        return new Uuid58DecodeError(`Decoded hexadecimal string is not 32 characters: ${uuid58}`);
     }
     return (hex.slice(0, 8) +
         "-" +
@@ -55,37 +58,21 @@ export function uuid58DecodeSafe(base58) {
         hex.slice(20));
 }
 /**
- * Converts a Base58-encoded string back to a standard UUID string format.
+ * Converts a 22-character Base58-encoded string back to a standard UUID string format.
  *
- * @param base58 - The Base58-encoded string to decode
+ * @param uuid58 - The 22-character Base58-encoded string to decode
  * @returns A standard UUID string in the format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (always in lowercase)
- * @throws {Uuid58DecodeError} If the input string contains characters not in the Base58 alphabet
+ * @throws {Uuid58DecodeError} If the input string is not a valid 22-character Base58 string
  *
  * @example
  * ```typescript
  * const uuid = uuid58Decode("XDY9dmBbcMBXqcRvYw8xJ2"); // returns "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
  * ```
  */
-export function uuid58Decode(base58) {
-    let num = 0n;
-    for (const char of base58) {
-        const index = BASE58_MAP[char];
-        if (index === undefined) {
-            throw new Uuid58DecodeError(`Character '${char}' is not a valid Base58 character in string: ${base58}`);
-        }
-        num = num * ALPHABET_LENGTH + index;
-    }
-    const hex = num.toString(16).padStart(32, "0");
-    if (hex.length !== 32) {
-        throw new Uuid58DecodeError(`length not 32: ${base58}`);
+export function uuid58Decode(uuid58) {
+    const result = uuid58DecodeSafe(uuid58);
+    if (result instanceof Uuid58DecodeError) {
+        throw result;
     }
-    return (hex.slice(0, 8) +
-        "-" +
-        hex.slice(8, 12) +
-        "-" +
-        hex.slice(12, 16) +
-        "-" +
-        hex.slice(16, 20) +
-        "-" +
-        hex.slice(20));
+    return result;
 }

package/esm/encode.d.ts

@@ -5,11 +5,11 @@
 export declare class Uuid58EncodeError extends Error {
 }
 /**
- * Converts a standard UUID string to a Base58-encoded format, but instead of
+ * Converts a standard UUID string to a 22-character Base58-encoded format, but instead of
  * throwing an error for invalid input, it returns an `Uuid58EncodeError` instance.
  *
  * @param uuid - The UUID string to encode (with or without hyphens)
- * @returns A Base58-encoded string, or an `Uuid58EncodeError` if the input is
+ * @returns A 22-character Base58-encoded string, or an `Uuid58EncodeError` if the input is
  *   not a valid UUID
  * @note This function does not throw; it returns the error object instead.
  *
@@ -27,12 +27,12 @@ export declare class Uuid58EncodeError extends Error {
  */
 export declare function uuid58EncodeSafe(uuid: string): string | Uuid58EncodeError;
 /**
- * Converts a standard UUID string to a shortened Base58-encoded format.
+ * Converts a standard UUID string to a 22-character Base58-encoded format.
  *
  * @param uuid - The UUID string to encode. Can be provided with or without hyphens
  *              (format: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" or "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx").
  *              The input is case-insensitive, so both uppercase and lowercase hexadecimal characters are accepted.
- * @returns A Base58-encoded string representation of the UUID
+ * @returns A 22-character Base58-encoded string representation of the UUID
  * @throws {Uuid58EncodeError} If the input string is not a valid UUID format
  *
  * @example

package/esm/encode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../src/encode.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;CAI3C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAwBzE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAwBjD"}
+{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../src/encode.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;CAI3C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAwBzE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMjD"}

package/esm/encode.js

@@ -11,11 +11,11 @@ _a = Uuid58EncodeError;
     _a.prototype.name = "Uuid58EncodeError";
 })();
 /**
- * Converts a standard UUID string to a Base58-encoded format, but instead of
+ * Converts a standard UUID string to a 22-character Base58-encoded format, but instead of
  * throwing an error for invalid input, it returns an `Uuid58EncodeError` instance.
  *
  * @param uuid - The UUID string to encode (with or without hyphens)
- * @returns A Base58-encoded string, or an `Uuid58EncodeError` if the input is
+ * @returns A 22-character Base58-encoded string, or an `Uuid58EncodeError` if the input is
  *   not a valid UUID
  * @note This function does not throw; it returns the error object instead.
  *
@@ -48,15 +48,15 @@ export function uuid58EncodeSafe(uuid) {
         encoded = BASE58_ALPHABET[Number(num % ALPHABET_LENGTH)] + encoded;
         num /= ALPHABET_LENGTH;
     } while (num > 0n);
-    return encoded;
+    return encoded.padStart(22, BASE58_ALPHABET[0]);
 }
 /**
- * Converts a standard UUID string to a shortened Base58-encoded format.
+ * Converts a standard UUID string to a 22-character Base58-encoded format.
  *
  * @param uuid - The UUID string to encode. Can be provided with or without hyphens
  *              (format: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" or "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx").
  *              The input is case-insensitive, so both uppercase and lowercase hexadecimal characters are accepted.
- * @returns A Base58-encoded string representation of the UUID
+ * @returns A 22-character Base58-encoded string representation of the UUID
  * @throws {Uuid58EncodeError} If the input string is not a valid UUID format
  *
  * @example
@@ -70,21 +70,9 @@ export function uuid58EncodeSafe(uuid) {
  * ```
  */
 export function uuid58Encode(uuid) {
-    const hex = uuid.replaceAll("-", "");
-    if (hex.length !== 32) {
-        throw new Uuid58EncodeError(`Invalid UUID length: expected 32 characters (excluding hyphens), got ${hex.length} characters in "${uuid}"`);
+    const result = uuid58EncodeSafe(uuid);
+    if (result instanceof Uuid58EncodeError) {
+        throw result;
     }
-    let num;
-    try {
-        num = BigInt("0x" + hex);
-    }
-    catch {
-        throw new Uuid58EncodeError(`Invalid UUID format: "${uuid}" contains non-hexadecimal characters`);
-    }
-    let encoded = "";
-    do {
-        encoded = BASE58_ALPHABET[Number(num % ALPHABET_LENGTH)] + encoded;
-        num /= ALPHABET_LENGTH;
-    } while (num > 0n);
-    return encoded;
+    return result;
 }

package/esm/uuid58.d.ts

@@ -1,14 +1,14 @@
 /**
- * Generates a new Base58-encoded UUID.
+ * Generates a new Base58-encoded UUID (always 22 characters).
  *
  * This function combines the standard UUID generation (using crypto.randomUUID())
  * with Base58 encoding to create a shorter, URL-safe identifier.
  *
- * @returns A Base58-encoded string representing a newly generated UUID
+ * @returns A 22-character Base58-encoded string representing a newly generated UUID
  *
  * @example
  * ```typescript
- * const id = uuid58(); // returns something like "XDY9dmBbcMBXqcRvYw8xJ2"
+ * const id = uuid58(); // returns a 22-character string like "XDY9dmBbcMBXqcRvYw8xJ2"
  * ```
  */
 export declare function uuid58(): string;

package/esm/uuid58.js

@@ -1,15 +1,15 @@
 import { ALPHABET_LENGTH, BASE58_ALPHABET } from "./alphabet.js";
 /**
- * Generates a new Base58-encoded UUID.
+ * Generates a new Base58-encoded UUID (always 22 characters).
  *
  * This function combines the standard UUID generation (using crypto.randomUUID())
  * with Base58 encoding to create a shorter, URL-safe identifier.
  *
- * @returns A Base58-encoded string representing a newly generated UUID
+ * @returns A 22-character Base58-encoded string representing a newly generated UUID
  *
  * @example
  * ```typescript
- * const id = uuid58(); // returns something like "XDY9dmBbcMBXqcRvYw8xJ2"
+ * const id = uuid58(); // returns a 22-character string like "XDY9dmBbcMBXqcRvYw8xJ2"
  * ```
  */
 export function uuid58() {
@@ -19,5 +19,5 @@ export function uuid58() {
         encoded = BASE58_ALPHABET[Number(num % ALPHABET_LENGTH)] + encoded;
         num /= ALPHABET_LENGTH;
     } while (num > 0n);
-    return encoded;
+    return encoded.padStart(22, BASE58_ALPHABET[0]);
 }

package/package.json

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

package/script/decode.d.ts

@@ -5,13 +5,13 @@
 export declare class Uuid58DecodeError extends Error {
 }
 /**
- * Converts a Base58-encoded string back to a standard UUID format, but instead of
+ * Converts a 22-character Base58-encoded string back to a standard UUID format, but instead of
  * throwing an error for invalid input, it returns an `Uuid58DecodeError`
  * instance.
  *
- * @param base58 - The Base58-encoded string to decode
+ * @param uuid58 - The 22-character Base58-encoded UUID string to decode
  * @returns A standard UUID string (lowercase, with hyphens), or an
- *   `Uuid58DecodeError` if the input contains invalid Base58 characters
+ *   `Uuid58DecodeError` if the input is not a valid 22-character Base58 string
  * @note This function does not throw; it returns the error object instead.
  *
  * @example
@@ -20,18 +20,18 @@ export declare class Uuid58DecodeError extends Error {
  * const error = uuid58DecodeSafe("invalid"); // returns Uuid58DecodeError
  * ```
  */
-export declare function uuid58DecodeSafe(base58: string): string | Uuid58DecodeError;
+export declare function uuid58DecodeSafe(uuid58: string): string | Uuid58DecodeError;
 /**
- * Converts a Base58-encoded string back to a standard UUID string format.
+ * Converts a 22-character Base58-encoded string back to a standard UUID string format.
  *
- * @param base58 - The Base58-encoded string to decode
+ * @param uuid58 - The 22-character Base58-encoded string to decode
  * @returns A standard UUID string in the format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (always in lowercase)
- * @throws {Uuid58DecodeError} If the input string contains characters not in the Base58 alphabet
+ * @throws {Uuid58DecodeError} If the input string is not a valid 22-character Base58 string
  *
  * @example
  * ```typescript
  * const uuid = uuid58Decode("XDY9dmBbcMBXqcRvYw8xJ2"); // returns "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
  * ```
  */
-export declare function uuid58Decode(base58: string): string;
+export declare function uuid58Decode(uuid58: string): string;
 //# sourceMappingURL=decode.d.ts.map

package/script/decode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../src/decode.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;CAI3C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CA4B3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CA4BnD"}
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../src/decode.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;CAI3C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAoC3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMnD"}

package/script/decode.js

@@ -22,13 +22,13 @@ _a = Uuid58DecodeError;
     _a.prototype.name = "Uuid58DecodeError";
 })();
 /**
- * Converts a Base58-encoded string back to a standard UUID format, but instead of
+ * Converts a 22-character Base58-encoded string back to a standard UUID format, but instead of
  * throwing an error for invalid input, it returns an `Uuid58DecodeError`
  * instance.
  *
- * @param base58 - The Base58-encoded string to decode
+ * @param uuid58 - The 22-character Base58-encoded UUID string to decode
  * @returns A standard UUID string (lowercase, with hyphens), or an
- *   `Uuid58DecodeError` if the input contains invalid Base58 characters
+ *   `Uuid58DecodeError` if the input is not a valid 22-character Base58 string
  * @note This function does not throw; it returns the error object instead.
  *
  * @example
@@ -37,18 +37,21 @@ _a = Uuid58DecodeError;
  * const error = uuid58DecodeSafe("invalid"); // returns Uuid58DecodeError
  * ```
  */
-function uuid58DecodeSafe(base58) {
+function uuid58DecodeSafe(uuid58) {
+    if (uuid58.length !== 22) {
+        return new Uuid58DecodeError(`Base58 string must be exactly 22 characters: ${uuid58}`);
+    }
     let num = 0n;
-    for (const char of base58) {
+    for (const char of uuid58) {
         const index = BASE58_MAP[char];
         if (index === undefined) {
-            return new Uuid58DecodeError(`Character '${char}' is not a valid Base58 character in string: ${base58}`);
+            return new Uuid58DecodeError(`Invalid Base58 character '${char}' found in input: ${uuid58}`);
         }
         num = num * alphabet_js_1.ALPHABET_LENGTH + index;
     }
     const hex = num.toString(16).padStart(32, "0");
     if (hex.length !== 32) {
-        return new Uuid58DecodeError(`length not 32: ${base58}`);
+        return new Uuid58DecodeError(`Decoded hexadecimal string is not 32 characters: ${uuid58}`);
     }
     return (hex.slice(0, 8) +
         "-" +
@@ -61,37 +64,21 @@ function uuid58DecodeSafe(base58) {
         hex.slice(20));
 }
 /**
- * Converts a Base58-encoded string back to a standard UUID string format.
+ * Converts a 22-character Base58-encoded string back to a standard UUID string format.
  *
- * @param base58 - The Base58-encoded string to decode
+ * @param uuid58 - The 22-character Base58-encoded string to decode
  * @returns A standard UUID string in the format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (always in lowercase)
- * @throws {Uuid58DecodeError} If the input string contains characters not in the Base58 alphabet
+ * @throws {Uuid58DecodeError} If the input string is not a valid 22-character Base58 string
  *
  * @example
  * ```typescript
  * const uuid = uuid58Decode("XDY9dmBbcMBXqcRvYw8xJ2"); // returns "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
  * ```
  */
-function uuid58Decode(base58) {
-    let num = 0n;
-    for (const char of base58) {
-        const index = BASE58_MAP[char];
-        if (index === undefined) {
-            throw new Uuid58DecodeError(`Character '${char}' is not a valid Base58 character in string: ${base58}`);
-        }
-        num = num * alphabet_js_1.ALPHABET_LENGTH + index;
-    }
-    const hex = num.toString(16).padStart(32, "0");
-    if (hex.length !== 32) {
-        throw new Uuid58DecodeError(`length not 32: ${base58}`);
+function uuid58Decode(uuid58) {
+    const result = uuid58DecodeSafe(uuid58);
+    if (result instanceof Uuid58DecodeError) {
+        throw result;
     }
-    return (hex.slice(0, 8) +
-        "-" +
-        hex.slice(8, 12) +
-        "-" +
-        hex.slice(12, 16) +
-        "-" +
-        hex.slice(16, 20) +
-        "-" +
-        hex.slice(20));
+    return result;
 }

package/script/encode.d.ts

@@ -5,11 +5,11 @@
 export declare class Uuid58EncodeError extends Error {
 }
 /**
- * Converts a standard UUID string to a Base58-encoded format, but instead of
+ * Converts a standard UUID string to a 22-character Base58-encoded format, but instead of
  * throwing an error for invalid input, it returns an `Uuid58EncodeError` instance.
  *
  * @param uuid - The UUID string to encode (with or without hyphens)
- * @returns A Base58-encoded string, or an `Uuid58EncodeError` if the input is
+ * @returns A 22-character Base58-encoded string, or an `Uuid58EncodeError` if the input is
  *   not a valid UUID
  * @note This function does not throw; it returns the error object instead.
  *
@@ -27,12 +27,12 @@ export declare class Uuid58EncodeError extends Error {
  */
 export declare function uuid58EncodeSafe(uuid: string): string | Uuid58EncodeError;
 /**
- * Converts a standard UUID string to a shortened Base58-encoded format.
+ * Converts a standard UUID string to a 22-character Base58-encoded format.
  *
  * @param uuid - The UUID string to encode. Can be provided with or without hyphens
  *              (format: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" or "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx").
  *              The input is case-insensitive, so both uppercase and lowercase hexadecimal characters are accepted.
- * @returns A Base58-encoded string representation of the UUID
+ * @returns A 22-character Base58-encoded string representation of the UUID
  * @throws {Uuid58EncodeError} If the input string is not a valid UUID format
  *
  * @example

package/script/encode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../src/encode.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;CAI3C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAwBzE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAwBjD"}
+{"version":3,"file":"encode.d.ts","sourceRoot":"","sources":["../src/encode.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;CAI3C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAwBzE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMjD"}

package/script/encode.js

@@ -17,11 +17,11 @@ _a = Uuid58EncodeError;
     _a.prototype.name = "Uuid58EncodeError";
 })();
 /**
- * Converts a standard UUID string to a Base58-encoded format, but instead of
+ * Converts a standard UUID string to a 22-character Base58-encoded format, but instead of
  * throwing an error for invalid input, it returns an `Uuid58EncodeError` instance.
  *
  * @param uuid - The UUID string to encode (with or without hyphens)
- * @returns A Base58-encoded string, or an `Uuid58EncodeError` if the input is
+ * @returns A 22-character Base58-encoded string, or an `Uuid58EncodeError` if the input is
  *   not a valid UUID
  * @note This function does not throw; it returns the error object instead.
  *
@@ -54,15 +54,15 @@ function uuid58EncodeSafe(uuid) {
         encoded = alphabet_js_1.BASE58_ALPHABET[Number(num % alphabet_js_1.ALPHABET_LENGTH)] + encoded;
         num /= alphabet_js_1.ALPHABET_LENGTH;
     } while (num > 0n);
-    return encoded;
+    return encoded.padStart(22, alphabet_js_1.BASE58_ALPHABET[0]);
 }
 /**
- * Converts a standard UUID string to a shortened Base58-encoded format.
+ * Converts a standard UUID string to a 22-character Base58-encoded format.
  *
  * @param uuid - The UUID string to encode. Can be provided with or without hyphens
  *              (format: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" or "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx").
  *              The input is case-insensitive, so both uppercase and lowercase hexadecimal characters are accepted.
- * @returns A Base58-encoded string representation of the UUID
+ * @returns A 22-character Base58-encoded string representation of the UUID
  * @throws {Uuid58EncodeError} If the input string is not a valid UUID format
  *
  * @example
@@ -76,21 +76,9 @@ function uuid58EncodeSafe(uuid) {
  * ```
  */
 function uuid58Encode(uuid) {
-    const hex = uuid.replaceAll("-", "");
-    if (hex.length !== 32) {
-        throw new Uuid58EncodeError(`Invalid UUID length: expected 32 characters (excluding hyphens), got ${hex.length} characters in "${uuid}"`);
+    const result = uuid58EncodeSafe(uuid);
+    if (result instanceof Uuid58EncodeError) {
+        throw result;
     }
-    let num;
-    try {
-        num = BigInt("0x" + hex);
-    }
-    catch {
-        throw new Uuid58EncodeError(`Invalid UUID format: "${uuid}" contains non-hexadecimal characters`);
-    }
-    let encoded = "";
-    do {
-        encoded = alphabet_js_1.BASE58_ALPHABET[Number(num % alphabet_js_1.ALPHABET_LENGTH)] + encoded;
-        num /= alphabet_js_1.ALPHABET_LENGTH;
-    } while (num > 0n);
-    return encoded;
+    return result;
 }

package/script/uuid58.d.ts

@@ -1,14 +1,14 @@
 /**
- * Generates a new Base58-encoded UUID.
+ * Generates a new Base58-encoded UUID (always 22 characters).
  *
  * This function combines the standard UUID generation (using crypto.randomUUID())
  * with Base58 encoding to create a shorter, URL-safe identifier.
  *
- * @returns A Base58-encoded string representing a newly generated UUID
+ * @returns A 22-character Base58-encoded string representing a newly generated UUID
  *
  * @example
  * ```typescript
- * const id = uuid58(); // returns something like "XDY9dmBbcMBXqcRvYw8xJ2"
+ * const id = uuid58(); // returns a 22-character string like "XDY9dmBbcMBXqcRvYw8xJ2"
  * ```
  */
 export declare function uuid58(): string;

package/script/uuid58.js

@@ -3,16 +3,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.uuid58 = uuid58;
 const alphabet_js_1 = require("./alphabet.js");
 /**
- * Generates a new Base58-encoded UUID.
+ * Generates a new Base58-encoded UUID (always 22 characters).
  *
  * This function combines the standard UUID generation (using crypto.randomUUID())
  * with Base58 encoding to create a shorter, URL-safe identifier.
  *
- * @returns A Base58-encoded string representing a newly generated UUID
+ * @returns A 22-character Base58-encoded string representing a newly generated UUID
  *
  * @example
  * ```typescript
- * const id = uuid58(); // returns something like "XDY9dmBbcMBXqcRvYw8xJ2"
+ * const id = uuid58(); // returns a 22-character string like "XDY9dmBbcMBXqcRvYw8xJ2"
  * ```
  */
 function uuid58() {
@@ -22,5 +22,5 @@ function uuid58() {
         encoded = alphabet_js_1.BASE58_ALPHABET[Number(num % alphabet_js_1.ALPHABET_LENGTH)] + encoded;
         num /= alphabet_js_1.ALPHABET_LENGTH;
     } while (num > 0n);
-    return encoded;
+    return encoded.padStart(22, alphabet_js_1.BASE58_ALPHABET[0]);
 }