@nakanoaas/uuid58 1.2.2 → 2.0.0

package/README.md

@@ -124,7 +124,10 @@ function uuid58Encode(uuid: string): string; // always returns a 22-character st
 ```
 
 - **Parameters:**
-  - `uuid`: The UUID string to encode (with or without hyphens)
+  - `uuid`: The UUID string to encode: hyphenated
+    (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) or 32 hexadecimal digits, in any
+    letter case. Other forms (braces, `urn:uuid:`, whitespace, hyphens in other
+    positions) are rejected.
 - **Returns:** A 22-character Base58-encoded string
 - **Throws:** `Uuid58EncodeError` if the input is not a valid UUID
 
@@ -139,7 +142,7 @@ function uuid58EncodeSafe(uuid: string): string | Uuid58EncodeError; // string i
 ```
 
 - **Parameters:**
-  - `uuid`: The UUID string to encode (with or without hyphens)
+  - `uuid`: The UUID string to encode (same forms as `uuid58Encode`)
 - **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.
@@ -174,26 +177,70 @@ 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.
 
+### `uuid58EncodeBytes(bytes: Uint8Array)` / `uuid58EncodeBytesSafe`
+
+Encodes 16 bytes, in big-endian (RFC 9562) order, as a 22-character string.
+
+```typescript
+function uuid58EncodeBytes(bytes: Uint8Array): string;
+function uuid58EncodeBytesSafe(bytes: Uint8Array): string | Uuid58EncodeError;
+```
+
+- **Throws / returns:** `Uuid58EncodeError` with kind `"invalid_length"` if
+  `bytes` is not exactly 16 bytes long
+
+### `uuid58DecodeBytes(uuid58: string)` / `uuid58DecodeBytesSafe`
+
+Decodes a 22-character string to a new 16-byte `Uint8Array` in big-endian
+(RFC 9562) order.
+
+```typescript
+function uuid58DecodeBytes(uuid58: string): Uint8Array;
+function uuid58DecodeBytesSafe(uuid58: string): Uint8Array | Uuid58DecodeError;
+```
+
+- **Throws / returns:** `Uuid58DecodeError`, as for `uuid58Decode`
+
 ### Error Classes
 
+Both error classes have a `kind` property with the error kind defined by the
+[specification](https://github.com/nakanoasaservice/uuid58/blob/main/spec/SPEC.md)
+(type `Uuid58ErrorKind`). Use it instead of parsing the message, which may
+change.
+
+| `kind`                | Meaning                                                                        |
+| --------------------- | ------------------------------------------------------------------------------ |
+| `"invalid_length"`    | Wrong length: not 32 or 36 characters (UUID), not 22 (uuid58), or not 16 bytes |
+| `"invalid_character"` | Right length, but a character not allowed in its position                      |
+| `"overflow"`          | (decoding only) Well formed, but the value is greater than 2^128 − 1           |
+
+```typescript
+const result = uuid58DecodeSafe(input);
+if (result instanceof Uuid58DecodeError && result.kind === "overflow") {
+  // ...
+}
+```
+
 #### `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).
+Error thrown when an invalid UUID string or byte array is provided for
+encoding. `kind` is `"invalid_length"` or `"invalid_character"`.
 
 ```typescript
-class Uuid58EncodeError extends Error;
+class Uuid58EncodeError extends Error {
+  readonly kind: "invalid_length" | "invalid_character";
+}
 ```
 
 #### `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.
+Error thrown when an invalid string is provided for decoding. `kind` is
+`"invalid_length"`, `"invalid_character"`, or `"overflow"`.
 
 ```typescript
-class Uuid58DecodeError extends Error;
+class Uuid58DecodeError extends Error {
+  readonly kind: Uuid58ErrorKind;
+}
 ```
 
 ### `isUuid58(uuid58: string)`
@@ -272,15 +319,38 @@ 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.
 
+This package implements the
+[uuid58 specification](https://github.com/nakanoasaservice/uuid58/blob/main/spec/SPEC.md).
+Since 2.0 it follows the spec fully. 1.x accepted hyphens anywhere in the
+input of `uuid58Encode` (see Section 9.1 of the spec).
+
+## Migrating from 1.x
+
+2.0 has two breaking changes:
+
+- **Stricter UUID input.** `uuid58Encode` and `uuid58EncodeSafe` accept only
+  the hyphenated form (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) and 32
+  hexadecimal digits. 1.x removed every hyphen first, so inputs such as
+  `f4b247f-d1f87-45d4-aa06-1c6fc0a8dfaf` or `f4b247fd-1f8745d4aa061c6fc0a8dfaf`
+  were accepted; they are now rejected. Normalize such input yourself before
+  encoding if you need it, for example with `uuid.replace(/-/g, "")`.
+- **Error constructors** take a second argument, the error kind
+  (`new Uuid58EncodeError(message, kind)`). This matters only if you
+  construct these errors yourself.
+
+New in 2.0: the `kind` property on errors, and `uuid58EncodeBytes` /
+`uuid58DecodeBytes` for `Uint8Array`.
+
 ## Development
 
-This project uses [Vite+](https://viteplus.dev/) (`vp`) and pnpm.
+This package lives in the `js/` directory of the repository and uses
+[Vite+](https://viteplus.dev/) (`vp`) and pnpm. Run these commands in `js/`:
 
 ```bash
 pnpm install
 pnpm check   # format, lint and type check
-pnpm test    # run tests
-pnpm bench   # run benchmarks
+pnpm test    # run tests, including the spec's conformance vectors
+pnpm bench   # build and benchmark (see bench/README.md)
 pnpm build   # build the npm package into dist/
 ```
 
@@ -289,14 +359,14 @@ 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:
+1. Bump `version` in `js/package.json` and merge the change into `main`.
+2. Tag that commit with a `js/` prefix and push the tag:
 
    ```bash
-   git tag v1.2.3 && git push origin v1.2.3
+   git tag js/v1.2.3 && git push origin js/v1.2.3
    ```
 
-The `Publish` workflow then checks that the tag matches `package.json` and
+The `Publish` workflow then checks that the tag matches `js/package.json` and
 is on `main`, runs the tests, publishes to JSR and npm, and creates the
 GitHub Release.
 

package/dist/index.cjs

@@ -17,57 +17,37 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 * ```
 */
 const UUID58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+// internal.ts
+const MAX_PREVIEW_LENGTH = 40;
 /**
 * @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.
+* 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 UUID58_LENGTH = BigInt(58);
-// check.ts
-const MAX_UUID58 = "YcVfxkQb6JRzqk5kF2tNLv";
+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;
+}
 /**
-* 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.
+* @internal
+* Encodes an unsigned 128-bit integer as a 22-character Base58 string.
 *
-* @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)
-* ```
+* The value is split into 4 + 9 + 9 digit chunks with two BigInt divisions,
+* instead of 22 BigInt divisions (one per digit).
 */
-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;
+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.ts
-const MAX_PREVIEW_LENGTH = 40;
 /**
 * @internal
 * Formats untrusted input for inclusion in an error message.
@@ -81,16 +61,48 @@ function previewInput(input) {
 }
 // decode.ts
 var _Uuid58DecodeError;
-const BASE58_MAP = {};
-for (let i = 0; i < 58; i++) BASE58_MAP[UUID58_ALPHABET[i]] = BigInt(i);
+const BASE58_INDEX = (/* @__PURE__ */ new Int8Array(128)).fill(-1);
+for (let i = 0; i < 58; i++) BASE58_INDEX[UUID58_ALPHABET.charCodeAt(i)] = i;
+const MAX_UINT128 = (1n << 128n) - 1n;
 /**
-* Error thrown when an invalid Base58 string is provided for decoding.
-* This includes strings containing characters not in the Base58 alphabet.
+* Error thrown when an invalid uuid58 string is provided for decoding.
+* Its {@link Uuid58DecodeError.kind | kind} tells why.
 */
-var Uuid58DecodeError = class extends Error {};
+var Uuid58DecodeError = class extends Error {
+	constructor(message, kind) {
+		super(message);
+		this.kind = kind;
+	}
+};
 _Uuid58DecodeError = Uuid58DecodeError;
 _Uuid58DecodeError.prototype.name = "Uuid58DecodeError";
 /**
+* @internal
+* Decodes a uuid58 string to an unsigned 128-bit integer, checking length,
+* then characters, then range (specification, Section 4).
+*/
+function decodeUint128(uuid58) {
+	if (uuid58.length !== 22) return new Uuid58DecodeError(`Expected Base58 string of length 22, but received string of length ${uuid58.length}: ${previewInput(uuid58)}`, "invalid_length");
+	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)}`, "invalid_character");
+			}
+			chunk = chunk * 58 + index;
+		}
+		num = num * BASE58_CHUNK + BigInt(chunk);
+		start = end;
+	}
+	if (num > MAX_UINT128) return new Uuid58DecodeError(`Decoded value exceeds 128 bits of UUID: ${previewInput(uuid58)}`, "overflow");
+	return num;
+}
+/**
 * 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.
@@ -103,19 +115,13 @@ _Uuid58DecodeError.prototype.name = "Uuid58DecodeError";
 * @example
 * ```typescript
 * const uuid = uuid58DecodeSafe("XDY9dmBbcMBXqcRvYw8xJ2"); // returns "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"
-* const error = uuid58DecodeSafe("invalid"); // returns Uuid58DecodeError
+* const error = uuid58DecodeSafe("invalid"); // returns Uuid58DecodeError (kind: "invalid_length")
 * ```
 */
 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 (const char of uuid58) {
-		const index = BASE58_MAP[char];
-		if (index === void 0) return new Uuid58DecodeError(`Invalid Base58 character ${JSON.stringify(char)} found in input: ${previewInput(uuid58)}`);
-		num = num * UUID58_LENGTH + index;
-	}
+	const num = decodeUint128(uuid58);
+	if (typeof num !== "bigint") return num;
 	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);
 }
 /**
@@ -138,18 +144,44 @@ function uuid58Decode(uuid58) {
 // encode.ts
 var _Uuid58EncodeError;
 const HEX32_REGEX = /^[0-9a-f]{32}$/i;
+const HYPHENATED_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/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).
+* Error thrown when an invalid UUID string or byte array is provided for
+* encoding. Its {@link Uuid58EncodeError.kind | kind} tells why.
 */
-var Uuid58EncodeError = class extends Error {};
+var Uuid58EncodeError = class extends Error {
+	constructor(message, kind) {
+		super(message);
+		this.kind = kind;
+	}
+};
 _Uuid58EncodeError = Uuid58EncodeError;
 _Uuid58EncodeError.prototype.name = "Uuid58EncodeError";
 /**
+* @internal
+* Parses a UUID string in one of the two forms of the specification
+* (Section 5.1) into an unsigned 128-bit integer.
+*/
+function parseUuidString(uuid) {
+	let hex;
+	if (uuid.length === 32) {
+		if (!HEX32_REGEX.test(uuid)) return new Uuid58EncodeError(`Invalid UUID: ${previewInput(uuid)} must be 32 hexadecimal digits`, "invalid_character");
+		hex = uuid;
+	} else if (uuid.length === 36) {
+		if (!HYPHENATED_REGEX.test(uuid)) return new Uuid58EncodeError(`Invalid UUID: ${previewInput(uuid)} must be in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, "invalid_character");
+		hex = uuid.slice(0, 8) + uuid.slice(9, 13) + uuid.slice(14, 18) + uuid.slice(19, 23) + uuid.slice(24);
+	} else return new Uuid58EncodeError(`Invalid UUID length: expected 32 or 36 characters, got ${uuid.length} in ${previewInput(uuid)}`, "invalid_length");
+	return BigInt("0x" + hex);
+}
+/**
 * 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)
+* Only two forms are accepted, in any letter case: the hyphenated form
+* (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) and 32 hexadecimal digits. Braces,
+* `urn:uuid:`, whitespace, and hyphens in other positions are rejected.
+*
+* @param uuid - The UUID string to encode (hyphenated, or 32 hexadecimal digits)
 * @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.
@@ -163,27 +195,20 @@ _Uuid58EncodeError.prototype.name = "Uuid58EncodeError";
 * // Uppercase UUID is also accepted
 * const base58 = uuid58EncodeSafe("F4B247FD-1F87-45D4-AA06-1C6FC0A8DFAF"); // returns "XDY9dmBbcMBXqcRvYw8xJ2"
 * // Invalid UUID format
-* const error = uuid58EncodeSafe("invalid"); // returns Uuid58EncodeError
+* const error = uuid58EncodeSafe("invalid"); // returns Uuid58EncodeError (kind: "invalid_length")
 * ```
 */
 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`);
-	let num = BigInt("0x" + hex);
-	let encoded = "";
-	do {
-		encoded = UUID58_ALPHABET[Number(num % UUID58_LENGTH)] + encoded;
-		num /= UUID58_LENGTH;
-	} while (num > 0n);
-	return encoded.padStart(22, UUID58_ALPHABET[0]);
+	const num = parseUuidString(uuid);
+	return typeof num === "bigint" ? encodeUint128(num) : num;
 }
 /**
 * 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.
+* @param uuid - The UUID string to encode, either hyphenated
+*              ("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx") or as 32 hexadecimal digits
+*              ("xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"). Hexadecimal digits may be in any case.
+*              Other forms, including hyphens in other positions, are rejected.
 * @returns A 22-character Base58-encoded string representation of the UUID
 * @throws {Uuid58EncodeError} If the input string is not a valid UUID format
 *
@@ -202,7 +227,131 @@ function uuid58Encode(uuid) {
 	if (result instanceof Uuid58EncodeError) throw result;
 	return result;
 }
+// bytes.ts
+/**
+* Encodes 16 bytes, in big-endian (RFC 9562) order, as a 22-character uuid58
+* string, but instead of throwing an error for invalid input, it returns an
+* `Uuid58EncodeError` instance.
+*
+* @param bytes - The 16 bytes of the UUID
+* @returns A 22-character uuid58 string, or an `Uuid58EncodeError` (kind
+*   `"invalid_length"`) if `bytes` is not exactly 16 bytes long
+* @note This function does not throw; it returns the error object instead.
+*
+* @example
+* ```typescript
+* const bytes = new Uint8Array(16); // nil UUID
+* uuid58EncodeBytesSafe(bytes); // returns "1111111111111111111111"
+* ```
+*/
+function uuid58EncodeBytesSafe(bytes) {
+	if (bytes.length !== 16) return new Uuid58EncodeError(`Invalid byte length: expected 16 bytes, got ${bytes.length}`, "invalid_length");
+	const view = new DataView(bytes.buffer, bytes.byteOffset, 16);
+	return encodeUint128(view.getBigUint64(0) << 64n | view.getBigUint64(8));
+}
+/**
+* Encodes 16 bytes, in big-endian (RFC 9562) order, as a 22-character uuid58
+* string.
+*
+* @param bytes - The 16 bytes of the UUID
+* @returns A 22-character uuid58 string
+* @throws {Uuid58EncodeError} If `bytes` is not exactly 16 bytes long
+*
+* @example
+* ```typescript
+* uuid58EncodeBytes(new Uint8Array(16)); // returns "1111111111111111111111"
+* ```
+*/
+function uuid58EncodeBytes(bytes) {
+	const result = uuid58EncodeBytesSafe(bytes);
+	if (result instanceof Uuid58EncodeError) throw result;
+	return result;
+}
+/**
+* Decodes a uuid58 string to 16 bytes in big-endian (RFC 9562) order, but
+* instead of throwing an error for invalid input, it returns an
+* `Uuid58DecodeError` instance.
+*
+* @param uuid58 - The 22-character uuid58 string to decode
+* @returns A new 16-byte `Uint8Array`, or an `Uuid58DecodeError`
+* @note This function does not throw; it returns the error object instead.
+*
+* @example
+* ```typescript
+* uuid58DecodeBytesSafe("1111111111111111111111"); // returns Uint8Array(16) of zeros
+* ```
+*/
+function uuid58DecodeBytesSafe(uuid58) {
+	const num = decodeUint128(uuid58);
+	if (typeof num !== "bigint") return num;
+	const bytes = /* @__PURE__ */ new Uint8Array(16);
+	const view = new DataView(bytes.buffer);
+	view.setBigUint64(0, num >> 64n);
+	view.setBigUint64(8, num & 18446744073709551615n);
+	return bytes;
+}
+/**
+* Decodes a uuid58 string to 16 bytes in big-endian (RFC 9562) order.
+*
+* @param uuid58 - The 22-character uuid58 string to decode
+* @returns A new 16-byte `Uint8Array`
+* @throws {Uuid58DecodeError} If the input is not a valid uuid58 string
+*
+* @example
+* ```typescript
+* const bytes = uuid58DecodeBytes("XDY9dmBbcMBXqcRvYw8xJ2");
+* ```
+*/
+function uuid58DecodeBytes(uuid58) {
+	const result = uuid58DecodeBytesSafe(uuid58);
+	if (result instanceof Uuid58DecodeError) throw result;
+	return result;
+}
+// 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;
+}
 // generate.ts
+const random = /* @__PURE__ */ new BigUint64Array(2);
 /**
 * Generates a new Base58-encoded UUID (always 22 characters).
 *
@@ -217,16 +366,10 @@ function uuid58Encode(uuid) {
 * ```
 */
 function uuid58() {
-	const bytes = crypto.getRandomValues(/* @__PURE__ */ new BigUint64Array(2));
-	bytes[0] = bytes[0] & 18446744073709490175n | 16384n;
-	bytes[1] = bytes[1] & 4611686018427387903n | 9223372036854775808n;
-	let num = bytes[0] << 64n | bytes[1];
-	let encoded = "";
-	do {
-		encoded = UUID58_ALPHABET[Number(num % UUID58_LENGTH)] + encoded;
-		num /= UUID58_LENGTH;
-	} while (num > 0n);
-	return encoded.padStart(22, UUID58_ALPHABET[0]);
+	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;
@@ -235,6 +378,10 @@ exports.Uuid58EncodeError = Uuid58EncodeError;
 exports.isUuid58 = isUuid58;
 exports.uuid58 = uuid58;
 exports.uuid58Decode = uuid58Decode;
+exports.uuid58DecodeBytes = uuid58DecodeBytes;
+exports.uuid58DecodeBytesSafe = uuid58DecodeBytesSafe;
 exports.uuid58DecodeSafe = uuid58DecodeSafe;
 exports.uuid58Encode = uuid58Encode;
+exports.uuid58EncodeBytes = uuid58EncodeBytes;
+exports.uuid58EncodeBytesSafe = uuid58EncodeBytesSafe;
 exports.uuid58EncodeSafe = uuid58EncodeSafe;