@nakanoaas/uuid58 1.2.1 → 1.2.3

package/README.md

@@ -272,6 +272,34 @@ 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.
 
+## Development
+
+This project uses [Vite+](https://viteplus.dev/) (`vp`) and pnpm.
+
+```bash
+pnpm install
+pnpm check   # format, lint and type check
+pnpm test    # run tests
+pnpm bench   # build and benchmark (see bench/README.md)
+pnpm build   # build the npm package into dist/
+```
+
+The version lives only in `package.json`. `jsr.json` is generated from it
+by `vp pack` and is not committed.
+
+### Releasing
+
+1. Bump `version` in `package.json` and merge the change into `main`.
+2. Tag that commit and push the tag:
+
+   ```bash
+   git tag v1.2.3 && git push origin v1.2.3
+   ```
+
+The `Publish` workflow then checks that the tag matches `package.json` and
+is on `main`, runs the tests, publishes to JSR and npm, and creates the
+GitHub Release.
+
 ## License
 
 MIT License - see the [LICENSE](LICENSE) file for details

package/dist/index.cjs

@@ -0,0 +1,262 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+// alphabet.ts
+/**
+* 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"
+* ```
+*/
+const UUID58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+// check.ts
+const MAX_UUID58 = "YcVfxkQb6JRzqk5kF2tNLv";
+/**
+* Regular expression pattern for validating UUID58 strings.
+*
+* This regex ensures that a string:
+* - Contains exactly 22 characters
+* - Uses only characters from the Base58 alphabet
+*
+* **Note:** This regex does NOT validate that the decoded value fits within
+* 128 bits (UUID size). For complete validation including 128-bit range
+* checking, use {@link isUuid58} instead.
+*
+* @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)
+* ```
+*/
+const UUID58_REGEX = /^[1-9A-HJ-NP-Za-km-z]{22}$/u;
+/**
+* Checks if a given string is a valid UUID58-encodable string.
+* This function efficiently validates without performing full decoding.
+*
+* A valid UUID58 string must:
+* - Be exactly 22 characters long
+* - Contain only characters from the Base58 alphabet
+* - Decode to a value that fits within 128 bits (UUID size)
+*
+* @param uuid58 - The string to check
+* @returns `true` if the string is a valid UUID58 string, `false` otherwise
+*
+* @example
+* ```typescript
+* isUuid58("XDY9dmBbcMBXqcRvYw8xJ2"); // true
+* isUuid58("invalid"); // false
+* isUuid58("O0lI"); // false (contains invalid characters)
+* ```
+*/
+function isUuid58(uuid58) {
+	return UUID58_REGEX.test(uuid58) && uuid58 <= MAX_UUID58;
+}
+// internal.ts
+const MAX_PREVIEW_LENGTH = 40;
+/**
+* @internal
+* 58^9, the largest power of 58 below 2^53. A 9-digit Base58 chunk therefore
+* fits in a Number, so most digit arithmetic can avoid slow BigInt division.
+*/
+const BASE58_CHUNK = 7427658739644928n;
+/** Appends `digits` Base58 digits of `value` (most significant first). */
+function appendDigits(out, value, digits) {
+	let chunk = "";
+	for (let i = 0; i < digits; i++) {
+		const quotient = Math.floor(value / 58);
+		chunk = UUID58_ALPHABET[value - quotient * 58] + chunk;
+		value = quotient;
+	}
+	return out + chunk;
+}
+/**
+* @internal
+* Encodes an unsigned 128-bit integer as a 22-character Base58 string.
+*
+* The value is split into 4 + 9 + 9 digit chunks with two BigInt divisions,
+* instead of 22 BigInt divisions (one per digit).
+*/
+function encodeUint128(num) {
+	const low = Number(num % BASE58_CHUNK);
+	num /= BASE58_CHUNK;
+	const mid = Number(num % BASE58_CHUNK);
+	return appendDigits(appendDigits(appendDigits("", Number(num / BASE58_CHUNK), 4), mid, 9), low, 9);
+}
+/**
+* @internal
+* Formats untrusted input for inclusion in an error message.
+*
+* The input is truncated so huge strings do not bloat error messages or logs,
+* and JSON-escaped so control characters (e.g. newlines) cannot forge log
+* lines.
+*/
+function previewInput(input) {
+	return input.length > MAX_PREVIEW_LENGTH ? `${JSON.stringify(input.slice(0, MAX_PREVIEW_LENGTH))}... (${input.length} characters)` : JSON.stringify(input);
+}
+// decode.ts
+var _Uuid58DecodeError;
+const BASE58_INDEX = (/* @__PURE__ */ new Int8Array(128)).fill(-1);
+for (let i = 0; i < 58; i++) BASE58_INDEX[UUID58_ALPHABET.charCodeAt(i)] = i;
+/**
+* Error thrown when an invalid Base58 string is provided for decoding.
+* This includes strings containing characters not in the Base58 alphabet.
+*/
+var Uuid58DecodeError = class extends Error {};
+_Uuid58DecodeError = Uuid58DecodeError;
+_Uuid58DecodeError.prototype.name = "Uuid58DecodeError";
+/**
+* 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 uuid58 - The 22-character Base58-encoded UUID string to decode
+* @returns A standard UUID string (lowercase, with hyphens), or an
+*   `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
+* ```typescript
+* const uuid = uuid58DecodeSafe("XDY9dmBbcMBXqcRvYw8xJ2"); // returns "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
+* const error = uuid58DecodeSafe("invalid"); // returns Uuid58DecodeError
+* ```
+*/
+function uuid58DecodeSafe(uuid58) {
+	if (uuid58.length !== 22) return new Uuid58DecodeError(`Expected Base58 string of length 22, but received string of length ${uuid58.length}: ${previewInput(uuid58)}`);
+	let num = 0n;
+	for (let start = 0; start < 22;) {
+		const end = start === 0 ? 4 : start + 9;
+		let chunk = 0;
+		for (let i = start; i < end; i++) {
+			const code = uuid58.charCodeAt(i);
+			const index = code < 128 ? BASE58_INDEX[code] : -1;
+			if (index < 0) {
+				const char = String.fromCodePoint(uuid58.codePointAt(i));
+				return new Uuid58DecodeError(`Invalid Base58 character ${JSON.stringify(char)} found in input: ${previewInput(uuid58)}`);
+			}
+			chunk = chunk * 58 + index;
+		}
+		num = num * BASE58_CHUNK + BigInt(chunk);
+		start = end;
+	}
+	const hex = num.toString(16).padStart(32, "0");
+	if (hex.length !== 32) return new Uuid58DecodeError(`Decoded value exceeds 128 bits of UUID: ${previewInput(uuid58)}`);
+	return hex.slice(0, 8) + "-" + hex.slice(8, 12) + "-" + hex.slice(12, 16) + "-" + hex.slice(16, 20) + "-" + hex.slice(20);
+}
+/**
+* Converts a 22-character Base58-encoded string back to a standard UUID string format.
+*
+* @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 is not a valid 22-character Base58 string
+*
+* @example
+* ```typescript
+* const uuid = uuid58Decode("XDY9dmBbcMBXqcRvYw8xJ2"); // returns "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
+* ```
+*/
+function uuid58Decode(uuid58) {
+	const result = uuid58DecodeSafe(uuid58);
+	if (result instanceof Uuid58DecodeError) throw result;
+	return result;
+}
+// encode.ts
+var _Uuid58EncodeError;
+const HEX32_REGEX = /^[0-9a-f]{32}$/i;
+/**
+* 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).
+*/
+var Uuid58EncodeError = class extends Error {};
+_Uuid58EncodeError = Uuid58EncodeError;
+_Uuid58EncodeError.prototype.name = "Uuid58EncodeError";
+/**
+* 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 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.
+*
+* @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.replace(/-/g, "");
+	if (hex.length !== 32) return new Uuid58EncodeError(`Invalid UUID length: expected 32 characters (excluding hyphens), got ${hex.length} characters in ${previewInput(uuid)}`);
+	if (!HEX32_REGEX.test(hex)) return new Uuid58EncodeError(`Invalid UUID format: ${previewInput(uuid)} contains non-hexadecimal characters`);
+	return encodeUint128(BigInt("0x" + hex));
+}
+/**
+* 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 22-character Base58-encoded string representation of the UUID
+* @throws {Uuid58EncodeError} If the input string is not a valid UUID format
+*
+* @example
+* ```typescript
+* // With hyphens
+* const base58 = uuid58Encode("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+* // Without hyphens
+* const base58 = uuid58Encode("f4b247fd1f8745d4aa061c6fc0a8dfaf"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+* // Uppercase UUID is also accepted
+* const base58 = uuid58Encode("F4B247FD-1F87-45D4-AA06-1C6FC0A8DFAF"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+* ```
+*/
+function uuid58Encode(uuid) {
+	const result = uuid58EncodeSafe(uuid);
+	if (result instanceof Uuid58EncodeError) throw result;
+	return result;
+}
+// generate.ts
+const random = /* @__PURE__ */ new BigUint64Array(2);
+/**
+* Generates a new Base58-encoded UUID (always 22 characters).
+*
+* This function combines the standard UUID generation (using crypto.getRandomValues())
+* with Base58 encoding to create a shorter, URL-safe identifier.
+*
+* @returns A 22-character Base58-encoded string representing a newly generated UUID
+*
+* @example
+* ```typescript
+* const id = uuid58(); // returns a 22-character string like "XDY9dmBbcMBXqcRvYw8xJ2"
+* ```
+*/
+function uuid58() {
+	crypto.getRandomValues(random);
+	const high = random[0] & 18446744073709490175n | 16384n;
+	const low = random[1] & 4611686018427387903n | 9223372036854775808n;
+	return encodeUint128(high << 64n | low);
+}
+exports.UUID58_ALPHABET = UUID58_ALPHABET;
+exports.UUID58_REGEX = UUID58_REGEX;
+exports.Uuid58DecodeError = Uuid58DecodeError;
+exports.Uuid58EncodeError = Uuid58EncodeError;
+exports.isUuid58 = isUuid58;
+exports.uuid58 = uuid58;
+exports.uuid58Decode = uuid58Decode;
+exports.uuid58DecodeSafe = uuid58DecodeSafe;
+exports.uuid58Encode = uuid58Encode;
+exports.uuid58EncodeSafe = uuid58EncodeSafe;

package/dist/index.d.cts

@@ -0,0 +1,152 @@
+/**
+ * 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;
+/**
+ * Regular expression pattern for validating UUID58 strings.
+ *
+ * This regex ensures that a string:
+ * - Contains exactly 22 characters
+ * - Uses only characters from the Base58 alphabet
+ *
+ * **Note:** This regex does NOT validate that the decoded value fits within
+ * 128 bits (UUID size). For complete validation including 128-bit range
+ * checking, use {@link isUuid58} instead.
+ *
+ * @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;
+/**
+ * Checks if a given string is a valid UUID58-encodable string.
+ * This function efficiently validates without performing full decoding.
+ *
+ * A valid UUID58 string must:
+ * - Be exactly 22 characters long
+ * - Contain only characters from the Base58 alphabet
+ * - Decode to a value that fits within 128 bits (UUID size)
+ *
+ * @param uuid58 - The string to check
+ * @returns `true` if the string is a valid UUID58 string, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * isUuid58("XDY9dmBbcMBXqcRvYw8xJ2"); // true
+ * isUuid58("invalid"); // false
+ * isUuid58("O0lI"); // false (contains invalid characters)
+ * ```
+ */
+export declare function isUuid58(uuid58: string): boolean;
+/**
+ * Error thrown when an invalid Base58 string is provided for decoding.
+ * This includes strings containing characters not in the Base58 alphabet.
+ */
+export declare class Uuid58DecodeError extends Error {}
+/**
+ * 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 uuid58 - The 22-character Base58-encoded UUID string to decode
+ * @returns A standard UUID string (lowercase, with hyphens), or an
+ *   `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
+ * ```typescript
+ * const uuid = uuid58DecodeSafe("XDY9dmBbcMBXqcRvYw8xJ2"); // returns "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
+ * const error = uuid58DecodeSafe("invalid"); // returns Uuid58DecodeError
+ * ```
+ */
+export declare function uuid58DecodeSafe(uuid58: string): string | Uuid58DecodeError;
+/**
+ * Converts a 22-character Base58-encoded string back to a standard UUID string format.
+ *
+ * @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 is not a valid 22-character Base58 string
+ *
+ * @example
+ * ```typescript
+ * const uuid = uuid58Decode("XDY9dmBbcMBXqcRvYw8xJ2"); // returns "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
+ * ```
+ */
+export declare function uuid58Decode(uuid58: string): string;
+/**
+ * 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 Uuid58EncodeError extends Error {}
+/**
+ * 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 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.
+ *
+ * @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 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 22-character Base58-encoded string representation of the UUID
+ * @throws {Uuid58EncodeError} If the input string is not a valid UUID format
+ *
+ * @example
+ * ```typescript
+ * // With hyphens
+ * const base58 = uuid58Encode("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * // Without hyphens
+ * const base58 = uuid58Encode("f4b247fd1f8745d4aa061c6fc0a8dfaf"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * // Uppercase UUID is also accepted
+ * const base58 = uuid58Encode("F4B247FD-1F87-45D4-AA06-1C6FC0A8DFAF"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * ```
+ */
+export declare function uuid58Encode(uuid: string): string;
+/**
+ * Generates a new Base58-encoded UUID (always 22 characters).
+ *
+ * This function combines the standard UUID generation (using crypto.getRandomValues())
+ * with Base58 encoding to create a shorter, URL-safe identifier.
+ *
+ * @returns A 22-character Base58-encoded string representing a newly generated UUID
+ *
+ * @example
+ * ```typescript
+ * const id = uuid58(); // returns a 22-character string like "XDY9dmBbcMBXqcRvYw8xJ2"
+ * ```
+ */
+export declare function uuid58(): string;

package/dist/index.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 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;
+/**
+ * Regular expression pattern for validating UUID58 strings.
+ *
+ * This regex ensures that a string:
+ * - Contains exactly 22 characters
+ * - Uses only characters from the Base58 alphabet
+ *
+ * **Note:** This regex does NOT validate that the decoded value fits within
+ * 128 bits (UUID size). For complete validation including 128-bit range
+ * checking, use {@link isUuid58} instead.
+ *
+ * @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;
+/**
+ * Checks if a given string is a valid UUID58-encodable string.
+ * This function efficiently validates without performing full decoding.
+ *
+ * A valid UUID58 string must:
+ * - Be exactly 22 characters long
+ * - Contain only characters from the Base58 alphabet
+ * - Decode to a value that fits within 128 bits (UUID size)
+ *
+ * @param uuid58 - The string to check
+ * @returns `true` if the string is a valid UUID58 string, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * isUuid58("XDY9dmBbcMBXqcRvYw8xJ2"); // true
+ * isUuid58("invalid"); // false
+ * isUuid58("O0lI"); // false (contains invalid characters)
+ * ```
+ */
+export declare function isUuid58(uuid58: string): boolean;
+/**
+ * Error thrown when an invalid Base58 string is provided for decoding.
+ * This includes strings containing characters not in the Base58 alphabet.
+ */
+export declare class Uuid58DecodeError extends Error {}
+/**
+ * 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 uuid58 - The 22-character Base58-encoded UUID string to decode
+ * @returns A standard UUID string (lowercase, with hyphens), or an
+ *   `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
+ * ```typescript
+ * const uuid = uuid58DecodeSafe("XDY9dmBbcMBXqcRvYw8xJ2"); // returns "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
+ * const error = uuid58DecodeSafe("invalid"); // returns Uuid58DecodeError
+ * ```
+ */
+export declare function uuid58DecodeSafe(uuid58: string): string | Uuid58DecodeError;
+/**
+ * Converts a 22-character Base58-encoded string back to a standard UUID string format.
+ *
+ * @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 is not a valid 22-character Base58 string
+ *
+ * @example
+ * ```typescript
+ * const uuid = uuid58Decode("XDY9dmBbcMBXqcRvYw8xJ2"); // returns "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
+ * ```
+ */
+export declare function uuid58Decode(uuid58: string): string;
+/**
+ * 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 Uuid58EncodeError extends Error {}
+/**
+ * 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 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.
+ *
+ * @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 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 22-character Base58-encoded string representation of the UUID
+ * @throws {Uuid58EncodeError} If the input string is not a valid UUID format
+ *
+ * @example
+ * ```typescript
+ * // With hyphens
+ * const base58 = uuid58Encode("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * // Without hyphens
+ * const base58 = uuid58Encode("f4b247fd1f8745d4aa061c6fc0a8dfaf"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * // Uppercase UUID is also accepted
+ * const base58 = uuid58Encode("F4B247FD-1F87-45D4-AA06-1C6FC0A8DFAF"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
+ * ```
+ */
+export declare function uuid58Encode(uuid: string): string;
+/**
+ * Generates a new Base58-encoded UUID (always 22 characters).
+ *
+ * This function combines the standard UUID generation (using crypto.getRandomValues())
+ * with Base58 encoding to create a shorter, URL-safe identifier.
+ *
+ * @returns A 22-character Base58-encoded string representing a newly generated UUID
+ *
+ * @example
+ * ```typescript
+ * const id = uuid58(); // returns a 22-character string like "XDY9dmBbcMBXqcRvYw8xJ2"
+ * ```
+ */
+export declare function uuid58(): string;