@terpjs/react-core 0.9.0 → 0.11.0

package/src/unwrap.test.ts

@@ -96,3 +96,135 @@ describe("unwrapOptional", () => {
     expect((caught as ApiError).status).toBe(403);
   });
 });
+
+// The per-field half of the error envelope.
+//
+// `Field` shipped an `error` prop, a `field-error` marker, an `aria-describedby`, an
+// `aria-invalid` and a style rule for all of it, and nothing in this package could produce the
+// value: every `error=` on a `Field` in all three trees was a test or a specimen. The reason was
+// one function here, which computed each reason's field path and then joined it into a sentence.
+// The information reached the client and was discarded on arrival.
+//
+// So these do not assert that a parser parses. Each one names a way the path can be lost again.
+describe("ApiError.fields", () => {
+  function failureOf(error: unknown, status = 422): ApiError {
+    try {
+      unwrap({ error, response: response(status) });
+    } catch (thrown) {
+      return thrown as ApiError;
+    }
+    throw new Error("unwrap returned instead of throwing");
+  }
+
+  it("keys a FastAPI 422 by dotted path, with the body/query/path prefix dropped", () => {
+    expect(
+      failureOf({
+        detail: [
+          { loc: ["body", "title"], msg: "String should have at least 1 character" },
+          { loc: ["body", "owner", "email"], msg: "Input should be a valid email" },
+        ],
+      }).fields,
+    ).toEqual({
+      title: "String should have at least 1 character",
+      "owner.email": "Input should be a valid email",
+    });
+  });
+
+  it("reads the envelope's own `details`, whose `loc` is already a dotted string", () => {
+    // `terp.core.ErrorDetail` documents its shape as "deliberately mirrors FastAPI's own 422
+    // detail entries ... so a frontend handles both with one branch", and no such branch existed:
+    // `unwrap` named `details` in a doc comment and never read the key. Handling only the array
+    // spelling would have kept half of that promise while claiming all of it.
+    // Mutation: delete the string arm of `fieldPath` and only this test goes red.
+    expect(
+      failureOf({
+        code: "validation_failed",
+        detail: "Two things are wrong.",
+        details: [
+          { code: "too_short", loc: "name", msg: "Name is too short." },
+          { code: "not_unique", loc: "contact.email", msg: "Already registered." },
+        ],
+      }).fields,
+    ).toEqual({ name: "Name is too short.", "contact.email": "Already registered." });
+  });
+
+  it("leaves the message to `detail` when `details` rides beside it", () => {
+    // `details` is additive on the wire, so it must be additive here too. If it captured the
+    // message slot that `detail` already fills, every existing caller's copy would change on the
+    // day a backend first emits a reason list.
+    expect(
+      failureOf({
+        detail: "Two things are wrong.",
+        details: [{ code: "too_short", loc: "name", msg: "Name is too short." }],
+      }).message,
+    ).toBe("Two things are wrong.");
+  });
+
+  it("is empty for every failure that names no field", () => {
+    expect(failureOf({ code: "permission_denied", detail: "Nope." }, 403).fields).toEqual({});
+    expect(failureOf({ code: "conflict" }, 409).fields).toEqual({});
+    expect(failureOf(undefined, 500).fields).toEqual({});
+  });
+
+  it("keeps a reason with no `loc` in the message, the only place it can go", () => {
+    // A record keyed by field has no slot for a reason about the request as a whole, which
+    // `ErrorDetail` documents as a supported case. Dropping it silently would be a regression
+    // from the joined string this replaced, so the message keeps carrying it.
+    const failure = failureOf({
+      detail: [
+        { loc: [], msg: "The window overlaps an existing one." },
+        { loc: ["body", "name"], msg: "Name is too short." },
+      ],
+    });
+    expect(failure.fields).toEqual({ name: "Name is too short." });
+    expect(failure.message).toBe("The window overlaps an existing one.; name: Name is too short.");
+  });
+
+  it("takes the first reason per field and leaves the rest in the message", () => {
+    const failure = failureOf({
+      detail: [
+        { loc: ["body", "password"], msg: "Too short." },
+        { loc: ["body", "password"], msg: "Needs a digit." },
+      ],
+    });
+    expect(failure.fields).toEqual({ password: "Too short." });
+    expect(failure.message).toBe("password: Too short.; password: Needs a digit.");
+  });
+
+  it("drops only a LEADING body/query/path, because elsewhere the same word is a field name", () => {
+    // FastAPI puts exactly one of these at the front to say where in the request the value came
+    // from. Anywhere else it is a name the caller chose, and a webhook with a `path` field is not
+    // a hypothetical. Stripping every occurrence attached the reason to the wrong control, or —
+    // for a top-level field called `path` — to no control at all, since the key came out empty.
+    expect(failureOf({ detail: [{ loc: ["body", "path"], msg: "Must start with a slash." }] }).fields)
+      .toEqual({ path: "Must start with a slash." });
+    expect(
+      failureOf({ detail: [{ loc: ["body", "config", "body"], msg: "Required." }] }).fields,
+    ).toEqual({ "config.body": "Required." });
+    // A loc that is ONLY the prefix is still about the request as a whole, so it keeps no key.
+    const whole = failureOf({ detail: [{ loc: ["body"], msg: "Malformed JSON." }] });
+    expect(whole.fields).toEqual({});
+    expect(whole.message).toBe("Malformed JSON.");
+  });
+
+  it("keeps a reason whose field is named after something on Object.prototype", () => {
+    // The keys are server-supplied. `fields["constructor"]` on a plain object is truthy before
+    // anything is written to it, so a first-wins guard spelled `=== undefined` decides the slot is
+    // taken and drops the reason with no trace.
+    expect(
+      failureOf({
+        detail: [
+          { loc: ["body", "constructor"], msg: "Unknown builder." },
+          { loc: ["body", "toString"], msg: "Not a template." },
+        ],
+      }).fields,
+    ).toEqual({ constructor: "Unknown builder.", toString: "Not a template." });
+  });
+
+  it("is frozen, so one failure's reasons cannot be edited into something the server never said", () => {
+    const fields = failureOf({ detail: [{ loc: ["body", "name"], msg: "Too short." }] }).fields;
+    expect(() => {
+      (fields as Record<string, string>).name = "anything";
+    }).toThrow();
+  });
+});

package/src/unwrap.ts

@@ -30,13 +30,36 @@ export class ApiError extends Error {
   readonly status: number;
   /** Correlation id from the envelope, for support and log lookup. */
   readonly requestId?: string;
+  /**
+   * Per-field reasons, keyed by dotted field path (`loc` with FastAPI's `body` / `query` /
+   * `path` prefix removed). Empty for every failure that names no field, so
+   * `Object.keys(error.fields).length > 0` is the test for "this belongs on the form".
+   *
+   * What a caller does with it is hand it to `Field`'s `error` prop, which is the whole
+   * reason it exists: the framework shipped the rendering half of field-level validation —
+   * the marker, the `aria-describedby`, the `aria-invalid`, the styling — and nothing that
+   * produces the value. The path was already being computed one function below and joined
+   * into a sentence, so the information reached the client and was discarded on arrival.
+   */
+  readonly fields: Readonly<Record<string, string>>;
 
-  constructor(message: string, options: { code?: string; status: number; requestId?: string }) {
+  constructor(
+    message: string,
+    options: {
+      code?: string;
+      status: number;
+      requestId?: string;
+      fields?: Readonly<Record<string, string>>;
+    },
+  ) {
     super(message);
     this.name = "ApiError";
     this.code = options.code;
     this.status = options.status;
     this.requestId = options.requestId;
+    // Defaulted and frozen: every caller reads `.fields` without a presence check, and an
+    // error's reasons cannot be edited into something the server never said.
+    this.fields = Object.freeze({ ...options.fields });
   }
 }
 
@@ -63,55 +86,118 @@ export function unwrap<T>(result: FetchResult<T>): T {
       result.error !== null && typeof result.error === "object"
         ? (result.error as { code?: unknown; request_id?: unknown })
         : {};
-    throw new ApiError(errorMessage(result.error, result.response), {
+    const failure = describeFailure(result.error, result.response);
+    throw new ApiError(failure.message, {
       code: typeof envelope.code === "string" ? envelope.code : undefined,
       status: result.response.status,
       requestId: typeof envelope.request_id === "string" ? envelope.request_id : undefined,
+      fields: failure.fields,
     });
   }
   return result.data as T;
 }
 
-/** Human-readable message for a failed request: envelope `detail`, else `code`, else the status. */
-function errorMessage(error: unknown, response: Response): string {
+/** A failure's message and its per-field reasons — one value, because one walk produces both. */
+interface Failure {
+  message: string;
+  fields: Record<string, string>;
+}
+
+/**
+ * Human-readable message for a failed request — envelope `detail`, else `code`, else the
+ * status — paired with whatever per-field reasons came with it.
+ *
+ * The envelope keeps its reasons in two different places depending on who raised the error,
+ * and both are read here. A Terp `AppError` puts a sentence in `detail` and its structured
+ * reasons in `details` beside it, so the sentence still wins the message. FastAPI's own 422
+ * handler makes `detail` *itself* the list — the app registers no `RequestValidationError`
+ * override, so that is the shape a schema rejection actually arrives in.
+ */
+function describeFailure(error: unknown, response: Response): Failure {
   if (error !== null && typeof error === "object") {
-    const envelope = error as { detail?: unknown; code?: unknown };
+    const envelope = error as { detail?: unknown; details?: unknown; code?: unknown };
+    // `details` sits beside `detail` rather than replacing it, so its reasons attach to
+    // whichever message wins below instead of competing for the slot.
+    const reasons = structuredDetail(envelope.details);
+    const fields = reasons?.fields ?? {};
     if (typeof envelope.detail === "string" && envelope.detail.length > 0) {
-      return envelope.detail;
+      return { message: envelope.detail, fields };
     }
-    const structured = structuredDetail(envelope.detail);
-    if (structured !== null) {
-      return structured;
+    const validation = structuredDetail(envelope.detail);
+    if (validation !== null) {
+      return validation;
     }
     if (typeof envelope.code === "string" && envelope.code.length > 0) {
-      return envelope.code;
+      return { message: envelope.code, fields };
     }
   }
-  return `Request failed (HTTP ${response.status})`;
+  return { message: `Request failed (HTTP ${response.status})`, fields: {} };
+}
+
+/**
+ * The dotted field path a reason addresses, or `""` when it is about the request as a whole.
+ *
+ * Two spellings arrive and reading only one is how the client stayed half-deaf to its own
+ * contract: FastAPI emits `loc` as an array (`["body", "owner", "email"]`), while
+ * `terp.core.ErrorDetail` emits it already dotted — a shape whose docstring says it
+ * "deliberately mirrors FastAPI's own 422 detail entries ... so a frontend handles both with
+ * one branch". Nothing had written that branch. This is it.
+ *
+ * Only a LEADING `body` / `query` / `path` is dropped. FastAPI puts exactly one of them at the
+ * front to say where in the request the value came from; anywhere else the same word is a field
+ * the caller named, and `["body", "path"]` is a webhook's `path` field, not a bare request. While
+ * this only shaped a sentence the difference was cosmetic. It now chooses which input lights up,
+ * so stripping every occurrence would attach a reason to the wrong control — or, for a top-level
+ * field called `path`, to no control at all.
+ */
+const LOC_PREFIXES = new Set(["body", "query", "path"]);
+
+function fieldPath(loc: unknown): string {
+  if (Array.isArray(loc)) {
+    const parts = loc.filter(
+      (part): part is string | number => typeof part === "string" || typeof part === "number",
+    );
+    const start = typeof parts[0] === "string" && LOC_PREFIXES.has(parts[0]) ? 1 : 0;
+    return parts.slice(start).join(".");
+  }
+  return typeof loc === "string" ? loc : "";
 }
 
-/** Flatten common FastAPI/Pydantic validation details into an agent/user-actionable message. */
-function structuredDetail(detail: unknown): string | null {
+/**
+ * Flatten common FastAPI/Pydantic validation details into an agent/user-actionable message,
+ * keeping each reason's field alongside it.
+ *
+ * The message is assembled exactly as before, deliberately: it is what every existing caller
+ * shows, and `fields` is additive beside it rather than a replacement for it. A reason with
+ * no `loc` therefore still reaches the user through the message, which is the only place it
+ * can go — a record keyed by field has no slot for a reason about the request as a whole.
+ */
+function structuredDetail(detail: unknown): Failure | null {
   if (!Array.isArray(detail)) {
     return null;
   }
-  const messages = detail
-    .map((item) => {
-      if (item === null || typeof item !== "object") {
-        return null;
-      }
-      const field = item as { loc?: unknown; msg?: unknown };
-      if (typeof field.msg !== "string" || field.msg.length === 0) {
-        return null;
-      }
-      const loc = Array.isArray(field.loc)
-        ? field.loc.filter((part) => typeof part === "string" || typeof part === "number")
-        : [];
-      const path = loc
-        .filter((part) => part !== "body" && part !== "query" && part !== "path")
-        .join(".");
-      return path.length > 0 ? `${path}: ${field.msg}` : field.msg;
-    })
-    .filter((message): message is string => message !== null);
-  return messages.length > 0 ? messages.join("; ") : null;
+  const messages: string[] = [];
+  const fields: Record<string, string> = {};
+  for (const item of detail) {
+    if (item === null || typeof item !== "object") {
+      continue;
+    }
+    const reason = item as { loc?: unknown; msg?: unknown };
+    if (typeof reason.msg !== "string" || reason.msg.length === 0) {
+      continue;
+    }
+    const path = fieldPath(reason.loc);
+    messages.push(path.length > 0 ? `${path}: ${reason.msg}` : reason.msg);
+    // First reason wins per path. A field that fails two checks shows the one the server
+    // reported first and keeps the rest in the message; overwriting would show the last,
+    // which is no more correct and reads as arbitrary.
+    //
+    // `Object.hasOwn`, not `=== undefined`: the keys are server-supplied, and a field called
+    // `constructor` or `toString` inherits a truthy value from `Object.prototype`, so the
+    // cheaper test would decide the slot was already taken and drop the reason silently.
+    if (path.length > 0 && !Object.hasOwn(fields, path)) {
+      fields[path] = reason.msg;
+    }
+  }
+  return messages.length > 0 ? { message: messages.join("; "), fields } : null;
 }