feat: improved error diagnostics

Richer errors

Issue now has optional received; ValidationError / UnexpectedError / FnError all serialize via toJSON()
Schema messages include value previews (types, email/URL/regex/check, unions with branch N: labels)
Paths name the door: fn.input…, model.create…
HTTP edge

encodeError → ValidationError 400, FnError status/422, UnexpectedError 500
createHandler / handler return JSON bodies instead of rethrowing
http.err status is stamped onto FnError at mint (read from the original declaration, since asType drops the symbol)
Breaking: input paths now include .input (e.g. fnt.multi.input.a).

Author: ping-maxwell

packages/experimental/README.md

@@ -109,7 +109,19 @@ What this buys, all Effect-inspired but with plain functions:
 - **Failure vs defect.** A thrown `c.error(...)` is a `FnError` - a domain outcome, tagged, serializable (`{ tag, data, trail }` survives a wire). Once a fn declares `errors`, any *untagged* throw escaping its body is a bug and comes out as `UnexpectedError` with the original on `cause`. Callers never string-match to tell the two apart.
 - **Typed recovery.** `fn.try(input)` returns `{ ok: true, value } | { ok: false, error }` where `error` is the union of declared errors - TS narrows on `error.tag`. Defects and contract violations still throw. `FnErrors<typeof fn>` gives the union for catch sites.
 - **The trail.** As an error crosses fn frames it collects their keys - `["audit.log", "profile.update", "capability.exec"]` - origin first, so nothing about where a failure started is ever lost.
-- **All issues, not the first.** Validation collects every bad field / tuple position in one `ValidationError.issues` list.
+- **All issues, not the first.** Validation collects every bad field / tuple position in one `ValidationError.issues` list. Paths name the contract door (`sign_in.email.input.email`), and each issue can carry a `received` preview:
+
+```ts
+// sign_in.email.input.email: expected an email address, received "nope"
+// sign_in.email.input.password: expected string, received number (1)
+err.issues;
+// [
+//   { path: "sign_in.email.input.email", message: "expected an email address, received \"nope\"", received: "\"nope\"" },
+//   { path: "sign_in.email.input.password", message: "expected string, received number (1)", received: "1" },
+// ]
+```
+
+At the HTTP edge (`createHandler` / `handler`), `ValidationError` becomes `400` with that JSON body, `FnError` uses `http.err` status (or `422`), and `UnexpectedError` becomes `500`.
 
 ### vars
 

packages/experimental/src/error.ts

@@ -1,18 +1,39 @@
-export type Issue = { path: string; message: string };
+export type Issue = {
+	path: string;
+	message: string;
+	/** Truncated, JSON-safe preview of the bad value. */
+	received?: string;
+};
 
 /** A contract violation - input, output, requires, provides. Carries
  * EVERY issue found in the pass that threw it, not just the first;
  * `message` lists them all. */
 export class ValidationError extends Error {
 	public path: string;
 	public issues: Issue[];
-	constructor(path: string, message: string, issues?: Issue[]) {
+	constructor(
+		path: string,
+		message: string,
+		issues?: Issue[],
+		options?: ErrorOptions,
+	) {
 		const all = issues?.length ? issues : [{ path, message }];
-		super(all.map((issue) => `${issue.path}: ${issue.message}`).join("; "));
+		super(
+			all.map((issue) => `${issue.path}: ${issue.message}`).join("; "),
+			options,
+		);
 		this.name = "ValidationError";
 		this.path = all[0]?.path ?? path;
 		this.issues = all;
 	}
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+			path: this.path,
+			issues: this.issues,
+		};
+	}
 }
 
 /**
@@ -21,27 +42,33 @@ export class ValidationError extends Error {
  * fn's `errors` schema. The `tag` is the discriminant callers narrow on;
  * `trail` records the fn that threw, then every frame it crossed.
  * Serializes as data, so it survives a remote boundary intact.
+ * Optional `status` is set when the declaration carried HTTP metadata
+ * (`http.err`); the edge uses it without looking the map back up.
  */
 export class FnError<
 	Tag extends string = string,
 	Data = unknown,
 > extends Error {
 	public trail: string[];
+	public status?: number;
 	constructor(
 		public tag: Tag,
 		public data: Data,
 		fn: string,
+		status?: number,
 	) {
 		super(`${fn}: ${tag}`);
 		this.name = "FnError";
 		this.trail = [fn];
+		if (status !== undefined) this.status = status;
 	}
 	toJSON() {
 		return {
 			name: this.name,
 			tag: this.tag as Tag,
 			data: this.data,
 			trail: this.trail,
+			...(this.status !== undefined ? { status: this.status } : {}),
 		};
 	}
 }
@@ -63,6 +90,19 @@ export class UnexpectedError extends Error {
 		this.name = "UnexpectedError";
 		this.trail = [fn];
 	}
+	toJSON() {
+		const cause = this.cause;
+		return {
+			name: this.name,
+			message: this.message,
+			trail: this.trail,
+			...(cause instanceof Error
+				? { cause: { name: cause.name, message: cause.message } }
+				: cause !== undefined
+					? { cause: { message: String(cause) } }
+					: {}),
+		};
+	}
 }
 
 /** Plugin/transport control that is neither a domain refusal nor a defect.

packages/experimental/src/fn.test.ts

@@ -416,7 +416,7 @@ describe("tuple input - positional args", () => {
 			{ input: [v.string({ min: 3 })] },
 			(c) => c.input[0],
 		);
-		expect(() => f("ab")).toThrow(/fnt\.pos\[0\]/);
+		expect(() => f("ab")).toThrow(/fnt\.pos\.input\[0\]/);
 	});
 
 	it("used fns forward positional args and still share the scope", async () => {
@@ -459,7 +459,7 @@ describe("fn as input schema", () => {
 			(c) => c.input.execute({ n: "x" } as never),
 		);
 		expect(() => run({ execute: (i) => i.n })).toThrow(
-			/fnt\.runner\.execute\(\)/,
+			/fnt\.runner\.input\.execute\(\)/,
 		);
 	});
 
@@ -975,7 +975,17 @@ describe("multi-issue validation", () => {
 			expect(thrown).toBeInstanceOf(ValidationError);
 			const err = thrown as ValidationError;
 			expect(err.issues).toHaveLength(2);
-			expect(err.message).toMatch(/fnt\.multi\.a.*fnt\.multi\.b/s);
+			expect(err.message).toMatch(
+				/fnt\.multi\.input\.a.*fnt\.multi\.input\.b/s,
+			);
+			expect(err.issues[0]?.received).toBe("1");
+			expect(err.issues[1]?.received).toBe('"x"');
+			expect(JSON.parse(JSON.stringify(err))).toEqual({
+				name: "ValidationError",
+				message: err.message,
+				path: "fnt.multi.input.a",
+				issues: err.issues,
+			});
 		}
 	});
 
@@ -991,8 +1001,8 @@ describe("multi-issue validation", () => {
 		} catch (thrown) {
 			const err = thrown as ValidationError;
 			expect(err.issues.map((issue) => issue.path)).toEqual([
-				"fnt.multiArr.tags[0]",
-				"fnt.multiArr.tags[2]",
+				"fnt.multiArr.input.tags[0]",
+				"fnt.multiArr.input.tags[2]",
 			]);
 		}
 	});
@@ -1009,8 +1019,8 @@ describe("multi-issue validation", () => {
 		} catch (thrown) {
 			const err = thrown as ValidationError;
 			expect(err.issues.map((issue) => issue.path)).toEqual([
-				"fnt.multiPos[0]",
-				"fnt.multiPos[1]",
+				"fnt.multiPos.input[0]",
+				"fnt.multiPos.input[1]",
 			]);
 		}
 	});

packages/experimental/src/fn.ts

@@ -905,7 +905,7 @@ const defineFn = (
 						const result = validate(
 							asType(def),
 							(input as unknown[])[index],
-							`${key}[${index}]`,
+							`${key}.input[${index}]`,
 						);
 						if (isThenable(result)) {
 							return result.then(
@@ -955,7 +955,7 @@ const defineFn = (
 			}
 			return options.input === undefined
 				? input
-				: validate(asType(options.input), input, key);
+				: validate(asType(options.input), input, `${key}.input`);
 		};
 
 		const applyInputExtensions = (parsed: unknown) => {
@@ -1022,10 +1022,18 @@ const defineFn = (
 								: `"${key}" declares no errors`,
 						);
 					}
+					// HTTP status lives on the ORIGINAL declaration (`http.err`);
+					// `asType` copies enumerable fields only, so read it there.
+					const meta = (
+						declaredErrors?.[tag] as
+							| Record<symbol, { status?: number } | undefined>
+							| undefined
+					)?.[Symbol.for("better-call:http.err")];
 					return new FnError(
 						tag,
 						validate(schema, data ?? {}, `${key}.errors.${tag}`),
 						key,
+						meta?.status,
 					);
 				},
 				[STORE]: cells,

packages/experimental/src/plugins/http/attrs.test.ts

@@ -100,6 +100,15 @@ describe("http field attrs", () => {
 		await expect(fromJsonBody(smuggle, v.object(shape))).rejects.toThrow(
 			ValidationError,
 		);
+
+		const badJson = new Request("https://example.com", {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: "{",
+		});
+		await expect(fromJsonBody(badJson, v.object(shape))).rejects.toThrow(
+			/expected a JSON body \(/,
+		);
 	});
 
 	it("clientSchema and rejectServerOnly recurse into union arms", () => {

packages/experimental/src/plugins/http/attrs.ts

@@ -120,8 +120,13 @@ export const fromJsonBody = async <S>(
 	let body: unknown;
 	try {
 		body = await request.json();
-	} catch {
-		throw new ValidationError(path, "expected a JSON body");
+	} catch (cause) {
+		throw new ValidationError(
+			path,
+			`expected a JSON body (${cause instanceof Error ? cause.message : String(cause)})`,
+			undefined,
+			{ cause },
+		);
 	}
 	return await wireInput(schema, body, path);
 };

packages/experimental/src/plugins/http/error.test.ts

@@ -1,7 +1,8 @@
 import { describe, expect, expectTypeOf, it } from "vitest";
-import { FnError, v } from "../../index";
+import { FnError, UnexpectedError, ValidationError, v } from "../../index";
 import {
 	applyError,
+	encodeError,
 	err,
 	errorStatus,
 	type HttpResponse,
@@ -65,6 +66,7 @@ describe("http.err - status on declared errors", () => {
 			expect(bad.error).toBeInstanceOf(FnError);
 			expect(bad.error.tag).toBe("invalid_credentials");
 			expect(bad.error.data).toEqual({ attempts: 3 });
+			expect(bad.error.status).toBe(401);
 			if (bad.error.tag === "invalid_credentials") {
 				expectTypeOf(bad.error.data).toEqualTypeOf<{
 					readonly attempts: number;
@@ -77,6 +79,7 @@ describe("http.err - status on declared errors", () => {
 		if (!gone.ok) {
 			expect(gone.error.tag).toBe("gone");
 			expect(gone.error.data).toEqual({});
+			expect(gone.error.status).toBe(410);
 		}
 
 		expect(() =>
@@ -133,6 +136,12 @@ describe("http.err - status on declared errors", () => {
 		expect(response.status).toBe(401);
 	});
 
+	it("applyError uses FnError.status when the map is absent", () => {
+		const response: HttpResponse = { headers: new Headers() };
+		applyError(response, undefined, { tag: "denied", status: 403 });
+		expect(response.status).toBe(403);
+	});
+
 	it("applyError leaves res.status alone for plain error tags", () => {
 		const response = { headers: new Headers(), status: 200 };
 		applyError(response, { plain: { reason: v.string() } }, { tag: "plain" });
@@ -144,3 +153,88 @@ describe("http.err - status on declared errors", () => {
 		expect(http.statusOf(http.err(418))).toBe(418);
 	});
 });
+
+describe("encodeError + createHandler JSON bodies", () => {
+	it("encodeError maps ValidationError to 400", () => {
+		const error = new ValidationError(
+			"body.n",
+			'expected number, received string ("x")',
+			[
+				{
+					path: "body.n",
+					message: 'expected number, received string ("x")',
+					received: '"x"',
+				},
+			],
+		);
+		expect(encodeError(error)).toEqual({
+			status: 400,
+			body: error.toJSON(),
+		});
+	});
+
+	it("encodeError maps FnError status or defaults to 422", () => {
+		const stamped = new FnError("denied", {}, "f", 403);
+		expect(encodeError(stamped)?.status).toBe(403);
+		const plain = new FnError("denied", {}, "f");
+		expect(encodeError(plain)?.status).toBe(422);
+	});
+
+	it("encodeError maps UnexpectedError to 500 without a cause stack", () => {
+		const unexpected = new UnexpectedError(new Error("boom"), "f");
+		expect(encodeError(unexpected)).toEqual({
+			status: 500,
+			body: {
+				name: "UnexpectedError",
+				message: "f: unexpected - boom",
+				trail: ["f"],
+				cause: { name: "Error", message: "boom" },
+			},
+		});
+	});
+
+	it("createHandler returns 400 JSON for ValidationError", async () => {
+		const fetch = http.createHandler(() => {
+			throw new ValidationError(
+				"body.email",
+				'expected an email address, received "x"',
+				[
+					{
+						path: "body.email",
+						message: 'expected an email address, received "x"',
+						received: '"x"',
+					},
+				],
+			);
+		});
+		const response = await fetch(new Request("http://x.test/"));
+		expect(response.status).toBe(400);
+		await expect(response.json()).resolves.toMatchObject({
+			name: "ValidationError",
+			path: "body.email",
+			issues: [{ path: "body.email", received: '"x"' }],
+		});
+	});
+
+	it("createHandler returns declared status JSON for FnError", async () => {
+		const deny = app.fn(
+			"httpt.err.deny",
+			{ errors: { denied: err(403) } },
+			(c) => {
+				throw c.error("denied");
+			},
+		);
+		const fetch = http.createHandler(() => {
+			throw deny();
+		});
+		const response = await fetch(new Request("http://x.test/"));
+		expect(response.status).toBe(403);
+		await expect(response.json()).resolves.toEqual({
+			name: "FnError",
+			tag: "denied",
+			data: {},
+			trail: ["httpt.err.deny"],
+			status: 403,
+		});
+	});
+});