@zerotal/validator 1.7.0 → 1.7.3

package/CHANGELOG.md

@@ -8,6 +8,22 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+### Fixed
+
+- **An optional `number` or `date` reads `""` as absence.** An HTML `<select>` has one way to
+  say "none" — `<option value="">` — and it sends the empty string. `r.number().optional()`
+  refused it, so a form with an optional assignee could not be submitted _without_ one: the
+  single case the field was optional for. The message named a field the reader never touched,
+  which is the part that made it expensive to find.
+
+  It is now read as no value. The field is skipped, or set to `null` when the rule is also
+  `nullable()` — because clearing is what that option means, and skipping would leave the
+  previous value in place while reporting success. This mirrors how an explicit `null` on a
+  `nullable()` field already behaves.
+
+  Narrow on purpose: `string` still keeps `""`, where it may be a value someone meant, and the
+  remaining types wait for a case that needs them. Nothing that validated before stops doing so.
+
 ## [1.5.0] — 2026-08-15
 
 ### Fixed

package/api-surface.md

@@ -130,6 +130,7 @@ class 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>
+  prepareForValidation: (body: Record<string, unknown>) => Record<string, unknown>
   rules: (_r: RuleBuilder) => Record<string, FieldRule>
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/validator",
-  "version": "1.7.0",
+  "version": "1.7.3",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -30,7 +30,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.7.0"
+    "@zerotal/core": "1.7.3"
   },
   "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

@@ -10,6 +10,12 @@ import type { UniqueOptions } from "./dbRules.ts";
 import { RULES } from "./stringRules.ts";
 
 /** Resolve whether a field is effectively required given its conditional modifiers. */
+/**
+ * Rule types for which the empty string cannot be a value, so an optional field
+ * handed `""` is a form saying "none" rather than data to check.
+ */
+const EMPTY_MEANS_ABSENT: ReadonlySet<FieldRuleDefinition["type"]> = new Set(["number", "date"]);
+
 function resolveRequired(def: FieldRuleDefinition, input: Record<string, unknown>): boolean {
   if (def.requiredIf !== undefined) {
     const cond = def.requiredIf;
@@ -124,18 +130,46 @@ export function runValidation<S extends Schema>(
       continue;
     }
 
+    const isRequired = resolveRequired(def, input);
+
+    // An HTML form has exactly one way to say "no value": the empty string. A
+    // `<select>`'s placeholder option sends it, and for a type that can never
+    // hold `""` — a number, a date — reading it as the literal text rather than
+    // as absence is what made an optional select unsubmittable in the one case
+    // it was optional for. The message named a field the reader never touched,
+    // which is the part that made it expensive to find.
+    //
+    // Narrow deliberately. `string` keeps `""`, where it may be a value someone
+    // meant; the remaining types wait for a case that needs them. Each is a
+    // widening when it comes — nothing that validated before stops doing so.
+    if (!isRequired && value === "" && EMPTY_MEANS_ABSENT.has(def.type)) {
+      // `nullable()` is the field saying it can be cleared, and clearing is what
+      // the placeholder option is for — so it reaches the output as null rather
+      // than being skipped, exactly as an explicit null does below. Skipping it
+      // would leave the previous value in place and report success.
+      value = def.nullable ? null : undefined;
+    }
+
     if ((value === undefined || value === null) && def.defaultVal !== undefined) {
       value = def.defaultVal;
     }
 
-    const isRequired = resolveRequired(def, input);
-
     if (isRequired && (value === undefined || value === null || value === "")) {
       errors[field] ??= def.requiredMessage ?? `The ${field} field is required.`;
       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;
     }