Merge changes from v1.9.0-next.1 into main (#103)

Author: trevor-anderson

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+# [1.9.0-next.1](https://github.com/Nerdware-LLC/ts-string-helpers/compare/v1.8.1...v1.9.0-next.1) (2025-02-24)
+
+
+### Features
+
+* add `isValidUUID` ([5d77323](https://github.com/Nerdware-LLC/ts-string-helpers/commit/5d773230f72c035da2423856c71bacb8177ac98d))
+
 ## [1.8.1](https://github.com/Nerdware-LLC/ts-string-helpers/compare/v1.8.0...v1.8.1) (2025-02-24)
 
 

README.md

@@ -147,6 +147,7 @@ app.post("/register", (req, res, next) => {
 | [`isValidText`](src/validate/text.ts)                         | Returns `true` if `value` does not contain potentially harmful characters ([🌎i18n-friendly](#-unicode-support)) |
 | [`isValidURL`](src/validate/url.ts)                           | Returns `true` if `value` is a valid absolute or relative URL (protocol agnostic)                                |
 | [`isValidHttpURL`](src/validate/url.ts)                       | Returns `true` if `value` is a valid absolute HTTP/S URL                                                         |
+| [`isValidUUID`](src/validate/uuid.ts)                         | Returns `true` if `value` is a valid UUID _**of any version**_                                                   |
 
 ## 🌎 Unicode Support
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerdware/ts-string-helpers",
-  "version": "1.8.1",
+  "version": "1.9.0-next.1",
   "description": "TypeScript string utils for validation and sanitization.",
   "author": {
     "name": "Trevor Anderson",

package.json

@@ -17,3 +17,4 @@ export * from "./phone.js";
 export * from "./streetAddress.js";
 export * from "./text.js";
 export * from "./url.js";
+export * from "./uuid.js";

src/validate/index.ts

@@ -0,0 +1,39 @@
+import { isValidUUID } from "./uuid.js";
+
+describe("isValidUUID", () => {
+  // POSITIVE TEST CASES
+  test.each([
+    // The UUID spec defines a total of 8 versions
+    ...["1", "2", "3", "4", "5", "6", "7", "8"].map((uuidVersionNum) => ({
+      // Note: the hard-coded 8 reflects the UUID variant
+      input: `aaaaaaaa-aaaa-${uuidVersionNum}aaa-8aaa-aaaaaaaaaaaa`,
+      description: `a version-${uuidVersionNum} UUID string`,
+    })),
+    { input: "00000000-0000-0000-0000-000000000000", description: "the nil UUID (all zeros)" },
+    { input: "ffffffff-ffff-ffff-ffff-ffffffffffff", description: "the max UUID (all f's)" },
+  ])(`returns true when called with $description`, ({ input }) => {
+    expect(isValidUUID(input)).toBe(true);
+  });
+
+  // NEGATIVE TEST CASES
+  test.each([
+    { input: "", description: "an empty string" },
+    { input: "foo", description: "a non-UUID string" },
+    { input: 1, description: "1 (a truthy number)" },
+    { input: 0, description: "0 (zero)" },
+    { input: true, description: "true (boolean)" },
+    { input: false, description: "false (boolean)" },
+    { input: null, description: "null" },
+    { input: undefined, description: "undefined" },
+    {
+      input: "aaaaaaaa-aaaa-9aaa-8aaa-aaaaaaaaaaaa",
+      description: "a UUID with an invalid version number",
+    },
+    {
+      input: "aaaaaaaa-aaaa-1aaa-7aaa-aaaaaaaaaaaa",
+      description: "a UUID with an invalid variant identifier", // must be 8, 9, a, or b
+    },
+  ])("returns false when called with $description", ({ input }) => {
+    expect(isValidUUID(input)).toBe(false);
+  });
+});

src/validate/uuid.test.ts

@@ -0,0 +1,14 @@
+import { getValidatorFn } from "../utils/getValidatorFn.js";
+
+/**
+ * Regex for validating UUIDs _**of any version**_.
+ *
+ * Regex source: https://github.com/uuidjs/uuid/blob/6dcb15b86357afdf29ae2dabf5b2a8afab83c2c0/src/regex.js
+ */
+export const UUID_VALIDATION_REGEX =
+  /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/i;
+
+/**
+ * Returns `true` if `value` is a valid UUID _**of any version**_.
+ */
+export const isValidUUID = getValidatorFn(UUID_VALIDATION_REGEX);