@nakanoaas/uuid58 1.2.2 → 2.0.0

package/dist/index.d.cts

@@ -16,49 +16,33 @@
  */
 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)
- * ```
+ * The kind of an encoding or decoding error, as defined by the uuid58
+ * specification (Section 7).
+ *
+ * - `"invalid_length"`: the input has the wrong length (a UUID string that is
+ *   neither 32 nor 36 characters, a uuid58 string that is not 22 characters,
+ *   or a byte array that is not 16 bytes long).
+ * - `"invalid_character"`: the input has the right length but contains a
+ *   character not allowed in its position.
+ * - `"overflow"`: (decoding only) the uuid58 string is well formed, but its
+ *   value is greater than 2^128 - 1.
+ *
+ * Inputs containing non-ASCII characters may report either
+ * `"invalid_length"` or `"invalid_character"`.
  */
-export declare function isUuid58(uuid58: string): boolean;
+type Uuid58ErrorKind = "invalid_length" | "invalid_character" | "overflow";
 /**
- * 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.
  */
-export declare class Uuid58DecodeError extends Error {}
+export declare class Uuid58DecodeError extends Error {
+  /**
+   * Why the input was rejected: `"invalid_length"`, `"invalid_character"`,
+   * or `"overflow"`.
+   */
+  readonly kind: Uuid58ErrorKind;
+  constructor(message: string, kind: Uuid58ErrorKind);
+}
 /**
  * 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`
@@ -72,7 +56,7 @@ export declare class Uuid58DecodeError extends Error {}
  * @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")
  * ```
  */
 export declare function uuid58DecodeSafe(uuid58: string): string | Uuid58DecodeError;
@@ -90,15 +74,25 @@ export declare function uuid58DecodeSafe(uuid58: string): string | Uuid58DecodeE
  */
 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).
+ * Error thrown when an invalid UUID string or byte array is provided for
+ * encoding. Its {@link Uuid58EncodeError.kind | kind} tells why.
  */
-export declare class Uuid58EncodeError extends Error {}
+export declare class Uuid58EncodeError extends Error {
+  /**
+   * Why the input was rejected: `"invalid_length"` or `"invalid_character"`.
+   */
+  readonly kind: Exclude<Uuid58ErrorKind, "overflow">;
+  constructor(message: string, kind: Exclude<Uuid58ErrorKind, "overflow">);
+}
 /**
  * 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.
@@ -112,16 +106,17 @@ export declare class Uuid58EncodeError extends Error {}
  * // 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")
  * ```
  */
 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.
+ * @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
  *
@@ -136,6 +131,104 @@ export declare function uuid58EncodeSafe(uuid: string): string | Uuid58EncodeErr
  * ```
  */
 export declare function uuid58Encode(uuid: string): string;
+/**
+ * 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"
+ * ```
+ */
+export declare function uuid58EncodeBytesSafe(bytes: Uint8Array): string | Uuid58EncodeError;
+/**
+ * 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"
+ * ```
+ */
+export declare function uuid58EncodeBytes(bytes: Uint8Array): string;
+/**
+ * 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
+ * ```
+ */
+export declare function uuid58DecodeBytesSafe(uuid58: string): Uint8Array | Uuid58DecodeError;
+/**
+ * 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");
+ * ```
+ */
+export declare function uuid58DecodeBytes(uuid58: string): Uint8Array;
+/**
+ * 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;
 /**
  * Generates a new Base58-encoded UUID (always 22 characters).
  *
@@ -149,4 +242,5 @@ export declare function uuid58Encode(uuid: string): string;
  * const id = uuid58(); // returns a 22-character string like "XDY9dmBbcMBXqcRvYw8xJ2"
  * ```
  */
-export declare function uuid58(): string;
+export declare function uuid58(): string;
+export type { Uuid58ErrorKind };

package/dist/index.d.ts

@@ -16,49 +16,33 @@
  */
 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)
- * ```
+ * The kind of an encoding or decoding error, as defined by the uuid58
+ * specification (Section 7).
+ *
+ * - `"invalid_length"`: the input has the wrong length (a UUID string that is
+ *   neither 32 nor 36 characters, a uuid58 string that is not 22 characters,
+ *   or a byte array that is not 16 bytes long).
+ * - `"invalid_character"`: the input has the right length but contains a
+ *   character not allowed in its position.
+ * - `"overflow"`: (decoding only) the uuid58 string is well formed, but its
+ *   value is greater than 2^128 - 1.
+ *
+ * Inputs containing non-ASCII characters may report either
+ * `"invalid_length"` or `"invalid_character"`.
  */
-export declare function isUuid58(uuid58: string): boolean;
+type Uuid58ErrorKind = "invalid_length" | "invalid_character" | "overflow";
 /**
- * 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.
  */
-export declare class Uuid58DecodeError extends Error {}
+export declare class Uuid58DecodeError extends Error {
+  /**
+   * Why the input was rejected: `"invalid_length"`, `"invalid_character"`,
+   * or `"overflow"`.
+   */
+  readonly kind: Uuid58ErrorKind;
+  constructor(message: string, kind: Uuid58ErrorKind);
+}
 /**
  * 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`
@@ -72,7 +56,7 @@ export declare class Uuid58DecodeError extends Error {}
  * @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")
  * ```
  */
 export declare function uuid58DecodeSafe(uuid58: string): string | Uuid58DecodeError;
@@ -90,15 +74,25 @@ export declare function uuid58DecodeSafe(uuid58: string): string | Uuid58DecodeE
  */
 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).
+ * Error thrown when an invalid UUID string or byte array is provided for
+ * encoding. Its {@link Uuid58EncodeError.kind | kind} tells why.
  */
-export declare class Uuid58EncodeError extends Error {}
+export declare class Uuid58EncodeError extends Error {
+  /**
+   * Why the input was rejected: `"invalid_length"` or `"invalid_character"`.
+   */
+  readonly kind: Exclude<Uuid58ErrorKind, "overflow">;
+  constructor(message: string, kind: Exclude<Uuid58ErrorKind, "overflow">);
+}
 /**
  * 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.
@@ -112,16 +106,17 @@ export declare class Uuid58EncodeError extends Error {}
  * // 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")
  * ```
  */
 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.
+ * @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
  *
@@ -136,6 +131,104 @@ export declare function uuid58EncodeSafe(uuid: string): string | Uuid58EncodeErr
  * ```
  */
 export declare function uuid58Encode(uuid: string): string;
+/**
+ * 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"
+ * ```
+ */
+export declare function uuid58EncodeBytesSafe(bytes: Uint8Array): string | Uuid58EncodeError;
+/**
+ * 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"
+ * ```
+ */
+export declare function uuid58EncodeBytes(bytes: Uint8Array): string;
+/**
+ * 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
+ * ```
+ */
+export declare function uuid58DecodeBytesSafe(uuid58: string): Uint8Array | Uuid58DecodeError;
+/**
+ * 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");
+ * ```
+ */
+export declare function uuid58DecodeBytes(uuid58: string): Uint8Array;
+/**
+ * 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;
 /**
  * Generates a new Base58-encoded UUID (always 22 characters).
  *
@@ -149,4 +242,5 @@ export declare function uuid58Encode(uuid: string): string;
  * const id = uuid58(); // returns a 22-character string like "XDY9dmBbcMBXqcRvYw8xJ2"
  * ```
  */
-export declare function uuid58(): string;
+export declare function uuid58(): string;
+export type { Uuid58ErrorKind };