Added assert.string.pattern()

Author: JamesMessinger

README.md

@@ -363,6 +363,40 @@ assert.string.length("John Doe", 5);           // ❌ Invalid value: "John Doe".
 ```
 
 
+### `assert.string.pattern(value, regex, [fieldName], [defaultValue])`
+Asserts that a value is a string that matches the specified Regular Expression pattern.
+
+- **value** - The value to check
+- **regex** - The regular expression to test
+- **fieldName** - (optional) The name of the field being assertd. This is used in the error message if the assertion fails.
+- **defaultValue** - (optional) The default value to use if `value` is `undefined`.
+
+```javascript
+import assert from "@jsdevtools/assert";
+
+assert.string.pattern("Foo", /^fo+$/i);                 // ✔
+assert.string.pattern("image.jpg", /\.(jpg|jpeg)/);     // ✔
+assert.string.pattern("", /^\w*$/);                     // ✔
+
+assert.string.pattern("foobar", /^fo+$/i);              // ❌ Invalid value: "foobar". It must match /^fo+$/i.
+assert.string.pattern("jpeg.gif", /\.(jpg|jpeg)/);      // ❌ Invalid value: "jpeg.gif". It must match /\\.(jpg|jpeg)/.
+```
+
+You can customize the assertion error message by adding an `example` or `examples` property to the RegExp object.
+
+```javascript
+import assert from "@jsdevtools/assert";
+
+let pattern = /\.(jpg|jpeg)/;
+pattern.example = "image.jpg";
+assert.string.pattern("jpeg.gif", pattern);       // ❌ Invalid value: "jpeg.gif". It should look like "image.jpg".
+
+let pattern = /\.(jpg|jpeg)/;
+pattern.examples = ["image.jpg", "image.jpeg"];
+assert.string.pattern("jpeg.gif", pattern);       // ❌ Invalid value: "jpeg.gif". It should look like "image.jpg" or "image.jpeg".
+```
+
+
 ### `assert.string.enum(value, enum, [fieldName], [defaultValue])`
 Asserts that a value is a string that is a member of the specified enumeration object.
 

src/string.ts

@@ -81,6 +81,16 @@ export interface AssertString {
    * Asserts that a value is one of the values of an enumeration object.
    */
   enum(value: unknown, enumeration: object, fieldName?: string, defaultValue?: string): string;
+
+  /**
+   * Asserts that a value matches the specified regular expression pattern.
+   */
+  pattern<T extends string>(value: T | undefined, pattern: RegExp, fieldName?: string, defaultValue?: T): T;
+
+  /**
+   * Asserts that a value matches the specified regular expression pattern.
+   */
+  pattern(value: unknown, pattern: RegExp, fieldName?: string, defaultValue?: unknown): string;
 }
 
 
@@ -95,6 +105,7 @@ string.minLength = assertMinLength;
 string.maxLength = assertMaxLength;
 Object.defineProperty(string, "length", { value: assertLength });
 string.enum = assertEnum;
+string.pattern = assertPattern;
 
 
 function assertNonEmpty(value: string | undefined, fieldName = "value", defaultValue?: string): string {
@@ -183,3 +194,29 @@ value: string | undefined, enumeration: object, fieldName = "value", defaultValu
 
   return value;
 }
+
+declare global {
+  interface RegExp {
+    example?: string;
+    examples?: string[];
+  }
+}
+
+function assertPattern(value: string | undefined, pattern: RegExp, fieldName = "value", defaultValue?: string): string {
+  value = type.string(value, fieldName, defaultValue);
+
+  if (!pattern.test(value)) {
+    if (Array.isArray(pattern.examples)) {
+      let humanizedExamples = humanize.values(pattern.examples, { conjunction: "or" });
+      throw ono(`Invalid ${fieldName}: ${humanize(value)}. It should look like ${humanizedExamples}.`);
+    }
+    if (typeof pattern.example === "string") {
+      throw ono(`Invalid ${fieldName}: ${humanize(value)}. It should look like ${humanize(pattern.example)}.`);
+    }
+    else {
+      throw ono(`Invalid ${fieldName}: ${humanize(value)}. It must match ${pattern}.`);
+    }
+  }
+
+  return value;
+}

test/specs/string-enum.spec.js

@@ -11,7 +11,7 @@ describe("assert.string.enum()", () => {
     expect(assert.string.enum("", { None: "", All: "all" })).to.equal("");
   });
 
-  it("should throw an error for values that are not in the list of allowed values", () => {
+  it("should throw an error for values that are not in the enumeration", () => {
     function notAllowed (value, enumeration) {
       return () => {
         assert.string.enum(value, enumeration);

test/specs/string-pattern.spec.js

@@ -0,0 +1,85 @@
+"use strict";
+
+const { assert } = require("../../lib");
+const { expect } = require("chai");
+
+describe("assert.string.pattern()", () => {
+
+  it("should assert values that match the pattern", () => {
+    expect(assert.string.pattern("", /^$/)).to.equal("");
+    expect(assert.string.pattern("FoOo", /^fo+$/i)).to.equal("FoOo");
+    expect(assert.string.pattern("logo.jpg", /\.(jpg|jpeg)$/)).to.equal("logo.jpg");
+  });
+
+  it("should throw an error for values that do not match the pattern", () => {
+    function invalid (value, pattern) {
+      return () => {
+        assert.string.pattern(value, pattern);
+      };
+    }
+
+    expect(invalid("foobar", /^fo+$/i))
+      .to.throw(Error, 'Invalid value: "foobar". It must match /^fo+$/i.');
+
+    expect(invalid("jpeg.gif", /\.(jpg|jpeg)$/))
+      .to.throw(Error, 'Invalid value: "jpeg.gif". It must match /\\.(jpg|jpeg)$/.');
+
+    expect(invalid("", /^a-z+$/))
+      .to.throw(Error, 'Invalid value: "". It must match /^a-z+$/.');
+  });
+
+  it("should throw an error for invalid defaults", () => {
+    function badDefault (defaultValue, pattern) {
+      return () => {
+        assert.string.pattern(undefined, pattern, "thing", defaultValue);
+      };
+    }
+
+    expect(badDefault("foobar", /^fo+$/i))
+      .to.throw(Error, 'Invalid thing: "foobar". It must match /^fo+$/i.');
+
+    expect(badDefault("jpeg.gif", /\.(jpg|jpeg)$/))
+      .to.throw(Error, 'Invalid thing: "jpeg.gif". It must match /\\.(jpg|jpeg)$/.');
+
+    expect(badDefault("", /^a-z+$/))
+      .to.throw(Error, 'Invalid thing: "". It must match /^a-z+$/.');
+  });
+
+  it("should throw an error using the example", () => {
+    function invalidWithExample (value, pattern, example) {
+      return () => {
+        pattern.examples = example;
+        pattern.example = example;
+        assert.string.pattern(value, pattern);
+      };
+    }
+
+    expect(invalidWithExample("foobar", /^fo+$/i, "fooooo"))
+      .to.throw(Error, 'Invalid value: "foobar". It should look like "fooooo".');
+
+    expect(invalidWithExample("jpeg.gif", /\.(jpg|jpeg)$/, ["image.jpg", "image.jpeg"]))
+      .to.throw(Error, 'Invalid value: "jpeg.gif". It should look like "image.jpg" or "image.jpeg".');
+
+    expect(invalidWithExample("", /^a-z$/, ["a", "b", "c", "d", "e"]))
+      .to.throw(Error, 'Invalid value: "". It should look like "a", "b", "c", "d", or "e".');
+  });
+
+  it("should not use the example if it's not a string", () => {
+    function invalidExample (value, pattern, example) {
+      return () => {
+        pattern.example = example;
+        assert.string.pattern(value, pattern);
+      };
+    }
+
+    expect(invalidExample("foobar", /^fo+$/i, 12345))
+      .to.throw(Error, 'Invalid value: "foobar". It must match /^fo+$/i.');
+
+    expect(invalidExample("jpeg.gif", /\.(jpg|jpeg)$/, new Date()))
+      .to.throw(Error, 'Invalid value: "jpeg.gif". It must match /\\.(jpg|jpeg)$/.');
+
+    expect(invalidExample("", /^a-z+$/, String))
+      .to.throw(Error, 'Invalid value: "". It must match /^a-z+$/.');
+  });
+
+});