feat: FormData, File, and FileList body types

aklinker1 · aklinker1 · commit f3bdffa5ee01 · 2025-12-25T11:54:14.000-06:00
diff --git a/example.ts b/example.ts
@@ -8,6 +8,7 @@ import {
 import { version } from "./package.json" with { type: "json" };
 import { z } from "zod/v4";
 import { zodSchemaAdapter } from "./src/adapters/zod-schema-adapter";
+import { UploadFileBody, FormDataBody, UploadFilesBody } from "./src/schema";
 
 const EntryId = z.coerce.number().int().min(0).meta({ ref: "EntryId" });
 type EntryId = z.infer<typeof EntryId>;
@@ -148,6 +149,48 @@ const app = createApp({
       responses: z.string().meta({ contentType: "text/csv" }),
     },
     () => "test",
+  )
+  .post(
+    "/api/upload-form",
+    {
+      summary: "Upload Form",
+      tags: ["Uploads"],
+      body: FormDataBody,
+      responses: {
+        [HttpStatus.NoContent]: NoResponse,
+      },
+    },
+    ({ status, body }) => {
+      return status(HttpStatus.NoContent, undefined);
+    },
+  )
+  .post(
+    "/api/upload-file",
+    {
+      summary: "Upload File",
+      tags: ["Uploads"],
+      body: UploadFileBody,
+      responses: {
+        [HttpStatus.NoContent]: NoResponse,
+      },
+    },
+    ({ status, body }) => {
+      return status(HttpStatus.NoContent, undefined);
+    },
+  )
+  .post(
+    "/api/upload-files",
+    {
+      summary: "Upload Files",
+      tags: ["Uploads"],
+      body: UploadFilesBody,
+      responses: {
+        [HttpStatus.NoContent]: NoResponse,
+      },
+    },
+    ({ status, body }) => {
+      return status(HttpStatus.NoContent, undefined);
+    },
   );
 
 console.log(
diff --git a/jsr.json b/jsr.json
@@ -12,6 +12,7 @@
     "./types": "./src/types.ts",
     "./client": "./src/client.ts",
     "./testing": "./src/testing.ts",
+    "./schema": "./src/schema.ts",
     "./adapters/zod-schema-adapter": "./src/adapters/zod-schema-adapter.ts",
     "./transports/bun-transport": "./src/transports/bun-transport.ts",
     "./transports/deno-transport": "./src/transports/deno-transport.ts"
diff --git a/package.json b/package.json
@@ -12,6 +12,7 @@
     "./types": "./src/types.ts",
     "./client": "./src/client.ts",
     "./testing": "./src/testing.ts",
+    "./schema": "./src/schema.ts",
     "./adapters/zod-schema-adapter": "./src/adapters/zod-schema-adapter.ts",
     "./transports/bun-transport": "./src/transports/bun-transport.ts",
     "./transports/deno-transport": "./src/transports/deno-transport.ts"
diff --git a/src/__tests__/client.test.ts b/src/__tests__/client.test.ts
@@ -6,7 +6,7 @@ import type { GetClientRoutes } from "../client";
 import { expectTypeOf } from "expect-type";
 import { z } from "zod/v4";
 import { HttpStatus } from "../status";
-import { ErrorResponse, NoResponse } from "../custom-responses";
+import { ErrorResponse, NoResponse } from "../schema";
 
 // Silence console.error logs
 globalThis.console.error = mock();
diff --git a/src/__tests__/types.test.ts b/src/__tests__/types.test.ts
@@ -3,7 +3,7 @@ import { expectTypeOf } from "expect-type";
 import type * as t from "../types";
 import { z } from "zod/v4";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import { ErrorResponse } from "../custom-responses";
+import { ErrorResponse } from "../schema";
 import type { HttpStatus } from "../status";
 
 describe("Types", () => {
diff --git a/src/client.ts b/src/client.ts
@@ -8,7 +8,7 @@ import type {
   GetRequestParamsInput,
   GetResponseOutput,
 } from "./types";
-import type { ErrorResponse } from "./custom-responses";
+import type { ErrorResponse } from "./schema";
 import { smartDeserialize, smartSerialize } from "./internal/serialization";
 import type {
   GetAppRoutes,
diff --git a/src/index.ts b/src/index.ts
@@ -1,5 +1,5 @@
 export * from "./app";
 export type { App } from "./types";
-export { ErrorResponse, NoResponse, type ZetaSchema } from "./custom-responses";
+export { ErrorResponse, NoResponse, type ZetaSchema } from "./schema";
 export * from "./status";
 export * from "./errors";
diff --git a/src/internal/serialization.ts b/src/internal/serialization.ts
@@ -13,6 +13,26 @@ export function smartSerialize(value: unknown):
     };
   }
 
+  if (value instanceof File) {
+    const serialized = new FormData();
+    serialized.append("file", value);
+    return {
+      contentType: undefined,
+      serialized,
+    };
+  }
+
+  if (value instanceof FileList) {
+    const serialized = new FormData();
+    for (let i = 0; i < value.length; i++) {
+      serialized.append("files", value.item(i)!);
+    }
+    return {
+      contentType: undefined,
+      serialized,
+    };
+  }
+
   if (value instanceof Blob) {
     return {
       contentType: value.type,
diff --git a/src/internal/utils.ts b/src/internal/utils.ts
@@ -10,7 +10,7 @@ import type {
   Transport,
 } from "../types";
 import type { MatchedRoute } from "rou3";
-import type { ErrorResponse } from "../custom-responses";
+import type { ErrorResponse } from "../schema";
 import { createBunTransport } from "../transports/bun-transport";
 import { createDenoTransport } from "../transports/deno-transport";
 
diff --git a/src/meta.ts b/src/meta.ts
@@ -1,13 +1,13 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { SchemaAdapter } from "./types";
-import type { ZetaSchema } from "./custom-responses";
+import { isZetaSchema, type ZetaSchema } from "./schema";
 
 /** Get metadata for either a ZetaSchema or a StandardSchemaV1. */
 export function getMeta(
   adapter: SchemaAdapter | undefined,
   schema: StandardSchemaV1 | ZetaSchema,
 ): Record<string, any> {
-  if ("~zeta" in schema) return schema.meta;
+  if (isZetaSchema(schema)) return schema["~zeta"].meta;
 
   if (!adapter) return {};
   return adapter.getMeta(schema) ?? {};
diff --git a/src/open-api.ts b/src/open-api.ts
@@ -3,7 +3,11 @@ import type { App, BasePath, SchemaAdapter } from "./types";
 import type { CreateAppOptions } from "./app";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import { getHttpStatusName } from "./status";
-import { ErrorResponseJsonSchema, type ZetaSchema } from "./custom-responses";
+import {
+  ErrorResponseJsonSchema,
+  isZetaSchema,
+  type ZetaSchema,
+} from "./schema";
 import { getMeta } from "./meta";
 
 export function buildOpenApiDocs(
@@ -51,7 +55,9 @@ export function buildOpenApiDocs(
             ? {
                 content: {
                   [getMeta(adapter, body)?.contentType ?? "application/json"]: {
-                    schema: adapter.toJsonSchema(body),
+                    schema: isZetaSchema(body)
+                      ? body.toJsonSchema?.()
+                      : adapter.toJsonSchema(body),
                   },
                 },
               }
@@ -159,7 +165,7 @@ function buildResponse(
 ): NonNullable<OpenAPI.Operation["responses"]>[string] {
   const meta = getMeta(adapter, schema);
 
-  if ("~zeta" in schema) {
+  if (isZetaSchema(schema)) {
     const description =
       meta?.responseDescription ?? getHttpStatusName(status) ?? "";
 
diff --git a/src/schema.ts b/src/schema.ts
@@ -9,12 +9,14 @@ export type ZetaSchema<Input = unknown, Output = Input> = StandardSchemaV1<
     type: string;
     meta: Record<string, any>;
   };
+  toJsonSchema?(): any;
   meta(meta?: Record<string, any>): ZetaSchema<Input, Output>;
 };
 
 function createZetaSchema<Input = unknown, Output = Input>(
   name: string,
   validate: (value: unknown) => StandardSchemaV1.Result<Output>,
+  toJsonSchema?: () => any,
   meta: Record<string, string> = {},
 ): ZetaSchema<Input, Output> {
   const parentMeta = meta;
@@ -29,11 +31,12 @@ function createZetaSchema<Input = unknown, Output = Input>(
       validate,
     },
     meta(meta) {
-      return createZetaSchema(name, validate, {
+      return createZetaSchema(name, validate, undefined, {
         ...parentMeta,
         ...meta,
       });
     },
+    toJsonSchema,
   };
 }
 
@@ -97,6 +100,10 @@ export const ErrorResponse: ZetaSchema<unknown, ErrorResponse> =
     },
   );
 
+export function isZetaSchema(schema: any): schema is ZetaSchema {
+  return schema?.["~standard"]?.vendor === "@aklinker/zeta";
+}
+
 /**
  * The actual type an error response conforms to.
  */
@@ -164,3 +171,101 @@ export const NoResponse: ZetaSchema<undefined | null | void, void> =
         : { value: undefined };
     },
   );
+
+export const FormDataBody: ZetaSchema<FormData> = createZetaSchema<FormData>(
+  "FormDataBody",
+  (value: unknown): StandardSchemaV1.Result<FormData> => {
+    return value instanceof FormData
+      ? { value }
+      : {
+          issues: [{ message: `Expected FormData, got ${typeof value}` }],
+        };
+  },
+  () => ({
+    type: "object",
+    additionalProperties: true,
+  }),
+  {
+    contentType: "multipart/form-data",
+  },
+);
+
+export const UploadFileBody: ZetaSchema<File> = createZetaSchema<File>(
+  "UploadFileBody",
+  (value: unknown): StandardSchemaV1.Result<File> => {
+    if (!(value instanceof FormData)) {
+      return {
+        issues: [{ message: `Expected FormData, got ${typeof value}` }],
+      };
+    }
+
+    const file = value.get("file");
+    if (!(file instanceof File)) {
+      return {
+        issues: [{ message: `Expected File, got ${typeof file}` }],
+      };
+    }
+
+    return { value: file };
+  },
+  () => ({
+    type: "object",
+    properties: {
+      file: {
+        type: "string",
+        format: "binary",
+      },
+    },
+  }),
+  {
+    contentType: "multipart/form-data",
+  },
+);
+
+export const UploadFilesBody: ZetaSchema<FormData, File[]> = createZetaSchema<
+  FormData,
+  File[]
+>(
+  "UploadFilesBody",
+  (value): StandardSchemaV1.Result<File[]> => {
+    if (!(value instanceof FormData)) {
+      return {
+        issues: [{ message: `Expected FormData, got ${typeof value}` }],
+      };
+    }
+
+    const files = value.getAll("file");
+    if (!Array.isArray(files)) {
+      return {
+        issues: [{ message: `Expected array of Files, got ${typeof files}` }],
+      };
+    }
+
+    const issues: string[] = [];
+    for (const file of files) {
+      if (!(file instanceof File)) {
+        issues.push(`Expected File, got ${typeof file}`);
+      }
+    }
+    if (issues.length > 0) {
+      return { issues: issues.map((message) => ({ message })) };
+    }
+
+    return { value: files as File[] };
+  },
+  () => ({
+    type: "object",
+    properties: {
+      files: {
+        type: "array",
+        items: {
+          type: "string",
+          format: "binary",
+        },
+      },
+    },
+  }),
+  {
+    contentType: "multipart/form-data",
+  },
+);
