@mantiq/validation 0.0.1

package/README.md

@@ -0,0 +1,19 @@
+# @mantiq/validation
+
+Validation rule engine with 40+ built-in rules and FormRequest base class for MantiqJS.
+
+Part of [MantiqJS](https://github.com/abdullahkhan/mantiq) — a batteries-included TypeScript web framework for Bun.
+
+## Installation
+
+```bash
+bun add @mantiq/validation
+```
+
+## Documentation
+
+See the [MantiqJS repository](https://github.com/abdullahkhan/mantiq) for full documentation.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@mantiq/validation",
+  "version": "0.0.1",
+  "description": "Rule engine, form requests",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abdullah Khan",
+  "homepage": "https://github.com/abdullahkhan/mantiq/tree/main/packages/validation",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/abdullahkhan/mantiq.git",
+    "directory": "packages/validation"
+  },
+  "bugs": {
+    "url": "https://github.com/abdullahkhan/mantiq/issues"
+  },
+  "keywords": [
+    "mantiq",
+    "mantiqjs",
+    "bun",
+    "typescript",
+    "framework",
+    "validation"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@mantiq/core": "workspace:*"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.7.0"
+  }
+}

package/src/FormRequest.ts

@@ -0,0 +1,79 @@
+import type { MantiqRequest } from '@mantiq/core'
+import { ForbiddenError } from '@mantiq/core'
+import { Validator, type RuleDefinition } from './Validator.ts'
+import type { Rule } from './contracts/Rule.ts'
+
+/**
+ * Base form request — subclass this to declare validation rules and
+ * authorization logic for a specific endpoint.
+ *
+ * @example
+ *   class StoreUserRequest extends FormRequest {
+ *     rules() {
+ *       return { name: 'required|string|max:255', email: 'required|email' }
+ *     }
+ *     authorize() {
+ *       return this.request.isAuthenticated()
+ *     }
+ *   }
+ *
+ *   // In a controller:
+ *   const data = await new StoreUserRequest(request).validate()
+ */
+export abstract class FormRequest {
+  protected _validator: Validator | null = null
+
+  constructor(protected readonly request: MantiqRequest) {}
+
+  /** Define the validation rules for this request. */
+  abstract rules(): Record<string, RuleDefinition>
+
+  /** Determine if the user is authorized to make this request. Defaults to true. */
+  authorize(): boolean | Promise<boolean> {
+    return true
+  }
+
+  /** Custom error messages keyed by 'field.rule' or 'rule'. */
+  messages(): Record<string, string> {
+    return {}
+  }
+
+  /** Custom attribute names for error message replacement. */
+  attributes(): Record<string, string> {
+    return {}
+  }
+
+  /**
+   * Run authorization + validation. Returns validated data or throws.
+   * Throws ForbiddenError (403) if unauthorized, ValidationError (422) if invalid.
+   */
+  async validate(): Promise<Record<string, any>> {
+    const authorized = await this.authorize()
+    if (!authorized) {
+      throw new ForbiddenError('This action is unauthorized.')
+    }
+
+    const data = await this.data()
+    this._validator = new Validator(data, this.rules(), this.messages(), this.attributes())
+    this.configureValidator(this._validator)
+    return this._validator.validate()
+  }
+
+  /** Override to customize which data is validated (defaults to all input). */
+  protected async data(): Promise<Record<string, any>> {
+    return this.request.input()
+  }
+
+  /** Override to configure the validator (e.g., set a presence verifier). */
+  protected configureValidator(_validator: Validator): void {}
+
+  /** Access the validator after validate() has been called. */
+  get validator(): Validator | null {
+    return this._validator
+  }
+
+  /** Access validation errors after validate() has been called. */
+  get errors(): Record<string, string[]> {
+    return this._validator?.errors() ?? {}
+  }
+}

package/src/ValidationServiceProvider.ts

@@ -0,0 +1,40 @@
+import { ServiceProvider } from '@mantiq/core'
+import { Validator } from './Validator.ts'
+import type { Rule } from './contracts/Rule.ts'
+import type { PresenceVerifier } from './contracts/PresenceVerifier.ts'
+
+export const PRESENCE_VERIFIER = Symbol('PresenceVerifier')
+
+/**
+ * Registers validation-related bindings in the container.
+ *
+ * @example
+ *   // In your app bootstrap:
+ *   app.register(new ValidationServiceProvider(app))
+ *
+ *   // To enable database rules (exists, unique), also bind a PresenceVerifier:
+ *   app.singleton(PRESENCE_VERIFIER, () => new DatabasePresenceVerifier(db))
+ */
+export class ValidationServiceProvider extends ServiceProvider {
+  register(): void {
+    // Bind a factory that creates pre-configured Validators
+    this.app.bind('validator', () => {
+      return (
+        data: Record<string, any>,
+        rules: Record<string, string | (string | Rule)[]>,
+        messages?: Record<string, string>,
+        attributes?: Record<string, string>,
+      ) => {
+        const validator = new Validator(data, rules, messages, attributes)
+        // Auto-attach presence verifier if one is bound
+        try {
+          const verifier = this.app.make<PresenceVerifier>(PRESENCE_VERIFIER)
+          validator.setPresenceVerifier(verifier)
+        } catch {
+          // No presence verifier bound — database rules will throw if used
+        }
+        return validator
+      }
+    })
+  }
+}

package/src/Validator.ts

@@ -0,0 +1,283 @@
+import { ValidationError } from '@mantiq/core'
+import type { Rule, ValidationContext } from './contracts/Rule.ts'
+import type { PresenceVerifier } from './contracts/PresenceVerifier.ts'
+import { builtinRules } from './rules/builtin.ts'
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+interface ParsedRule {
+  name: string
+  params: string[]
+  rule?: Rule
+}
+
+export type RuleDefinition = string | (string | Rule)[]
+
+// ── Validator ────────────────────────────────────────────────────────────────
+
+export class Validator {
+  private _errors: Record<string, string[]> = {}
+  private _validated: Record<string, any> = {}
+  private _hasRun = false
+  private _presenceVerifier: PresenceVerifier | null = null
+  private _stopOnFirstFailure = false
+
+  private static _extensions: Record<string, Rule> = {}
+
+  constructor(
+    private readonly _data: Record<string, any>,
+    private readonly _rules: Record<string, RuleDefinition>,
+    private readonly _customMessages: Record<string, string> = {},
+    private readonly _customAttributes: Record<string, string> = {},
+  ) {}
+
+  // ── Configuration ─────────────────────────────────────────────────────────
+
+  setPresenceVerifier(verifier: PresenceVerifier): this {
+    this._presenceVerifier = verifier
+    return this
+  }
+
+  stopOnFirstFailure(stop = true): this {
+    this._stopOnFirstFailure = stop
+    return this
+  }
+
+  // ── Run ───────────────────────────────────────────────────────────────────
+
+  async validate(): Promise<Record<string, any>> {
+    await this.run()
+    if (Object.keys(this._errors).length > 0) {
+      throw new ValidationError(this._errors)
+    }
+    return this._validated
+  }
+
+  async fails(): Promise<boolean> {
+    await this.run()
+    return Object.keys(this._errors).length > 0
+  }
+
+  async passes(): Promise<boolean> {
+    return !(await this.fails())
+  }
+
+  errors(): Record<string, string[]> {
+    return { ...this._errors }
+  }
+
+  validated(): Record<string, any> {
+    return { ...this._validated }
+  }
+
+  // ── Static extensions ─────────────────────────────────────────────────────
+
+  static extend(name: string, rule: Rule): void {
+    Validator._extensions[name] = rule
+  }
+
+  static resetExtensions(): void {
+    Validator._extensions = {}
+  }
+
+  // ── Private: orchestration ────────────────────────────────────────────────
+
+  private async run(): Promise<void> {
+    if (this._hasRun) return
+    this._hasRun = true
+    this._errors = {}
+    this._validated = {}
+
+    for (const [fieldPattern, ruleSet] of Object.entries(this._rules)) {
+      const fields = this.expandField(fieldPattern)
+      for (const field of fields) {
+        await this.validateField(field, ruleSet)
+        if (this._stopOnFirstFailure && this._errors[field]?.length) break
+      }
+      if (this._stopOnFirstFailure && Object.keys(this._errors).length > 0) break
+    }
+  }
+
+  private async validateField(field: string, ruleSet: RuleDefinition): Promise<void> {
+    const rules = this.parseRules(ruleSet)
+    const value = this.getValue(field)
+
+    // Pre-scan for meta rules
+    let bail = false
+    let isNullable = false
+    let isSometimes = false
+    for (const r of rules) {
+      if (r.name === 'bail') bail = true
+      if (r.name === 'nullable') isNullable = true
+      if (r.name === 'sometimes') isSometimes = true
+    }
+
+    // sometimes: skip if field not present in data
+    if (isSometimes && !this.hasField(field)) return
+
+    // nullable: if value is null/undefined, accept it and skip remaining rules
+    if (isNullable && (value === null || value === undefined)) {
+      this.setValidated(field, value)
+      return
+    }
+
+    let hasError = false
+    for (const parsed of rules) {
+      if (parsed.name === 'bail' || parsed.name === 'nullable' || parsed.name === 'sometimes') continue
+
+      const result = await this.runRule(parsed, value, field)
+      if (typeof result === 'string') {
+        this.addError(field, result, parsed)
+        hasError = true
+        if (bail) break
+      }
+    }
+
+    if (!hasError) {
+      this.setValidated(field, value)
+    }
+  }
+
+  // ── Private: rule execution ───────────────────────────────────────────────
+
+  private async runRule(parsed: ParsedRule, value: any, field: string): Promise<boolean | string> {
+    const rule = parsed.rule
+      ?? Validator._extensions[parsed.name]
+      ?? builtinRules[parsed.name]
+
+    if (!rule) {
+      throw new Error(`Validation rule [${parsed.name}] is not defined.`)
+    }
+
+    const context: ValidationContext = {
+      validator: this,
+      presenceVerifier: this._presenceVerifier,
+    }
+
+    return rule.validate(value, field, this._data, parsed.params, context)
+  }
+
+  // ── Private: parsing ──────────────────────────────────────────────────────
+
+  private parseRules(ruleSet: RuleDefinition): ParsedRule[] {
+    if (typeof ruleSet === 'string') {
+      return ruleSet.split('|').map((s) => this.parseRuleString(s))
+    }
+    return ruleSet.map((r) => {
+      if (typeof r === 'string') return this.parseRuleString(r)
+      return { name: r.name, params: [], rule: r }
+    })
+  }
+
+  private parseRuleString(rule: string): ParsedRule {
+    const colonIndex = rule.indexOf(':')
+    if (colonIndex === -1) return { name: rule.trim(), params: [] }
+    const name = rule.slice(0, colonIndex).trim()
+    const paramStr = rule.slice(colonIndex + 1)
+    return { name, params: paramStr.split(',') }
+  }
+
+  // ── Private: field expansion (wildcards) ──────────────────────────────────
+
+  private expandField(pattern: string): string[] {
+    if (!pattern.includes('*')) return [pattern]
+    return this.expandWildcard(pattern.split('.'), this._data, '')
+  }
+
+  private expandWildcard(segments: string[], data: any, prefix: string): string[] {
+    if (segments.length === 0) {
+      // Remove trailing dot
+      return prefix.length > 0 ? [prefix.slice(0, -1)] : ['']
+    }
+
+    const [head, ...rest] = segments
+
+    if (head === '*') {
+      if (Array.isArray(data)) {
+        const results: string[] = []
+        for (let i = 0; i < data.length; i++) {
+          results.push(...this.expandWildcard(rest, data[i], `${prefix}${i}.`))
+        }
+        return results
+      }
+      if (data && typeof data === 'object') {
+        const results: string[] = []
+        for (const key of Object.keys(data)) {
+          results.push(...this.expandWildcard(rest, data[key], `${prefix}${key}.`))
+        }
+        return results
+      }
+      return []
+    }
+
+    const next = data?.[head!]
+    return this.expandWildcard(rest, next, `${prefix}${head}.`)
+  }
+
+  // ── Private: data access ──────────────────────────────────────────────────
+
+  private getValue(field: string): any {
+    return field.split('.').reduce((obj, key) => {
+      if (obj === null || obj === undefined) return undefined
+      if (Array.isArray(obj) && /^\d+$/.test(key)) return obj[Number(key)]
+      return obj[key]
+    }, this._data as any)
+  }
+
+  private hasField(field: string): boolean {
+    const parts = field.split('.')
+    let current: any = this._data
+    for (const part of parts) {
+      if (current === null || current === undefined) return false
+      if (typeof current !== 'object') return false
+      if (Array.isArray(current)) {
+        if (!/^\d+$/.test(part)) return false
+        if (Number(part) >= current.length) return false
+        current = current[Number(part)]
+      } else {
+        if (!(part in current)) return false
+        current = current[part]
+      }
+    }
+    return true
+  }
+
+  private setValidated(field: string, value: any): void {
+    const parts = field.split('.')
+    let target = this._validated
+    for (let i = 0; i < parts.length - 1; i++) {
+      const key = parts[i]!
+      const nextKey = parts[i + 1]!
+      if (!(key in target)) {
+        target[key] = /^\d+$/.test(nextKey) ? [] : {}
+      }
+      target = target[key]
+    }
+    target[parts[parts.length - 1]!] = value
+  }
+
+  // ── Private: error messages ───────────────────────────────────────────────
+
+  private addError(field: string, message: string, parsed: ParsedRule): void {
+    // Custom message lookup: 'field.rule' > 'rule'
+    const customMessage = this._customMessages[`${field}.${parsed.name}`]
+      ?? this._customMessages[parsed.name]
+
+    const finalMessage = customMessage
+      ? this.replaceMessagePlaceholders(customMessage, field, parsed)
+      : message
+
+    if (!this._errors[field]) this._errors[field] = []
+    this._errors[field].push(finalMessage)
+  }
+
+  private replaceMessagePlaceholders(message: string, field: string, parsed: ParsedRule): string {
+    const attribute = this._customAttributes[field] ?? field.replace(/[_.]/g, ' ')
+    let result = message.replace(/:attribute/g, attribute)
+    // Replace positional params: :0, :1, etc.
+    for (let i = 0; i < parsed.params.length; i++) {
+      result = result.replace(new RegExp(`:${i}`, 'g'), parsed.params[i]!)
+    }
+    return result
+  }
+}

package/src/contracts/PresenceVerifier.ts

@@ -0,0 +1,34 @@
+/**
+ * Verifies the existence/uniqueness of values in a data store (typically a database).
+ * Used by the `exists` and `unique` validation rules.
+ */
+export interface PresenceVerifier {
+  /**
+   * Count the number of rows matching the given value.
+   *
+   * @param table     - Table name to query
+   * @param column    - Column to check
+   * @param value     - Value to look for
+   * @param excludeId - ID to exclude from the check (for unique with ignore)
+   * @param idColumn  - The ID column name (default 'id')
+   * @param extra     - Additional where clauses as [column, operator, value] tuples
+   */
+  getCount(
+    table: string,
+    column: string,
+    value: any,
+    excludeId?: string | number | null,
+    idColumn?: string,
+    extra?: [string, string, any][],
+  ): Promise<number>
+
+  /**
+   * Count the number of rows where the column matches any of the given values.
+   */
+  getMultiCount(
+    table: string,
+    column: string,
+    values: any[],
+    extra?: [string, string, any][],
+  ): Promise<number>
+}

package/src/contracts/Rule.ts

@@ -0,0 +1,28 @@
+/**
+ * Context passed to rules during validation — gives access to the
+ * validator instance and optional database presence verifier.
+ */
+export interface ValidationContext {
+  validator: any
+  presenceVerifier: any | null
+}
+
+/**
+ * A validation rule that can check a single field value.
+ */
+export interface Rule {
+  /** Rule name (e.g. 'required', 'min', 'email') */
+  readonly name: string
+
+  /**
+   * Validate the value.
+   * @returns true if valid, or a string error message if invalid.
+   */
+  validate(
+    value: any,
+    field: string,
+    data: Record<string, any>,
+    params: string[],
+    context?: ValidationContext,
+  ): boolean | string | Promise<boolean | string>
+}

package/src/helpers/validate.ts

@@ -0,0 +1,19 @@
+import { Validator, type RuleDefinition } from '../Validator.ts'
+
+/**
+ * Validate data against rules. Returns validated data or throws ValidationError.
+ *
+ * @example
+ *   const data = await validate(
+ *     { name: 'Alice', email: 'alice@example.com' },
+ *     { name: 'required|string|max:255', email: 'required|email' },
+ *   )
+ */
+export async function validate(
+  data: Record<string, any>,
+  rules: Record<string, RuleDefinition>,
+  messages?: Record<string, string>,
+  attributes?: Record<string, string>,
+): Promise<Record<string, any>> {
+  return new Validator(data, rules, messages, attributes).validate()
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+// @mantiq/validation — public API exports
+
+// ── Contracts ────────────────────────────────────────────────────────────────
+export type { Rule, ValidationContext } from './contracts/Rule.ts'
+export type { PresenceVerifier } from './contracts/PresenceVerifier.ts'
+
+// ── Core ─────────────────────────────────────────────────────────────────────
+export { Validator, type RuleDefinition } from './Validator.ts'
+export { FormRequest } from './FormRequest.ts'
+
+// ── Rules ────────────────────────────────────────────────────────────────────
+export { builtinRules } from './rules/builtin.ts'
+export {
+  // Presence
+  required, nullable, present, filled,
+  requiredIf, requiredUnless, requiredWith, requiredWithout,
+  // Types
+  string, numeric, integer, boolean, array, object,
+  // Size
+  min, max, between, size,
+  // String
+  email, url, uuid, regex, alpha, alphaNum, alphaDash,
+  startsWith, endsWith, lowercase, uppercase,
+  // Comparison
+  confirmed, same, different, gt, gte, lt, lte,
+  // Inclusion
+  inRule, notIn,
+  // Date
+  date, before, after,
+  // Special
+  ip, json,
+  // Database
+  exists, unique,
+} from './rules/builtin.ts'
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+export { validate } from './helpers/validate.ts'
+
+// ── Service Provider ─────────────────────────────────────────────────────────
+export { ValidationServiceProvider, PRESENCE_VERIFIER } from './ValidationServiceProvider.ts'

package/src/rules/builtin.ts

@@ -0,0 +1,396 @@
+import type { Rule } from '../contracts/Rule.ts'
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function isEmpty(v: any): boolean {
+  return v === undefined || v === null || v === '' || (Array.isArray(v) && v.length === 0)
+}
+
+function getSize(v: any): number {
+  if (typeof v === 'string' || Array.isArray(v)) return v.length
+  if (typeof v === 'number') return v
+  return 0
+}
+
+function getNestedValue(data: Record<string, any>, path: string): any {
+  return path.split('.').reduce((obj, key) => obj?.[key], data)
+}
+
+// ── Presence rules ───────────────────────────────────────────────────────────
+
+export const required: Rule = {
+  name: 'required',
+  validate: (v, field) => !isEmpty(v) || `The ${field} field is required.`,
+}
+
+export const nullable: Rule = {
+  name: 'nullable',
+  validate: () => true, // marker rule — handled by Validator
+}
+
+export const present: Rule = {
+  name: 'present',
+  validate: (v, field, data) =>
+    field in data || `The ${field} field must be present.`,
+}
+
+export const filled: Rule = {
+  name: 'filled',
+  validate: (v, field, data) =>
+    !(field in data) || !isEmpty(v) || `The ${field} field must not be empty when present.`,
+}
+
+// ── Conditional presence ─────────────────────────────────────────────────────
+
+export const requiredIf: Rule = {
+  name: 'required_if',
+  validate: (v, field, data, [otherField, ...values]) => {
+    const other = getNestedValue(data, otherField!)
+    if (values.includes(String(other))) {
+      return !isEmpty(v) || `The ${field} field is required when ${otherField} is ${values.join(', ')}.`
+    }
+    return true
+  },
+}
+
+export const requiredUnless: Rule = {
+  name: 'required_unless',
+  validate: (v, field, data, [otherField, ...values]) => {
+    const other = getNestedValue(data, otherField!)
+    if (!values.includes(String(other))) {
+      return !isEmpty(v) || `The ${field} field is required unless ${otherField} is ${values.join(', ')}.`
+    }
+    return true
+  },
+}
+
+export const requiredWith: Rule = {
+  name: 'required_with',
+  validate: (v, field, data, params) => {
+    const anyPresent = params.some((p) => !isEmpty(getNestedValue(data, p)))
+    if (anyPresent) return !isEmpty(v) || `The ${field} field is required when ${params.join(', ')} is present.`
+    return true
+  },
+}
+
+export const requiredWithout: Rule = {
+  name: 'required_without',
+  validate: (v, field, data, params) => {
+    const anyMissing = params.some((p) => isEmpty(getNestedValue(data, p)))
+    if (anyMissing) return !isEmpty(v) || `The ${field} field is required when ${params.join(', ')} is not present.`
+    return true
+  },
+}
+
+// ── Type rules ───────────────────────────────────────────────────────────────
+
+export const string: Rule = {
+  name: 'string',
+  validate: (v, field) =>
+    isEmpty(v) || typeof v === 'string' || `The ${field} field must be a string.`,
+}
+
+export const numeric: Rule = {
+  name: 'numeric',
+  validate: (v, field) =>
+    isEmpty(v) || !isNaN(Number(v)) || `The ${field} field must be a number.`,
+}
+
+export const integer: Rule = {
+  name: 'integer',
+  validate: (v, field) =>
+    isEmpty(v) || Number.isInteger(Number(v)) || `The ${field} field must be an integer.`,
+}
+
+export const boolean: Rule = {
+  name: 'boolean',
+  validate: (v, field) =>
+    isEmpty(v) || [true, false, 0, 1, '0', '1', 'true', 'false'].includes(v) || `The ${field} field must be true or false.`,
+}
+
+export const array: Rule = {
+  name: 'array',
+  validate: (v, field) =>
+    isEmpty(v) || Array.isArray(v) || `The ${field} field must be an array.`,
+}
+
+export const object: Rule = {
+  name: 'object',
+  validate: (v, field) =>
+    isEmpty(v) || (typeof v === 'object' && v !== null && !Array.isArray(v)) || `The ${field} field must be an object.`,
+}
+
+// ── Size rules ───────────────────────────────────────────────────────────────
+
+export const min: Rule = {
+  name: 'min',
+  validate: (v, field, _data, [param]) => {
+    if (isEmpty(v)) return true
+    const limit = Number(param)
+    const size = getSize(v)
+    if (typeof v === 'string' || Array.isArray(v))
+      return size >= limit || `The ${field} field must be at least ${limit} characters.`
+    return size >= limit || `The ${field} field must be at least ${limit}.`
+  },
+}
+
+export const max: Rule = {
+  name: 'max',
+  validate: (v, field, _data, [param]) => {
+    if (isEmpty(v)) return true
+    const limit = Number(param)
+    const size = getSize(v)
+    if (typeof v === 'string' || Array.isArray(v))
+      return size <= limit || `The ${field} field must not be greater than ${limit} characters.`
+    return size <= limit || `The ${field} field must not be greater than ${limit}.`
+  },
+}
+
+export const between: Rule = {
+  name: 'between',
+  validate: (v, field, _data, [lo, hi]) => {
+    if (isEmpty(v)) return true
+    const size = getSize(v)
+    return (size >= Number(lo) && size <= Number(hi)) || `The ${field} field must be between ${lo} and ${hi}.`
+  },
+}
+
+export const size: Rule = {
+  name: 'size',
+  validate: (v, field, _data, [param]) => {
+    if (isEmpty(v)) return true
+    const expected = Number(param)
+    return getSize(v) === expected || `The ${field} field must be ${expected}.`
+  },
+}
+
+// ── String rules ─────────────────────────────────────────────────────────────
+
+export const email: Rule = {
+  name: 'email',
+  validate: (v, field) =>
+    isEmpty(v) || /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(v)) || `The ${field} field must be a valid email address.`,
+}
+
+export const url: Rule = {
+  name: 'url',
+  validate: (v, field) => {
+    if (isEmpty(v)) return true
+    try { new URL(String(v)); return true } catch { return `The ${field} field must be a valid URL.` }
+  },
+}
+
+export const uuid: Rule = {
+  name: 'uuid',
+  validate: (v, field) =>
+    isEmpty(v) || /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(String(v)) || `The ${field} field must be a valid UUID.`,
+}
+
+export const regex: Rule = {
+  name: 'regex',
+  validate: (v, field, _data, [pattern]) => {
+    if (isEmpty(v)) return true
+    const match = pattern!.match(/^\/(.+)\/([gimsuy]*)$/)
+    const re = match ? new RegExp(match[1]!, match[2]) : new RegExp(pattern!)
+    return re.test(String(v)) || `The ${field} field format is invalid.`
+  },
+}
+
+export const alpha: Rule = {
+  name: 'alpha',
+  validate: (v, field) =>
+    isEmpty(v) || /^[a-zA-Z]+$/.test(String(v)) || `The ${field} field must only contain letters.`,
+}
+
+export const alphaNum: Rule = {
+  name: 'alpha_num',
+  validate: (v, field) =>
+    isEmpty(v) || /^[a-zA-Z0-9]+$/.test(String(v)) || `The ${field} field must only contain letters and numbers.`,
+}
+
+export const alphaDash: Rule = {
+  name: 'alpha_dash',
+  validate: (v, field) =>
+    isEmpty(v) || /^[a-zA-Z0-9_-]+$/.test(String(v)) || `The ${field} field must only contain letters, numbers, dashes and underscores.`,
+}
+
+export const startsWith: Rule = {
+  name: 'starts_with',
+  validate: (v, field, _data, params) =>
+    isEmpty(v) || params.some((p) => String(v).startsWith(p)) || `The ${field} field must start with one of: ${params.join(', ')}.`,
+}
+
+export const endsWith: Rule = {
+  name: 'ends_with',
+  validate: (v, field, _data, params) =>
+    isEmpty(v) || params.some((p) => String(v).endsWith(p)) || `The ${field} field must end with one of: ${params.join(', ')}.`,
+}
+
+export const lowercase: Rule = {
+  name: 'lowercase',
+  validate: (v, field) =>
+    isEmpty(v) || String(v) === String(v).toLowerCase() || `The ${field} field must be lowercase.`,
+}
+
+export const uppercase: Rule = {
+  name: 'uppercase',
+  validate: (v, field) =>
+    isEmpty(v) || String(v) === String(v).toUpperCase() || `The ${field} field must be uppercase.`,
+}
+
+// ── Comparison rules ─────────────────────────────────────────────────────────
+
+export const confirmed: Rule = {
+  name: 'confirmed',
+  validate: (v, field, data) =>
+    isEmpty(v) || v === data[`${field}_confirmation`] || `The ${field} confirmation does not match.`,
+}
+
+export const same: Rule = {
+  name: 'same',
+  validate: (v, field, data, [other]) =>
+    isEmpty(v) || v === getNestedValue(data, other!) || `The ${field} and ${other} must match.`,
+}
+
+export const different: Rule = {
+  name: 'different',
+  validate: (v, field, data, [other]) =>
+    isEmpty(v) || v !== getNestedValue(data, other!) || `The ${field} and ${other} must be different.`,
+}
+
+export const gt: Rule = {
+  name: 'gt',
+  validate: (v, field, data, [other]) => {
+    if (isEmpty(v)) return true
+    const otherVal = getNestedValue(data, other!)
+    return getSize(v) > getSize(otherVal) || `The ${field} field must be greater than ${other}.`
+  },
+}
+
+export const gte: Rule = {
+  name: 'gte',
+  validate: (v, field, data, [other]) => {
+    if (isEmpty(v)) return true
+    const otherVal = getNestedValue(data, other!)
+    return getSize(v) >= getSize(otherVal) || `The ${field} field must be greater than or equal to ${other}.`
+  },
+}
+
+export const lt: Rule = {
+  name: 'lt',
+  validate: (v, field, data, [other]) => {
+    if (isEmpty(v)) return true
+    const otherVal = getNestedValue(data, other!)
+    return getSize(v) < getSize(otherVal) || `The ${field} field must be less than ${other}.`
+  },
+}
+
+export const lte: Rule = {
+  name: 'lte',
+  validate: (v, field, data, [other]) => {
+    if (isEmpty(v)) return true
+    const otherVal = getNestedValue(data, other!)
+    return getSize(v) <= getSize(otherVal) || `The ${field} field must be less than or equal to ${other}.`
+  },
+}
+
+// ── Inclusion rules ──────────────────────────────────────────────────────────
+
+export const inRule: Rule = {
+  name: 'in',
+  validate: (v, field, _data, params) =>
+    isEmpty(v) || params.includes(String(v)) || `The selected ${field} is invalid.`,
+}
+
+export const notIn: Rule = {
+  name: 'not_in',
+  validate: (v, field, _data, params) =>
+    isEmpty(v) || !params.includes(String(v)) || `The selected ${field} is invalid.`,
+}
+
+// ── Date rules ───────────────────────────────────────────────────────────────
+
+export const date: Rule = {
+  name: 'date',
+  validate: (v, field) =>
+    isEmpty(v) || !isNaN(Date.parse(String(v))) || `The ${field} field must be a valid date.`,
+}
+
+export const before: Rule = {
+  name: 'before',
+  validate: (v, field, _data, [param]) =>
+    isEmpty(v) || new Date(String(v)) < new Date(param!) || `The ${field} field must be a date before ${param}.`,
+}
+
+export const after: Rule = {
+  name: 'after',
+  validate: (v, field, _data, [param]) =>
+    isEmpty(v) || new Date(String(v)) > new Date(param!) || `The ${field} field must be a date after ${param}.`,
+}
+
+// ── Special rules ────────────────────────────────────────────────────────────
+
+export const ip: Rule = {
+  name: 'ip',
+  validate: (v, field) => {
+    if (isEmpty(v)) return true
+    const s = String(v)
+    const v4 = /^(\d{1,3}\.){3}\d{1,3}$/.test(s) && s.split('.').every((p) => Number(p) <= 255)
+    const v6 = /^([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}$/.test(s)
+    return v4 || v6 || `The ${field} field must be a valid IP address.`
+  },
+}
+
+export const json: Rule = {
+  name: 'json',
+  validate: (v, field) => {
+    if (isEmpty(v)) return true
+    try { JSON.parse(String(v)); return true } catch { return `The ${field} field must be a valid JSON string.` }
+  },
+}
+
+// ── Database rules (require PresenceVerifier) ───────────────────────────────
+
+export const exists: Rule = {
+  name: 'exists',
+  validate: async (v, field, _data, params, context) => {
+    if (isEmpty(v)) return true
+    const [table, column = field] = params
+    if (!table) throw new Error('The exists rule requires a table parameter.')
+    const verifier = context?.presenceVerifier
+    if (!verifier) throw new Error('A presence verifier is required for the exists rule. Set it via validator.setPresenceVerifier().')
+    const count = await verifier.getCount(table, column, v)
+    return count > 0 || `The selected ${field} is invalid.`
+  },
+}
+
+export const unique: Rule = {
+  name: 'unique',
+  validate: async (v, field, _data, params, context) => {
+    if (isEmpty(v)) return true
+    const [table, column = field, except, idColumn = 'id'] = params
+    if (!table) throw new Error('The unique rule requires a table parameter.')
+    const verifier = context?.presenceVerifier
+    if (!verifier) throw new Error('A presence verifier is required for the unique rule. Set it via validator.setPresenceVerifier().')
+    const excludeId = !except || except === 'NULL' ? null : except
+    const count = await verifier.getCount(table, column, v, excludeId, idColumn)
+    return count === 0 || `The ${field} has already been taken.`
+  },
+}
+
+// ── Map rule names to implementations ────────────────────────────────────────
+
+export const builtinRules: Record<string, Rule> = {
+  required, nullable, present, filled,
+  required_if: requiredIf, required_unless: requiredUnless,
+  required_with: requiredWith, required_without: requiredWithout,
+  string, numeric, integer, boolean, array, object,
+  min, max, between, size,
+  email, url, uuid, regex, alpha, alpha_num: alphaNum, alpha_dash: alphaDash,
+  starts_with: startsWith, ends_with: endsWith, lowercase, uppercase,
+  confirmed, same, different, gt, gte, lt, lte,
+  in: inRule, not_in: notIn,
+  date, before, after,
+  ip, json,
+  exists, unique,
+}