@zeroxsolutions/server 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+## 0.3.0 (2026-09-13)
+
+### 💅 Refactors
+
+- ⚠️  **server:** render a rejected request through the error handler ([59b6f32](https://github.com/zeroxsolutions/zeroxsolutions/commit/59b6f32))
+
+### ⚠️  Breaking Changes
+
+- **server:** render a rejected request through the error handler  ([59b6f32](https://github.com/zeroxsolutions/zeroxsolutions/commit/59b6f32))
+  `createValidationHook` throws the rejection instead of
+  answering it, so an app passing it to `OpenAPIHono` also needs
+  `createErrorHandler` as its `onError`; without one hono answers the
+  rejection with a text 500. The hook's type is now
+  `Hook<unknown, E, string, undefined>`. The handler asks `resolve` before
+  it renders the rejection, so a `resolve` answering every error now
+  answers validation failures too. Where `requestId` is configured, a
+  validation 400 or 422 carries it as each error object's `id`, and every
+  error document the handler renders carries `jsonapi: { version: '1.1' }`.
+
+### ❤️ Thank You
+
+- Claude Sonnet 5
+- Lương Văn Tú
+
+## 0.2.4 (2026-09-13)
+
+This was a version bump only for @zeroxsolutions/server to align it with other projects, there were no code changes.
+
+## 0.2.3 (2026-09-13)
+
+This was a version bump only for @zeroxsolutions/server to align it with other projects, there were no code changes.
+
+## 0.2.2 (2026-09-13)
+
+### 🧱 Updated Dependencies
+
+- Updated @zeroxsolutions/response to 0.11.2
+- Updated @zeroxsolutions/jsonapi to 0.10.2
+
+## 0.2.1 (2026-09-07)
+
+Repackaged only, no source change: the previous tarball still carried the pre-flatten `dist/hono/http/` and `dist/hono/jsonapi/` tree, which `tsc --build` leaves behind when a source file is renamed away. 48 entries down to 21.
+
+## 0.2.0 (2026-09-07)
+
+### 🚀 Features
+
+- ⚠️  **server,jsonapi:** one surface, one error-code vocabulary ([32b4aed](https://github.com/zeroxsolutions/zeroxsolutions/commit/32b4aed))
+
+### ⚠️  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>`.
+
+### ❤️ Thank You
+
+- Lương Văn Tú
+
+## 0.1.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.0.3 (2026-09-07)
+
+This was a version bump only for @zeroxsolutions/server to align it with other projects, there were no code changes.
+
+## 0.0.2 (2026-09-07)
+
+### 🚀 Features
+
+- **server:** add the package holding every house Hono handler ([2b1f05d](https://github.com/zeroxsolutions/zeroxsolutions/commit/2b1f05d))
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú

package/README.md

@@ -0,0 +1,128 @@
+# @zeroxsolutions/server
+
+Every Hono handler the house ships: the middlewares, the `onError` and the `defaultHook` a worker wires
+before its routes. A concern package holds the DECISION as a plain function over values;
+this one holds the handler that calls it. That split is what leaves the concern packages framework-free.
+
+| Holds | Wires the decisions in |
+| --- | --- |
+| `createEnvironment` | the worker's own `bindingsSchema` - no package owns a worker's bindings |
+| `createErrorHandler`, `createValidationHook`, `jsonApiContentNegotiation` | `@zeroxsolutions/response`, `@zeroxsolutions/jsonapi` |
+
+## What the split bought
+
+| Package | Peers before | Peers now |
+| --- | --- | --- |
+| `@zeroxsolutions/jsonapi` | `hono` | none - plain functions over strings and documents, which is what an SPA loads |
+| `@zeroxsolutions/response` | `@hono/zod-openapi`, `@logtape/logtape`, `hono`, `zod` | `zod` - `hono` left with the plain spelling |
+
+That is the test for anything else moving here: it moves when the move DROPS a framework peer from the
+package it left. `auth()` and `permission()` do not - the provider's own surface decides them, and
+`hasPermission` is a call rather than a shape. Neither does `dependencies()`, which registers one
+context's own tokens and so has nothing to share.
+
+## Install
+
+```sh
+pnpm add @zeroxsolutions/server
+```
+
+`hono`, `zod` and `@logtape/logtape` are peers - the worker already declares them.
+`@zeroxsolutions/jsonapi` and `@zeroxsolutions/response` come with it, as dependencies: this package
+CALLS them rather than reading a host's instance.
+
+## Quickstart
+
+`createEnvironment` builds the gate that refuses a request whose bindings do not match the schema the
+transport declares its `Bindings` from:
+
+```ts
+// packages/<context>/src/entrypoints/http/middlewares/environment.ts
+import { createEnvironment } from '@zeroxsolutions/server';
+import { LOG_CATEGORY } from '../../../lib/constants/index.js';
+import { bindingsSchema, type AppEnvironment } from '../env.js';
+
+/** Refuses a request whose environment does not match `bindingsSchema`, before any other middleware reads a field. */
+export const environment = createEnvironment<AppEnvironment>({ schema: bindingsSchema, category: LOG_CATEGORY });
+```
+
+The mount site is unchanged, because the binder returns a factory rather than the middleware:
+
+```ts
+// entrypoints/http/app.ts - first, so a missing binding is named once rather than at first use
+app.use('*', environment());
+```
+
+A rejected parse logs `app.env.invalid` with the failing PATHS and the request id, then throws an error
+carrying no field name - which input an operator failed to set is not the caller's business, and the
+transport's `onError` renders it as a bare 500.
+
+`jsonApiContentNegotiation` binds to nothing of the product's - the media type and the parameter rule
+are the standard's, identical on every surface answering it. It takes the surface's `namespace` for the
+same reason the other two do: a refusal it mints is an error object like any other, and a client reading
+`not_acceptable` beside `api.place.not_found` cannot tell which surface spoke.
+
+```ts
+// entrypoints/http/app.ts - one middleware, before the routes, never a per-handler check
+import { jsonApiContentNegotiation } from '@zeroxsolutions/server';
+
+app.use('*', jsonApiContentNegotiation({ namespace: 'api' }));
+```
+
+It refuses with `JsonApiError`, so the refusal renders through the same central `onError` as every other
+failure. `@zeroxsolutions/jsonapi`'s README carries the two decisions the headers alone do not settle -
+why `Content-Type` is read on a write only, and why an empty `Accept` is refused.
+
+## One error seat
+
+`createErrorHandler` is the app's `onError`, and every failure renders through it as one
+`application/vnd.api+json` error document carrying `jsonapi: { version: '1.1' }`. It asks, in order:
+
+1. `resolve(err, c)` - where a surface's domain error map answers, through
+   `@zeroxsolutions/response`'s `createDomainErrorResolver`;
+2. a request the validation hook rejected, one error object per issue;
+3. a `JsonApiError`, rendered as it was thrown;
+4. otherwise the status alone - a hono `HTTPException` at its own, anything else as a 500, written to
+   the log first because that 500 carries nothing of the error.
+
+The `requestId` option's value becomes the `id` of each error object that carries none, so a client
+quotes the id the request's log lines carry.
+
+`createValidationHook` throws its rejection rather than answering, which is what puts a 400 or 422 on
+that same path. It is still passed to the `OpenAPIHono` constructor, because without a hook
+`@hono/zod-validator` (0.9.0) answers a rejected parse with its own raw 400. And it needs
+`createErrorHandler` on the same app: hono answers an error no `onError` catches with a text 500.
+
+```ts
+// entrypoints/http/app.ts
+const app = new OpenAPIHono<AppEnvironment>({ defaultHook: createValidationHook({ namespace: 'api' }) });
+app.onError(
+  createErrorHandler({
+    namespace: 'api',
+    category: LOG_CATEGORY,
+    resolve: createDomainErrorResolver(apiErrors),
+    requestId: (c) => c.var.requestId,
+  }),
+);
+```
+
+## Why a binder rather than a ready middleware
+
+The schema and the log category are the package's, not the library's: the schema is what the transport
+declares its `Bindings` from, and the category names that worker's isolate. A ready middleware would
+have to read both from somewhere global. Binding them once, at the module that owns them, keeps the
+type flowing (`createEnvironment<AppEnvironment>`) and leaves the mount site the shape a middleware
+module already has - a factory named for its file, called where it is mounted.
+
+## API reference
+
+The version-accurate API **is the shipped types** - every export carries TSDoc compiled into
+`dist/**/*.d.ts`. Read it in your editor or at `node_modules/@zeroxsolutions/server/dist/`. This README
+does not restate the API: the types are the source of truth and never drift from the version.
+
+## Building & testing
+
+```sh
+pnpm nx build @zeroxsolutions/server
+pnpm nx test @zeroxsolutions/server
+```

package/dist/content-negotiation.d.ts

@@ -0,0 +1,17 @@
+import type { MiddlewareHandler } from 'hono';
+import type { SurfaceVocabulary } from './surface-vocabulary.js';
+/**
+ * Hono adapter over {@link negotiateJsonApi}: rejects with 415/406 per JSON:API v1.1 content
+ * negotiation, then stamps the JSON:API media type onto the response `Content-Type`.
+ *
+ * `Content-Type` is read only where the request carries content - a bodyless `Request` has `body === null`,
+ * a write's is a stream - because a header describes a representation and a read route has none, so an
+ * unconditional read would cost a client sending a blanket default the whole collection.
+ *
+ * @example
+ * ```ts
+ * app.use('*', jsonApiContentNegotiation({ namespace: 'api' })); // one middleware, before the routes
+ * ```
+ */
+export declare function jsonApiContentNegotiation(options: SurfaceVocabulary): MiddlewareHandler;
+//# sourceMappingURL=content-negotiation.d.ts.map

package/dist/content-negotiation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-negotiation.d.ts","sourceRoot":"","sources":["../src/content-negotiation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,iBAAiB,GAAG,iBAAiB,CAQvF"}

package/dist/content-negotiation.js

@@ -0,0 +1,25 @@
+import { negotiateJsonApi } from '@zeroxsolutions/jsonapi';
+import { JSON_API_MEDIA_TYPE } from '@zeroxsolutions/response';
+/**
+ * Hono adapter over {@link negotiateJsonApi}: rejects with 415/406 per JSON:API v1.1 content
+ * negotiation, then stamps the JSON:API media type onto the response `Content-Type`.
+ *
+ * `Content-Type` is read only where the request carries content - a bodyless `Request` has `body === null`,
+ * a write's is a stream - because a header describes a representation and a read route has none, so an
+ * unconditional read would cost a client sending a blanket default the whole collection.
+ *
+ * @example
+ * ```ts
+ * app.use('*', jsonApiContentNegotiation({ namespace: 'api' })); // one middleware, before the routes
+ * ```
+ */
+export function jsonApiContentNegotiation(options) {
+    return async (c, next) => {
+        const contentType = c.req.raw.body === null ? undefined : c.req.header('Content-Type');
+        const error = negotiateJsonApi(contentType, c.req.header('Accept'), options.namespace);
+        if (error)
+            throw error;
+        await next();
+        c.header('Content-Type', JSON_API_MEDIA_TYPE);
+    };
+}

package/dist/environment.d.ts

@@ -0,0 +1,19 @@
+import type { Env, MiddlewareHandler } from 'hono';
+import type { ZodType } from 'zod';
+/** What {@link createEnvironment} binds to: the schema a worker's bindings must match, and the category naming its isolate. */
+export interface EnvironmentOptions {
+    /** Parsed against `c.env`. Its inferred type is what the transport declares its `Bindings` from. */
+    schema: ZodType;
+    /** Handed to `getLogger` once, when the middleware is built rather than on each request. */
+    category: readonly string[];
+}
+/**
+ * Binds the environment gate to one package's schema and category, returning that package's own
+ * `environment` factory - the gate refuses a request whose `c.env` does not match `schema`, before any
+ * other middleware reads a field, so a missing binding is named once rather than at first use.
+ *
+ * It returns a FACTORY rather than the middleware: a middleware module exports a factory named for its
+ * file and the mount site calls it, so `app.use('*', environment())` is what a transport still writes.
+ */
+export declare function createEnvironment<E extends Env = Env>({ schema, category, }: EnvironmentOptions): () => MiddlewareHandler<E>;
+//# sourceMappingURL=environment.d.ts.map

package/dist/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,GAAG,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAKnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,+HAA+H;AAC/H,MAAM,WAAW,kBAAkB;IACjC,oGAAoG;IACpG,MAAM,EAAE,OAAO,CAAC;IAChB,4FAA4F;IAC5F,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG,EAAE,EACrD,MAAM,EACN,QAAQ,GACT,EAAE,kBAAkB,GAAG,MAAM,iBAAiB,CAAC,CAAC,CAAC,CAoBjD"}

package/dist/environment.js

@@ -0,0 +1,29 @@
+import { getLogger } from '@logtape/logtape';
+import { createMiddleware } from 'hono/factory';
+/**
+ * Binds the environment gate to one package's schema and category, returning that package's own
+ * `environment` factory - the gate refuses a request whose `c.env` does not match `schema`, before any
+ * other middleware reads a field, so a missing binding is named once rather than at first use.
+ *
+ * It returns a FACTORY rather than the middleware: a middleware module exports a factory named for its
+ * file and the mount site calls it, so `app.use('*', environment())` is what a transport still writes.
+ */
+export function createEnvironment({ schema, category, }) {
+    const logger = getLogger(category);
+    return () => createMiddleware(async (c, next) => {
+        const parsed = schema.safeParse(c.env);
+        if (!parsed.success) {
+            // Paths only: the field names are the whole diagnostic, and zod 4.4.3 putting no failing value
+            // on an issue is that version's property, not something a log sink could take back.
+            logger.error('app.env.invalid {requestId} {fields}', {
+                requestId: c.var.requestId,
+                fields: parsed.error.issues.map((issue) => issue.path.join('.')),
+            });
+            // Carries no field name: which input an operator failed to set is not the caller's business,
+            // and a transport's `onError` renders this as a bare 500.
+            throw new Error('environment is not configured');
+        }
+        // `parsed.data` goes unused because every consumer reads `c.env`, the raw object.
+        await next();
+    });
+}

package/dist/error-handler.d.ts

@@ -0,0 +1,26 @@
+import type { Context, ErrorHandler } from 'hono';
+import { type ResolvedError } from '@zeroxsolutions/response';
+import type { SurfaceVocabulary } from './surface-vocabulary.js';
+/** Tunes {@link createErrorHandler} for a specific transport (the edge gateway vs a service). */
+export interface ErrorHandlerOptions extends SurfaceVocabulary {
+    /**
+     * The ISOLATE's own logging category, which the unhandled-500 line is written under. Required
+     * rather than defaulted: a category the isolate did not configure is silent, and silence here
+     * looks the same as a request that never failed.
+     */
+    category: readonly string[];
+    /** Resolves a transport's own error type first; `undefined` falls through to the built-in dispatch. */
+    resolve?: (err: Error, c: Context) => ResolvedError | undefined;
+    /** A request id stamped onto each error object's `id` when it carries none, so a client can correlate. */
+    requestId?: (c: Context) => string | undefined | null;
+}
+/**
+ * The one central `onError` a transport installs, rendering every failure as one `application/vnd.api+json`
+ * `errors[]` document. It asks, in order: `resolve`, then a request the validation hook rejected, then a
+ * {@link JsonApiError} as thrown, then the HTTP status alone.
+ *
+ * A failure none of those claimed is written to the log before it answers, because the generic 500 it renders
+ * carries nothing of the error itself.
+ */
+export declare function createErrorHandler(options: ErrorHandlerOptions): ErrorHandler;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../src/error-handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAGlD,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAuBjE,iGAAiG;AACjG,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D;;;;OAIG;IACH,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,uGAAuG;IACvG,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,KAAK,aAAa,GAAG,SAAS,CAAC;IAChE,0GAA0G;IAC1G,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;CACvD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAkC7E"}

package/dist/error-handler.js

@@ -0,0 +1,60 @@
+import { getLogger } from '@logtape/logtape';
+import { HTTPException } from 'hono/http-exception';
+import { BASE_ERROR_CODES, JsonApiError, JSON_API_MEDIA_TYPE, toErrorDocument, toErrorObject, } from '@zeroxsolutions/response';
+import { RequestInvalid } from './request-invalid.js';
+// The `code` and `title` each HTTP status is answered with, from the first entry the base registry gives it.
+const META_BY_STATUS = new Map();
+for (const [name, meta] of Object.entries(BASE_ERROR_CODES)) {
+    if (!META_BY_STATUS.has(meta.status)) {
+        META_BY_STATUS.set(meta.status, { code: name.toLowerCase(), title: meta.title });
+    }
+}
+// Projects a failure hono raised - or one nothing claimed - onto a JSON:API error object by HTTP status.
+function errorObjectByStatus(err, namespace) {
+    const status = err instanceof HTTPException ? err.status : 500;
+    const meta = META_BY_STATUS.get(status) ?? { code: 'error', title: 'Error' };
+    const detail = err instanceof HTTPException ? err.message : 'Internal server error';
+    return {
+        status: String(status),
+        code: `${namespace}.${meta.code}`,
+        title: meta.title,
+        ...(detail && detail !== meta.title ? { detail } : {}),
+    };
+}
+/**
+ * The one central `onError` a transport installs, rendering every failure as one `application/vnd.api+json`
+ * `errors[]` document. It asks, in order: `resolve`, then a request the validation hook rejected, then a
+ * {@link JsonApiError} as thrown, then the HTTP status alone.
+ *
+ * A failure none of those claimed is written to the log before it answers, because the generic 500 it renders
+ * carries nothing of the error itself.
+ */
+export function createErrorHandler(options) {
+    const logger = getLogger(options.category);
+    return (err, c) => {
+        const requestId = options.requestId?.(c);
+        const stamp = (e) => (requestId && !e.id ? { ...e, id: requestId } : e);
+        const claimed = options.resolve?.(err, c) ??
+            (err instanceof RequestInvalid ? { status: err.status, errors: err.errors } : undefined) ??
+            (err instanceof JsonApiError ? { status: err.status, errors: [toErrorObject(err)] } : undefined);
+        if (!claimed && !(err instanceof HTTPException)) {
+            logger.error('http.error.unhandled {method} {path} {type}', {
+                // Undefined where a transport never mounted `requestId()` - minting one here is a second id for one request.
+                requestId: requestId ?? c.get('requestId'),
+                method: c.req.method,
+                // `path`, not `url`: a query string is where a caller puts a token, and a sink keeps what it is given.
+                path: c.req.path,
+                type: err.name,
+                message: err.message,
+            });
+        }
+        const resolved = claimed ?? {
+            status: err instanceof HTTPException ? err.status : 500,
+            errors: [errorObjectByStatus(err, options.namespace)],
+        };
+        const doc = toErrorDocument(resolved.errors.map(stamp));
+        return c.body(JSON.stringify(doc), resolved.status, {
+            'Content-Type': JSON_API_MEDIA_TYPE,
+        });
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Every Hono handler the house ships - the bindings gate, and the three the wire spelling decides.
+ */
+export { createEnvironment, type EnvironmentOptions } from './environment.js';
+export type { SurfaceVocabulary } from './surface-vocabulary.js';
+export { jsonApiContentNegotiation } from './content-negotiation.js';
+export { createErrorHandler, type ErrorHandlerOptions } from './error-handler.js';
+export { createValidationHook } from './validation-hook.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC9E,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * Every Hono handler the house ships - the bindings gate, and the three the wire spelling decides.
+ */
+export { createEnvironment } from './environment.js';
+export { jsonApiContentNegotiation } from './content-negotiation.js';
+export { createErrorHandler } from './error-handler.js';
+export { createValidationHook } from './validation-hook.js';

package/dist/request-invalid.d.ts

@@ -0,0 +1,12 @@
+import type { ErrorObject } from '@zeroxsolutions/response';
+/**
+ * A request its route's own schema rejected, thrown by the validation hook so the app's one `onError` renders it.
+ *
+ * The package root does not list it: the hook is its only producer and the error handler its only reader.
+ */
+export declare class RequestInvalid extends Error {
+    readonly status: 400 | 422;
+    readonly errors: ErrorObject[];
+    constructor(status: 400 | 422, errors: ErrorObject[]);
+}
+//# sourceMappingURL=request-invalid.d.ts.map

package/dist/request-invalid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-invalid.d.ts","sourceRoot":"","sources":["../src/request-invalid.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;IAErC,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE;gBADrB,MAAM,EAAE,GAAG,GAAG,GAAG,EACjB,MAAM,EAAE,WAAW,EAAE;CAKjC"}

package/dist/request-invalid.js

@@ -0,0 +1,15 @@
+/**
+ * A request its route's own schema rejected, thrown by the validation hook so the app's one `onError` renders it.
+ *
+ * The package root does not list it: the hook is its only producer and the error handler its only reader.
+ */
+export class RequestInvalid extends Error {
+    status;
+    errors;
+    constructor(status, errors) {
+        super('The request does not match its route schema');
+        this.status = status;
+        this.errors = errors;
+        this.name = 'RequestInvalid';
+    }
+}

package/dist/surface-vocabulary.d.ts

@@ -0,0 +1,11 @@
+/** What every code a surface renders is prefixed with, so one surface answers in one vocabulary. */
+export interface SurfaceVocabulary {
+    /**
+     * The transport's own namespace - `api`, `back_office` - prefixed onto every code these handlers mint.
+     *
+     * Required rather than defaulted: a handler answering `bad_request` beside a route map answering
+     * `api.place.not_found` publishes two vocabularies, and a client cannot tell which surface spoke.
+     */
+    namespace: string;
+}
+//# sourceMappingURL=surface-vocabulary.d.ts.map

package/dist/surface-vocabulary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-vocabulary.d.ts","sourceRoot":"","sources":["../src/surface-vocabulary.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/surface-vocabulary.js

@@ -0,0 +1 @@
+export {};

package/dist/validation-hook.d.ts

@@ -0,0 +1,14 @@
+import type { Hook } from '@hono/zod-openapi';
+import type { Env } from 'hono';
+import type { SurfaceVocabulary } from './surface-vocabulary.js';
+/**
+ * The `defaultHook` an `OpenAPIHono` is constructed with, rejecting a request its own schema refuses as one error
+ * object per issue - 422 for a `json` or `form` target, 400 otherwise.
+ *
+ * It throws rather than answering, so the rejection renders through the app's `createErrorHandler` like every other
+ * failure, carrying the request id that handler stamps; an app without that handler answers the throw with hono's
+ * text 500. @hono/zod-validator 0.9.0 lets a hook's throw through, and answers `c.json(result, 400)` itself unless a
+ * hook answers or throws first - which is why the hook is still passed to the constructor.
+ */
+export declare function createValidationHook<E extends Env = Env>(options: SurfaceVocabulary): Hook<unknown, E, string, undefined>;
+//# sourceMappingURL=validation-hook.d.ts.map

package/dist/validation-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-hook.d.ts","sourceRoot":"","sources":["../src/validation-hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAGhC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAoBjE;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG,EACtD,OAAO,EAAE,iBAAiB,GACzB,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,CAoBrC"}

package/dist/validation-hook.js

@@ -0,0 +1,47 @@
+import { BASE_ERROR_CODES } from '@zeroxsolutions/response';
+import { RequestInvalid } from './request-invalid.js';
+/**
+ * The error object's `source` for one issue, by the slot it was read from.
+ *
+ * The spec defines exactly three members, and a path segment matches none of them: `pointer` is a JSON
+ * Pointer into the request DOCUMENT, `parameter` a URI query parameter, `header` a header name. So a
+ * `param` or `cookie` issue names its slot in `meta` rather than borrowing a member that means
+ * something else.
+ */
+function sourceFor(target, path) {
+    if (target === 'json' || target === 'form')
+        return { source: { pointer: `/${path.split('.').join('/')}` } };
+    if (target === 'query')
+        return { source: { parameter: path } };
+    if (target === 'header')
+        return { source: { header: path } };
+    return { meta: { target, path } };
+}
+/**
+ * The `defaultHook` an `OpenAPIHono` is constructed with, rejecting a request its own schema refuses as one error
+ * object per issue - 422 for a `json` or `form` target, 400 otherwise.
+ *
+ * It throws rather than answering, so the rejection renders through the app's `createErrorHandler` like every other
+ * failure, carrying the request id that handler stamps; an app without that handler answers the throw with hono's
+ * text 500. @hono/zod-validator 0.9.0 lets a hook's throw through, and answers `c.json(result, 400)` itself unless a
+ * hook answers or throws first - which is why the hook is still passed to the constructor.
+ */
+export function createValidationHook(options) {
+    return (result) => {
+        if (result.success)
+            return;
+        const target = result.target;
+        const body = target === 'json' || target === 'form';
+        const { status, title } = body ? BASE_ERROR_CODES.UNPROCESSABLE_ENTITY : BASE_ERROR_CODES.BAD_REQUEST;
+        const code = `${options.namespace}.${body ? 'unprocessable_entity' : 'bad_request'}`;
+        const errors = result.error.issues.map((issue) => ({
+            status: String(status),
+            code,
+            title,
+            detail: issue.message,
+            // A whole-object refinement carries an empty path, so the slot it was read from stands in.
+            ...sourceFor(target, issue.path.map(String).join('.') || target),
+        }));
+        throw new RequestInvalid(status, errors);
+    };
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@zeroxsolutions/server",
+  "version": "0.3.0",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "description": "Every Hono handler the ZeroXSolutions house ships: the environment gate bound to a worker's own bindings schema, the central onError, the OpenAPIHono defaultHook and the JSON:API content-negotiation middleware - kept out of the packages that decide what they do, so those carry no framework peer.",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "!**/*.tsbuildinfo"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "tslib": "^2.3.0",
+    "@zeroxsolutions/jsonapi": "0.11.0",
+    "@zeroxsolutions/response": "0.12.0"
+  },
+  "peerDependencies": {
+    "@hono/zod-openapi": "^1.0.0",
+    "@logtape/logtape": "^2.0.0",
+    "hono": "^4.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@hono/zod-openapi": "^1.4.0",
+    "@logtape/logtape": "^2.3.2",
+    "hono": "^4.12.27",
+    "zod": "^4.4.3"
+  },
+  "nx": {
+    "name": "@zeroxsolutions/server"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}