feat!: rename schema modes to input/wire, fix optional handling per direction

The previous exact/coerced split conflated two orthogonal concerns:
optional handling and wire coercion. The "coerced" variant — used by the
hono middleware and rest-client response validation — was permissive about
\`undefined\` even though JSON-parsed wire data can never carry one. The
"exact" variant — intended for strict in-memory use — rejected \`undefined\`
even though TS callers legitimately destructure-with-default into it.

Realigned along direction of data flow:

  input — TS-side outgoing. Uses v.optional, no wire coercion. Tolerates
          \`{ foo: undefined }\` since JSON.stringify strips those keys.
          For pre-flight client-side validation of request data.

  wire  — JSON-parsed incoming. Uses v.exactOptional (present-or-absent,
          never undefined). Includes bigint/number coercion for HTTP wire
          formats. For server middleware and response parsing.

Generated naming flips accordingly:
  exactPetSchema → inputPetSchema (was: exactOptional + no coercion;
                                   now: optional + no coercion)
  petSchema     → petSchema       (was: optional + coercion;
                                   now: exactOptional + coercion)

CLI flag: --exact-only → --input-only.
CodegenOptions: exactOnly → inputOnly.

The hono middleware and validated commands continue to use the wire
variant — now with correct exactOptional semantics so handlers receive
clean \`{ field?: T }\` types with no undefined leakage.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: maxholman

__tests__/__snapshots__/nullables.test.ts.snap

@@ -11,14 +11,14 @@ export type NullConst = null;
 exports[`const values 2`] = `
 "import * as v from "valibot";
 
-export const exactStringConstSchema = v.literal("hello");
-export const stringConstSchema = exactStringConstSchema;
-export const exactNumberConstSchema = v.literal(42);
-export const numberConstSchema = exactNumberConstSchema;
-export const exactBooleanConstSchema = v.literal(true);
-export const booleanConstSchema = exactBooleanConstSchema;
-export const exactNullConstSchema = v.null();
-export const nullConstSchema = exactNullConstSchema;
+export const inputStringConstSchema = v.literal("hello");
+export const stringConstSchema = inputStringConstSchema;
+export const inputNumberConstSchema = v.literal(42);
+export const numberConstSchema = inputNumberConstSchema;
+export const inputBooleanConstSchema = v.literal(true);
+export const booleanConstSchema = inputBooleanConstSchema;
+export const inputNullConstSchema = v.null();
+export const nullConstSchema = inputNullConstSchema;
 "
 `;
 
@@ -77,25 +77,25 @@ export class UploadDataCommand extends commands.UploadDataCommand {
 exports[`header parameters 4`] = `
 "import * as v from "valibot";
 
-export const exactUploadStatusSchema = v.picklist(["pending", "complete"]);
-export const uploadStatusSchema = exactUploadStatusSchema;
-export const exactUploadDataCommandResponseSchema = exactUploadStatusSchema;
+export const inputUploadStatusSchema = v.picklist(["pending", "complete"]);
+export const uploadStatusSchema = inputUploadStatusSchema;
+export const inputUploadDataCommandResponseSchema = inputUploadStatusSchema;
 export const uploadDataCommandResponseSchema = uploadStatusSchema;
-export const exactUploadDataCommandParamsSchema = v.strictObject({
+export const inputUploadDataCommandParamsSchema = v.strictObject({
         "uploadId": v.string()
     });
 export const uploadDataCommandParamsSchema = v.strictObject({
         "uploadId": v.pipe(v.string(), v.trim())
     });
-export const exactUploadDataCommandHeaderSchema = v.object({
+export const inputUploadDataCommandHeaderSchema = v.object({
         "content-type": v.picklist(["application/json", "text/csv", "application/xml"]),
         "content-length": v.bigint(),
-        "x-idempotency-key": v.exactOptional(v.pipe(v.string(), v.uuid()))
+        "x-idempotency-key": v.optional(v.pipe(v.string(), v.uuid()))
     });
 export const uploadDataCommandHeaderSchema = v.object({
         "content-type": v.picklist(["application/json", "text/csv", "application/xml"]),
         "content-length": v.union([v.pipe(v.string(), v.decimal(), v.toBigint(), v.bigint()), v.pipe(v.number(), v.integer(), v.toBigint(), v.bigint()), v.bigint()]),
-        "x-idempotency-key": v.optional(v.pipe(v.string(), v.uuid()))
+        "x-idempotency-key": v.exactOptional(v.pipe(v.string(), v.uuid()))
     });
 "
 `;
@@ -131,7 +131,7 @@ exports[`nullables 1`] = `
 exports[`oneOf with type null generates v.null() 1`] = `
 "import * as v from "valibot";
 
-export const exactNullableImageSchema = v.union([v.string(), v.null()]);
+export const inputNullableImageSchema = v.union([v.string(), v.null()]);
 export const nullableImageSchema = v.union([v.pipe(v.string(), v.trim()), v.null()]);
 "
 `;
@@ -153,21 +153,21 @@ export type ListFilesCommandInput = ListFilesCommandQuery;
 exports[`query and header integer params coerce strings to numbers 2`] = `
 "import * as v from "valibot";
 
-export const exactDummySchema = v.string();
+export const inputDummySchema = v.string();
 export const dummySchema = v.pipe(v.string(), v.trim());
-export const exactExpireTimeSchema = v.pipe(v.bigint(), v.minValue(BigInt(0)));
+export const inputExpireTimeSchema = v.pipe(v.bigint(), v.minValue(BigInt(0)));
 export const expireTimeSchema = v.union([v.pipe(v.string(), v.decimal(), v.toBigint(), v.pipe(v.bigint(), v.minValue(BigInt(0)))), v.pipe(v.number(), v.integer(), v.toBigint(), v.pipe(v.bigint(), v.minValue(BigInt(0)))), v.pipe(v.bigint(), v.minValue(BigInt(0)))]);
-export const exactListFilesCommandResponseSchema = exactDummySchema;
+export const inputListFilesCommandResponseSchema = inputDummySchema;
 export const listFilesCommandResponseSchema = dummySchema;
-export const exactListFilesCommandQuerySchema = v.strictObject({
+export const inputListFilesCommandQuerySchema = v.strictObject({
         "exp": v.pipe(v.bigint(), v.minValue(BigInt(0))),
-        "limit": v.exactOptional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(100)))
+        "limit": v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(100)))
     });
 export const listFilesCommandQuerySchema = v.strictObject({
         "exp": v.union([v.pipe(v.string(), v.decimal(), v.toBigint(), v.pipe(v.bigint(), v.minValue(BigInt(0)))), v.pipe(v.number(), v.integer(), v.toBigint(), v.pipe(v.bigint(), v.minValue(BigInt(0)))), v.pipe(v.bigint(), v.minValue(BigInt(0)))]),
-        "limit": v.optional(v.union([v.pipe(v.string(), v.decimal(), v.toNumber(), v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(100))), v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(100))]))
+        "limit": v.exactOptional(v.union([v.pipe(v.string(), v.decimal(), v.toNumber(), v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(100))), v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(100))]))
     });
-export const exactListFilesCommandHeaderSchema = v.object({
+export const inputListFilesCommandHeaderSchema = v.object({
         "x-rate-limit": v.pipe(v.number(), v.integer(), v.minValue(0))
     });
 export const listFilesCommandHeaderSchema = v.object({
@@ -187,14 +187,14 @@ export type MultiType = string | number;
 exports[`top-level type array with null 2`] = `
 "import * as v from "valibot";
 
-export const exactNullableStringSchema = v.nullable(v.string());
-export const nullableStringSchema = exactNullableStringSchema;
-export const exactNullableStringEnumSchema = v.nullable(v.picklist(["active", "inactive"]));
-export const nullableStringEnumSchema = exactNullableStringEnumSchema;
-export const exactNullableIntegerSchema = v.nullable(v.pipe(v.number(), v.integer()));
-export const nullableIntegerSchema = exactNullableIntegerSchema;
-export const exactMultiTypeSchema = v.union([v.string(), v.number()]);
-export const multiTypeSchema = exactMultiTypeSchema;
+export const inputNullableStringSchema = v.nullable(v.string());
+export const nullableStringSchema = inputNullableStringSchema;
+export const inputNullableStringEnumSchema = v.nullable(v.picklist(["active", "inactive"]));
+export const nullableStringEnumSchema = inputNullableStringEnumSchema;
+export const inputNullableIntegerSchema = v.nullable(v.pipe(v.number(), v.integer()));
+export const nullableIntegerSchema = inputNullableIntegerSchema;
+export const inputMultiTypeSchema = v.union([v.string(), v.number()]);
+export const multiTypeSchema = inputMultiTypeSchema;
 "
 `;
 

__tests__/nullables.test.ts

@@ -279,7 +279,7 @@ test("header parameters", async () => {
 	expect(result.honoValibotFile.getText()).toMatchSnapshot();
 });
 
-test("exact-only mode omits coerced schemas", async () => {
+test("input-only mode omits wire schemas", async () => {
 	const result = await processOpenApiDocument(
 		"/tmp/like-you-know-whatever",
 		{
@@ -325,13 +325,13 @@ test("exact-only mode omits coerced schemas", async () => {
 			},
 		},
 		[],
-		{ exactOnly: true },
+		{ inputOnly: true },
 	);
 
 	const valibotText = result.valibotFile.getText();
 
-	expect(valibotText).toContain("exactNameSchema");
-	expect(valibotText).toContain("exactAmountSchema");
+	expect(valibotText).toContain("inputNameSchema");
+	expect(valibotText).toContain("inputAmountSchema");
 	expect(valibotText).not.toMatch(/export const nameSchema\b/);
 	expect(valibotText).not.toMatch(/export const amountSchema\b/);
 	expect(valibotText).not.toContain("v.trim()");

bin/index.ts

@@ -26,9 +26,10 @@ const cliArgs = await yargs(hideBin(process.argv))
 					return Array.isArray(arg) ? arg : [arg];
 				},
 			})
-			.option("exact-only", {
+			.option("input-only", {
 				type: "boolean",
-				description: "Only emit exact schemas, skip coerced variants",
+				description:
+					"Only emit input schemas (TS-side, v.optional, no wire coercion); skip wire variants",
 				default: false,
 			});
 	})
@@ -38,5 +39,5 @@ await build(
 	join(process.cwd(), String(cliArgs.i)),
 	join(process.cwd(), String(cliArgs.o)),
 	cliArgs.t as Array<string>,
-	{ exactOnly: Boolean(cliArgs.exactOnly) },
+	{ inputOnly: Boolean(cliArgs.inputOnly) },
 );

lib/process-document.ts

@@ -39,7 +39,12 @@ import {
 } from "./valibot.ts";
 
 export interface CodegenOptions {
-	exactOnly?: boolean;
+	/**
+	 * Emit only `input*` variants (TS-side schemas: `v.optional`, no wire
+	 * coercion). Skips the `*Schema` (wire) variants used by hono middleware
+	 * and response parsing. For non-HTTP / in-memory-only consumers.
+	 */
+	inputOnly?: boolean;
 }
 
 interface OperationMiddlewareInfo {
@@ -145,7 +150,7 @@ export async function processOpenApiDocument(
 	const valibotFile = createValibotFile(project, outputDir);
 
 	// Track registered validators by their $ref path
-	const validators = new Map<string, { exact: string; coerced: string }>();
+	const validators = new Map<string, { input: string; wire: string }>();
 
 	// Track all operations for middleware generation
 	const allOperations: OperationMiddlewareInfo[] = [];
@@ -284,7 +289,7 @@ export async function processOpenApiDocument(
 			valibotFile,
 			schemaName,
 			schemaObject,
-			options?.exactOnly,
+			options?.inputOnly,
 		);
 
 		// Add enum values to enums file
@@ -832,7 +837,7 @@ export async function processOpenApiDocument(
 							query: queryParameters,
 							header: headerParameters,
 						},
-						options?.exactOnly,
+						options?.inputOnly,
 					);
 
 					// Track operation for middleware generation (use coerced schemas)
@@ -841,9 +846,9 @@ export async function processOpenApiDocument(
 					);
 					allOperations.push({
 						exportName: middlewareExportName,
-						schemas: options?.exactOnly
-							? operationSchemas.exact
-							: operationSchemas.coerced,
+						schemas: options?.inputOnly
+							? operationSchemas.input
+							: operationSchemas.wire,
 					});
 
 					// CommandInput
@@ -993,14 +998,16 @@ export async function processOpenApiDocument(
 					// schemas aren't read by rest-client anyway (hono-valibot.ts imports
 					// directly from valibot.ts for server middleware), and the response
 					// schema lives on the validated subclass.
-					const coercedSchemas = options?.exactOnly
-						? operationSchemas.exact
-						: operationSchemas.coerced;
+					// Wire variant is what rest-client + hono consume; falls back to
+					// the input variant under --input-only.
+					const wireSchemas = options?.inputOnly
+						? operationSchemas.input
+						: operationSchemas.wire;
 
-					if (coercedSchemas.response) {
+					if (wireSchemas.response) {
 						validatedSubclasses.push({
 							commandName,
-							responseSchema: coercedSchemas.response,
+							responseSchema: wireSchemas.response,
 						});
 					} else {
 						validatedReExports.push(commandName);