@zerotal/validator 1.0.0

package/src/index.ts

@@ -0,0 +1,34 @@
+export { validate } from "./validate.ts";
+export { FormRequest } from "./FormRequest.ts";
+export { ValidatorFacade as Validator } from "./facades/Validator.ts";
+export { RuleBuilder } from "./RuleBuilder.ts";
+export {
+  StringRule,
+  NumberRule,
+  BooleanRule,
+  ArrayRule,
+  ObjectRule,
+  DateRule,
+  FileRule,
+  PasswordRule,
+} from "./FieldRule.ts";
+export type { FieldRule } from "./FieldRule.ts";
+export { ValidationRedirectError, ValidationJsonError } from "./ValidationError.ts";
+export { PrecognitionResponseError } from "./PrecognitionError.ts";
+export { runValidation, runValidationAsync } from "./Validator.ts";
+export { runStringRules, runStringRulesAsync } from "./stringRules.ts";
+export type { StringRules } from "./stringRules.ts";
+export { registerDbRuleRunner } from "./dbRules.ts";
+export type { UniqueOptions } from "./dbRules.ts";
+export type {
+  Schema,
+  FieldRuleDefinition,
+  ValidationErrors,
+  Infer,
+  ValidationOutcome,
+  InferFieldType,
+} from "./types.ts";
+
+// Config factory
+export { ValidatorConfig } from "./config.ts";
+export type { ValidatorConfigShape } from "./config.ts";

package/src/stringRules.ts

@@ -0,0 +1,298 @@
+/**
+ * Pipe-delimited string-rule validation ("required|min:3|email").
+ *
+ * This complements the fluent `RuleBuilder` schema API with the pipe-separated string syntax
+ * (and string arrays). It is the single engine for string rules across the framework — Flow's
+ * `@validate("…")` decorator and `this.validate()` delegate here rather than rolling their own,
+ * and the fluent schema engine (`Validator.ts`) delegates to the {@link RULES} registry for
+ * every rule it covers.
+ */
+
+export type StringRules = Record<string, string | string[]>;
+
+export type RuleFn = (
+  value: unknown,
+  param: string,
+  data: Record<string, unknown>,
+) => string | null;
+
+/**
+ * The shared rule registry — one implementation per rule name.
+ *
+ * Both the string-rule engine ({@link runStringRules}) and the fluent schema engine
+ * (`Validator.applyRule`) resolve rules from this map, so a rule like `email` behaves
+ * identically no matter which entry point it is validated through. Messages use the
+ * `:attr` placeholder, replaced with the field label by the caller.
+ */
+export const RULES: Record<string, RuleFn> = {
+  required(value) {
+    if (value === null || value === undefined || value === "") return ":attr is required.";
+    if (Array.isArray(value) && value.length === 0) return ":attr is required.";
+    return null;
+  },
+  nullable: () => null,
+  sometimes: () => null,
+
+  string(value) {
+    return typeof value !== "string" ? ":attr must be a string." : null;
+  },
+  numeric(value) {
+    return isNaN(Number(value)) ? ":attr must be numeric." : null;
+  },
+  integer(value) {
+    return !Number.isInteger(Number(value)) ? ":attr must be an integer." : null;
+  },
+  boolean(value) {
+    return ([true, false, "true", "false", "1", "0", 1, 0] as unknown[]).includes(value)
+      ? null
+      : ":attr must be true or false.";
+  },
+  array(value) {
+    return Array.isArray(value) ? null : ":attr must be an array.";
+  },
+  email(value) {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(value ?? ""))
+      ? null
+      : ":attr must be a valid email address.";
+  },
+  url(value) {
+    try {
+      new URL(String(value ?? ""));
+      return null;
+    } catch {
+      return ":attr must be a valid URL.";
+    }
+  },
+  min(value, param) {
+    const n = Number(param);
+    if (typeof value === "string") {
+      return value.length < n ? `:attr must be at least ${n} characters.` : null;
+    }
+    if (Array.isArray(value)) {
+      return value.length < n ? `:attr must have at least ${n} items.` : null;
+    }
+    const num = Number(value);
+    return isNaN(num) || num < n ? `:attr must be at least ${n}.` : null;
+  },
+  max(value, param) {
+    const n = Number(param);
+    if (typeof value === "string") {
+      return value.length > n ? `:attr must not exceed ${n} characters.` : null;
+    }
+    if (Array.isArray(value)) {
+      return value.length > n ? `:attr must have no more than ${n} items.` : null;
+    }
+    const num = Number(value);
+    return isNaN(num) || num > n ? `:attr must not exceed ${n}.` : null;
+  },
+  size(value, param) {
+    const n = Number(param);
+    if (typeof value === "string") {
+      return value.length !== n ? `:attr must be exactly ${n} characters.` : null;
+    }
+    if (Array.isArray(value)) {
+      return value.length !== n ? `:attr must contain exactly ${n} items.` : null;
+    }
+    return Number(value) !== n ? `:attr must be exactly ${n}.` : null;
+  },
+  between(value, param) {
+    const [lo, hi] = param.split(",").map(Number) as [number, number];
+    const n = Number(value);
+    if (typeof value === "string") {
+      return value.length < lo || value.length > hi
+        ? `:attr must be between ${lo} and ${hi} characters.`
+        : null;
+    }
+    return isNaN(n) || n < lo || n > hi ? `:attr must be between ${lo} and ${hi}.` : null;
+  },
+  in(value, param) {
+    const opts = param.split(",").map((s) => s.trim());
+    return opts.includes(String(value)) ? null : `:attr must be one of: ${opts.join(", ")}.`;
+  },
+  not_in(value, param) {
+    const opts = param.split(",").map((s) => s.trim());
+    return !opts.includes(String(value)) ? null : `:attr must not be one of: ${opts.join(", ")}.`;
+  },
+  same(value, param, data) {
+    return value === data[param] ? null : `:attr must match ${param}.`;
+  },
+  different(value, param, data) {
+    return value !== data[param] ? null : `:attr must be different from ${param}.`;
+  },
+  gt(value, param, data) {
+    const ref = Number(data[param] ?? param);
+    return Number(value) > ref ? null : `:attr must be greater than ${param}.`;
+  },
+  lt(value, param, data) {
+    const ref = Number(data[param] ?? param);
+    return Number(value) < ref ? null : `:attr must be less than ${param}.`;
+  },
+  gte(value, param, data) {
+    const ref = Number(data[param] ?? param);
+    return Number(value) >= ref ? null : `:attr must be greater than or equal to ${param}.`;
+  },
+  lte(value, param, data) {
+    const ref = Number(data[param] ?? param);
+    return Number(value) <= ref ? null : `:attr must be less than or equal to ${param}.`;
+  },
+  alpha(value) {
+    return /^[a-zA-Z]+$/.test(String(value)) ? null : ":attr must only contain letters.";
+  },
+  alpha_num(value) {
+    return /^[a-zA-Z0-9]+$/.test(String(value))
+      ? null
+      : ":attr must only contain letters and numbers.";
+  },
+  alpha_dash(value) {
+    return /^[a-zA-Z0-9_-]+$/.test(String(value))
+      ? null
+      : ":attr must only contain letters, numbers, dashes, and underscores.";
+  },
+  starts_with(value, param) {
+    const vals = param.split(",");
+    return vals.some((v) => String(value).startsWith(v))
+      ? null
+      : `:attr must start with: ${vals.join(", ")}.`;
+  },
+  ends_with(value, param) {
+    const vals = param.split(",");
+    return vals.some((v) => String(value).endsWith(v))
+      ? null
+      : `:attr must end with: ${vals.join(", ")}.`;
+  },
+  regex(value, param) {
+    try {
+      const m = param.match(/^\/(.+)\/([gimsuy]*)$/);
+      const re = m ? new RegExp(m[1]!, m[2]) : new RegExp(param);
+      return re.test(String(value)) ? null : ":attr format is invalid.";
+    } catch {
+      return ":attr format is invalid.";
+    }
+  },
+  accepted(value) {
+    return (["yes", "on", "1", "true", 1, true] as unknown[]).includes(value)
+      ? null
+      : ":attr must be accepted.";
+  },
+  declined(value) {
+    return (["no", "off", "0", "false", 0, false] as unknown[]).includes(value)
+      ? null
+      : ":attr must be declined.";
+  },
+  digits(value, param) {
+    const s = String(value);
+    return /^\d+$/.test(s) && s.length === Number(param) ? null : `:attr must be ${param} digits.`;
+  },
+  digits_between(value, param) {
+    const [lo, hi] = param.split(",").map(Number) as [number, number];
+    const s = String(value);
+    return /^\d+$/.test(s) && s.length >= lo && s.length <= hi
+      ? null
+      : `:attr must be between ${lo} and ${hi} digits.`;
+  },
+  ip(value) {
+    const s = String(value);
+    const ipv4 = /^(\d{1,3}\.){3}\d{1,3}$/;
+    const ipv6 = /^([0-9a-fA-F]{0,4}:){2,7}[0-9a-fA-F]{0,4}$/;
+    return ipv4.test(s) || ipv6.test(s) ? null : ":attr must be a valid IP address.";
+  },
+  password_mixed_case(value) {
+    const s = String(value);
+    return /[a-z]/.test(s) && /[A-Z]/.test(s)
+      ? null
+      : ":attr must contain at least one uppercase and one lowercase letter.";
+  },
+  password_numbers(value) {
+    return /\d/.test(String(value)) ? null : ":attr must contain at least one number.";
+  },
+  password_symbols(value) {
+    return /[^a-zA-Z0-9]/.test(String(value)) ? null : ":attr must contain at least one symbol.";
+  },
+  password_no_spaces(value) {
+    return /\s/.test(String(value)) ? ":attr must not contain spaces." : null;
+  },
+  date(value) {
+    const d = new Date(String(value));
+    return isNaN(d.getTime()) ? ":attr must be a valid date." : null;
+  },
+  json(value) {
+    try {
+      JSON.parse(String(value));
+      return null;
+    } catch {
+      return ":attr must be valid JSON.";
+    }
+  },
+};
+
+function _parseRules(raw: string | string[]): Array<{ name: string; param: string }> {
+  const list = typeof raw === "string" ? raw.split("|") : raw;
+  return list.map((r) => {
+    const i = r.indexOf(":");
+    return i === -1
+      ? { name: r.trim(), param: "" }
+      : { name: r.slice(0, i).trim(), param: r.slice(i + 1).trim() };
+  });
+}
+
+function _label(field: string): string {
+  return `The ${field.replace(/_/g, " ")} field`;
+}
+
+/**
+ * Validate `data` against pipe-delimited string `rules`. Returns a map of field → error messages
+ * for every field that failed (an empty object means everything passed).
+ */
+export function runStringRules(
+  data: Record<string, unknown>,
+  rules: StringRules,
+): Record<string, string[]> {
+  const errors: Record<string, string[]> = {};
+
+  for (const [field, rawRules] of Object.entries(rules)) {
+    const parsed = _parseRules(rawRules);
+    const value = data[field];
+
+    // `sometimes` — skip if field absent from data
+    if (parsed.some((r) => r.name === "sometimes") && !(field in data)) continue;
+
+    // `nullable` — skip remaining rules if value is empty
+    const isEmpty = value === null || value === undefined || value === "";
+    if (parsed.some((r) => r.name === "nullable") && isEmpty) continue;
+
+    const msgs: string[] = [];
+    for (const { name, param } of parsed) {
+      if (name === "sometimes" || name === "nullable") continue;
+
+      // `confirmed` — field must equal field_confirmation
+      if (name === "confirmed") {
+        if (value !== data[`${field}_confirmation`]) {
+          msgs.push(`${_label(field)} confirmation does not match.`);
+        }
+        continue;
+      }
+
+      const fn = RULES[name];
+      if (!fn) continue; // unknown string rule — skip gracefully (may be a decorator-only rule)
+
+      const msg = fn(value, param, data);
+      if (msg) msgs.push(msg.replace(":attr", _label(field)));
+    }
+
+    if (msgs.length > 0) errors[field] = msgs;
+  }
+
+  return errors;
+}
+
+/**
+ * Async variant of {@link runStringRules}. Currently wraps the synchronous engine; exists so
+ * callers (e.g. Flow's `await this.validate()`) have a stable async entry point as
+ * database-backed string rules (`unique`/`exists`) are layered in.
+ */
+export async function runStringRulesAsync(
+  data: Record<string, unknown>,
+  rules: StringRules,
+): Promise<Record<string, string[]>> {
+  return runStringRules(data, rules);
+}

package/src/types.ts

@@ -0,0 +1,77 @@
+export type CustomFn = (
+  value: unknown,
+  input: Record<string, unknown>,
+) => boolean | string | Promise<boolean | string>;
+
+export interface FieldRuleDefinition {
+  type: "string" | "number" | "boolean" | "array" | "object" | "date" | "file";
+  required: boolean;
+  /** Custom message for the basic "is required" failure (set via `.required(message)`). */
+  requiredMessage?: string;
+  nullable: boolean;
+  defaultVal: unknown;
+  /** Skip this field entirely when it is absent from input (no presence in output either). */
+  sometimes?: boolean;
+  /** Make this field required only when `field === value` in the current input. */
+  requiredIf?:
+    { field: string; value: unknown } | { fn: (input: Record<string, unknown>) => boolean };
+  /** Make this field required unless `field === value` in the current input. */
+  requiredUnless?:
+    { field: string; value: unknown } | { fn: (input: Record<string, unknown>) => boolean };
+  /** Required when ANY of the listed fields are present in input. */
+  requiredWith?: string[];
+  /** Required when ANY of the listed fields are absent from input. */
+  requiredWithout?: string[];
+  /** Required when ALL of the listed fields are present. */
+  requiredWithAll?: string[];
+  /** Required when ALL of the listed fields are absent. */
+  requiredWithoutAll?: string[];
+  /** Field must be absent when `field === value`. */
+  prohibitedIf?: { field: string; value: unknown };
+  /** Field must be absent unless `field === value`. */
+  prohibitedUnless?: { field: string; value: unknown };
+  /** Stop validation on the first failing rule for this field. */
+  bail?: boolean;
+  rules: Array<{ name: string; args: unknown[]; message?: string; fn?: CustomFn }>;
+  children?: FieldRuleDefinition;
+  shape?: Record<string, FieldRuleDefinition>;
+}
+
+export type Schema = Record<string, FieldRuleDefinition>;
+
+export type InferFieldType<F extends FieldRuleDefinition> = F["type"] extends "string"
+  ? string
+  : F["type"] extends "number"
+    ? number
+    : F["type"] extends "boolean"
+      ? boolean
+      : F["type"] extends "date"
+        ? Date
+        : unknown;
+
+/**
+ * Infer the validated TypeScript type from a Schema.
+ * All fields are treated as required at the type level — the required/optional
+ * distinction is enforced at runtime only. Trade-off acknowledged in the plan.
+ */
+export type Infer<S extends Schema> = {
+  [K in keyof S]: S[K]["nullable"] extends true
+    ? InferFieldType<S[K]> | null
+    : InferFieldType<S[K]>;
+};
+
+export type ValidationErrors = Record<string, string>;
+
+export interface ValidationResult<T> {
+  success: true;
+  data: T;
+  errors: undefined;
+}
+
+export interface ValidationFailure {
+  success: false;
+  data: undefined;
+  errors: ValidationErrors;
+}
+
+export type ValidationOutcome<T> = ValidationResult<T> | ValidationFailure;

package/src/validate.ts

@@ -0,0 +1,95 @@
+import type { HttpContext } from "@zerotal/core";
+import { safeRedirectPath } from "@zerotal/core";
+import type { Schema, Infer, FieldRuleDefinition } from "./types.ts";
+import type { FieldRule } from "./FieldRule.ts";
+import { RuleBuilder } from "./RuleBuilder.ts";
+import { runValidationAsync } from "./Validator.ts";
+import { ValidationRedirectError, ValidationJsonError } from "./ValidationError.ts";
+
+type SessionLike = {
+  set(key: string, value: unknown): void;
+  forget(key: string): void;
+};
+
+// Maps a factory-schema (Record<string, FieldRule>) to raw FieldRuleDefinitions.
+// Used to drive Infer<> type inference from the narrow _def types on each rule class.
+type ExtractDefs<S extends Record<string, FieldRule>> = {
+  [K in keyof S]: S[K]["_def"];
+};
+
+/**
+ * Validate the HTTP request body against the given schema.
+ *
+ * On success: returns the validated, typed data object (only schema fields).
+ * On failure (Inertia or web form): stores errors in session + throws
+ *   ValidationRedirectError → global handler converts to 303 redirect.
+ * On failure (JSON API): throws ValidationJsonError → global handler → 422.
+ */
+export async function validate<S extends Record<string, FieldRule>>(
+  ctx: HttpContext,
+  factory: (rules: RuleBuilder) => S,
+): Promise<Infer<ExtractDefs<S>>> {
+  const builder = new RuleBuilder();
+  const factoryResult = factory(builder);
+
+  // Convert FieldRule objects → raw FieldRuleDefinitions for runValidation
+  const schema: Record<string, FieldRuleDefinition> = {};
+  for (const [key, rule] of Object.entries(factoryResult)) {
+    schema[key] = rule._def;
+  }
+
+  let body: Record<string, unknown> = {};
+  try {
+    const contentType = ctx.request.headers.get("Content-Type") ?? "";
+    if (contentType.includes("application/json")) {
+      body = (await ctx.request.json()) as Record<string, unknown>;
+    } else if (
+      contentType.includes("application/x-www-form-urlencoded") ||
+      contentType.includes("multipart/form-data")
+    ) {
+      const formData = await ctx.request.formData();
+      formData.forEach((val, key) => {
+        body[key] = val;
+      });
+    }
+  } catch {
+    body = {};
+  }
+
+  if (ctx.request.method === "GET") {
+    ctx.url.searchParams.forEach((val, key) => {
+      body[key] ??= val;
+    });
+  }
+
+  const result = await runValidationAsync(schema as Schema, body);
+
+  if (!result.success) {
+    const errors = result.errors;
+    const session = (ctx as unknown as { session?: SessionLike }).session;
+
+    session?.set("errors", errors);
+    session?.set("old", body);
+
+    const isInertia = ctx.request.headers.get("X-Inertia") === "true";
+    const accept = ctx.request.headers.get("Accept") ?? "";
+    const isJson = accept.includes("application/json") && !isInertia;
+
+    if (isJson) {
+      throw new ValidationJsonError(errors);
+    } else {
+      // Referer is attacker-controllable and this is a redirect target, so it must go
+      // through the same origin check every other redirect in the framework uses. Without it,
+      // a plain <a href="https://app.com/search"> on an attacker's page bounced the victim
+      // straight back off-site under the app's own domain — no CSRF token involved.
+      const back = safeRedirectPath(ctx.request.headers.get("Referer"), ctx.url.origin) ?? "/";
+      throw new ValidationRedirectError(back, errors);
+    }
+  }
+
+  const session = (ctx as unknown as { session?: { forget(key: string): void } }).session;
+  session?.forget("errors");
+  session?.forget("old");
+
+  return result.data as Infer<ExtractDefs<S>>;
+}