@nakanoaas/uuid58 1.1.0 → 1.2.0

package/README.md

@@ -94,6 +94,15 @@ if (decodedSafe instanceof Uuid58DecodeError) {
 }
 // use decoded UUID
 console.log(decodedSafe);
+
+import { isUuid58, UUID58_REGEX } from "@nakanoaas/uuid58";
+
+// Validate UUID58 string without decoding
+const isValid = isUuid58("XDY9dmBbcMBXqcRvYw8xJ2"); // true
+const isValid2 = isUuid58("invalid"); // false
+
+// Or use regex pattern for validation
+const isValid3 = UUID58_REGEX.test("XDY9dmBbcMBXqcRvYw8xJ2"); // true
 ```
 
 ## API Reference
@@ -187,6 +196,34 @@ that are not exactly 22 characters long.
 class Uuid58DecodeError extends Error;
 ```
 
+### `isUuid58(uuid58: string)`
+
+Checks if a given string is a valid UUID58-encodable string. This function
+efficiently validates without performing full decoding.
+
+```typescript
+function isUuid58(uuid58: string): boolean;
+```
+
+- **Parameters:**
+  - `uuid58`: The string to check
+- **Returns:** `true` if the string is a valid UUID58 string, `false` otherwise
+- **Note:** This function validates:
+  - Length (must be exactly 22 characters)
+  - Base58 alphabet characters only
+  - That the decoded value fits within 128 bits (UUID size)
+
+**Example:**
+
+```typescript
+import { isUuid58 } from "@nakanoaas/uuid58";
+
+isUuid58("XDY9dmBbcMBXqcRvYw8xJ2"); // true
+isUuid58("invalid"); // false
+isUuid58("O0lI"); // false (contains invalid characters)
+isUuid58("short"); // false (too short)
+```
+
 ### Alphabet and Utilities
 
 #### `UUID58_ALPHABET`
@@ -211,6 +248,11 @@ Base58 alphabet.
 const UUID58_REGEX: RegExp; // /^[1-9A-HJ-NP-Za-km-z]{22}$/
 ```
 
+**Note:** While `UUID58_REGEX` can validate the format, `isUuid58()` provides
+more comprehensive validation by also checking that the decoded value fits
+within 128 bits. For simple format checks, the regex is sufficient; for complete
+validation, use `isUuid58()`.
+
 **Example:**
 
 ```typescript

package/esm/alphabet.d.ts

@@ -21,20 +21,4 @@ export declare const UUID58_ALPHABET: string;
  * This is exported for internal use but not part of the public API.
  */
 export declare const UUID58_LENGTH: bigint;
-/**
- * Regular expression pattern for validating UUID58 strings.
- *
- * This regex ensures that a string:
- * - Contains exactly 22 characters
- * - Uses only characters from the Base58 alphabet
- * - Does not start with leading zeros (represented as "1" in Base58)
- *
- * @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;
 //# sourceMappingURL=alphabet.d.ts.map

package/esm/alphabet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alphabet.d.ts","sourceRoot":"","sources":["../src/alphabet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,EAAE,MACgC,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,MAAuC,CAAC;AAEpE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,MAAsC,CAAC"}
+{"version":3,"file":"alphabet.d.ts","sourceRoot":"","sources":["../src/alphabet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,EAAE,MACgC,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,MAAuC,CAAC"}

package/esm/alphabet.js

@@ -21,19 +21,3 @@ export const UUID58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnop
  * This is exported for internal use but not part of the public API.
  */
 export const UUID58_LENGTH = BigInt(UUID58_ALPHABET.length);
-/**
- * Regular expression pattern for validating UUID58 strings.
- *
- * This regex ensures that a string:
- * - Contains exactly 22 characters
- * - Uses only characters from the Base58 alphabet
- * - Does not start with leading zeros (represented as "1" in Base58)
- *
- * @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 const UUID58_REGEX = /^[1-9A-HJ-NP-Za-km-z]{22}$/u;

package/esm/check.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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;
+/**
+ * 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;
+//# sourceMappingURL=check.d.ts.map

package/esm/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAmChD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,YAAY,EAAE,MAAsC,CAAC"}

package/esm/check.js

@@ -0,0 +1,73 @@
+const MAX_UUID58_CODES = Array.from(
+// UUID max value encoded in Base58 (length 22)
+"YcVfxkQb6JRzqk5kF2tNLv", // cspell:disable-line
+(char) => char.charCodeAt(0));
+/**
+ * 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 function isUuid58(uuid58) {
+    // Check length: UUID58 strings must be exactly 22 characters
+    if (uuid58.length !== 22) {
+        return false;
+    }
+    // Compare chars against the max-UUID Base58 string using ASCII order
+    let isBelowMax = false;
+    for (let i = 0; i < 22; i++) {
+        const code = uuid58.charCodeAt(i);
+        // Check if character is in the Bitcoin Base58 alphabet
+        if (code < 49 ||
+            (code >= 58 && code <= 64) || // ':'..'@'
+            code === 73 || // 'I'
+            code === 79 || // 'O'
+            (code >= 91 && code <= 96) || // '['..'`'
+            code === 108 || // 'l'
+            code > 122) {
+            return false;
+        }
+        if (!isBelowMax) {
+            const maxCode = MAX_UUID58_CODES[i];
+            if (code < maxCode) {
+                isBelowMax = true;
+            }
+            else if (code > maxCode) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * 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 const UUID58_REGEX = /^[1-9A-HJ-NP-Za-km-z]{22}$/u;

package/esm/index.d.ts

@@ -1,4 +1,5 @@
-export { UUID58_ALPHABET, UUID58_REGEX } from "./alphabet.js";
+export { UUID58_ALPHABET } from "./alphabet.js";
+export * from "./check.js";
 export * from "./decode.js";
 export * from "./encode.js";
 export * from "./generate.js";

package/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC9D,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}

package/esm/index.js

@@ -1,4 +1,5 @@
-export { UUID58_ALPHABET, UUID58_REGEX } from "./alphabet.js";
+export { UUID58_ALPHABET } from "./alphabet.js";
+export * from "./check.js";
 export * from "./decode.js";
 export * from "./encode.js";
 export * from "./generate.js";

package/package.json

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

package/script/alphabet.d.ts

@@ -21,20 +21,4 @@ export declare const UUID58_ALPHABET: string;
  * This is exported for internal use but not part of the public API.
  */
 export declare const UUID58_LENGTH: bigint;
-/**
- * Regular expression pattern for validating UUID58 strings.
- *
- * This regex ensures that a string:
- * - Contains exactly 22 characters
- * - Uses only characters from the Base58 alphabet
- * - Does not start with leading zeros (represented as "1" in Base58)
- *
- * @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;
 //# sourceMappingURL=alphabet.d.ts.map

package/script/alphabet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alphabet.d.ts","sourceRoot":"","sources":["../src/alphabet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,EAAE,MACgC,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,MAAuC,CAAC;AAEpE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE,MAAsC,CAAC"}
+{"version":3,"file":"alphabet.d.ts","sourceRoot":"","sources":["../src/alphabet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,EAAE,MACgC,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,MAAuC,CAAC"}

package/script/alphabet.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UUID58_REGEX = exports.UUID58_LENGTH = exports.UUID58_ALPHABET = void 0;
+exports.UUID58_LENGTH = exports.UUID58_ALPHABET = void 0;
 /**
  * Character set for Base58 encoding (Bitcoin compatible).
  *
@@ -24,19 +24,3 @@ exports.UUID58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstu
  * This is exported for internal use but not part of the public API.
  */
 exports.UUID58_LENGTH = BigInt(exports.UUID58_ALPHABET.length);
-/**
- * Regular expression pattern for validating UUID58 strings.
- *
- * This regex ensures that a string:
- * - Contains exactly 22 characters
- * - Uses only characters from the Base58 alphabet
- * - Does not start with leading zeros (represented as "1" in Base58)
- *
- * @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)
- * ```
- */
-exports.UUID58_REGEX = /^[1-9A-HJ-NP-Za-km-z]{22}$/u;

package/script/check.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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;
+/**
+ * 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;
+//# sourceMappingURL=check.d.ts.map

package/script/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAmChD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,YAAY,EAAE,MAAsC,CAAC"}

package/script/check.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UUID58_REGEX = void 0;
+exports.isUuid58 = isUuid58;
+const MAX_UUID58_CODES = Array.from(
+// UUID max value encoded in Base58 (length 22)
+"YcVfxkQb6JRzqk5kF2tNLv", // cspell:disable-line
+(char) => char.charCodeAt(0));
+/**
+ * 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) {
+    // Check length: UUID58 strings must be exactly 22 characters
+    if (uuid58.length !== 22) {
+        return false;
+    }
+    // Compare chars against the max-UUID Base58 string using ASCII order
+    let isBelowMax = false;
+    for (let i = 0; i < 22; i++) {
+        const code = uuid58.charCodeAt(i);
+        // Check if character is in the Bitcoin Base58 alphabet
+        if (code < 49 ||
+            (code >= 58 && code <= 64) || // ':'..'@'
+            code === 73 || // 'I'
+            code === 79 || // 'O'
+            (code >= 91 && code <= 96) || // '['..'`'
+            code === 108 || // 'l'
+            code > 122) {
+            return false;
+        }
+        if (!isBelowMax) {
+            const maxCode = MAX_UUID58_CODES[i];
+            if (code < maxCode) {
+                isBelowMax = true;
+            }
+            else if (code > maxCode) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * 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)
+ * ```
+ */
+exports.UUID58_REGEX = /^[1-9A-HJ-NP-Za-km-z]{22}$/u;

package/script/index.d.ts

@@ -1,4 +1,5 @@
-export { UUID58_ALPHABET, UUID58_REGEX } from "./alphabet.js";
+export { UUID58_ALPHABET } from "./alphabet.js";
+export * from "./check.js";
 export * from "./decode.js";
 export * from "./encode.js";
 export * from "./generate.js";

package/script/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC9D,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}

package/script/index.js

@@ -14,10 +14,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UUID58_REGEX = exports.UUID58_ALPHABET = void 0;
+exports.UUID58_ALPHABET = void 0;
 var alphabet_js_1 = require("./alphabet.js");
 Object.defineProperty(exports, "UUID58_ALPHABET", { enumerable: true, get: function () { return alphabet_js_1.UUID58_ALPHABET; } });
-Object.defineProperty(exports, "UUID58_REGEX", { enumerable: true, get: function () { return alphabet_js_1.UUID58_REGEX; } });
+__exportStar(require("./check.js"), exports);
 __exportStar(require("./decode.js"), exports);
 __exportStar(require("./encode.js"), exports);
 __exportStar(require("./generate.js"), exports);