@regexto/validators 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukasz Oleniuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# @regexto/validators
+
+A curated collection of battle-tested regex patterns with TypeScript types, Zod v4 integration, and multi-language code generation.
+
+**Patterns live in `/patterns/*.json`** — the single source of truth used by both this package and the [regex.to](https://regex.to) website.
+
+[![npm version](https://img.shields.io/npm/v/@regexto/validators)](https://www.npmjs.com/package/@regexto/validators)
+[![license](https://img.shields.io/npm/l/@regexto/validators)](LICENSE)
+
+## Installation
+
+```bash
+npm install @regexto/validators
+# with Zod v4 integration:
+npm install @regexto/validators zod
+```
+
+## Usage
+
+```typescript
+import { test, validate, getRegex, getAllPatterns } from '@regexto/validators';
+
+// Quick boolean test (partial match — use validate() for full-string validation)
+test('email', 'user@example.com');   // → true
+test('email', 'invalid');            // → false
+
+// Full-string validation with anchors
+const { valid } = validate('ipv4', '192.168.1.1');  // → { valid: true, ... }
+const { valid: no } = validate('ipv4', '999.0.0.0'); // → { valid: false, ... }
+
+// Get the compiled RegExp
+const re = getRegex('email');        // → /[a-zA-Z0-9...]+@.../i
+
+// All patterns as an array
+const all = getAllPatterns();        // → PatternData[]
+```
+
+### Zod v4 Integration
+
+```typescript
+import { zodSchema, zodObjectSchema } from '@regexto/validators/zod';
+import { z } from 'zod';
+
+// Single-field schema
+const emailSchema = zodSchema('email');
+emailSchema.parse('user@example.com');   // ✓
+emailSchema.parse('invalid');            // ✗ ZodError
+
+// Object schema from a field map
+const contactSchema = zodObjectSchema({
+  email: 'email',
+  website: 'url',
+});
+type ContactForm = z.infer<typeof contactSchema>;
+```
+
+### detect() — Auto-detect string type
+
+```typescript
+import { detect } from '@regexto/validators';
+
+detect('user@example.com');
+// → [{ pattern: { slug: 'email', ... }, matchType: 'full', coverage: 1 }]
+
+detect('+14155552671');
+// → [{ pattern: { slug: 'phone-e164', ... }, matchType: 'full', coverage: 1 }]
+
+detect('0x742d35Cc6634C0532925a3b844Bc454e4438f44e');
+// → [{ pattern: { slug: 'eth-address', ... }, matchType: 'full', coverage: 1 }]
+```
+
+## Available Patterns
+
+| Slug | Name | Category |
+|------|------|----------|
+| `email` | Email Address | Internet |
+| `url` | URL (HTTP/HTTPS) | Internet |
+| `ipv4` | IPv4 Address | Network |
+| `ipv6` | IPv6 Address | Network |
+| `hex-color` | Hex Color | Design |
+| `rgb-color` | RGB Color | Design |
+| `iso-date` | ISO 8601 Date | Date & Time |
+| `semver` | Semantic Version | Dev |
+| `slug` | URL Slug | Web |
+| `uuid` | UUID | Dev |
+| `credit-card` | Credit Card Number | Finance |
+| `iban` | IBAN | Finance |
+| `jwt` | JSON Web Token | Security |
+| `sha256` | SHA-256 Hash | Crypto |
+| `ethereum-address` | Ethereum Address | Crypto |
+| `bitcoin-address` | Bitcoin Address | Crypto |
+| `pl-nip` | Polish NIP (Tax ID) | Finance |
+| `pl-pesel` | Polish PESEL | Identity |
+| `pl-regon` | Polish REGON | Finance |
+| `us-ssn` | US Social Security Number | Identity |
+| `us-zip` | US ZIP Code | Address |
+| `uk-postcode` | UK Postcode | Address |
+| … | 79 patterns total | [Browse all](https://regex.to/patterns) |
+
+## API
+
+| Function | Description |
+|----------|-------------|
+| `test(slug, value)` | Quick boolean — partial match (substring) |
+| `validate(slug, value)` | Full-string match with anchors, returns result object |
+| `getRegex(slug)` | Returns the compiled `RegExp` |
+| `detect(input)` | Auto-detect type of an unknown string |
+| `getAllPatterns()` | Returns all patterns as `PatternData[]` |
+| `getPattern(slug)` | Returns a single `PatternData` or `null` |
+| `getByCategory(category)` | Filter by category |
+| `getByTags(tags[])` | Filter by tags |
+| `getSlugs()` | All available slugs |
+| `getCategories()` | All available category names |
+| `zodSchema(slug)` | Zod string schema *(zod import)* |
+| `zodObjectSchema(fieldMap)` | Zod object schema *(zod import)* |
+
+## Adding a Pattern
+
+Create a JSON file in `patterns/` and open a Pull Request:
+
+```json
+{
+  "slug": "my-pattern",
+  "name": "My Pattern",
+  "description": "What it validates",
+  "category": "Internet",
+  "pattern": "your[regex]+",
+  "flags": "i",
+  "examples": ["valid"],
+  "counterExamples": ["invalid"],
+  "tags": ["tag1"],
+  "useCases": ["Use case description"]
+}
+```
+
+The JSON file is automatically picked up by both the npm package and the regex.to website at build time — no code changes needed.
+
+See the full [contribution guide](https://regex.to/docs#contributing).
+
+## License
+
+MIT © [regex.to](https://regex.to)

package/dist/chunk-DL6DNLHZ.mjs

@@ -0,0 +1,117 @@
+// node_modules/tsup/assets/esm_shims.js
+import path from "path";
+import { fileURLToPath } from "url";
+var getFilename = () => fileURLToPath(import.meta.url);
+var getDirname = () => path.dirname(getFilename());
+var __dirname = /* @__PURE__ */ getDirname();
+
+// src/index.ts
+import fs from "fs";
+import path2 from "path";
+
+// src/detect.ts
+function detect(input) {
+  if (!input || !input.trim()) return [];
+  const all = Object.values(PATTERNS);
+  const results = [];
+  for (const p of all) {
+    try {
+      const baseFlags = p.flags.replace(/[gm]/g, "");
+      try {
+        const fullRe = new RegExp(`^(?:${p.pattern})$`, baseFlags);
+        if (fullRe.test(input)) {
+          results.push({ pattern: p, matchType: "full", matchedText: input, coverage: 1 });
+          continue;
+        }
+      } catch {
+      }
+      try {
+        const partialRe = new RegExp(p.pattern, baseFlags);
+        const m = partialRe.exec(input);
+        if (m?.[0] && m[0].length >= 4 && m[0].length / input.length >= 0.2) {
+          results.push({
+            pattern: p,
+            matchType: "partial",
+            matchedText: m[0],
+            coverage: m[0].length / input.length
+          });
+        }
+      } catch {
+      }
+    } catch {
+    }
+  }
+  return results.sort((a, b) => {
+    if (a.matchType !== b.matchType) return a.matchType === "full" ? -1 : 1;
+    if (Math.abs(b.coverage - a.coverage) > 0.05) return b.coverage - a.coverage;
+    return b.pattern.pattern.length - a.pattern.pattern.length;
+  });
+}
+
+// src/index.ts
+function loadPatterns() {
+  const dir = path2.join(__dirname, "..", "patterns");
+  const result = {};
+  try {
+    const files = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+    for (const file of files) {
+      const raw = fs.readFileSync(path2.join(dir, file), "utf-8");
+      const p = JSON.parse(raw);
+      result[p.slug] = p;
+    }
+  } catch {
+  }
+  return result;
+}
+var PATTERNS = loadPatterns();
+function getRegex(slug) {
+  const p = PATTERNS[slug];
+  if (!p) throw new Error(`Pattern "${slug}" not found in @regex.to/validators`);
+  return new RegExp(p.pattern, p.flags);
+}
+function test(slug, value) {
+  return getRegex(slug).test(value);
+}
+function validate(slug, value) {
+  const p = PATTERNS[slug];
+  if (!p) throw new Error(`Pattern "${slug}" not found`);
+  const regex = new RegExp(`^(?:${p.pattern})$`, p.flags);
+  const matches = value.match(regex);
+  return { valid: matches !== null, pattern: p, matches };
+}
+function getAllPatterns() {
+  return Object.values(PATTERNS);
+}
+function getByCategory(category) {
+  return Object.values(PATTERNS).filter((p) => p.category === category);
+}
+function getByTags(tags) {
+  return Object.values(PATTERNS).filter(
+    (p) => tags.some((t) => p.tags.includes(t))
+  );
+}
+function getPattern(slug) {
+  return PATTERNS[slug] ?? null;
+}
+function getCategories() {
+  return [...new Set(Object.values(PATTERNS).map((p) => p.category))].sort();
+}
+function getSlugs() {
+  return Object.keys(PATTERNS);
+}
+var index_default = PATTERNS;
+
+export {
+  detect,
+  PATTERNS,
+  getRegex,
+  test,
+  validate,
+  getAllPatterns,
+  getByCategory,
+  getByTags,
+  getPattern,
+  getCategories,
+  getSlugs,
+  index_default
+};

package/dist/index.d.mts

@@ -0,0 +1,107 @@
+type MatchType = "full" | "partial";
+interface DetectResult {
+    /** The matching pattern */
+    pattern: PatternData;
+    /** "full" = entire string matches; "partial" = substring matches */
+    matchType: MatchType;
+    /** The substring that was matched (equals input for full matches) */
+    matchedText: string;
+    /** Ratio of matchedText.length / input.length (1.0 for full matches) */
+    coverage: number;
+}
+/**
+ * Detects the type(s) of an unknown string by testing it against all
+ * available patterns. Returns results sorted by confidence — full matches
+ * first, then by coverage ratio.
+ *
+ * @example
+ * detect("user@example.com")
+ * // → [{ pattern: { slug: "email", ... }, matchType: "full", coverage: 1 }]
+ *
+ * @example
+ * detect("+14155552671")
+ * // → [{ slug: "phone-e164", matchType: "full" }, { slug: "phone-us", matchType: "partial" }, ...]
+ */
+declare function detect(input: string): DetectResult[];
+
+type PatternFlavor = "javascript" | "golang" | "php" | "python";
+interface PatternData {
+    /** Unique slug used in URLs, e.g. "email", "pl-nip" */
+    slug: string;
+    /** Human-readable name */
+    name: string;
+    /** Short description */
+    description: string;
+    /** Category for catalog grouping */
+    category: string;
+    /** The raw regex source (no delimiters) */
+    pattern: string;
+    /** Regex flags, e.g. "gi" */
+    flags: string;
+    /** Example strings that should match */
+    examples: string[];
+    /** Example strings that should NOT match */
+    counterExamples: string[];
+    /** Named capture groups (if any) */
+    groups?: Record<string, string>;
+    /** ISO 639-1 locale codes this pattern is designed for */
+    locales?: string[];
+    /** Tags for search */
+    tags: string[];
+    /** Use-case descriptions */
+    useCases?: string[];
+    /** SEO page title override */
+    seoTitle?: string;
+    /** SEO meta description override */
+    seoDescription?: string;
+}
+/** @deprecated Use PatternData instead */
+type RegexPattern = PatternData;
+/**
+ * All available regex patterns, keyed by slug.
+ * Loaded at module initialisation from the /patterns JSON files.
+ */
+declare const PATTERNS: Readonly<Record<string, PatternData>>;
+/**
+ * Returns a compiled RegExp for the given pattern slug.
+ * Throws if the slug is not found.
+ */
+declare function getRegex(slug: string): RegExp;
+/**
+ * Tests a value against a named pattern.
+ */
+declare function test(slug: string, value: string): boolean;
+/**
+ * Validates a value and returns a typed result.
+ */
+declare function validate(slug: string, value: string): {
+    valid: boolean;
+    pattern: PatternData;
+    matches: RegExpMatchArray | null;
+};
+/**
+ * Returns all patterns as an array, optionally filtered.
+ */
+declare function getAllPatterns(): PatternData[];
+/**
+ * Returns all patterns belonging to a category.
+ */
+declare function getByCategory(category: string): PatternData[];
+/**
+ * Returns all patterns matching one or more tags.
+ */
+declare function getByTags(tags: string[]): PatternData[];
+/**
+ * Returns a single pattern by slug, or null if not found.
+ */
+declare function getPattern(slug: string): PatternData | null;
+/**
+ * Returns all available category names (sorted).
+ */
+declare function getCategories(): string[];
+/**
+ * Returns all pattern slugs.
+ */
+declare function getSlugs(): string[];
+
+export { type DetectResult, type MatchType, PATTERNS, type PatternData, type PatternFlavor, type RegexPattern, PATTERNS as default, detect, getAllPatterns, getByCategory, getByTags, getCategories, getPattern, getRegex, getSlugs, test, validate };

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+type MatchType = "full" | "partial";
+interface DetectResult {
+    /** The matching pattern */
+    pattern: PatternData;
+    /** "full" = entire string matches; "partial" = substring matches */
+    matchType: MatchType;
+    /** The substring that was matched (equals input for full matches) */
+    matchedText: string;
+    /** Ratio of matchedText.length / input.length (1.0 for full matches) */
+    coverage: number;
+}
+/**
+ * Detects the type(s) of an unknown string by testing it against all
+ * available patterns. Returns results sorted by confidence — full matches
+ * first, then by coverage ratio.
+ *
+ * @example
+ * detect("user@example.com")
+ * // → [{ pattern: { slug: "email", ... }, matchType: "full", coverage: 1 }]
+ *
+ * @example
+ * detect("+14155552671")
+ * // → [{ slug: "phone-e164", matchType: "full" }, { slug: "phone-us", matchType: "partial" }, ...]
+ */
+declare function detect(input: string): DetectResult[];
+
+type PatternFlavor = "javascript" | "golang" | "php" | "python";
+interface PatternData {
+    /** Unique slug used in URLs, e.g. "email", "pl-nip" */
+    slug: string;
+    /** Human-readable name */
+    name: string;
+    /** Short description */
+    description: string;
+    /** Category for catalog grouping */
+    category: string;
+    /** The raw regex source (no delimiters) */
+    pattern: string;
+    /** Regex flags, e.g. "gi" */
+    flags: string;
+    /** Example strings that should match */
+    examples: string[];
+    /** Example strings that should NOT match */
+    counterExamples: string[];
+    /** Named capture groups (if any) */
+    groups?: Record<string, string>;
+    /** ISO 639-1 locale codes this pattern is designed for */
+    locales?: string[];
+    /** Tags for search */
+    tags: string[];
+    /** Use-case descriptions */
+    useCases?: string[];
+    /** SEO page title override */
+    seoTitle?: string;
+    /** SEO meta description override */
+    seoDescription?: string;
+}
+/** @deprecated Use PatternData instead */
+type RegexPattern = PatternData;
+/**
+ * All available regex patterns, keyed by slug.
+ * Loaded at module initialisation from the /patterns JSON files.
+ */
+declare const PATTERNS: Readonly<Record<string, PatternData>>;
+/**
+ * Returns a compiled RegExp for the given pattern slug.
+ * Throws if the slug is not found.
+ */
+declare function getRegex(slug: string): RegExp;
+/**
+ * Tests a value against a named pattern.
+ */
+declare function test(slug: string, value: string): boolean;
+/**
+ * Validates a value and returns a typed result.
+ */
+declare function validate(slug: string, value: string): {
+    valid: boolean;
+    pattern: PatternData;
+    matches: RegExpMatchArray | null;
+};
+/**
+ * Returns all patterns as an array, optionally filtered.
+ */
+declare function getAllPatterns(): PatternData[];
+/**
+ * Returns all patterns belonging to a category.
+ */
+declare function getByCategory(category: string): PatternData[];
+/**
+ * Returns all patterns matching one or more tags.
+ */
+declare function getByTags(tags: string[]): PatternData[];
+/**
+ * Returns a single pattern by slug, or null if not found.
+ */
+declare function getPattern(slug: string): PatternData | null;
+/**
+ * Returns all available category names (sorted).
+ */
+declare function getCategories(): string[];
+/**
+ * Returns all pattern slugs.
+ */
+declare function getSlugs(): string[];
+
+export { type DetectResult, type MatchType, PATTERNS, type PatternData, type PatternFlavor, type RegexPattern, PATTERNS as default, detect, getAllPatterns, getByCategory, getByTags, getCategories, getPattern, getRegex, getSlugs, test, validate };

package/dist/index.js

@@ -0,0 +1,154 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PATTERNS: () => PATTERNS,
+  default: () => index_default,
+  detect: () => detect,
+  getAllPatterns: () => getAllPatterns,
+  getByCategory: () => getByCategory,
+  getByTags: () => getByTags,
+  getCategories: () => getCategories,
+  getPattern: () => getPattern,
+  getRegex: () => getRegex,
+  getSlugs: () => getSlugs,
+  test: () => test,
+  validate: () => validate
+});
+module.exports = __toCommonJS(index_exports);
+var import_fs = __toESM(require("fs"));
+var import_path = __toESM(require("path"));
+
+// src/detect.ts
+function detect(input) {
+  if (!input || !input.trim()) return [];
+  const all = Object.values(PATTERNS);
+  const results = [];
+  for (const p of all) {
+    try {
+      const baseFlags = p.flags.replace(/[gm]/g, "");
+      try {
+        const fullRe = new RegExp(`^(?:${p.pattern})$`, baseFlags);
+        if (fullRe.test(input)) {
+          results.push({ pattern: p, matchType: "full", matchedText: input, coverage: 1 });
+          continue;
+        }
+      } catch {
+      }
+      try {
+        const partialRe = new RegExp(p.pattern, baseFlags);
+        const m = partialRe.exec(input);
+        if (m?.[0] && m[0].length >= 4 && m[0].length / input.length >= 0.2) {
+          results.push({
+            pattern: p,
+            matchType: "partial",
+            matchedText: m[0],
+            coverage: m[0].length / input.length
+          });
+        }
+      } catch {
+      }
+    } catch {
+    }
+  }
+  return results.sort((a, b) => {
+    if (a.matchType !== b.matchType) return a.matchType === "full" ? -1 : 1;
+    if (Math.abs(b.coverage - a.coverage) > 0.05) return b.coverage - a.coverage;
+    return b.pattern.pattern.length - a.pattern.pattern.length;
+  });
+}
+
+// src/index.ts
+function loadPatterns() {
+  const dir = import_path.default.join(__dirname, "..", "patterns");
+  const result = {};
+  try {
+    const files = import_fs.default.readdirSync(dir).filter((f) => f.endsWith(".json"));
+    for (const file of files) {
+      const raw = import_fs.default.readFileSync(import_path.default.join(dir, file), "utf-8");
+      const p = JSON.parse(raw);
+      result[p.slug] = p;
+    }
+  } catch {
+  }
+  return result;
+}
+var PATTERNS = loadPatterns();
+function getRegex(slug) {
+  const p = PATTERNS[slug];
+  if (!p) throw new Error(`Pattern "${slug}" not found in @regex.to/validators`);
+  return new RegExp(p.pattern, p.flags);
+}
+function test(slug, value) {
+  return getRegex(slug).test(value);
+}
+function validate(slug, value) {
+  const p = PATTERNS[slug];
+  if (!p) throw new Error(`Pattern "${slug}" not found`);
+  const regex = new RegExp(`^(?:${p.pattern})$`, p.flags);
+  const matches = value.match(regex);
+  return { valid: matches !== null, pattern: p, matches };
+}
+function getAllPatterns() {
+  return Object.values(PATTERNS);
+}
+function getByCategory(category) {
+  return Object.values(PATTERNS).filter((p) => p.category === category);
+}
+function getByTags(tags) {
+  return Object.values(PATTERNS).filter(
+    (p) => tags.some((t) => p.tags.includes(t))
+  );
+}
+function getPattern(slug) {
+  return PATTERNS[slug] ?? null;
+}
+function getCategories() {
+  return [...new Set(Object.values(PATTERNS).map((p) => p.category))].sort();
+}
+function getSlugs() {
+  return Object.keys(PATTERNS);
+}
+var index_default = PATTERNS;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PATTERNS,
+  detect,
+  getAllPatterns,
+  getByCategory,
+  getByTags,
+  getCategories,
+  getPattern,
+  getRegex,
+  getSlugs,
+  test,
+  validate
+});

package/dist/index.mjs

@@ -0,0 +1,28 @@
+import {
+  PATTERNS,
+  detect,
+  getAllPatterns,
+  getByCategory,
+  getByTags,
+  getCategories,
+  getPattern,
+  getRegex,
+  getSlugs,
+  index_default,
+  test,
+  validate
+} from "./chunk-DL6DNLHZ.mjs";
+export {
+  PATTERNS,
+  index_default as default,
+  detect,
+  getAllPatterns,
+  getByCategory,
+  getByTags,
+  getCategories,
+  getPattern,
+  getRegex,
+  getSlugs,
+  test,
+  validate
+};