@gusnips/server 0.1.0

package/dist/responses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.js","sourceRoot":"","sources":["../src/responses.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,4FAA4F;AAC5F,MAAM,UAAU,EAAE,CAAwB,IAAO,EAAE,IAAQ;IACzD,MAAM,IAAI,GAAqB,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC9E,OAAO,EAAE,MAAM,EAAE,GAAY,EAAE,IAAI,EAAE,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,OAAO,CAAI,IAAO;IAChC,MAAM,IAAI,GAAkB,EAAE,IAAI,EAAE,CAAC;IACrC,OAAO,EAAE,MAAM,EAAE,GAAY,EAAE,IAAI,EAAE,CAAC;AACxC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAI,IAAS,EAAE,IAAqC;IAC3E,MAAM,IAAI,GAAoB;QAC5B,IAAI,EAAE,IAAI;QACV,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE;KACnE,CAAC;IACF,OAAO,EAAE,MAAM,EAAE,GAAY,EAAE,IAAI,EAAE,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,EAAE,MAAM,EAAE,GAAY,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC9C,CAAC;AA4DD;;;;;;;;;GASG;AACH,SAAS,gBAAgB,CAAC,GAAa;IACrC,IAAI,GAAG,CAAC,cAAc,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC,OAAO,CAAC;IACzD,MAAM,OAAO,GACX,GAAG,CAAC,OAAO,KAAK,SAAS;QACzB,CAAC,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3F,IAAI,CAAC,OAAO;QAAE,OAAO,GAAG,CAAC,OAAO,CAAC;IACjC,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,CAAC,cAAc,EAAE,CAAC;AAChE,CAAC;AAED;;;;;;GAMG;AACH,SAAS,YAAY,CAAsB,GAAmB;IAC5D,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO;QACL,KAAK,EAAE;YACL,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,GAAG,CAAC,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC;YACnE,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;YACvD,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,CAAC;SAC1C;KACF,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CACf,MAA8B,EAC9B,OAAiB;IAEjB,OAAO;QACL,KAAK,EAAE;YACL,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,GAAG,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;YACzE,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,CAAC;SAC1C;KACF,CAAC;AACJ,CAAC;AASD;;;;;;;GAOG;AACH,SAAS,SAAS,CAAC,GAAY;IAC7B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACzD,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,GAA2C,CAAC;IACrE,IAAI,IAAI,KAAK,UAAU,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/D,OAAO,MAAoB,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,UAAU,CAAC,MAAkB;IACpC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,GAAG,CAAC,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;QACpE,GAAG,CAAC,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;KACrE,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAsB,GAAY;IACnD,OAAO,GAAG,YAAY,QAAQ,CAAC;AACjC,CAAC;AAED,MAAM,cAAc,GAAG,CAAC,gBAAgB,CAAC,CAAC;AAE1C;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAqC;IAErC,MAAM,WAAW,GAAsB,IAAI,CAAC,WAAW,IAAI,cAAc,CAAC;IAE1E,OAAO,SAAS,aAAa,CAAC,GAAY;QACxC,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,OAAO;gBACL,MAAM,EAAE,GAAG;gBACX,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;gBACnD,OAAO,EAAE,EAAE;gBACX,IAAI,EAAE,QAAQ;aACf,CAAC;QACJ,CAAC;QAED,IAAI,UAAU,CAAO,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,OAAO,GAA2B,EAAE,CAAC;YAC3C,uFAAuF;YACvF,uFAAuF;YACvF,iFAAiF;YACjF,wEAAwE;YACxE,IAAI,OAAO,GAAG,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;gBAC3C,OAAO,CAAC,aAAa,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;YACtD,CAAC;YACD,0FAA0F;YAC1F,0EAA0E;YAC1E,IAAI,GAAG,CAAC,UAAU,KAAK,GAAG;gBAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,QAAQ,CAAC;YAEnE,IAAI,GAAG,CAAC,UAAU,GAAG,GAAG;gBACtB,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YAEtF,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,IAAI,IAAI,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;YACtF,IAAI,IAAI,EAAE,CAAC;gBACT,oFAAoF;gBACpF,sFAAsF;gBACtF,kFAAkF;gBAClF,mFAAmF;gBACnF,iBAAiB;gBACjB,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC5F,CAAC;YACD,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;YACzD,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QACnE,CAAC;QAED,yFAAyF;QACzF,0FAA0F;QAC1F,+DAA+D;QAC/D,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;IACzF,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@gusnips/server",
+  "version": "0.1.0",
+  "description": "The layer under a TypeScript backend: one error shape, one response envelope, one retry rule, one logger.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Gustavo Salomé",
+  "homepage": "https://github.com/gusnips/serverkit/tree/main/server#readme",
+  "bugs": {
+    "url": "https://github.com/gusnips/serverkit/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./hono": {
+      "types": "./dist/hono/index.d.ts",
+      "default": "./dist/hono/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "backend",
+    "hono",
+    "errors",
+    "logging",
+    "retry",
+    "typescript"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.node.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "purity": "bun run scripts/check-purity.ts",
+    "sync:docs": "cp ../LICENSE .",
+    "prepublishOnly": "bun run lint && bun run typecheck && bun run purity && bun run test && bun run build && bun run sync:docs",
+    "release:patch": "bun pm version patch && bun publish --access public",
+    "release:minor": "bun pm version minor && bun publish --access public",
+    "release:major": "bun pm version major && bun publish --access public"
+  },
+  "peerDependencies": {
+    "@gusnips/http": ">=0.1 <1",
+    "hono": ">=4.9.9 <5"
+  },
+  "peerDependenciesMeta": {
+    "hono": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@gusnips/http": ">=0.1 <1",
+    "@types/node": "^24.12.0",
+    "hono": "^4.10.6",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2",
+    "zod": "^4.3.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gusnips/serverkit.git",
+    "directory": "server"
+  }
+}

package/src/errors.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import { AppError, toMessage } from "./errors.ts";
+
+describe("toMessage", () => {
+  it("reads an Error's message", () => {
+    expect(toMessage(new Error("boom"))).toBe("boom");
+  });
+
+  it("reads a string message off a plain object", () => {
+    expect(toMessage({ code: "23505", message: "duplicate key value" })).toBe(
+      "duplicate key value",
+    );
+  });
+
+  it("returns a string as itself", () => {
+    expect(toMessage("just a string")).toBe("just a string");
+  });
+
+  it("serializes a plain object with no message rather than flattening it", () => {
+    const out = toMessage({ code: "PGRST205", hint: "run the migration" });
+    expect(out).not.toBe("[object Object]");
+    expect(out).toContain("PGRST205");
+    expect(out).toContain("run the migration");
+  });
+
+  it("keeps a messageless object's diagnostic and drops the inputs hung beside it", () => {
+    // The same allow-list the log serializer runs, and for the same reason one step later: this
+    // string becomes an Error's message in `errorBoundary`, and a message is printed. An SDK that
+    // rejects with the request it sent would otherwise put that request into the log through here.
+    const out = toMessage({ code: "PGRST301", payload: '{"card":"4242424242424242"}' });
+
+    expect(out).toContain("PGRST301");
+    expect(out).not.toContain("4242");
+  });
+
+  it("names the keys of an object with nothing printable, rather than printing nothing", () => {
+    // `{}` would be the "[object Object]" failure again in a new spelling: a useless string where
+    // the real failure was. The key names come from the SDK, never from a caller, so they are the
+    // one part of an unprintable object that identifies it.
+    expect(toMessage({ payload: "the whole request body", header: "t=1,v1=deadbeef" })).toBe(
+      "An object was thrown with no message. Its keys: payload, header.",
+    );
+  });
+
+  it("survives a circular object", () => {
+    const cycle: Record<string, unknown> = { code: "E_CYCLE" };
+    cycle.self = cycle;
+    expect(() => toMessage(cycle)).not.toThrow();
+    expect(toMessage(cycle)).toContain("E_CYCLE");
+  });
+
+  it("falls back to String() for a primitive", () => {
+    expect(toMessage(null)).toBe("null");
+    expect(toMessage(42)).toBe("42");
+  });
+});
+
+describe("an AppError is an ordinary Error to anything that serializes it", () => {
+  /**
+   * `JSON.stringify` calls a value's own `toJSON()` BEFORE it calls the replacer, so a class
+   * that defines one never reaches a logger's Error branch at all. Seven backends define
+   * `toJSON()` on this class, so `logger.error("x", { error: appErr })` writes a doubly-nested
+   * envelope with no `stack` and no `cause` — live in all seven, and invisible because the line
+   * still looks like a log line. The wire body is built by `errorResponse`; the error stays an
+   * error.
+   */
+  function serializeLikeALogger(value: unknown): { json: string; sawError: boolean } {
+    let sawError = false;
+    const json = JSON.stringify(value, (_key, val: unknown) => {
+      if (val instanceof Error) {
+        sawError = true;
+        return { name: val.name, message: val.message, stack: val.stack, cause: val.cause };
+      }
+      return val;
+    });
+    return { json, sawError };
+  }
+
+  it("reaches the replacer's Error branch, with its stack and its cause", () => {
+    const cause = new Error("connection refused");
+    const err = new AppError(500, "INTERNAL_ERROR", "the write failed", { cause });
+    const { json, sawError } = serializeLikeALogger({ error: err });
+    expect(sawError).toBe(true);
+    expect(json).toContain("the write failed");
+    expect(json).toContain("connection refused");
+    expect(json).toContain('"stack"');
+  });
+
+  it("defines no toJSON, so nothing can shadow that branch", () => {
+    const err = new AppError(500, "INTERNAL_ERROR", "boom");
+    expect("toJSON" in err).toBe(false);
+  });
+});

package/src/errors.ts

@@ -0,0 +1,264 @@
+/**
+ * The one error a route throws, and the one function that turns any thrown value into words.
+ *
+ * Extracted from six backends whose copies of this file are byte-identical in the parts that
+ * matter: the envelope builder in four of them, `toMessage()` in six. Where they differ, the
+ * version carrying the production reason won — every comment below names a failure somebody
+ * shipped.
+ *
+ * Nothing here knows about the wire. That is deliberate and it is the fix to a live bug; see
+ * the note on {@link AppError}.
+ */
+
+import { narrowErrorLike } from "./logger/serialize.ts";
+
+export interface AppErrorOptions<Key extends string = string> {
+  /** What makes the refusal ACTIONABLE: the plan that lifts a 402, the scope of a quota. */
+  details?: unknown;
+  /**
+   * The stable key a client localizes. Type it against your own closed list of keys, so a
+   * typo'd or stale key is a compile error at the emit site rather than a raw dotted string
+   * in front of a reader. The WIRE type stays `string`, so an older client tolerates a key
+   * from a newer server and degrades to `message`.
+   */
+  messageKey?: Key;
+  /** Interpolation values for `messageKey`. */
+  params?: Record<string, string | number>;
+  /**
+   * How the refusal clears: seconds until the caller may retry, or `null` for a refusal that
+   * waiting cannot fix.
+   *
+   * Set it HERE rather than hand-rolling it into `details`. `errorResponse` renders a number as
+   * the standard `Retry-After` header AND folds it into `details`, so an HTTP client, a proxy
+   * and your own SDK all learn the same wait from one value; `null` is folded in without a
+   * header, because a `Retry-After` that states no time is worse than none.
+   */
+  retryAfterSecs?: number | null;
+  /**
+   * The `message` was authored for the client — a deployment fact like "payments are not set
+   * up here", a named dependency that is down — so a 5xx keeps it instead of the generic
+   * sentence. Never set it on a message built from a caught error: that is where driver text
+   * lives, and one donor's whole masking policy exists because its repository layer
+   * interpolates the driver's message into every failure it raises.
+   */
+  expose?: boolean;
+  cause?: unknown;
+}
+
+/**
+ * The one error type routes throw; {@link errorResponse} formats the envelope.
+ *
+ * `Code` is your product's error-code union and `Key` its message-key union. Neither is
+ * shipped here: across six donors the factory tables hold 46 distinct code names and exactly
+ * nine appear in all six. The codes are an API's vocabulary. What this package ships is the
+ * shape, the wire format and the mask.
+ *
+ * Prefer {@link createAppError} over `new AppError(…)`: it reads the status off your own
+ * code→status map, so no call site names a status and a code added without one is a build
+ * error.
+ *
+ * Constructing one directly is the one path where a 429 with no wait is still representable:
+ * the rule lives on the factory, because only the factory knows the map. That is the reason to
+ * prefer it, not a style note.
+ *
+ * **There is no `toJSON()`, on purpose**, and the reason is not the one first written here.
+ * `JSON.stringify` calls a value's own `toJSON()` BEFORE the replacer, so an error class that
+ * defines one hands a logger whatever that method returns instead of the error. Seven backends
+ * define one, and every one of them logs `{"error":{"error":{code,message}}}` — doubly nested,
+ * no `stack`, no `cause` — from a line that still looks like a log line.
+ *
+ * This file used to say a logger cannot fix that from its side. It can, and ours does: the
+ * replacer is called with the HOLDER as `this`, whose own property is still the untouched error
+ * (see `errorReplacer`). What remains true is the design: the wire body is built by
+ * `errorResponse`, where the mask lives anyway, so one function owns the shape a client sees —
+ * and this stays an ordinary Error to anything that serializes it.
+ */
+export class AppError<Code extends string = string, Key extends string = string> extends Error {
+  public readonly statusCode: number;
+  public readonly code: Code;
+  public readonly details?: unknown;
+  public readonly messageKey?: Key;
+  public readonly params?: Record<string, string | number>;
+  public readonly retryAfterSecs?: number | null;
+  public readonly expose: boolean;
+
+  constructor(statusCode: number, code: Code, message: string, opts: AppErrorOptions<Key> = {}) {
+    super(message, { cause: opts.cause });
+    this.name = "AppError";
+    this.statusCode = statusCode;
+    this.code = code;
+    this.details = opts.details;
+    this.messageKey = opts.messageKey;
+    this.params = opts.params;
+    this.retryAfterSecs = opts.retryAfterSecs;
+    this.expose = opts.expose ?? false;
+  }
+}
+
+/**
+ * A map is widened to `Record<string, number>` unless it is declared `as const`, and a widened
+ * map cannot tell a 429 from a 404 — so the rule below would silently stop applying. Refusing
+ * the map is loud; accepting it with the guard switched off is the failure this package spends
+ * a paragraph on everywhere else.
+ *
+ * It catches the HALF-widened map too, which is the realistic way this happens: one status read
+ * from config turns `404 | number` into `number`, and the whole map loses its literals. The
+ * property name is what the compiler prints, so it is plain ASCII — an arrow there comes out as
+ * `\u2192` in the diagnostic, and the message is the entire point of the trick.
+ */
+type LiteralStatuses<S> = number extends S[keyof S]
+  ? { "declare your code-to-status map as const": never }
+  : S;
+
+/**
+ * Extra options a code's status makes mandatory.
+ *
+ * **A 429 states its own wait.** This is the highest-value line extracted from the whole
+ * reading. One donor writes a `resetAt` ISO date that no HTTP client parses, and then needs a
+ * hand-maintained list of "codes that do not clear by waiting" in its browser app to
+ * compensate — its own comment says so. Another donor needs no such list, because every 429 it
+ * sends states its wait, and a stated wait answers the question the list was guessing at. A
+ * third raises a spent DAILY cap with no wait at all, on a code its client treats as transient,
+ * so the browser retries a limit that clears at midnight — twice, immediately.
+ *
+ * Making it a required argument deletes that list from three repos and makes the retry bug
+ * unrepresentable. Measured against the fleet it came from: of 40 places that raise a 429,
+ * **34 already state a wait**, so the rule costs six edits in six repos.
+ *
+ * It is `[429] extends [Status]`, not `Status extends 429`, because the second form distributes:
+ * a code narrowed to a UNION — off a lookup table, a switch, a value read from the wire —
+ * produced a union of argument tuples, one of which had the options optional, and an empty
+ * argument list satisfied it. The obligation vanished on exactly the shape that is hardest to
+ * read. The tuples stop the distribution, and they ask the better question: does this code's
+ * status set INCLUDE 429. A widened `number` then requires the wait everywhere rather than
+ * nowhere, which is the safe direction to fail.
+ *
+ * Deliberately not extended, and the same counting method is what settled each one. Three
+ * statuses, one method, three different answers — which is the strongest thing that can be said
+ * for the method:
+ *
+ * - **429 — obligation.** 34 of 40 raises already state a wait, so the required argument mostly
+ *   records a decision somebody had already made, and each of the six exceptions is
+ *   interesting.
+ * - **503 — capability, not obligation.** Only 16 of 94 raises of a 502/503/504 factory state
+ *   one. Most are "the database is unreachable" or "payments are not configured here", which
+ *   have no wait to state, so a rule would buy 78 `null`s and teach people to type one without
+ *   reading — and a client cannot tell a considered `null` from a reflex one. The raiser who
+ *   knows is rare, and that is exactly the shape where a capability beats an obligation.
+ * - **402 — nothing to add.** Of 13 raises across five repos, **none** states a wait. That is
+ *   what was measured, and it is all that was: it says no raiser in these repos claims a 402
+ *   clears by waiting, not that none ever could. A card retry window or a transfer clearing
+ *   overnight would be a real one — and it can say so, because the wait is available at every
+ *   status. The day one turns up it is a finding rather than a contradiction.
+ *
+ * So the capability is on every code: a number renders `Retry-After` at any status, and an
+ * explicit `null` says "durable". The residual gap it closes is narrower than "503s need
+ * waits" — it is ONE code raised in two senses, durable and transient, indistinguishable in the
+ * envelope. The raiser that answers closes it for its own code, and nobody else is nagged.
+ *
+ * `null` is the other half, and the six are what proved it necessary. Two of them cannot state
+ * a wait truthfully: a concurrency slot frees when somebody else's job finishes, and a cap on
+ * live objects clears by archiving one, never by waiting at all. A required `number` would have
+ * forced both to invent a number. `null` says "waiting cannot fix this" — which is the very
+ * question the code lists were guessing at, answered by the one place that knows: the raiser.
+ * An omission is invisible in a diff; a `null` is a claim somebody has to read.
+ */
+type RequiredOptions<Status, Key extends string> = [429] extends [Status]
+  ? [opts: AppErrorOptions<Key> & { retryAfterSecs: number | null }]
+  : [opts?: AppErrorOptions<Key>];
+
+/**
+ * Binds your code→status map, and returns the factory your `errors.*` table calls.
+ *
+ * ```ts
+ * const ERROR_STATUS = {
+ *   NOT_FOUND: 404,
+ *   RATE_LIMIT_EXCEEDED: 429,
+ * } as const satisfies Record<ErrorCode, number>;
+ *
+ * const appError = createAppError<typeof ERROR_STATUS, MessageKey>(ERROR_STATUS);
+ *
+ * export const errors = {
+ *   notFound: (what = "Resource") => appError("NOT_FOUND", `${what} not found`),
+ *   rateLimit: (retryAfterSecs: number) =>
+ *     appError("RATE_LIMIT_EXCEEDED", "Too many requests", { retryAfterSecs }),
+ * };
+ * ```
+ *
+ * The `satisfies` on your map is what makes a code with no status a build error — one line,
+ * in your repo, and the only version of this that cannot drift. Three of the five newest
+ * donors pass the status at every call site instead, which compiles no matter what.
+ */
+export function createAppError<S extends Record<string, number>, Key extends string = string>(
+  statusOf: S & LiteralStatuses<S>,
+): <C extends keyof S & string>(
+  code: C,
+  message: string,
+  ...opts: RequiredOptions<S[C], Key>
+) => AppError<C, Key> {
+  return (code, message, ...opts) =>
+    // A code with no status is a build error at your `satisfies`. One reaching here anyway —
+    // a map assembled at runtime, a code narrowed off the wire — is our bug, not the caller's.
+    new AppError(statusOf[code] ?? 500, code, message, opts[0]);
+}
+
+/**
+ * `JSON.stringify` that never throws and never answers `"[object Object]"`.
+ *
+ * Private on purpose: it exists for {@link toMessage}'s last branch. A logger wants a richer
+ * one (an allow-list over an error's own fields), which is a different function.
+ */
+function safeStringify(value: unknown): string {
+  const seen = new WeakSet<object>();
+  try {
+    return (
+      JSON.stringify(value, (_key, val: unknown) => {
+        if (val instanceof Error) return { name: val.name, message: val.message };
+        if (typeof val === "bigint") return val.toString();
+        if (typeof val === "object" && val !== null) {
+          if (seen.has(val)) return "[Circular]";
+          seen.add(val);
+        }
+        return val;
+      }) ?? "null"
+    );
+  } catch {
+    return "[unserializable]";
+  }
+}
+
+/**
+ * Turn any thrown value into a string.
+ *
+ * The single home for the `err instanceof Error ? err.message : String(err)` idiom, which is
+ * wrong twice over and shipped that way in six repos:
+ *
+ * 1. A data layer rejects with a PLAIN OBJECT — `{code, message, hint}` is what PostgREST and
+ *    several drivers throw — so the useful text is in `message` and `String()` never reads it.
+ *    Six donors fixed this half.
+ * 2. An object with no string `message` still flattens to `"[object Object]"`, which is the
+ *    real failure masked by a useless string. One donor fixed that half and named it exactly:
+ *    *"masking the real failure."* Its version is the one here.
+ */
+export function toMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  if (typeof err === "object" && err !== null) {
+    const { message } = err as { message?: unknown };
+    if (typeof message === "string") return message;
+    // With no message to read, the object itself has to say what failed — and it cannot be
+    // printed whole. This string becomes an Error's `message` in `errorBoundary`, and a message
+    // is printed, so an SDK that rejects with the request it sent would put that request in the
+    // log through here. Same allow-list as the log serializer, one step earlier.
+    const kept = narrowErrorLike(err);
+    if (Object.keys(kept).length > 0) return safeStringify(kept);
+    // Nothing printable left. `{}` would be the "[object Object]" failure again in a new
+    // spelling: a useless string standing where the real failure was. The key names come from
+    // whoever threw, never from a caller, so they are the part that still identifies it.
+    const keys = Object.keys(err);
+    return keys.length > 0
+      ? `An object was thrown with no message. Its keys: ${keys.join(", ")}.`
+      : "An object was thrown with no message and no fields.";
+  }
+  return String(err);
+}

package/src/errors.types.test.ts

@@ -0,0 +1,96 @@
+/**
+ * Type-level guards. Most of this file never runs: `@ts-expect-error` fails
+ * `bun run typecheck` if the line under it ever starts compiling, which is the only way to
+ * pin a rule whose whole value is that a call site cannot be written.
+ *
+ * Every guarded statement is kept SHORT on purpose. `@ts-expect-error` binds to the next
+ * physical line, and the formatter decides where that is — wrap the call and the directive
+ * lands on `expect(() =>` , which has no error, while the real one moves out of its reach.
+ */
+import { describe, expect, it } from "vitest";
+import { type AppErrorOptions, createAppError } from "./errors.ts";
+
+const ERROR_STATUS = {
+  NOT_FOUND: 404,
+  RATE_LIMIT_EXCEEDED: 429,
+  QUOTA_EXCEEDED: 429,
+  INTERNAL_ERROR: 500,
+} as const satisfies Record<string, number>;
+
+type MessageKey = "serverErrors.notFound" | "serverErrors.rateLimit";
+
+const appError = createAppError<typeof ERROR_STATUS, MessageKey>(ERROR_STATUS);
+const spent = { details: { scope: "month" } };
+
+// Annotated, not inferred: a code narrowed off a lookup table or a switch has a UNION type,
+// which is the shape the rule used to lose.
+const mixedCode: "NOT_FOUND" | "RATE_LIMIT_EXCEEDED" = "RATE_LIMIT_EXCEEDED";
+const safeCodes: "NOT_FOUND" | "INTERNAL_ERROR" = "NOT_FOUND";
+const fromConfig: number = 429;
+
+describe("a 429 states its own wait", () => {
+  it("reads the status off the map, and keeps the wait", () => {
+    const err = appError("RATE_LIMIT_EXCEEDED", "Too many requests", { retryAfterSecs: 30 });
+    expect(err.statusCode).toBe(429);
+    expect(err.retryAfterSecs).toBe(30);
+    // The two honest answers, and only these two: a number, or a deliberate `null`.
+    const durable = appError("QUOTA_EXCEEDED", "Wait for a job to finish", {
+      retryAfterSecs: null,
+    });
+    expect(durable.retryAfterSecs).toBeNull();
+    // A union whose status set includes 429 owes the wait too, and one that cannot be a 429
+    // does not. Both directions, because only the pair proves the tuple wrappers.
+    expect(appError(mixedCode, "slow", { retryAfterSecs: 5 }).message).toBe("slow");
+    expect(appError(safeCodes, "gone").message).toBe("gone");
+    // Any status may state a wait voluntarily — a 503 that knows its own expiry, say. Only the
+    // OBLIGATION is 429-only.
+    const configured = appError("INTERNAL_ERROR", "Not configured here", { retryAfterSecs: null });
+    expect(configured.retryAfterSecs).toBeNull();
+    expect(appError("NOT_FOUND", "Workspace not found").statusCode).toBe(404);
+    expect(appError("INTERNAL_ERROR", "boom").statusCode).toBe(500);
+  });
+});
+
+/** Never called. Every line here is an assertion about what does not compile. */
+function refusals(): void {
+  // @ts-expect-error — RATE_LIMIT_EXCEEDED maps to 429, so it has to say how it clears:
+  // a number of seconds, or `null` for a refusal waiting cannot fix.
+  appError("RATE_LIMIT_EXCEEDED", "Too many requests");
+  // @ts-expect-error — options are there, the wait is not.
+  appError("QUOTA_EXCEEDED", "Spent", spent);
+  // @ts-expect-error — "TEAPOT" is not in the map.
+  appError("TEAPOT", "no");
+  // @ts-expect-error — "serverErrors.typo" is not a MessageKey.
+  appError("NOT_FOUND", "no", { messageKey: "serverErrors.typo" });
+
+  // The three ways a forgotten argument could have passed for a deliberate `null`. The second
+  // is the one that matters: it is verbatim how three donors write their own `rateLimit`
+  // factory, so it is the shape a migration reaches for first.
+  // @ts-expect-error — an explicit `undefined` is not an answer.
+  appError("RATE_LIMIT_EXCEEDED", "x", { retryAfterSecs: undefined });
+  const forward = (message: string, opts?: AppErrorOptions<MessageKey>) =>
+    // @ts-expect-error — forwarding a caller's optional opts cannot satisfy it either.
+    appError("RATE_LIMIT_EXCEEDED", message, { ...opts });
+  void forward;
+  const partial: { retryAfterSecs?: number } = {};
+  // @ts-expect-error — nor can spreading an object whose wait is optional.
+  appError("RATE_LIMIT_EXCEEDED", "x", { ...partial });
+
+  // A code narrowed to a UNION used to drop the obligation: the conditional distributed, one
+  // arm had the options optional, and an empty argument list satisfied it. That is the shape a
+  // code read off a lookup table or a switch actually has — the hardest one to eyeball.
+  // @ts-expect-error — the union's status set includes 429, so the wait is still owed.
+  appError(mixedCode, "slow");
+
+  const widened: Record<string, number> = { RATE_LIMIT_EXCEEDED: 429 };
+  // @ts-expect-error — without `as const` every value is `number`, so the rule above would
+  // compile away silently. Refusing the map is the loud version.
+  createAppError(widened);
+
+  // The realistic way a map widens: ONE status read from config. `404 | number` absorbs to
+  // `number`, and the whole map loses its literals.
+  const half = { NOT_FOUND: 404, RATE_LIMIT_EXCEEDED: fromConfig } as const;
+  // @ts-expect-error — half-widened is widened.
+  createAppError<typeof half>(half);
+}
+void refusals;