feat: add match regex validation

library/src/validations/index.ts

@@ -24,6 +24,7 @@ export * from './length/index.ts';
 export * from './mac/index.ts';
 export * from './mac48/index.ts';
 export * from './mac64/index.ts';
+export * from './match/index.ts';
 export * from './maxBytes/index.ts';
 export * from './maxLength/index.ts';
 export * from './maxSize/index.ts';

library/src/validations/match/index.ts

@@ -0,0 +1 @@
+export * from './match.ts';

library/src/validations/match/match.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from 'vitest';
+import { match } from './match.ts';
+
+describe('match', () => {
+  test('should pass only valid matches', () => {
+    const validate = match(/abc/u);
+    const value1 = 'abc';
+    expect(validate._parse(value1).output).toBe(value1);
+    const value2 = 'abcdev';
+    expect(validate._parse(value2).output).toBe(value2);
+    const value3 = '123abc';
+    expect(validate._parse(value3).output).toBe(value3);
+
+    const validate2 = match(/abc/iu);
+    const value4 = 'abc';
+    expect(validate2._parse(value4).output).toBe(value4);
+    const value5 = 'abcdef';
+    expect(validate2._parse(value5).output).toBe(value5);
+    const value6 = '123abc';
+    expect(validate2._parse(value6).output).toBe(value6);
+    const value7 = 'AbCd%';
+    expect(validate2._parse(value7).output).toBe(value7);
+
+    expect(validate._parse('').issues).toBeTruthy();
+    expect(validate._parse('acb').issues).toBeTruthy();
+    expect(validate._parse('Abc').issues).toBeTruthy();
+    expect(validate._parse('123').issues).toBeTruthy();
+
+    expect(validate2._parse('acb').issues).toBeTruthy();
+  });
+
+  test('should return custom error message', () => {
+    const error = 'Value not matching digit numbers!';
+    const validate = match(/^\d/u, error);
+    expect(validate._parse('abc').issues?.[0].message).toBe(error);
+  });
+});

library/src/validations/match/match.ts

@@ -0,0 +1,44 @@
+import type { BaseValidation, ErrorMessage } from '../../types/index.ts';
+import { actionIssue, actionOutput } from '../../utils/index.ts';
+
+/**
+ * Match validation type.
+ */
+export type MatchValidation<
+  TInput extends string,
+  TRequirement extends RegExp
+> = BaseValidation<TInput> & {
+  /**
+   * The validation type.
+   */
+  type: 'match';
+  /**
+   * The regular expression requirement
+   */
+  requirement: TRequirement;
+};
+
+/**
+ * Creates a validation function that validates string against regular expression [RegExp](https://en.wikipedia.org/wiki/Regular_expression).
+ *
+ * @param requirement regular expression requirement
+ * @param message The error message.
+ *
+ * @returns A validation function.
+ */
+export function match<TInput extends string, TRequirement extends RegExp>(
+  requirement: TRequirement,
+  message: ErrorMessage = 'Invalid string'
+): MatchValidation<TInput, TRequirement> {
+  return {
+    type: 'match',
+    async: false,
+    message,
+    requirement,
+    _parse(input) {
+      return !this.requirement.test(input)
+        ? actionIssue(this.type, this.message, input, this.requirement)
+        : actionOutput(input);
+    },
+  };
+}

website/src/routes/api/(validations)/match/index.mdx

@@ -0,0 +1,9 @@
+---
+title: match
+contributors:
+  - ariskemper
+---
+
+# match
+
+> The content of this page is not yet ready. Until then just use the [source code](https://github.com/fabian-hiller/valibot/blob/main/library/src/validations/match/match.ts).

website/src/routes/api/menu.md

@@ -87,6 +87,7 @@
 - [mac](/api/mac/)
 - [mac48](/api/mac48/)
 - [mac64](/api/mac64/)
+- [match](/api/match/)
 - [maxBytes](/api/maxBytes/)
 - [maxLength](/api/maxLength/)
 - [maxSize](/api/maxSize/)

website/src/routes/guides/(main-concepts)/pipelines/index.mdx

@@ -67,6 +67,7 @@ Validation functions examine the input and, if the input does not meet a certain
     'mac',
     'mac48',
     'mac64',
+    'match',
     'maxBytes',
     'maxLength',
     'maxSize',