@zerotal/validator 1.6.3 → 1.7.2

package/api-surface.md

@@ -0,0 +1,369 @@
+# @zerotal/validator — public API surface
+
+<!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
+     Run `bun run api:surface` to regenerate after an intentional API change. -->
+
+## .  `(./src/index.ts)`
+
+class ArrayRule = {
+  new <T extends FieldRule>(item: T): ArrayRule<T>
+  accepted: (message?: string) => ArrayRule<T>
+  bail: () => ArrayRule<T>
+  custom: (fn: CustomFn, message?: string) => ArrayRule<T>
+  declined: (message?: string) => ArrayRule<T>
+  default: (value: unknown) => ArrayRule<T>
+  max: (length: number, message?: string) => ArrayRule<T>
+  min: (length: number, message?: string) => ArrayRule<T>
+  nullable: () => ArrayRule<T>
+  optional: () => ArrayRule<T>
+  prohibitedIf: (field: string, value: unknown) => ArrayRule<T>
+  prohibitedUnless: (field: string, value: unknown) => ArrayRule<T>
+  readonly _def: ArrayDef<T['_def']>
+  required: (message?: string) => ArrayRule<T>
+  requiredIf: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => ArrayRule<T>
+  requiredUnless: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => ArrayRule<T>
+  requiredWith: (fields: string[]) => ArrayRule<T>
+  requiredWithAll: (fields: string[]) => ArrayRule<T>
+  requiredWithout: (fields: string[]) => ArrayRule<T>
+  requiredWithoutAll: (fields: string[]) => ArrayRule<T>
+  size: (n: number, message?: string) => ArrayRule<T>
+  sometimes: () => ArrayRule<T>
+}
+
+class BooleanRule = {
+  new (): BooleanRule
+  accepted: (message?: string) => BooleanRule
+  bail: () => BooleanRule
+  custom: (fn: CustomFn, message?: string) => BooleanRule
+  declined: (message?: string) => BooleanRule
+  default: (value: unknown) => BooleanRule
+  nullable: () => BooleanRule
+  optional: () => BooleanRule
+  prohibitedIf: (field: string, value: unknown) => BooleanRule
+  prohibitedUnless: (field: string, value: unknown) => BooleanRule
+  readonly _def: BooleanDef
+  required: (message?: string) => BooleanRule
+  requiredIf: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => BooleanRule
+  requiredUnless: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => BooleanRule
+  requiredWith: (fields: string[]) => BooleanRule
+  requiredWithAll: (fields: string[]) => BooleanRule
+  requiredWithout: (fields: string[]) => BooleanRule
+  requiredWithoutAll: (fields: string[]) => BooleanRule
+  sometimes: () => BooleanRule
+}
+
+class DateRule = {
+  new (): DateRule
+  accepted: (message?: string) => DateRule
+  after: (date: Date | string, message?: string) => DateRule
+  afterOrEqual: (date: Date | string, message?: string) => DateRule
+  bail: () => DateRule
+  before: (date: Date | string, message?: string) => DateRule
+  beforeOrEqual: (date: Date | string, message?: string) => DateRule
+  custom: (fn: CustomFn, message?: string) => DateRule
+  declined: (message?: string) => DateRule
+  default: (value: unknown) => DateRule
+  nullable: () => DateRule
+  optional: () => DateRule
+  prohibitedIf: (field: string, value: unknown) => DateRule
+  prohibitedUnless: (field: string, value: unknown) => DateRule
+  readonly _def: DateDef
+  required: (message?: string) => DateRule
+  requiredIf: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => DateRule
+  requiredUnless: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => DateRule
+  requiredWith: (fields: string[]) => DateRule
+  requiredWithAll: (fields: string[]) => DateRule
+  requiredWithout: (fields: string[]) => DateRule
+  requiredWithoutAll: (fields: string[]) => DateRule
+  sometimes: () => DateRule
+}
+
+class FieldRule = {
+  new (): FieldRule
+  accepted: (message?: string) => FieldRule
+  bail: () => FieldRule
+  custom: (fn: CustomFn, message?: string) => FieldRule
+  declined: (message?: string) => FieldRule
+  default: (value: unknown) => FieldRule
+  nullable: () => FieldRule
+  optional: () => FieldRule
+  prohibitedIf: (field: string, value: unknown) => FieldRule
+  prohibitedUnless: (field: string, value: unknown) => FieldRule
+  readonly _def: FieldRuleDefinition
+  required: (message?: string) => FieldRule
+  requiredIf: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => FieldRule
+  requiredUnless: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => FieldRule
+  requiredWith: (fields: string[]) => FieldRule
+  requiredWithAll: (fields: string[]) => FieldRule
+  requiredWithout: (fields: string[]) => FieldRule
+  requiredWithoutAll: (fields: string[]) => FieldRule
+  sometimes: () => FieldRule
+}
+
+class FileRule = {
+  new (): FileRule
+  accepted: (message?: string) => FileRule
+  bail: () => FileRule
+  custom: (fn: CustomFn, message?: string) => FileRule
+  declined: (message?: string) => FileRule
+  default: (value: unknown) => FileRule
+  max: (kb: number, message?: string) => FileRule
+  mimes: (extensions: string[], message?: string) => FileRule
+  min: (kb: number, message?: string) => FileRule
+  nullable: () => FileRule
+  optional: () => FileRule
+  prohibitedIf: (field: string, value: unknown) => FileRule
+  prohibitedUnless: (field: string, value: unknown) => FileRule
+  readonly _def: FileDef
+  required: (message?: string) => FileRule
+  requiredIf: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => FileRule
+  requiredUnless: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => FileRule
+  requiredWith: (fields: string[]) => FileRule
+  requiredWithAll: (fields: string[]) => FileRule
+  requiredWithout: (fields: string[]) => FileRule
+  requiredWithoutAll: (fields: string[]) => FileRule
+  sometimes: () => FileRule
+}
+
+class FormRequest = {
+  new (): FormRequest
+  static macro: (name: string, fn: (this: FormRequest, ...args: unknown[]) => unknown) => void
+  static validate: <T extends FormRequest>(this: new () => T) => Promise<Infer<ExtractDefs<ReturnType<T['rules']>>>>
+  authorize: () => boolean | Promise<boolean>
+  rules: (_r: RuleBuilder) => Record<string, FieldRule>
+}
+
+class NumberRule = {
+  new (): NumberRule
+  accepted: (message?: string) => NumberRule
+  bail: () => NumberRule
+  between: (min: number, max: number, message?: string) => NumberRule
+  custom: (fn: CustomFn, message?: string) => NumberRule
+  declined: (message?: string) => NumberRule
+  default: (value: unknown) => NumberRule
+  exists: (table: string, column: string, message?: string) => NumberRule
+  integer: (message?: string) => NumberRule
+  max: (value: number, message?: string) => NumberRule
+  min: (value: number, message?: string) => NumberRule
+  notIn: (values: number[], message?: string) => NumberRule
+  nullable: () => NumberRule
+  optional: () => NumberRule
+  positive: (message?: string) => NumberRule
+  prohibitedIf: (field: string, value: unknown) => NumberRule
+  prohibitedUnless: (field: string, value: unknown) => NumberRule
+  readonly _def: NumberDef
+  required: (message?: string) => NumberRule
+  requiredIf: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => NumberRule
+  requiredUnless: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => NumberRule
+  requiredWith: (fields: string[]) => NumberRule
+  requiredWithAll: (fields: string[]) => NumberRule
+  requiredWithout: (fields: string[]) => NumberRule
+  requiredWithoutAll: (fields: string[]) => NumberRule
+  sometimes: () => NumberRule
+}
+
+class ObjectRule = {
+  new <S extends Record<string, FieldRule>>(shape: S): ObjectRule<S>
+  accepted: (message?: string) => ObjectRule<S>
+  bail: () => ObjectRule<S>
+  custom: (fn: CustomFn, message?: string) => ObjectRule<S>
+  declined: (message?: string) => ObjectRule<S>
+  default: (value: unknown) => ObjectRule<S>
+  nullable: () => ObjectRule<S>
+  optional: () => ObjectRule<S>
+  prohibitedIf: (field: string, value: unknown) => ObjectRule<S>
+  prohibitedUnless: (field: string, value: unknown) => ObjectRule<S>
+  readonly _def: ObjectDef<{ [K in keyof S]: S[K]['_def']; }>
+  required: (message?: string) => ObjectRule<S>
+  requiredIf: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => ObjectRule<S>
+  requiredUnless: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => ObjectRule<S>
+  requiredWith: (fields: string[]) => ObjectRule<S>
+  requiredWithAll: (fields: string[]) => ObjectRule<S>
+  requiredWithout: (fields: string[]) => ObjectRule<S>
+  requiredWithoutAll: (fields: string[]) => ObjectRule<S>
+  sometimes: () => ObjectRule<S>
+}
+
+class PasswordRule = {
+  new (): PasswordRule
+  accepted: (message?: string) => PasswordRule
+  bail: () => PasswordRule
+  confirmed: (message?: string) => PasswordRule
+  custom: (fn: CustomFn, message?: string) => PasswordRule
+  declined: (message?: string) => PasswordRule
+  default: (value: unknown) => PasswordRule
+  min: (length: number, message?: string) => PasswordRule
+  mixedCase: (message?: string) => PasswordRule
+  nullable: () => PasswordRule
+  numbers: (message?: string) => PasswordRule
+  optional: () => PasswordRule
+  prohibitedIf: (field: string, value: unknown) => PasswordRule
+  prohibitedUnless: (field: string, value: unknown) => PasswordRule
+  readonly _def: FieldRuleDefinition & {    type: 'string';}
+  required: (message?: string) => PasswordRule
+  requiredIf: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => PasswordRule
+  requiredUnless: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => PasswordRule
+  requiredWith: (fields: string[]) => PasswordRule
+  requiredWithAll: (fields: string[]) => PasswordRule
+  requiredWithout: (fields: string[]) => PasswordRule
+  requiredWithoutAll: (fields: string[]) => PasswordRule
+  sometimes: () => PasswordRule
+  symbols: (message?: string) => PasswordRule
+  uncompromised: (message?: string) => PasswordRule
+}
+
+class PrecognitionResponseError = {
+  new (precognitionStatus: 204 | 422, errors?: ValidationErrors): PrecognitionResponseError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly errors: ValidationErrors
+  readonly name: 'PrecognitionResponse'
+  readonly precognitionStatus: 204 | 422
+  readonly status: number
+  toResponse: () => Response
+}
+
+class RuleBuilder = {
+  new (): RuleBuilder
+  array: <T extends FieldRule>(item: T) => ArrayRule<T>
+  boolean: () => BooleanRule
+  date: () => DateRule
+  email: (message?: string) => StringRule
+  file: () => FileRule
+  number: () => NumberRule
+  object: <S extends Record<string, FieldRule>>(shape: S) => ObjectRule<S>
+  password: () => PasswordRule
+  required: (message?: string) => StringRule
+  string: () => StringRule
+  url: (message?: string) => StringRule
+  uuid: (message?: string) => StringRule
+}
+
+class StringRule = {
+  new (): StringRule
+  accepted: (message?: string) => StringRule
+  alpha: (message?: string) => StringRule
+  alphaDash: (message?: string) => StringRule
+  alphaNum: (message?: string) => StringRule
+  bail: () => StringRule
+  confirmed: (message?: string) => StringRule
+  custom: (fn: CustomFn, message?: string) => StringRule
+  declined: (message?: string) => StringRule
+  default: (value: unknown) => StringRule
+  digits: (n: number, message?: string) => StringRule
+  digitsBetween: (min: number, max: number, message?: string) => StringRule
+  email: (message?: string) => StringRule
+  endsWith: (suffix: string, message?: string) => StringRule
+  exists: (table: string, column: string, message?: string) => StringRule
+  in: (values: string[], message?: string) => StringRule
+  ip: (message?: string) => StringRule
+  json: (message?: string) => StringRule
+  lowercase: () => StringRule
+  matches: (pattern: RegExp, message?: string) => StringRule
+  max: (length: number, message?: string) => StringRule
+  min: (length: number, message?: string) => StringRule
+  notIn: (values: string[], message?: string) => StringRule
+  nullable: () => StringRule
+  numeric: (message?: string) => StringRule
+  optional: () => StringRule
+  password: () => StringRule
+  present: (message?: string) => StringRule
+  prohibited: (message?: string) => StringRule
+  prohibitedIf: (field: string, value: unknown) => StringRule
+  prohibitedUnless: (field: string, value: unknown) => StringRule
+  readonly _def: StringDef
+  regex: (pattern: RegExp, message?: string) => StringRule
+  required: (message?: string) => StringRule
+  requiredIf: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => StringRule
+  requiredUnless: (fieldOrFn: string | ((input: Record<string, unknown>) => boolean), value?: unknown) => StringRule
+  requiredWith: (fields: string[]) => StringRule
+  requiredWithAll: (fields: string[]) => StringRule
+  requiredWithout: (fields: string[]) => StringRule
+  requiredWithoutAll: (fields: string[]) => StringRule
+  sameAs: (field: string, message?: string) => StringRule
+  size: (n: number, message?: string) => StringRule
+  sometimes: () => StringRule
+  startsWith: (prefix: string, message?: string) => StringRule
+  trim: () => StringRule
+  unique: (table: string, column: string, ignoreOrOpts?: string | number | UniqueOptions, message?: string) => StringRule
+  uppercase: () => StringRule
+  url: (message?: string) => StringRule
+  uuid: (message?: string) => StringRule
+}
+
+class ValidationJsonError = {
+  new (errors: ValidationErrors): ValidationJsonError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly errors: ValidationErrors
+  readonly name: 'ValidationJsonError'
+  readonly status: number
+}
+
+class ValidationRedirectError = {
+  new (redirectTo: string, errors: ValidationErrors): ValidationRedirectError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly errors: ValidationErrors
+  readonly name: 'ValidationRedirectError'
+  readonly redirectTo: string
+  readonly status: number
+}
+
+const Validator = {    check<S extends Record<string, FieldRule>>(data: Record<string, unknown>, factory: (rules: RuleBuilder) => S): ValidationOutcome<Infer<ExtractDefs<S>>>;}
+
+function registerDbRuleRunner = (runner: DbRuleRunner) => void
+
+function runStringRules = (data: Record<string, unknown>, rules: StringRules) => Record<string, string[]>
+
+function runStringRulesAsync = (data: Record<string, unknown>, rules: StringRules) => Promise<Record<string, string[]>>
+
+function runValidation = <S extends Schema>(schema: S, input: Record<string, unknown>) => ValidationOutcome<unknown>
+
+function runValidationAsync = <S extends Schema>(schema: S, input: Record<string, unknown>) => Promise<ValidationOutcome<unknown>>
+
+function validate = <S extends Record<string, FieldRule>>(ctx: HttpContext, factory: (rules: RuleBuilder) => S) => Promise<Infer<ExtractDefs<S>>>
+
+function ValidatorConfig = (options?: Partial<ValidatorConfigShape>) => ValidatorConfigShape
+
+interface FieldRuleDefinition = {
+  bail?: boolean
+  children?: FieldRuleDefinition
+  defaultVal: unknown
+  nullable: boolean
+  prohibitedIf?: {    field: string;    value: unknown;}
+  prohibitedUnless?: {    field: string;    value: unknown;}
+  required: boolean
+  requiredIf?: {    field: string;    value: unknown;} | {    fn: (input: Record<string, unknown>) => boolean;}
+  requiredMessage?: string
+  requiredUnless?: {    field: string;    value: unknown;} | {    fn: (input: Record<string, unknown>) => boolean;}
+  requiredWith?: string[]
+  requiredWithAll?: string[]
+  requiredWithout?: string[]
+  requiredWithoutAll?: string[]
+  rules: {    name: string;    args: unknown[];    message?: string;    fn?: CustomFn;}[]
+  shape?: Record<string, FieldRuleDefinition>
+  sometimes?: boolean
+  type: 'string' | 'number' | 'boolean' | 'object' | 'date' | 'file' | 'array'
+}
+
+interface UniqueOptions = {
+  ignoreId?: string | number
+}
+
+interface ValidatorConfigShape = {
+  locale: string
+  stopOnFirstFailure: boolean
+}
+
+type Infer = { [K in keyof S]: InferField<S[K]>; }
+
+type InferFieldType = F['type'] extends 'string' ? string : F['type'] extends 'number' ? number : F['type'] extends 'boolean' ? boolean : F['type'] extends 'date' ? Date : F['type'] extends 'array' ? InferArrayType<F> : F['type'] extends 'object' ? InferObjectType<F> : unknown
+
+type Schema = {    [x: string]: FieldRuleDefinition;}
+
+type StringRules = {    [x: string]: string | string[];}
+
+type ValidationErrors = {    [x: string]: string;}
+
+type ValidationOutcome = ValidationResult<T> | ValidationFailure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/validator",
-  "version": "1.6.3",
+  "version": "1.7.2",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -12,6 +12,7 @@
   },
   "files": [
     "CHANGELOG.md",
+    "api-surface.md",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
@@ -29,7 +30,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.6.3"
+    "@zerotal/core": "1.7.2"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/FormRequest.ts

@@ -113,6 +113,30 @@ export abstract class FormRequest {
     throw new Error(`${this.constructor.name}.rules() is not implemented.`);
   }
 
+  /**
+   * Normalise the raw body before the rules see it. Default: unchanged.
+   *
+   * This is where the shape of the *transport* gets reconciled with the shape of
+   * the rules. An HTML form has no way to say `null`: an unselected `<select>`
+   * posts `""`, so a `r.number().nullable()` field fails on the one input the
+   * browser can actually produce for "nothing". A client-side form can patch
+   * that up before it posts; a plain `<form method="post">` cannot, and a rule
+   * only reachable from a build with JavaScript is not a shared rule.
+   *
+   * Runs after `authorize()` and after the body is parsed, so it sees exactly
+   * what arrived. Return the object to validate — mutating and returning the
+   * argument is fine.
+   *
+   * @example
+   * override prepareForValidation(body: Record<string, unknown>) {
+   *   if (body["assigneeId"] === "") body["assigneeId"] = null;
+   *   return body;
+   * }
+   */
+  prepareForValidation(body: Record<string, unknown>): Record<string, unknown> {
+    return body;
+  }
+
   /**
    * Attach a helper method to all FormRequest instances at runtime.
    * Designed for framework packages (e.g. @zerotal/auth) that expose
@@ -193,6 +217,10 @@ export abstract class FormRequest {
       schema[key] = rule._def;
     }
 
+    // The transport's shape reconciled with the rules' shape, before the rules
+    // run. See `prepareForValidation` for why an HTML form needs this at all.
+    body = instance.prepareForValidation(body);
+
     const result = await runValidationAsync(schema as Schema, body);
     const session = (ctx as unknown as { session?: SessionLike }).session;
 

package/src/Validator.ts

@@ -135,7 +135,17 @@ export function runValidation<S extends Schema>(
       continue;
     }
 
-    if (!isRequired && (value === undefined || value === null)) {
+    // Absent → skipped, which is what `optional()` means. An explicit `null` on
+    // a field that also declared `nullable()` is *not* absence: it is someone
+    // saying "clear this", and it falls through to the branch below so it
+    // reaches the output. Without this, `optional().nullable()` silently drops
+    // the null, `fill()` sees `undefined`, and "unassign" saves nothing while
+    // reporting success.
+    //
+    // `null` on a field that is optional but *not* nullable keeps the old
+    // behaviour — skipped rather than an error — so this widens what survives
+    // validation without newly rejecting anything.
+    if (!isRequired && (value === undefined || (value === null && !def.nullable))) {
       continue;
     }