Merge pull request #198 from RtlZeroMemory/guardrails/form-validation

fix(core): stop swallowing async form validation errors

Author: RtlZeroMemory

packages/core/src/forms/__tests__/form.async-validation.test.ts

@@ -110,11 +110,17 @@ describe("form.async-validation - utility behavior", () => {
     assert.deepEqual(result, { username: "Taken" });
   });
 
-  test("runAsyncValidation swallows validator rejection", async () => {
-    const result = await runAsyncValidation({ username: "x" }, async () =>
-      Promise.reject(new Error("network")),
+  test("runAsyncValidation wraps validator rejection", async () => {
+    await assert.rejects(
+      runAsyncValidation({ username: "x" }, async () => Promise.reject(new Error("network"))),
+      (error: unknown) => {
+        assert.ok(error instanceof Error);
+        assert.equal(error.message, "async form validation failed: network");
+        assert.ok((error as { cause?: unknown }).cause instanceof Error);
+        assert.equal(((error as { cause?: unknown }).cause as Error).message, "network");
+        return true;
+      },
     );
-    assert.deepEqual(result, {});
   });
 
   test("createDebouncedAsyncValidator executes only after debounce window", async () => {
@@ -259,6 +265,36 @@ describe("form.async-validation - utility behavior", () => {
       timers.restore();
     }
   });
+
+  test("createDebouncedAsyncValidator ignores rejected in-flight results after cancel", async () => {
+    const timers = useFakeTimers();
+    try {
+      const deferred = createDeferred<ValidationResult<Values>>();
+      const results: ValidationResult<Values>[] = [];
+      const errors: unknown[] = [];
+      const validator = createDebouncedAsyncValidator<Values>(
+        async () => deferred.promise,
+        0,
+        (value) => {
+          results.push(value);
+        },
+        (error) => {
+          errors.push(error);
+        },
+      );
+
+      validator.run({ username: "late", email: "" });
+      timers.tick(0);
+      validator.cancel();
+      deferred.reject(new Error("late failure"));
+      await flushMicrotasks();
+
+      assert.equal(results.length, 0);
+      assert.equal(errors.length, 0);
+    } finally {
+      timers.restore();
+    }
+  });
 });
 
 describe("form.async-validation - useForm behavior", () => {
@@ -422,7 +458,7 @@ describe("form.async-validation - useForm behavior", () => {
     assert.equal(form.errors.email, "taken");
   });
 
-  test("handleSubmit continues when async validation throws network error", async () => {
+  test("handleSubmit aborts submit when async validation throws network error", async () => {
     const h = createFormHarness();
     let submitCalls = 0;
     const opts = options({
@@ -434,11 +470,13 @@ describe("form.async-validation - useForm behavior", () => {
       },
     });
 
-    const form = h.render(opts);
+    let form = h.render(opts);
     form.handleSubmit();
     await flushMicrotasks(4);
+    form = h.render(opts);
 
-    assert.equal(submitCalls, 1);
+    assert.equal(submitCalls, 0);
+    assert.equal(form.isSubmitting, false);
   });
 
   test("handleSubmit rejects concurrent submits while pending", async () => {

packages/core/src/forms/useForm.ts

@@ -35,6 +35,17 @@ import {
   runSyncValidation,
 } from "./validation.js";
 
+const NODE_ENV =
+  (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env?.NODE_ENV ??
+  "development";
+const DEV_MODE = NODE_ENV !== "production";
+
+function warnDev(message: string): void {
+  if (!DEV_MODE) return;
+  const c = (globalThis as { console?: { warn?: (msg: string) => void } }).console;
+  c?.warn?.(message);
+}
+
 type FieldOverrides<T extends Record<string, unknown>> = Partial<Record<keyof T, boolean>>;
 
 function cloneInitialValues<T extends Record<string, unknown>>(values: T): T {
@@ -66,6 +77,24 @@ function createInitialState<T extends Record<string, unknown>>(
   const stepCount = options.wizard?.steps.length ?? 0;
   const initialStep = clampStepIndex(options.wizard?.initialStep ?? 0, stepCount);
 
+  if (DEV_MODE) {
+    const valueKeys = new Set(Object.keys(options.initialValues));
+    if (options.fieldDisabled) {
+      for (const key of Object.keys(options.fieldDisabled)) {
+        if (!valueKeys.has(key)) {
+          warnDev(`[rezi] useForm: fieldDisabled key "${key}" does not exist in initialValues`);
+        }
+      }
+    }
+    if (options.fieldReadOnly) {
+      for (const key of Object.keys(options.fieldReadOnly)) {
+        if (!valueKeys.has(key)) {
+          warnDev(`[rezi] useForm: fieldReadOnly key "${key}" does not exist in initialValues`);
+        }
+      }
+    }
+  }
+
   return {
     values: cloneInitialValues(options.initialValues),
     errors: {},

packages/core/src/forms/validation.ts

@@ -100,12 +100,14 @@ export function isValidationClean<T extends Record<string, unknown>>(
  * @param validateAsync - Async validation function
  * @param debounceMs - Debounce delay in milliseconds
  * @param onResult - Callback when validation completes
+ * @param onError - Optional callback when async validation throws; if omitted the error is swallowed and onResult receives an empty result
  * @returns Object with run and cancel methods
  */
 export function createDebouncedAsyncValidator<T extends Record<string, unknown>>(
   validateAsync: (values: T) => Promise<ValidationResult<T>>,
   debounceMs: number,
   onResult: (errors: ValidationResult<T>) => void,
+  onError?: (error: unknown) => void,
 ): Readonly<{
   run: (values: T) => void;
   cancel: () => void;
@@ -134,9 +136,11 @@ export function createDebouncedAsyncValidator<T extends Record<string, unknown>>
               onResult(errors);
             }
           })
-          .catch(() => {
-            // Swallow async validation errors - form remains valid
-            if (!cancelled && myToken === token) {
+          .catch((e) => {
+            if (cancelled || myToken !== token) return;
+            if (onError) {
+              onError(e);
+            } else {
               onResult({});
             }
           });
@@ -172,8 +176,10 @@ export async function runAsyncValidation<T extends Record<string, unknown>>(
 
   try {
     return await validateAsync(values);
-  } catch {
-    // Async validation errors are swallowed - form remains valid
-    return {};
+  } catch (e) {
+    const detail = e instanceof Error ? e.message : String(e);
+    const wrapped = new Error(`async form validation failed: ${detail}`);
+    (wrapped as { cause?: unknown }).cause = e;
+    throw wrapped;
   }
 }