@nakanoaas/uuid58 0.0.4 → 0.0.6

package/README.md

@@ -61,6 +61,33 @@ const encoded = uuid58Encode("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf");
 // Convert Base58 back to UUID
 const decoded = uuid58Decode("XDY9dmBbcMBXqcRvYw8xJ2");
 // => "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
+
+import {
+  Uuid58DecodeError,
+  uuid58DecodeSafe,
+  Uuid58EncodeError,
+  uuid58EncodeSafe,
+} from "@nakanoaas/uuid58";
+
+// Safe encoding: returns error object instead of throwing
+const encodedSafe = uuid58EncodeSafe("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf");
+if (encodedSafe instanceof Uuid58EncodeError) {
+  // handle error
+  console.error(encodedSafe.message);
+  return;
+}
+// use encoded string
+console.log(encodedSafe);
+
+// Safe decoding: returns error object instead of throwing
+const decodedSafe = uuid58DecodeSafe("XDY9dmBbcMBXqcRvYw8xJ2");
+if (decodedSafe instanceof Uuid58DecodeError) {
+  // handle error
+  console.error(decodedSafe.message);
+  return;
+}
+// use decoded UUID
+console.log(decodedSafe);
 ```
 
 ## API Reference
@@ -84,7 +111,22 @@ function uuid58Encode(uuid: string): string;
 - **Parameters:**
   - `uuid`: The UUID string to encode (with or without hyphens)
 - **Returns:** A Base58-encoded string
-- **Throws:** `InvalidUuidError` if the input is not a valid UUID
+- **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.
+
+```typescript
+function uuid58EncodeSafe(uuid: string): string | Uuid58EncodeError;
+```
+
+- **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
+- **Note:** This function does not throw; it returns the error object instead.
 
 ### `uuid58Decode(encoded: string)`
 
@@ -97,9 +139,24 @@ function uuid58Decode(encoded: string): string;
 - **Parameters:**
   - `encoded`: The Base58-encoded string to decode
 - **Returns:** A standard UUID string (lowercase, with hyphens)
-- **Throws:** `InvalidBase58Error` if the input contains invalid Base58
+- **Throws:** `Uuid58DecodeError` if the input contains invalid Base58
   characters
 
+### `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.
+
+```typescript
+function uuid58DecodeSafe(encoded: string): string | Uuid58DecodeError;
+```
+
+- **Parameters:**
+  - `encoded`: The Base58-encoded string to decode
+- **Returns:** A standard UUID string (lowercase, with hyphens), or an
+  `Uuid58DecodeError` if the input contains invalid Base58 characters
+- **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

package/esm/decode.d.ts

@@ -2,15 +2,31 @@
  * Error thrown when an invalid Base58 string is provided for decoding.
  * This includes strings containing characters not in the Base58 alphabet.
  */
-export declare class InvalidBase58Error extends Error {
-    constructor(base58: string);
+export declare class Uuid58DecodeError extends Error {
 }
+/**
+ * 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.
+ *
+ * @param base58 - The Base58-encoded string to decode
+ * @returns A standard UUID string (lowercase, with hyphens), or an
+ *   `Uuid58DecodeError` if the input contains invalid Base58 characters
+ * @note This function does not throw; it returns the error object instead.
+ *
+ * @example
+ * ```typescript
+ * const uuid = uuid58DecodeSafe("XDY9dmBbcMBXqcRvYw8xJ2"); // returns "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
+ * const error = uuid58DecodeSafe("invalid"); // returns Uuid58DecodeError
+ * ```
+ */
+export declare function uuid58DecodeSafe(base58: string): string | Uuid58DecodeError;
 /**
  * Converts a Base58-encoded string back to a standard UUID string format.
  *
  * @param base58 - The Base58-encoded string to decode
  * @returns A standard UUID string in the format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (always in lowercase)
- * @throws {InvalidBase58Error} If the input string contains characters not in the Base58 alphabet
+ * @throws {Uuid58DecodeError} If the input string contains characters not in the Base58 alphabet
  *
  * @example
  * ```typescript

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,kBAAmB,SAAQ,KAAK;gBAK/B,MAAM,EAAE,MAAM;CAG3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CA0BnD"}
+{"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,CA0BnD"}

package/esm/decode.js

@@ -9,21 +9,57 @@ for (let i = 0; i < BASE58_ALPHABET.length; i++) {
  * Error thrown when an invalid Base58 string is provided for decoding.
  * This includes strings containing characters not in the Base58 alphabet.
  */
-export class InvalidBase58Error extends Error {
-    constructor(base58) {
-        super(`Invalid Base58 string: ${base58}`);
-    }
+export class Uuid58DecodeError extends Error {
 }
-_a = InvalidBase58Error;
+_a = Uuid58DecodeError;
 (() => {
-    _a.prototype.name = "InvalidBase58Error";
+    _a.prototype.name = "Uuid58DecodeError";
 })();
+/**
+ * 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.
+ *
+ * @param base58 - The Base58-encoded string to decode
+ * @returns A standard UUID string (lowercase, with hyphens), or an
+ *   `Uuid58DecodeError` if the input contains invalid Base58 characters
+ * @note This function does not throw; it returns the error object instead.
+ *
+ * @example
+ * ```typescript
+ * const uuid = uuid58DecodeSafe("XDY9dmBbcMBXqcRvYw8xJ2"); // returns "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
+ * const error = uuid58DecodeSafe("invalid"); // returns Uuid58DecodeError
+ * ```
+ */
+export function uuid58DecodeSafe(base58) {
+    let num = 0n;
+    for (const char of base58) {
+        const index = BASE58_MAP[char];
+        if (index === undefined) {
+            return 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) {
+        return new Uuid58DecodeError(`length not 32: ${base58}`);
+    }
+    return (hex.slice(0, 8) +
+        "-" +
+        hex.slice(8, 12) +
+        "-" +
+        hex.slice(12, 16) +
+        "-" +
+        hex.slice(16, 20) +
+        "-" +
+        hex.slice(20));
+}
 /**
  * Converts a Base58-encoded string back to a standard UUID string format.
  *
  * @param base58 - The Base58-encoded string to decode
  * @returns A standard UUID string in the format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (always in lowercase)
- * @throws {InvalidBase58Error} If the input string contains characters not in the Base58 alphabet
+ * @throws {Uuid58DecodeError} If the input string contains characters not in the Base58 alphabet
  *
  * @example
  * ```typescript
@@ -35,13 +71,13 @@ export function uuid58Decode(base58) {
     for (const char of base58) {
         const index = BASE58_MAP[char];
         if (index === undefined) {
-            throw new InvalidBase58Error(base58);
+            throw new Uuid58DecodeError(base58);
         }
         num = num * ALPHABET_LENGTH + index;
     }
     const hex = num.toString(16).padStart(32, "0");
     if (hex.length !== 32) {
-        throw new InvalidBase58Error(base58);
+        throw new Uuid58DecodeError(base58);
     }
     return (hex.slice(0, 8) +
         "-" +

package/esm/encode.d.ts

@@ -2,9 +2,30 @@
  * 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).
  */
-export declare class InvalidUuidError extends Error {
-    constructor(uuid: string);
+export declare class Uuid58EncodeError extends Error {
 }
+/**
+ * Converts a standard UUID string to a 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
+ *   not a valid UUID
+ * @note This function does not throw; it returns the error object instead.
+ *
+ * @example
+ * ```typescript
+ * // With hyphens
+ * const base58 = uuid58EncodeSafe("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * // Without hyphens
+ * const base58 = uuid58EncodeSafe("f4b247fd1f8745d4aa061c6fc0a8dfaf"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * // Uppercase UUID is also accepted
+ * const base58 = uuid58EncodeSafe("F4B247FD-1F87-45D4-AA06-1C6FC0A8DFAF"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * // Invalid UUID format
+ * const error = uuid58EncodeSafe("invalid"); // returns Uuid58EncodeError
+ * ```
+ */
+export declare function uuid58EncodeSafe(uuid: string): string | Uuid58EncodeError;
 /**
  * Converts a standard UUID string to a shortened Base58-encoded format.
  *
@@ -12,7 +33,7 @@ export declare class InvalidUuidError extends Error {
  *              (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
- * @throws {InvalidUuidError} If the input string is not a valid UUID format
+ * @throws {Uuid58EncodeError} If the input string is not a valid UUID format
  *
  * @example
  * ```typescript

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,gBAAiB,SAAQ,KAAK;gBAK7B,IAAI,EAAE,MAAM;CAGzB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqBjD"}
+{"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,CAoBjD"}

package/esm/encode.js

@@ -4,15 +4,52 @@ import { ALPHABET_LENGTH, BASE58_ALPHABET } 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).
  */
-export class InvalidUuidError extends Error {
-    constructor(uuid) {
-        super(`Invalid UUID format: ${uuid}`);
-    }
+export class Uuid58EncodeError extends Error {
 }
-_a = InvalidUuidError;
+_a = Uuid58EncodeError;
 (() => {
-    _a.prototype.name = "InvalidUuidError";
+    _a.prototype.name = "Uuid58EncodeError";
 })();
+/**
+ * Converts a standard UUID string to a 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
+ *   not a valid UUID
+ * @note This function does not throw; it returns the error object instead.
+ *
+ * @example
+ * ```typescript
+ * // With hyphens
+ * const base58 = uuid58EncodeSafe("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * // Without hyphens
+ * const base58 = uuid58EncodeSafe("f4b247fd1f8745d4aa061c6fc0a8dfaf"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * // Uppercase UUID is also accepted
+ * const base58 = uuid58EncodeSafe("F4B247FD-1F87-45D4-AA06-1C6FC0A8DFAF"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * // Invalid UUID format
+ * const error = uuid58EncodeSafe("invalid"); // returns Uuid58EncodeError
+ * ```
+ */
+export function uuid58EncodeSafe(uuid) {
+    const hex = uuid.replaceAll("-", "");
+    if (hex.length !== 32) {
+        return new Uuid58EncodeError(`Invalid UUID length: expected 32 characters (excluding hyphens), got ${hex.length} characters in "${uuid}"`);
+    }
+    let num;
+    try {
+        num = BigInt("0x" + hex);
+    }
+    catch {
+        return 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;
+}
 /**
  * Converts a standard UUID string to a shortened Base58-encoded format.
  *
@@ -20,7 +57,7 @@ _a = InvalidUuidError;
  *              (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
- * @throws {InvalidUuidError} If the input string is not a valid UUID format
+ * @throws {Uuid58EncodeError} If the input string is not a valid UUID format
  *
  * @example
  * ```typescript
@@ -33,21 +70,20 @@ _a = InvalidUuidError;
  * ```
  */
 export function uuid58Encode(uuid) {
-    const hex = uuid.replace(/-/g, "").toLowerCase();
+    const hex = uuid.replaceAll("-", "");
     if (hex.length !== 32) {
-        throw new InvalidUuidError(uuid);
+        throw new Uuid58EncodeError(uuid);
     }
     let num;
     try {
         num = BigInt("0x" + hex);
     }
     catch {
-        throw new InvalidUuidError(uuid);
+        throw new Uuid58EncodeError(uuid);
     }
     let encoded = "";
     do {
-        const rem = Number(num % ALPHABET_LENGTH);
-        encoded = BASE58_ALPHABET[rem] + encoded;
+        encoded = BASE58_ALPHABET[Number(num % ALPHABET_LENGTH)] + encoded;
         num /= ALPHABET_LENGTH;
     } while (num > 0n);
     return encoded;

package/esm/uuid58.d.ts.map

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

package/esm/uuid58.js

@@ -1,4 +1,4 @@
-import { uuid58Encode } from "./encode.js";
+import { ALPHABET_LENGTH, BASE58_ALPHABET } from "./alphabet.js";
 /**
  * Generates a new Base58-encoded UUID.
  *
@@ -13,5 +13,11 @@ import { uuid58Encode } from "./encode.js";
  * ```
  */
 export function uuid58() {
-    return uuid58Encode(crypto.randomUUID());
+    let num = BigInt("0x" + crypto.randomUUID().replaceAll("-", ""));
+    let encoded = "";
+    do {
+        encoded = BASE58_ALPHABET[Number(num % ALPHABET_LENGTH)] + encoded;
+        num /= ALPHABET_LENGTH;
+    } while (num > 0n);
+    return encoded;
 }

package/package.json

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

package/script/decode.d.ts

@@ -2,15 +2,31 @@
  * Error thrown when an invalid Base58 string is provided for decoding.
  * This includes strings containing characters not in the Base58 alphabet.
  */
-export declare class InvalidBase58Error extends Error {
-    constructor(base58: string);
+export declare class Uuid58DecodeError extends Error {
 }
+/**
+ * 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.
+ *
+ * @param base58 - The Base58-encoded string to decode
+ * @returns A standard UUID string (lowercase, with hyphens), or an
+ *   `Uuid58DecodeError` if the input contains invalid Base58 characters
+ * @note This function does not throw; it returns the error object instead.
+ *
+ * @example
+ * ```typescript
+ * const uuid = uuid58DecodeSafe("XDY9dmBbcMBXqcRvYw8xJ2"); // returns "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
+ * const error = uuid58DecodeSafe("invalid"); // returns Uuid58DecodeError
+ * ```
+ */
+export declare function uuid58DecodeSafe(base58: string): string | Uuid58DecodeError;
 /**
  * Converts a Base58-encoded string back to a standard UUID string format.
  *
  * @param base58 - The Base58-encoded string to decode
  * @returns A standard UUID string in the format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (always in lowercase)
- * @throws {InvalidBase58Error} If the input string contains characters not in the Base58 alphabet
+ * @throws {Uuid58DecodeError} If the input string contains characters not in the Base58 alphabet
  *
  * @example
  * ```typescript

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,kBAAmB,SAAQ,KAAK;gBAK/B,MAAM,EAAE,MAAM;CAG3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CA0BnD"}
+{"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,CA0BnD"}

package/script/decode.js

@@ -1,7 +1,8 @@
 "use strict";
 var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InvalidBase58Error = void 0;
+exports.Uuid58DecodeError = void 0;
+exports.uuid58DecodeSafe = uuid58DecodeSafe;
 exports.uuid58Decode = uuid58Decode;
 const alphabet_js_1 = require("./alphabet.js");
 // Fast lookup map from alphabet characters to their indices
@@ -13,22 +14,58 @@ for (let i = 0; i < alphabet_js_1.BASE58_ALPHABET.length; i++) {
  * Error thrown when an invalid Base58 string is provided for decoding.
  * This includes strings containing characters not in the Base58 alphabet.
  */
-class InvalidBase58Error extends Error {
-    constructor(base58) {
-        super(`Invalid Base58 string: ${base58}`);
-    }
+class Uuid58DecodeError extends Error {
 }
-exports.InvalidBase58Error = InvalidBase58Error;
-_a = InvalidBase58Error;
+exports.Uuid58DecodeError = Uuid58DecodeError;
+_a = Uuid58DecodeError;
 (() => {
-    _a.prototype.name = "InvalidBase58Error";
+    _a.prototype.name = "Uuid58DecodeError";
 })();
+/**
+ * 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.
+ *
+ * @param base58 - The Base58-encoded string to decode
+ * @returns A standard UUID string (lowercase, with hyphens), or an
+ *   `Uuid58DecodeError` if the input contains invalid Base58 characters
+ * @note This function does not throw; it returns the error object instead.
+ *
+ * @example
+ * ```typescript
+ * const uuid = uuid58DecodeSafe("XDY9dmBbcMBXqcRvYw8xJ2"); // returns "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
+ * const error = uuid58DecodeSafe("invalid"); // returns Uuid58DecodeError
+ * ```
+ */
+function uuid58DecodeSafe(base58) {
+    let num = 0n;
+    for (const char of base58) {
+        const index = BASE58_MAP[char];
+        if (index === undefined) {
+            return 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) {
+        return new Uuid58DecodeError(`length not 32: ${base58}`);
+    }
+    return (hex.slice(0, 8) +
+        "-" +
+        hex.slice(8, 12) +
+        "-" +
+        hex.slice(12, 16) +
+        "-" +
+        hex.slice(16, 20) +
+        "-" +
+        hex.slice(20));
+}
 /**
  * Converts a Base58-encoded string back to a standard UUID string format.
  *
  * @param base58 - The Base58-encoded string to decode
  * @returns A standard UUID string in the format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (always in lowercase)
- * @throws {InvalidBase58Error} If the input string contains characters not in the Base58 alphabet
+ * @throws {Uuid58DecodeError} If the input string contains characters not in the Base58 alphabet
  *
  * @example
  * ```typescript
@@ -40,13 +77,13 @@ function uuid58Decode(base58) {
     for (const char of base58) {
         const index = BASE58_MAP[char];
         if (index === undefined) {
-            throw new InvalidBase58Error(base58);
+            throw new Uuid58DecodeError(base58);
         }
         num = num * alphabet_js_1.ALPHABET_LENGTH + index;
     }
     const hex = num.toString(16).padStart(32, "0");
     if (hex.length !== 32) {
-        throw new InvalidBase58Error(base58);
+        throw new Uuid58DecodeError(base58);
     }
     return (hex.slice(0, 8) +
         "-" +

package/script/encode.d.ts

@@ -2,9 +2,30 @@
  * 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).
  */
-export declare class InvalidUuidError extends Error {
-    constructor(uuid: string);
+export declare class Uuid58EncodeError extends Error {
 }
+/**
+ * Converts a standard UUID string to a 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
+ *   not a valid UUID
+ * @note This function does not throw; it returns the error object instead.
+ *
+ * @example
+ * ```typescript
+ * // With hyphens
+ * const base58 = uuid58EncodeSafe("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * // Without hyphens
+ * const base58 = uuid58EncodeSafe("f4b247fd1f8745d4aa061c6fc0a8dfaf"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * // Uppercase UUID is also accepted
+ * const base58 = uuid58EncodeSafe("F4B247FD-1F87-45D4-AA06-1C6FC0A8DFAF"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * // Invalid UUID format
+ * const error = uuid58EncodeSafe("invalid"); // returns Uuid58EncodeError
+ * ```
+ */
+export declare function uuid58EncodeSafe(uuid: string): string | Uuid58EncodeError;
 /**
  * Converts a standard UUID string to a shortened Base58-encoded format.
  *
@@ -12,7 +33,7 @@ export declare class InvalidUuidError extends Error {
  *              (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
- * @throws {InvalidUuidError} If the input string is not a valid UUID format
+ * @throws {Uuid58EncodeError} If the input string is not a valid UUID format
  *
  * @example
  * ```typescript

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,gBAAiB,SAAQ,KAAK;gBAK7B,IAAI,EAAE,MAAM;CAGzB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqBjD"}
+{"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,CAoBjD"}

package/script/encode.js

@@ -1,23 +1,61 @@
 "use strict";
 var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InvalidUuidError = void 0;
+exports.Uuid58EncodeError = void 0;
+exports.uuid58EncodeSafe = uuid58EncodeSafe;
 exports.uuid58Encode = uuid58Encode;
 const alphabet_js_1 = require("./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).
  */
-class InvalidUuidError extends Error {
-    constructor(uuid) {
-        super(`Invalid UUID format: ${uuid}`);
-    }
+class Uuid58EncodeError extends Error {
 }
-exports.InvalidUuidError = InvalidUuidError;
-_a = InvalidUuidError;
+exports.Uuid58EncodeError = Uuid58EncodeError;
+_a = Uuid58EncodeError;
 (() => {
-    _a.prototype.name = "InvalidUuidError";
+    _a.prototype.name = "Uuid58EncodeError";
 })();
+/**
+ * Converts a standard UUID string to a 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
+ *   not a valid UUID
+ * @note This function does not throw; it returns the error object instead.
+ *
+ * @example
+ * ```typescript
+ * // With hyphens
+ * const base58 = uuid58EncodeSafe("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * // Without hyphens
+ * const base58 = uuid58EncodeSafe("f4b247fd1f8745d4aa061c6fc0a8dfaf"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * // Uppercase UUID is also accepted
+ * const base58 = uuid58EncodeSafe("F4B247FD-1F87-45D4-AA06-1C6FC0A8DFAF"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * // Invalid UUID format
+ * const error = uuid58EncodeSafe("invalid"); // returns Uuid58EncodeError
+ * ```
+ */
+function uuid58EncodeSafe(uuid) {
+    const hex = uuid.replaceAll("-", "");
+    if (hex.length !== 32) {
+        return new Uuid58EncodeError(`Invalid UUID length: expected 32 characters (excluding hyphens), got ${hex.length} characters in "${uuid}"`);
+    }
+    let num;
+    try {
+        num = BigInt("0x" + hex);
+    }
+    catch {
+        return 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;
+}
 /**
  * Converts a standard UUID string to a shortened Base58-encoded format.
  *
@@ -25,7 +63,7 @@ _a = InvalidUuidError;
  *              (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
- * @throws {InvalidUuidError} If the input string is not a valid UUID format
+ * @throws {Uuid58EncodeError} If the input string is not a valid UUID format
  *
  * @example
  * ```typescript
@@ -38,21 +76,20 @@ _a = InvalidUuidError;
  * ```
  */
 function uuid58Encode(uuid) {
-    const hex = uuid.replace(/-/g, "").toLowerCase();
+    const hex = uuid.replaceAll("-", "");
     if (hex.length !== 32) {
-        throw new InvalidUuidError(uuid);
+        throw new Uuid58EncodeError(uuid);
     }
     let num;
     try {
         num = BigInt("0x" + hex);
     }
     catch {
-        throw new InvalidUuidError(uuid);
+        throw new Uuid58EncodeError(uuid);
     }
     let encoded = "";
     do {
-        const rem = Number(num % alphabet_js_1.ALPHABET_LENGTH);
-        encoded = alphabet_js_1.BASE58_ALPHABET[rem] + encoded;
+        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;

package/script/uuid58.d.ts.map

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

package/script/uuid58.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.uuid58 = uuid58;
-const encode_js_1 = require("./encode.js");
+const alphabet_js_1 = require("./alphabet.js");
 /**
  * Generates a new Base58-encoded UUID.
  *
@@ -16,5 +16,11 @@ const encode_js_1 = require("./encode.js");
  * ```
  */
 function uuid58() {
-    return (0, encode_js_1.uuid58Encode)(crypto.randomUUID());
+    let num = BigInt("0x" + crypto.randomUUID().replaceAll("-", ""));
+    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;
 }