@gusnips/server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Salomé
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,323 @@
+# @gusnips/server
+
+One error shape, one response envelope, and one function that turns a thrown thing into an HTTP
+answer. No framework at the root: it runs in a Cloudflare Worker, in a Bun or Node server, in a
+queue consumer, and in an MCP tool handler.
+
+```bash
+bun add @gusnips/server @gusnips/http
+```
+
+`@gusnips/http` is a required peer: it declares the envelope, and your API and your browser
+client both import it, so there is one declaration of the wire contract and not two.
+
+```ts
+import { ok } from "@gusnips/server";
+
+ok({ id: 1 });
+// → { status: 200, body: { data: { id: 1 } } }
+```
+
+Every 2xx body is `{ data }`. Every refusal is `{ error: { code, message, messageKey?, params?,
+details? } }`. That is the envelope `@gusnips/http` declares and a browser client parses, so the
+two ends of one request never disagree about the shape.
+
+**Import `ApiError`, `ApiSuccess` and `PaginationMeta` from `@gusnips/http`, not from here.**
+This package does not re-export them, on purpose: two names for one type is how a version skew
+becomes invisible. You already have the import — the contract is the package your client reads
+it from too.
+
+## Answering a request
+
+`ok`, `created`, `paginated` and `noContent` return a plain `{ status, body }`. Hand it to
+whatever is holding the connection.
+
+```ts
+import { paginated } from "@gusnips/server";
+
+paginated(rows, { total: 128, limit: 20, offset: 100 });
+// → { status: 200, body: { data: rows, meta: { total: 128, limit: 20, offset: 100, hasMore: true } } }
+```
+
+`hasMore` is computed from the rows you actually returned, not from `limit`, so a page cut short
+by a filter still answers honestly.
+
+## Refusing a request
+
+Declare your own codes and what status each one answers with. The `satisfies` is the line that
+matters: adding a code without a status becomes a build error instead of a route answering 500
+for a refusal it knew how to explain.
+
+```ts
+import { createAppError } from "@gusnips/server";
+
+export const ERROR_STATUS = {
+  VALIDATION_ERROR: 400,
+  UNAUTHORIZED: 401,
+  NOT_FOUND: 404,
+  RATE_LIMIT_EXCEEDED: 429,
+  INTERNAL_ERROR: 500,
+} 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 }),
+};
+```
+
+Then throw one, anywhere:
+
+```ts
+throw errors.notFound("Workspace");
+```
+
+`AppError` has no `toJSON()`. `JSON.stringify` calls a value's own `toJSON()` **before** it calls
+the replacer, so a class that defines one hands a logger whatever that method returns instead of
+the error: `logger.error("failed", { error: err })` writes `{"error":{"error":{code,message}}}`
+with no stack and no cause. Seven backends on this stack define one and all seven log exactly
+that.
+
+`createLogger` recovers the error anyway — the replacer reads it back off the holder — so your
+own classes are safe either way. `AppError` still does not define one, because the wire body
+belongs to `errorResponse`, where the mask lives: one function owns the shape a client sees, and
+the error stays an error.
+
+The map has to be `as const`, or every value reads as `number` and the rule below cannot see a 429. A map without it is refused, with the instruction in the compiler's message.
+
+### A 429 says how it clears
+
+`RATE_LIMIT_EXCEEDED` maps to 429, so `retryAfterSecs` is a **required argument**: the seconds
+until the caller may retry, or `null` for a refusal that waiting cannot fix. Leave it out and
+the code does not compile.
+
+```ts
+rateLimit: (retryAfterSecs: number) =>
+  appError("RATE_LIMIT_EXCEEDED", "Too many requests", { retryAfterSecs }),
+
+concurrency: (limit: number) =>
+  // A slot frees when somebody else's job finishes. There is no wait to state.
+  appError("QUOTA_EXCEEDED", `${limit} jobs already running`, { retryAfterSecs: null }),
+```
+
+This is the rule with the best bug-per-line ratio in the whole extraction. One backend writes a
+`resetAt` ISO date that no HTTP client parses, and then keeps a hand-written list of "codes that
+do not clear by waiting" in its browser app to compensate — its own comment says that is why the
+list exists. Another backend needs no list, because every 429 it sends states its wait. A third
+raises a spent daily cap with no wait at all, on a code its client reads as transient, so the
+browser retries a limit that clears at midnight — twice, immediately, and says the same thing
+three times to a limiter that is already counting.
+
+Asking each refusal how it clears answers the question those lists were guessing at, and it
+answers it in the one place that knows: where the refusal is raised. A code cannot know — the
+same `QUOTA_EXCEEDED` can be a month that clears in days or a slot that clears in two seconds.
+
+Of 40 places that raise a 429 in the fleet this came from, 34 already state a wait. Of the six
+left, two genuinely cannot: a concurrency slot frees when another job finishes, and a cap on
+live objects clears by archiving one, never by waiting. `null` is for those. An omission is
+invisible in a diff; a `null` is a claim somebody has to read.
+
+`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. A
+`null` is folded in without a header, because a `Retry-After` that names no time is worse than
+none.
+
+Two edges worth knowing:
+
+- The obligation follows the code's whole status set. A code narrowed to a union that _could_ be
+  the 429 owes the wait too — `appError(code, msg)` where `code` is
+  `"NOT_FOUND" | "RATE_LIMIT_EXCEEDED"` does not compile without one.
+- **Only the obligation is 429-only.** Any code may state a wait, and a number renders
+  `Retry-After` at any status. Reach for it when ONE of your codes is raised in two senses —
+  one that clears on its own and one that does not. A `SERVICE_UNAVAILABLE` meaning "not
+  configured on this deployment" and one meaning "did not answer just now" are the same code and
+  the same status, so a client cannot separate them; the raiser can, with a number or an
+  explicit `null`.
+
+`new AppError(429, …)` skips the rule, because the rule lives on the factory: only the factory
+knows your map. That is the reason to prefer `createAppError`.
+
+## Turning a throw into an answer
+
+```ts
+import { createErrorResponse } from "@gusnips/server";
+
+export const errorResponse = createErrorResponse<ErrorCode, MessageKey>({
+  internal: { code: "INTERNAL_ERROR", message: "Something on our side failed" },
+  validation: { code: "VALIDATION_ERROR", message: "The request could not be read" },
+});
+
+errorResponse(err);
+// → { status, body, headers, kind }
+```
+
+Every throw lands in one of four arms:
+
+| What was thrown              | Answer                                       | `kind`       |
+| ---------------------------- | -------------------------------------------- | ------------ |
+| a validation failure         | 400, with the field path and the failed rule | `client`     |
+| an `AppError` under 500      | itself                                       | `client`     |
+| an `AppError` of 500 or more | itself, or the masked body                   | `server`     |
+| anything else                | a generic 500                                | `unexpected` |
+
+`kind` is the one thing you cannot read off the status. A 500 you raised and a `TypeError` that
+escaped are both 500s, and only the second one means nobody is watching a log for it — which is
+the branch where an alert belongs.
+
+Bind it once, at the edge of your app, and import that one function everywhere else. A tool
+handler and a worker's health port then cannot disagree with the API about what a refusal looks
+like. They did, in the fleet this came from: a worker's health route answered a caught Redis
+message on a 503 while the API next door masked exactly that.
+
+### What reaches the client, and what does not
+
+**A validation failure ships the field path, the failed rule, and — for a range — the bound it
+failed against. Nothing else.** Handing your validator's issues straight through ships back the
+caller's own key names, the enum's allowed values, the validator's English sentence and the
+expected type. The bound is the exception and it belongs to the caller: it is your published
+contract, and a "too big" without it costs somebody a bisect to rediscover a number your docs
+already state.
+
+Validation is recognized by shape, not by an import, so your validator does not become this
+package's dependency. Measured against zod 3.25, 4.4 and 4.5.
+
+**A 5xx keeps its message unless its code is masked.** By default only `INTERNAL_ERROR` is,
+because that is the code you raise when something unexpected broke, so its message may carry
+internals. The others were written for the client, and flattening a `GATEWAY_ERROR` into a
+generic 500 takes away the one thing that tells a developer whether to retry.
+
+> That default is safe because of your call sites, not because of this code. It holds only while
+> every unmasked 5xx is handed a message somebody wrote for a reader. If your data layer
+> interpolates the driver's error into what it raises, use `maskAll` and let `expose` opt the
+> authored sentences back in.
+
+`maskDetails` is a separate knob, because it is a separate decision. Some backends put a
+readiness report in a 503's `details` — which dependency is down, for the deploy gate and for a
+human at 3am — and need it on the wire. Others record caught error text there, and must never
+send it. Both are right about their own repo.
+
+**When a message is masked, the status is not.** A status comes from your own map and discloses
+nothing, and it is the last thing telling a client whether waiting can help.
+
+**An unexpected throw never reaches the client.** Log it with its `cause` and its stack; answer
+the generic 500.
+
+## Logging a failure
+
+`createLogger` writes one JSON line per event to stdout, and nothing else. Twelve backends were
+read for this and not one installs a logging library, so this ships no transports, no file
+rotation and no extra levels — every one of them runs under something that already owns stdout.
+
+```ts
+import { createLogger } from "@gusnips/server";
+
+const logger = createLogger({ level: process.env.LOG_LEVEL });
+
+logger.error("charge failed", { orderId, error: err }); // the RAW error, never String(err)
+```
+
+**Pass the error itself.** `message` and `stack` are non-enumerable, so a plain
+`JSON.stringify(err)` is `{}` — which is how a logger ends up printing nothing about the failure
+it was called to report. The serializer adds them, follows the `cause` chain and an
+`AggregateError`'s `errors`, and collapses a circular reference instead of crashing the log call.
+
+**What it keeps off an error is an allow-list**, and that is the one thing here that exists
+because of an incident rather than because of duplication. An SDK hangs its own INPUTS off the
+error it throws: a payment vendor's signature-verification error carries the unparsed webhook
+body and the signature, a Redis client puts the AUTH password in `command.args`, and a Postgres
+`DatabaseError` carries statement text with its literals in it. A loop over own properties copies
+all of that, and a webhook route is unauthenticated by definition — so anyone on the internet
+could choose what went into the log. The list admits 4 of that payment error's 25 properties, and
+it covers the `cause` chain, including a link that is not an `Error`.
+
+`level` is an argument rather than a `process.env` read, and that is the boundary the package is
+built on: a Cloudflare Worker has no `process` at all, so a module-scope read makes a package
+Node-only by accident. A Worker passes `env.LOG_LEVEL` from its handler argument. An unrecognized
+level throws at construction, because a box running at the wrong level is discovered during the
+incident it was meant to explain.
+
+## Hono
+
+`@gusnips/server/hono` is the only part that knows a framework, which is why it is a subpath:
+`hono` is an optional peer and nothing in the root entry imports it. Needs `hono >= 4.9.9` —
+before that, `routePath(c, -1)` silently ignores the `-1` and the request line names the wrong
+route.
+
+```ts
+import { errorBoundary, errorHandler, notFoundHandler, requestLogger } from "@gusnips/server/hono";
+
+app.use(requestLogger({ logger })); // first, so it times and sees everything under it
+app.use(errorBoundary); // right after
+app.onError(errorHandler({ errorResponse, logger }));
+app.notFound(notFoundHandler(errorResponse(errors.notFound("Route"))));
+```
+
+**`errorBoundary` is not optional.** Hono hands `onError` only what is `instanceof Error`.
+Anything else is rethrown past every layer and escapes as an unhandled rejection: no answer, a
+dropped connection, and a browser that reports it as a CORS failure — which sends whoever reads
+it to the wrong layer entirely. A PostgREST client rejects with plain objects, so this is not
+hypothetical. The boundary wraps one in an `Error` and keeps the original as `cause`.
+
+**The request line names the route TEMPLATE, never the path.** A path is what puts a customer's
+document number in a log and in whatever reads that log afterwards. `/health` is skipped with
+everything under it, because every deploy polls it in a loop; a throw is logged anyway.
+
+The request id goes back on `X-Request-ID`, on every answer including `onError`'s and
+`notFound`'s. A caller's own id is echoed only if it is 64 characters of `A-Z a-z 0-9 . _ -`,
+so the id in a line is always either the caller's or ours. Cross-origin, list that header in your
+CORS `exposeHeaders` or the browser hides it from the page.
+
+### The guard check
+
+```ts
+import { assertEveryRouteGuarded, guard, underAny } from "@gusnips/server/hono";
+
+export const requireUser = guard(async (c, next) => { … });   // mark it where it is defined
+
+// in a test
+assertEveryRouteGuarded(buildApp(), { isPublic: underAny(PUBLIC_PREFIXES) });
+```
+
+It walks every registered route through Hono's **own matcher** and fails naming each endpoint no
+guard runs in front of. The matcher is the point: a `use` registered AFTER its `route` never runs
+— the handler answers and the guard silently does not fire. A route whose guard did not fire is
+indistinguishable from one with no guard, and comparing pattern lists cannot tell you which you
+have.
+
+Pass the app's own public rule, never a second list kept for the test — an exemption list nothing
+else reads is the next thing to drift. It also fails a guard that runs in front of nothing, and
+an app with no endpoints, so the check cannot pass by asking nothing.
+
+## What this package does not ship
+
+Each of these was measured, not assumed.
+
+- **Your error codes.** Six backends' factory tables hold 46 distinct names and exactly nine
+  appear in all six. The codes are an API's vocabulary. This package ships the shape, the wire
+  format and the mask; the names stay with the product that speaks them.
+- **The code→status map, and a list of HTTP statuses.** Both are one object literal in your repo,
+  and writing them there is what makes `satisfies` catch a code you forgot. A helper wrapping
+  them would add a call and subtract nothing.
+- **A `messageKey` catalog.** The server owns the condition and the `params`; the client owns the
+  prose.
+- **A logging library, a transport, or an alerting client.** The measured gap between 60 lines
+  of `console.log(JSON.stringify(...))` and a real logging library is the error serializer, and
+  the standard one ships the same copy-loop this package exists to remove — so `createLogger` is
+  those 60 lines with the serializer fixed, and nothing else. `errorResponse` returns `kind` and
+  `errorHandler` takes `onUnexpected`, so alerting is yours to route.
+- **A styled error page.**
+
+## Rules it will not let you break
+
+- A 429 raised with no wait does not compile.
+- A code→status map that is not `as const` is refused.
+- A code outside your map, or a message key outside your union, does not compile.
+
+## Develop
+
+```bash
+bun install
+cd server && bun run test
+```

package/dist/errors.d.ts

@@ -0,0 +1,190 @@
+/**
+ * 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}.
+ */
+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 declare class AppError<Code extends string = string, Key extends string = string> extends Error {
+    readonly statusCode: number;
+    readonly code: Code;
+    readonly details?: unknown;
+    readonly messageKey?: Key;
+    readonly params?: Record<string, string | number>;
+    readonly retryAfterSecs?: number | null;
+    readonly expose: boolean;
+    constructor(statusCode: number, code: Code, message: string, opts?: AppErrorOptions<Key>);
+}
+/**
+ * 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 declare 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>;
+/**
+ * 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 declare function toMessage(err: unknown): string;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,WAAW,eAAe,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM;IAC1D,0FAA0F;IAC1F,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,GAAG,CAAC;IACjB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IACzC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,QAAQ,CAAC,IAAI,SAAS,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,KAAK;IAC5F,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,IAAI,EAAE,IAAI,CAAC;IAC3B,SAAgB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClC,SAAgB,UAAU,CAAC,EAAE,GAAG,CAAC;IACjC,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IACzD,SAAgB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,SAAgB,MAAM,EAAE,OAAO,CAAC;gBAEpB,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,eAAe,CAAC,GAAG,CAAM;CAW7F;AAED;;;;;;;;;;GAUG;AACH,KAAK,eAAe,CAAC,CAAC,IAAI,MAAM,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,GAC/C;IAAE,0CAA0C,EAAE,KAAK,CAAA;CAAE,GACrD,CAAC,CAAC;AAEN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,KAAK,eAAe,CAAC,MAAM,EAAE,GAAG,SAAS,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,GACrE,CAAC,IAAI,EAAE,eAAe,CAAC,GAAG,CAAC,GAAG;IAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,GAChE,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,SAAS,MAAM,GAAG,MAAM,EAC1F,QAAQ,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,GAC/B,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAC5B,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,MAAM,EACf,GAAG,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,KAChC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAKpB;AA2BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAqB9C"}