feat: add FormData parsing helpers

A.P.A. Slaa · A.P.A. Slaa · commit a2088d7ce61d · 2026-03-28T20:06:15.000+01:00
diff --git a/README.md b/README.md
@@ -86,6 +86,25 @@ try {
 }
 ```
 
+Use `safeParseFormData()` or `parseFormData()` when the payload starts as `FormData`:
+
+```ts
+const formData = new FormData();
+formData.set("name", " Ada ");
+formData.append("roles", "admin");
+formData.append("roles", "user");
+
+const result = Validator.safeParseFormData(
+  Validator.object({
+    name: Validator.string({ trim: true, non_empty: true }),
+    roles: Validator.array(Validator.enum(["admin", "user"] as const), { min: 1 }),
+  }),
+  formData
+);
+```
+
+Repeated `FormData` keys are exposed to validators as arrays in insertion order. Single entries remain single values.
+
 ## Core Validators
 
 ### Strings
@@ -219,7 +238,9 @@ Paths are rooted at `$` and include object keys and array indexes.
 | `Validator.transform(base, mapper, message?, code?)` | Map validated input into a new output type. |
 | `Validator.refine(base, predicate, message, code?)` | Add a custom predicate to an existing validator. |
 | `Validator.safeParse(validator, value)` | Return `{ success, data | errors }`. |
+| `Validator.safeParseFormData(validator, value)` | Convert `FormData` to an object and return `{ success, data | errors }`. |
 | `Validator.parse(validator, value)` | Return parsed data or throw `SchemaValidationError`. |
+| `Validator.parseFormData(validator, value)` | Convert `FormData` to an object and return parsed data or throw. |
 | `ok(data)` | Build a success result manually. |
 | `fail(message, path, code?)` | Build a failure result manually. |
 | `runValidation(validator, value, path?)` | Execute a validator directly. |
diff --git a/src/index.ts b/src/index.ts
@@ -32,6 +32,7 @@ export type ValidationResult<T> = ValidationSuccess<T> | ValidationFailure;
  * Internal path representation used while walking nested values.
  */
 export type ValidationPath = Array<string | number>;
+type FormDataValue = string | Blob;
 
 /**
  * Runtime validator function.
@@ -145,6 +146,21 @@ const testPattern = (pattern: RegExp, value: string) => {
     return new RegExp(pattern.source, flags).test(value);
 };
 
+const formDataToObject = (value: FormData) => {
+    const output: Record<string, FormDataValue | FormDataValue[]> = {};
+
+    for (const [key, entry] of value.entries()) {
+        const current = output[key];
+        if (current === undefined) {
+            output[key] = entry;
+            continue;
+        }
+        output[key] = Array.isArray(current) ? [...current, entry] : [current, entry];
+    }
+
+    return output;
+};
+
 /**
  * Runs a validator against a value.
  */
@@ -456,6 +472,13 @@ export const Validator = {
     safeParse: <T>(validator: Validator<T>, value: unknown): ValidationResult<T> =>
         runValidation(validator, value, []),
 
+    /**
+     * Runs a validator against a `FormData` payload and returns a result object.
+     * Repeated keys are exposed as arrays in insertion order.
+     */
+    safeParseFormData: <T>(validator: Validator<T>, value: FormData): ValidationResult<T> =>
+        runValidation(validator, formDataToObject(value), []),
+
     /**
      * Runs a validator and throws `SchemaValidationError` on failure.
      */
@@ -465,5 +488,17 @@ export const Validator = {
             throw new SchemaValidationError(result.errors);
         }
         return result.data;
+    },
+
+    /**
+     * Runs a validator against a `FormData` payload and throws on failure.
+     * Repeated keys are exposed as arrays in insertion order.
+     */
+    parseFormData: <T>(validator: Validator<T>, value: FormData): T => {
+        const result = runValidation(validator, formDataToObject(value), []);
+        if (isFailure(result)) {
+            throw new SchemaValidationError(result.errors);
+        }
+        return result.data;
     }
 };
diff --git a/tests/validator.test.ts b/tests/validator.test.ts
@@ -353,6 +353,58 @@ describe("validator", () => {
         }
     });
 
+    it("parses FormData payloads through object validators", () => {
+        const formData = new FormData();
+        formData.set("name", " Ada ");
+        formData.append("roles", "admin");
+        formData.append("roles", "user");
+
+        const validator = Validator.object({
+            name: Validator.string({trim: true, non_empty: true}),
+            roles: Validator.array(Validator.enum(["admin", "user"] as const), {min: 1}),
+        });
+
+        expect(Validator.safeParseFormData(validator, formData)).toEqual({
+            success: true,
+            data: {
+                name: "Ada",
+                roles: ["admin", "user"],
+            },
+        });
+        expect(Validator.parseFormData(validator, formData)).toEqual({
+            name: "Ada",
+            roles: ["admin", "user"],
+        });
+    });
+
+    it("preserves single FormData entries and files while reporting validation failures", () => {
+        const avatar = new File(["avatar"], "avatar.txt", {type: "text/plain"});
+        const formData = new FormData();
+        formData.set("name", "Ada");
+        formData.set("avatar", avatar);
+        formData.append("roles", "admin");
+        formData.append("roles", "guest");
+
+        const validator = Validator.object({
+            name: Validator.string(),
+            roles: Validator.array(Validator.enum(["admin", "user"] as const), {min: 1}),
+        }, {unknownKeys: "allow"});
+
+        expect(Validator.safeParseFormData(validator, formData)).toEqual(expect.objectContaining({
+            success: false,
+            errors: [expect.objectContaining({path: "$.roles[1]", code: "invalid_enum"})],
+        }));
+
+        expect(Validator.parseFormData(
+            Validator.object({name: Validator.string()}, {unknownKeys: "allow"}),
+            formData
+        )).toEqual({
+            name: "Ada",
+            avatar,
+            roles: ["admin", "guest"],
+        });
+    });
+
     it("exposes stable TypeScript inference for core validators", () => {
         const objectValidator = Validator.object({
             id: Validator.number({integer: true}),
