@zeroxsolutions/response 0.12.0

package/CHANGELOG.md

@@ -0,0 +1,330 @@
+## 0.12.0 (2026-09-13)
+
+### 💅 Refactors
+
+- ⚠️  **response:** list the names the package root publishes ([7b8a95d](https://github.com/zeroxsolutions/zeroxsolutions/commit/7b8a95d))
+- ⚠️  **response:** answer mapped errors with links and meta ([b78bc08](https://github.com/zeroxsolutions/zeroxsolutions/commit/b78bc08))
+- ⚠️  **response:** render every member of a JSON:API error object ([ca0c551](https://github.com/zeroxsolutions/zeroxsolutions/commit/ca0c551))
+
+### ⚠️  Breaking Changes
+
+- **response:** list the names the package root publishes  ([7b8a95d](https://github.com/zeroxsolutions/zeroxsolutions/commit/7b8a95d))
+  the root no longer exports `createSerializer`,
+  `serializeResource`, `serializeCollection`, `reachableResources`,
+  `resourceObjectSchema`, `resourceDocumentSchema`,
+  `collectionDocumentSchema`, `relationshipSchema`, `relationshipsSchema`,
+  `linkSchema`, `metaSchema`, `resourceLinksSchema`, `paginationLinksSchema`,
+  `resourceIdentifierSchema`, `jsonApiObjectSchema`, `errorSourceSchema` or
+  `errorObjectSchema`. Their inferred types stay listed. A resource's own
+  `document`, `collectionDocument`, `serialize` and `serializeMany` declare
+  and render its documents; the schema consts have no public replacement.
+- **response:** answer mapped errors with links and meta  ([b78bc08](https://github.com/zeroxsolutions/zeroxsolutions/commit/b78bc08))
+  `ErrorMeta` is `DomainErrorAnswer`, whose `code` is
+  required. `defineErrorMap` takes `DomainErrorEntry` objects, which
+  `errorEntry(type, answer)` builds, in place of `[type, meta]` tuples.
+  `ErrorMap<TMeta>` is `DomainErrorMap`, and `UpstreamErrorMap` takes no
+  type argument. `UpstreamErrorMeta` is `UpstreamErrorAnswer`, and
+  `toUpstreamError(map, document, fallback)` is
+  `createUpstreamErrorTranslator(map, fallback)(document)`.
+- **response:** render every member of a JSON:API error object  ([ca0c551](https://github.com/zeroxsolutions/zeroxsolutions/commit/ca0c551))
+  `buildErrorDocument` is `toErrorDocument`, and the
+  document it renders carries `jsonapi: { version: '1.1' }`.
+  `ErrorCodeMeta` is `ErrorStatus`; `ErrorRegistry` and `ErrorLike` are
+  removed. An error object's `links.about` and `links.type` are link values
+  rather than strings. A `JsonApiError` whose `detail` equals its `title`
+  now renders that `detail`.
+
+### ❤️ Thank You
+
+- Claude Sonnet 5
+- Lương Văn Tú
+
+## 0.11.4 (2026-09-13)
+
+This was a version bump only for @zeroxsolutions/response to align it with other projects, there were no code changes.
+
+## 0.11.3 (2026-09-13)
+
+### 🚀 Features
+
+- **response:** publish relationship names in the declared fieldsets ([211ab15](https://github.com/zeroxsolutions/zeroxsolutions/commit/211ab15))
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
+## 0.11.2 (2026-09-13)
+
+### 🩹 Fixes
+
+- **response:** key a resource's kept serializers by the shape asked for, and bound them ([f746e8d](https://github.com/zeroxsolutions/zeroxsolutions/commit/f746e8d))
+- **response,repo:** stop shipping the outputs a rename left in dist ([e64aa02](https://github.com/zeroxsolutions/zeroxsolutions/commit/e64aa02))
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
+## 0.11.1 (2026-09-07)
+
+Repackaged only, no source change: the previous tarball still carried the pre-flatten `dist/http/`, `dist/jsonapi/` and `dist/lib/shared/` tree, which `tsc --build` leaves behind when a source file is renamed away. 138 entries down to 57.
+
+## 0.11.0 (2026-09-07)
+
+### 🚀 Features
+
+- ⚠️  **server,jsonapi:** one surface, one error-code vocabulary ([32b4aed](https://github.com/zeroxsolutions/zeroxsolutions/commit/32b4aed))
+
+### 💅 Refactors
+
+- ⚠️  **query,response:** drop the seams the second spelling paid for ([40f1bca](https://github.com/zeroxsolutions/zeroxsolutions/commit/40f1bca))
+
+### ⚠️  Breaking Changes
+
+- **server,jsonapi:** one surface, one error-code vocabulary  ([32b4aed](https://github.com/zeroxsolutions/zeroxsolutions/commit/32b4aed))
+  createErrorHandler, createValidationHook and
+  jsonApiContentNegotiation take a required `namespace`; negotiateJsonApi takes it
+  as a third argument. Codes these mint are now `<namespace>.<name>`.
+- **query,response:** drop the seams the second spelling paid for  ([40f1bca](https://github.com/zeroxsolutions/zeroxsolutions/commit/40f1bca))
+  @zeroxsolutions/query no longer exports CollectionQueryParser,
+  CollectionQueryRenderer, collectionLinksWith, collectionQueryParser, parseSort,
+  parseFields, parseInclude or parsePagination. collectionLinks and
+  parseCollectionQuery / parseResourceQuery replace them. No in-house repo
+  imported any of the eight, but the caret range would otherwise carry the
+  removal into one as a patch.
+
+### ❤️ Thank You
+
+- Lương Văn Tú
+
+## 0.10.0 (2026-09-07)
+
+### 💅 Refactors
+
+- ⚠️  **query,response,server:** one wire spelling, flat exports ([5c57b3a](https://github.com/zeroxsolutions/zeroxsolutions/commit/5c57b3a))
+
+### ⚠️  Breaking Changes
+
+- **query,response,server:** one wire spelling, flat exports  ([5c57b3a](https://github.com/zeroxsolutions/zeroxsolutions/commit/5c57b3a))
+  `@zeroxsolutions/response/http`, `@zeroxsolutions/query/http`
+  and `@zeroxsolutions/server/hono/http` are gone, and the surviving `/jsonapi`
+  and `/hono` subpaths move to the package root. Every import drops its subpath.
+
+### ❤️ Thank You
+
+- Lương Văn Tú
+
+## 0.9.0 (2026-09-07)
+
+### 💅 Refactors
+
+- ⚠️  **response:** key the upstream map by string, drop its builder ([d5c5e6b](https://github.com/zeroxsolutions/zeroxsolutions/commit/d5c5e6b))
+
+### ⚠️  Breaking Changes
+
+- **response:** key the upstream map by string, drop its builder  ([d5c5e6b](https://github.com/zeroxsolutions/zeroxsolutions/commit/d5c5e6b))
+  defineUpstreamErrorMap is gone from both spellings. Declare the
+  map as an object literal with `satisfies UpstreamErrorMap<UpstreamErrorMeta>`;
+  toUpstreamError takes it unchanged.
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
+## 0.8.0 (2026-09-07)
+
+### 💅 Refactors
+
+- ⚠️  **response:** move the Hono handlers out, translate upstream errors ([ce60636](https://github.com/zeroxsolutions/zeroxsolutions/commit/ce60636))
+
+### ⚠️  Breaking Changes
+
+- **response:** move the Hono handlers out, translate upstream errors  ([ce60636](https://github.com/zeroxsolutions/zeroxsolutions/commit/ce60636))
+  the ./http/server and ./jsonapi/server subpaths are gone -
+  createErrorHandler and createValidationHook are @zeroxsolutions/server/http
+  and @zeroxsolutions/server. Both remaining subpaths resolve to
+  dist/<entry> rather than dist/lib/<entry>, so a consumer reaching past the
+  exports map into dist/ breaks.
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
+## 0.7.3 (2026-09-03)
+
+### 🚀 Features
+
+- **response:** let an error map name the request slot it blames ([27cc0c6](https://github.com/zeroxsolutions/zeroxsolutions/commit/27cc0c6))
+
+### ❤️ Thank You
+
+- Lương Văn Tú
+
+## 0.7.2 (2026-09-03)
+
+### 🚀 Features
+
+- **response:** bring the link value up to the version its documents claim ([b8e3a25](https://github.com/zeroxsolutions/zeroxsolutions/commit/b8e3a25))
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
+## 0.7.1 (2026-09-03)
+
+### 🚀 Features
+
+- **response:** read a resource declaration back as a document permit-list ([2b6763a](https://github.com/zeroxsolutions/zeroxsolutions/commit/2b6763a))
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
+## 0.7.0 (2026-09-02)
+
+### 🚀 Features
+
+- ⚠️  **response:** type /jsonapi's documents off the resource's attributes ([1dcf923](https://github.com/zeroxsolutions/zeroxsolutions/commit/1dcf923))
+
+### ⚠️  Breaking Changes
+
+- **response:** type /jsonapi's documents off the resource's attributes  ([1dcf923](https://github.com/zeroxsolutions/zeroxsolutions/commit/1dcf923))
+  `serialize` returns `ResourceDocument<A>` and `serializeMany`
+  `CollectionDocument<A>` instead of `Row`, and `okResponse`/`listResponse` are
+  generic in the resource's attribute schema.
+
+### ❤️ Thank You
+
+- Lương Văn Tú
+
+## 0.6.1 (2026-09-02)
+
+### 🩹 Fixes
+
+- **response:** export the response object /jsonapi's three helpers return ([f45fd15](https://github.com/zeroxsolutions/zeroxsolutions/commit/f45fd15))
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
+## 0.6.0 (2026-09-02)
+
+### 🚀 Features
+
+- ⚠️  **response:** bring /jsonapi's server half up to /http's ([a40fed4](https://github.com/zeroxsolutions/zeroxsolutions/commit/a40fed4))
+
+### ⚠️  Breaking Changes
+
+- **response:** bring /jsonapi's server half up to /http's  ([a40fed4](https://github.com/zeroxsolutions/zeroxsolutions/commit/a40fed4))
+  /jsonapi/server's createErrorHandler now requires `category`.
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
+## 0.5.0 (2026-09-02)
+
+### 🚀 Features
+
+- ⚠️  **response:** declare each JSON:API resource once ([748e006](https://github.com/zeroxsolutions/zeroxsolutions/commit/748e006))
+- ⚠️  **db:** let each table declare its own id column ([eca4aca](https://github.com/zeroxsolutions/zeroxsolutions/commit/eca4aca))
+
+### ⚠️  Breaking Changes
+
+- **response:** declare each JSON:API resource once  ([748e006](https://github.com/zeroxsolutions/zeroxsolutions/commit/748e006))
+  `/jsonapi`'s `okResponse` / `listResponse` take a resource
+  declaration instead of `(type, attributesSchema)`. `resourceDocument`,
+  `resourceCollectionDocument`, `applyFields`, `mergeIncluded`,
+  `documentResources` and `ResourceObject` are removed - the descriptor covers
+  them. `/jsonapi/server` now exports only `createErrorHandler`; the serializer
+  entry points moved behind the descriptor.
+- **db:** let each table declare its own id column  ([eca4aca](https://github.com/zeroxsolutions/zeroxsolutions/commit/eca4aca))
+  `baseTable` is removed - take `idColumn` and spread
+  `timestamps`. `defaultIndexedBaseColumns` is now `timestampIndexes` and
+  `BaseTableShape` is `TimestampColumns`; both were named for the removed concept.
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
+## 0.4.0 (2026-08-31)
+
+### 🚀 Features
+
+- ⚠️  **response:** take the isolate's own logging category, not the library's ([3409798](https://github.com/zeroxsolutions/zeroxsolutions/commit/3409798))
+
+### ⚠️  Breaking Changes
+
+- **response:** take the isolate's own logging category, not the library's  ([3409798](https://github.com/zeroxsolutions/zeroxsolutions/commit/3409798))
+  `createErrorHandler` takes one options object and `category` is
+  required - `createErrorHandler(errors)` becomes
+  `createErrorHandler({ category, errors })`. Required rather than defaulted
+  because a default is what made the silence invisible.
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
+## 0.3.0 (2026-08-31)
+
+### 🚀 Features
+
+- ⚠️  **response:** write the unhandled 500 through logtape, under the caller's id ([fdcb75b](https://github.com/zeroxsolutions/zeroxsolutions/commit/fdcb75b))
+
+### ⚠️  Breaking Changes
+
+- **response:** write the unhandled 500 through logtape, under the caller's id  ([fdcb75b](https://github.com/zeroxsolutions/zeroxsolutions/commit/fdcb75b))
+  `@logtape/logtape` is a new peer of `./http/server`, and the
+  unhandled-500 line is silent in an isolate that never calls `configureSync`.
+  It previously always reached stdout.
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
+## 0.2.2 (2026-08-29)
+
+### 💅 Refactors
+
+- state an explicit return type on every function ([8ee4264](https://github.com/zeroxsolutions/zeroxsolutions/commit/8ee4264))
+
+### ❤️ Thank You
+
+- Lương Văn Tú
+
+## 0.2.1 (2026-08-28)
+
+### 🚀 Features
+
+- **response:** render a rejected request in the surface's own error shape ([bdece2a](https://github.com/zeroxsolutions/zeroxsolutions/commit/bdece2a))
+
+### 🩹 Fixes
+
+- **response:** treat an empty projection as publishing nothing ([ffb0bb5](https://github.com/zeroxsolutions/zeroxsolutions/commit/ffb0bb5))
+- **db,response:** stop advertising a root entry neither package has ([18abe7e](https://github.com/zeroxsolutions/zeroxsolutions/commit/18abe7e))
+
+### ❤️ Thank You
+
+- Claude Opus 5
+- Lương Văn Tú
+
+## 0.1.0 (2026-08-15)
+
+### 🚀 Features
+
+- **http-error:** the HTTP error contract every transport answers with ([6d94faa](https://github.com/zeroxsolutions/zeroxsolutions/commit/6d94faa))
+
+### ❤️ Thank You
+
+- Claude Opus 5
+- Lương Văn Tú

package/README.md

@@ -0,0 +1,237 @@
+# @zeroxsolutions/response
+
+The response half of the HTTP contract a service and its edge gateway both answer with - the sibling
+of `@zeroxsolutions/query`, which owns the query-string half, and shaped the same way: one entry, one
+wire spelling.
+
+```ts
+import { errorResponse, jsonApiResource, listResponse, okResponse, toOne } from '@zeroxsolutions/response';
+
+export const subjects = jsonApiResource('subjects', subjectAttributesSchema, {
+  relationships: { org: toOne(() => orgs, (row) => row.org) },
+});
+
+responses: {
+  200: listResponse('Subjects', subjects),       // { data: [...], included?, links? }
+  201: okResponse('Subject created', subjects),  // { data: {...}, included?, ... }
+  401: errorResponse('Authentication required'), // { errors: [...] }
+}
+
+return c.json(await subjects.serializeMany(rows, { links }, c.req.valid('query')));
+```
+
+Both take the **item** on a list and wrap it, so no route restates the carrier. They take a resource
+DECLARATION rather than a bare schema, because a document carries a `type` and its relationships, which
+a schema alone has nowhere to put.
+
+The declaration is one value, and the schema a route advertises and the document its handler emits both
+come off it: the attribute keys ARE the serializer's projection, so a row member the schema does not
+declare cannot reach the wire, and the request's sparse fieldset reaches an `included` resource because
+the descriptor builds the related type's serializer from that same request. Two resources may name each
+other - a relationship holds a thunk - and one side of such a pair carries an explicit
+`JsonApiResource<typeof attributes>`, which is the only thing tsc cannot infer through the cycle.
+
+`declaredDocumentShape` reads that same declaration back as the permit-list a query guard needs: every
+reachable type with the fields it publishes - its attributes and its relationships, as the standard counts
+them - and every relationship path a document can compound.
+Deriving it is the point - a list written by hand beside the declaration permits a column the resource
+stopped publishing, with both halves compiling and both suites green.
+
+```ts
+const { fields, include } = declaredDocumentShape(classes); // feeds `@zeroxsolutions/query`'s permits
+```
+
+## Errors
+
+The domain raises a plain `Error` subclass carrying only domain data; the transport decides what it
+means on the wire, from a table keyed on the error's **constructor identity**.
+
+```ts
+// entrypoints/http/error-map.ts - the transport's type -> wire table
+import { defineErrorMap, errorEntry } from '@zeroxsolutions/response';
+
+export const academicsErrors = defineErrorMap([
+  errorEntry(ClassNotFound, { status: 404, title: 'Not Found', code: 'academics.class.not_found' }),
+  errorEntry(ClassFull, {
+    status: 409,
+    title: 'Conflict',
+    code: 'academics.class.full',
+    meta: (error) => ({ capacity: error.capacity }),   // `capacity` is typed off ClassFull
+  }),
+]);
+```
+
+Map membership is the discriminator between a known failure and a bug: an error type the map does not
+name answers `500` carrying nothing of itself, so a forgotten entry is loud rather than a lenient 4xx. A
+subclass of a mapped class is not mapped either - the lookup is identity, never `instanceof`.
+
+An answer is `{ status, title, code }`, all three required: an error object needs a `title`, and the
+`code` is this transport's own word for the failure, never the domain's. `errorEntry` infers the class, so
+an answer's optional members read what that class carries:
+
+- `meta` renders the error's own data a client acts on, in the member the standard gives it, rather than
+  a `detail` a client would have to parse;
+- `source` names the request slot to blame;
+- `links` points at a page about the problem.
+
+The rendered error object carries the error's `message` as `detail`.
+
+The `onError` handler itself is not in this package. It is a `hono` `ErrorHandler`, and keeping it out is
+what leaves this one with no framework peer: `createErrorHandler` and `createValidationHook` ship from
+`@zeroxsolutions/server`, and the map reaches the handler through `createDomainErrorResolver(map)`.
+
+```ts
+// entrypoints/http/app.ts - one central onError per transport
+import { createDomainErrorResolver } from '@zeroxsolutions/response';
+import { createErrorHandler } from '@zeroxsolutions/server';
+
+app.onError(
+  createErrorHandler({
+    namespace: 'academics',   // every code THESE handlers mint carries it, so one surface has one vocabulary
+    category: ['academics', 'http'],
+    resolve: createDomainErrorResolver(academicsErrors),
+  }),
+);
+```
+
+`JsonApiError` is for a failure whose wire answer is already decided at the throw site - a guard refusing
+a caller, or a gateway translating what a fronted service returned. It takes a `BASE_ERROR_CODES` entry
+for its `{ status, title }` and this transport's own `code` beside it, and may carry `detail`, `source`,
+`links` and `meta`.
+
+```ts
+throw new JsonApiError({ ...BASE_ERROR_CODES.FORBIDDEN, code: '<context>.forbidden' });
+// the spread FIRST: the entry carries no `code` today, and the explicit one has to win the day it does
+```
+
+Every error document renders through `toErrorDocument`, which stamps `jsonapi: { version: '1.1' }` as a
+success document carries it. No producer sets an error object's `id`: the handler stamps the request id,
+so a client quotes the id the request's log lines carry.
+
+## A fronted service's failure
+
+A gateway never re-emits the body a service below it rendered: that `code` names a namespace the public
+contract never declared, and that message was written for the gateway, which is the service's only caller.
+So the gateway owns a **second** map - keyed by the upstream `code`, because a rendered document carries no
+class and `defineErrorMap` resolves by constructor identity, which cannot reach one.
+
+It is a plain object, not a `Map`: the key is a string the source spells literally, so an object literal
+already carries the lookup and the literal keys. An entry earns its place by producing an answer no other
+entry produces - two keys reaching one `{ status, code }` is the fallback's job.
+
+```ts
+// entrypoints/http/error-map.ts - the gateway answers in ITS OWN vocabulary, and the status moves with it:
+// a lifecycle the public contract never published is no conflict to the caller, it is an absence.
+import {
+  createUpstreamErrorTranslator,
+  type Meta,
+  type UpstreamErrorAnswer,
+  type UpstreamErrorMap,
+} from '@zeroxsolutions/response';
+
+// 502, not 500: reaching the fallback means the gateway did not RECOGNISE what its dependency said, which is
+// what 502 states - 500 would claim the gateway itself broke, and a client retries the two differently.
+export const PLACE_UPSTREAM_FALLBACK = {
+  status: 502,
+  title: 'Bad Gateway',
+  code: 'api.upstream_failed',
+} as const satisfies UpstreamErrorAnswer;
+
+export const PLACE_UPSTREAM_ERRORS = {
+  'place.place.not_published': {
+    status: 404,
+    title: 'Not Found',
+    code: 'api.place.unavailable',
+    detail: 'This place is not available.',
+  },
+  'place.place.full': {
+    status: 409,
+    title: 'Conflict',
+    code: 'api.place.full',
+    // the return type is spelled: a callback in an object checked by `satisfies` alone is not a typed function
+    // expression to @typescript-eslint/explicit-function-return-type
+    meta: (upstream): Meta | undefined => {
+      const parsed = placeFullMetaSchema.safeParse(upstream);   // what the service promises, and nothing else
+      return parsed.success ? parsed.data : undefined;
+    },
+  },
+} satisfies UpstreamErrorMap;
+
+export const translatePlaceUpstreamError = createUpstreamErrorTranslator(PLACE_UPSTREAM_ERRORS, PLACE_UPSTREAM_FALLBACK);
+```
+
+A route throws what the translator returns, so the one `onError` renders it like every other failure:
+
+```ts
+// entrypoints/http/routes/places.ts - the route declares EVERY status it can emit, including its own 500, or
+// `ok` has nothing to narrow to. `ok` is typed `U extends SuccessStatusCode ? true : false` per declared
+// status (hono@4.13.3 dist/types/client/types.d.ts:108), so `!ok` IS the error arm - a `status !== 200` test
+// calls a declared 201 or 204 a failure.
+import type { ErrorDocument } from '@zeroxsolutions/response';
+
+const upstream = await c.var.place.v1.places[':placeId'].$get({ param });
+if (!upstream.ok) {
+  const body: ErrorDocument = await upstream.json();
+  throw translatePlaceUpstreamError(body);
+}
+```
+
+The translator reads the code off the document's FIRST error object, because `createErrorHandler` renders
+exactly one error per failure. Of that error it keeps only what an answer's `meta` reads: its `source`
+pointers name the SERVICE's request shape, not the one this caller sent, so echoing them would point a
+client at members it has no way to correct.
+
+A `meta` callback returns its parse, never `upstream` as received - the schema is what keeps a member the
+service adds later from crossing. Returning `undefined` answers the fallback: a mapped code missing the
+data its contract promises is an answer the gateway does not recognise.
+
+A request the route's own schema rejects reaches that same `onError`. `@hono/zod-validator` (0.9.0)
+answers a rejected parse with its own `c.json(result, 400)` unless a hook answers or throws first, so
+`createValidationHook` is passed to the constructor, and it throws the rejection for `createErrorHandler`
+to render.
+
+```ts
+// entrypoints/http/app.ts - the same shape for a request the route's own schema rejects
+import { createValidationHook } from '@zeroxsolutions/server';
+
+const app = new OpenAPIHono<AppEnvironment>({
+  defaultHook: createValidationHook<AppEnvironment>({ namespace: 'academics' }),
+});
+```
+
+It reads the status off the validation target - a `json` or `form` target is `422`, a
+param/query/header/cookie one is `400` - and renders **every** offending member as its own error object,
+not just the first. The target is the validator's own fact rather than a product's choice, so nothing here
+is configurable: an option would let two transports answer one failure two ways, which is the uniformity
+this package exists to hold.
+
+It locates each issue by the slot it was read from: a body member as `source.pointer`, a query member as
+`source.parameter`, a header as `source.header`. A path segment gets `meta` instead - the spec defines
+those three members and none of them means a path segment, so borrowing one would say something false.
+
+## Exports
+
+One root, no subpath, and `src/index.ts` lists every name it publishes:
+
+- `okResponse` / `listResponse` / `errorResponse`, the `JsonApiResponse` they return (exported so a
+  consumer's declaration emit can name it), and `errorDocumentSchema`, which `errorResponse` returns
+  inside it;
+- the resource declaration - `jsonApiResource`, `toOne` / `toMany`, `declaredDocumentShape` - and the
+  types their signatures name;
+- the error document's types, `JsonApiError`, `BASE_ERROR_CODES`, `toErrorObject` / `toErrorDocument`;
+- `defineErrorMap` / `errorEntry` / `createDomainErrorResolver` and `createUpstreamErrorTranslator`, with
+  the answer, entry and map types they take;
+- `JSON_API_MEDIA_TYPE`.
+
+The document and resource-object schemas, the link and identifier primitives and the serializer
+functions are what `jsonApiResource` is built from, and the root does not publish them: a resource's own
+`document`, `collectionDocument`, `serialize` and `serializeMany` are the one way to declare and render a
+document.
+
+`zod` is the only peer. `hono` left with the plain spelling: nothing here needs its
+`ContentfulStatusCode`, because a JSON:API status is carried by the error object.
+
+The content-negotiation DECISION for the JSON:API media type and the client-side document deserializer
+are **not** here - they are request- and client-side, and live in `@zeroxsolutions/jsonapi`. Everything
+that is a Hono handler - the `onError`, the `defaultHook`, the negotiation middleware - is
+`@zeroxsolutions/server`.

package/dist/api-response.d.ts

@@ -0,0 +1,24 @@
+import type { output, ZodObject, ZodType } from 'zod';
+import type { CollectionDocument, ResourceDocument } from './document.js';
+import { errorDocumentSchema } from './errors/index.js';
+import { JSON_API_MEDIA_TYPE } from './media-type.js';
+import type { JsonApiResource } from './resource.js';
+/**
+ * An OpenAPI response object for this spelling - one media type, one schema.
+ *
+ * Exported because a consumer emitting declarations has to NAME it: a route built from these helpers
+ * is an exported const whose type mentions it, and a private one fails that emit with TS4023.
+ */
+export interface JsonApiResponse<S extends ZodType> {
+    description: string;
+    content: Record<typeof JSON_API_MEDIA_TYPE, {
+        schema: S;
+    }>;
+}
+/** The response object for a failure status - the `errors[]` document. */
+export declare function errorResponse(description: string): JsonApiResponse<typeof errorDocumentSchema>;
+/** The response object for a single resource, off the resource's own declaration. */
+export declare function okResponse<A extends ZodObject>(description: string, resource: JsonApiResource<A>): JsonApiResponse<ZodType<ResourceDocument<output<A>>>>;
+/** The response object for a collection, off the resource's own declaration. */
+export declare function listResponse<A extends ZodObject>(description: string, resource: JsonApiResource<A>): JsonApiResponse<ZodType<CollectionDocument<output<A>>>>;
+//# sourceMappingURL=api-response.d.ts.map

package/dist/api-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-response.d.ts","sourceRoot":"","sources":["../src/api-response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AACtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,OAAO;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC,OAAO,mBAAmB,EAAE;QAAE,MAAM,EAAE,CAAC,CAAA;KAAE,CAAC,CAAC;CAC5D;AAOD,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAAC,OAAO,mBAAmB,CAAC,CAE9F;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,CAAC,SAAS,SAAS,EAC5C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,GAC3B,eAAe,CAAC,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAEvD;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,EAC9C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,GAC3B,eAAe,CAAC,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAEzD"}

package/dist/api-response.js

@@ -0,0 +1,18 @@
+import { errorDocumentSchema } from './errors/index.js';
+import { JSON_API_MEDIA_TYPE } from './media-type.js';
+const answers = (description, schema) => ({
+    description,
+    content: { [JSON_API_MEDIA_TYPE]: { schema } },
+});
+/** The response object for a failure status - the `errors[]` document. */
+export function errorResponse(description) {
+    return answers(description, errorDocumentSchema);
+}
+/** The response object for a single resource, off the resource's own declaration. */
+export function okResponse(description, resource) {
+    return answers(description, resource.document);
+}
+/** The response object for a collection, off the resource's own declaration. */
+export function listResponse(description, resource) {
+    return answers(description, resource.collectionDocument);
+}

package/dist/document-shape.d.ts

@@ -0,0 +1,17 @@
+import { type RelatedResource } from './relationship.js';
+/** The fieldsets and relationship paths one resource declaration can answer. */
+export interface DeclaredDocumentShape {
+    /** Every reachable type with the fields it publishes: its attribute names, then its relationship names. */
+    fields: Record<string, string[]>;
+    /** Every relationship path from the root, dotted for a nested one. */
+    include: string[];
+}
+/**
+ * What a client may ask a document to be shaped as, read off the declaration itself - the permit-list a query guard
+ * needs, without a second copy of it.
+ *
+ * The attribute keys ARE the projection, so a list written by hand beside them permits a column the resource stopped
+ * publishing, or refuses one it started, with both halves compiling and both suites green.
+ */
+export declare function declaredDocumentShape(root: RelatedResource): DeclaredDocumentShape;
+//# sourceMappingURL=document-shape.d.ts.map

package/dist/document-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-shape.d.ts","sourceRoot":"","sources":["../src/document-shape.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE7E,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACpC,2GAA2G;IAC3G,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACjC,sEAAsE;IACtE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,qBAAqB,CAuBlF"}

package/dist/document-shape.js

@@ -0,0 +1,29 @@
+import { reachableResources } from './relationship.js';
+/**
+ * What a client may ask a document to be shaped as, read off the declaration itself - the permit-list a query guard
+ * needs, without a second copy of it.
+ *
+ * The attribute keys ARE the projection, so a list written by hand beside them permits a column the resource stopped
+ * publishing, or refuses one it started, with both halves compiling and both suites green.
+ */
+export function declaredDocumentShape(root) {
+    const fields = Object.fromEntries(reachableResources(root).map((resource) => [
+        resource.type,
+        [...Object.keys(resource.attributes.shape), ...Object.keys(resource.relationships)],
+    ]));
+    const include = [];
+    // A path never revisits a type: two resources naming each other make `class.subject.class...` infinite, and the
+    // second lap addresses the same rows the first one already compounded.
+    const walk = (resource, prefix, seen) => {
+        for (const [name, def] of Object.entries(resource.relationships)) {
+            const related = def.related();
+            if (seen.has(related.type))
+                continue;
+            const path = prefix === '' ? name : `${prefix}.${name}`;
+            include.push(path);
+            walk(related, path, new Set([...seen, related.type]));
+        }
+    };
+    walk(root, '', new Set([root.type]));
+    return { fields, include };
+}