@zeroxsolutions/server 0.5.4 → 0.6.0

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 0.6.0 (2026-10-05)
+
+### 🚀 Features
+
+- ⚠️  **server:** answer an update a resource does not support 403 ([7607c77](https://github.com/zeroxsolutions/zeroxsolutions/commit/7607c77))
+
+### ⚠️  Breaking Changes
+
+- **server:** answer an update a resource does not support 403  ([7607c77](https://github.com/zeroxsolutions/zeroxsolutions/commit/7607c77))
+  jsonApiNotFound throws instead of rendering, so a surface
+  installing it installs createErrorHandler as its onError.
+  Refs: zeroxsolutions/travel#283
+
+### ❤️ Thank You
+
+- Claude Opus 5.5 (1M context)
+- Lương Văn Tú
+
 ## 0.5.3 (2026-10-03)
 
 This was a version bump only for @zeroxsolutions/server to align it with other projects, there were no code changes.

package/README.md

@@ -116,19 +116,26 @@ app.onError(
     category: LOG_CATEGORY,
     resolve: createDomainErrorResolver(apiErrors),
     requestId: (c) => c.var.requestId,
-    authenticationChallenge: 'Bearer',
+    authenticationChallenge: 'Session realm="api"',
   }),
 );
 ```
 
-`jsonApiNotFound({ namespace })` is `app.notFound(...)` - the answer for a route nobody declared. hono
-runs `notFound` outside `onError`, so this renders the same 404 error document without writing an
-`http.error.answered` line or stamping a request id: there is no failure here for the log line to join
-to, since nothing was thrown.
+`jsonApiNotFound({ namespace, routes })` is `app.notFound(...)` - the answer for a request no route
+matched. It throws rather than rendering, so `createErrorHandler` answers it, writes its
+`http.error.answered` line and stamps its request id; an app installing it installs
+`createErrorHandler` too, or hono answers the throw with a text 500.
+
+A PATCH to a path one of `routes` serves for another method throws `RequestForbidden` at `/data`,
+answered `403` as `<namespace>.request_forbidden`, because JSON:API 1.1 answers an update a resource
+does not support 403. Anything else, and every request when `routes` is left out, throws a 404
+`HTTPException`, answered as `<namespace>.not_found`. `routes` is the app's own `app.routes`, read on
+the first unmatched request; middleware (method `ALL`) serves no path, and a trailing slash the app
+does not serve stays a 404.
 
 ```ts
-// entrypoints/http/app.ts
-app.notFound(jsonApiNotFound({ namespace: 'api' }));
+// entrypoints/http/app.ts, after app.onError(createErrorHandler(...))
+app.notFound(jsonApiNotFound({ namespace: 'api', routes: app.routes }));
 ```
 
 ## Why a binder rather than a ready middleware

package/dist/error-handler.d.ts

@@ -1,7 +1,6 @@
 import type { Context, ErrorHandler } from 'hono';
-import { type ErrorObject, type ResolvedError } from '@zeroxsolutions/response';
+import { type ResolvedError } from '@zeroxsolutions/response';
 import type { SurfaceVocabulary } from './surface-vocabulary.js';
-export declare function errorObjectByStatus(err: Error, status: number, namespace: string): ErrorObject;
 /** Tunes {@link createErrorHandler} for a specific transport (the edge gateway vs a service). */
 export interface ErrorHandlerOptions extends SurfaceVocabulary {
     /**

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

@@ -1 +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;AAIlD,OAAO,EAQL,KAAK,WAAW,EAChB,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AA4BjE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,CAS9F;AAED,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;IACtD;;;OAGG;IACH,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAsED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAkC7E"}
+{"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;AAIlD,OAAO,EASL,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAuCjE,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;IACtD;;;OAGG;IACH,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAsED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAkC7E"}

package/dist/error-handler.js

@@ -15,7 +15,7 @@ for (const [name, meta] of Object.entries(BASE_ERROR_CODES)) {
 // The message template both levels write, so one search finds every error this handler answered.
 const ANSWERED_LINE = 'http.error.answered {method} {path} {status} {claimedBy}';
 // Projects a failure hono raised - or one nothing claimed - onto a JSON:API error object by HTTP status.
-export function errorObjectByStatus(err, status, namespace) {
+function errorObjectByStatus(err, status, namespace) {
     const meta = META_BY_STATUS.get(status) ?? { code: 'error', title: 'Error' };
     const detail = err instanceof HTTPException ? err.message : undefined;
     return {

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { createEnvironment, type EnvironmentOptions } from './environment.js';
 export type { SurfaceVocabulary } from './surface-vocabulary.js';
 export { jsonApiContentNegotiation, NEGOTIATION_RESPONSES } from './content-negotiation.js';
 export { createErrorHandler, type ErrorHandlerOptions } from './error-handler.js';
-export { jsonApiNotFound } from './not-found.js';
+export { jsonApiNotFound, type NotFoundOptions } from './not-found.js';
 export { PermissionRefused } from './permission-refused.js';
 export { Unauthenticated } from './unauthenticated.js';
 export { createValidationHook } from './validation-hook.js';

package/dist/index.d.ts.map

@@ -1 +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,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC5F,OAAO,EAAE,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}
+{"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,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC5F,OAAO,EAAE,kBAAkB,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/not-found.d.ts

@@ -1,5 +1,21 @@
 import type { NotFoundHandler } from 'hono';
 import type { SurfaceVocabulary } from './surface-vocabulary.js';
-/** The `notFound` handler a JSON:API surface installs, so a route nobody declared answers an error document. */
-export declare function jsonApiNotFound(options: SurfaceVocabulary): NotFoundHandler;
+/** What {@link jsonApiNotFound} is told about the surface it answers for. */
+export interface NotFoundOptions extends SurfaceVocabulary {
+    /** The routes the app serves, as `app.routes` lists them; a PATCH to a path one serves for another method answers 403. */
+    readonly routes?: readonly {
+        readonly method: string;
+        readonly path: string;
+    }[];
+}
+/**
+ * The `notFound` handler a JSON:API surface installs; it throws, so the surface's `onError` renders and logs the
+ * answer. A surface installing it installs `createErrorHandler` as its `onError`, or hono answers the throw
+ * with its own text 500.
+ *
+ * A PATCH to a path some route in {@link NotFoundOptions.routes} serves for another method throws
+ * `RequestForbidden` at `/data`, which JSON:API 1.1 answers 403; anything else throws a 404 `HTTPException`,
+ * answered `<namespace>.not_found`. Without `routes`, every request is the 404.
+ */
+export declare function jsonApiNotFound(options: NotFoundOptions): NotFoundHandler;
 //# sourceMappingURL=not-found.d.ts.map

package/dist/not-found.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"not-found.d.ts","sourceRoot":"","sources":["../src/not-found.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AAE5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,gHAAgH;AAChH,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,eAAe,CAK3E"}
+{"version":3,"file":"not-found.d.ts","sourceRoot":"","sources":["../src/not-found.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AAI5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,6EAA6E;AAC7E,MAAM,WAAW,eAAgB,SAAQ,iBAAiB;IACxD,0HAA0H;IAC1H,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAczE"}

package/dist/not-found.js

@@ -1,8 +1,37 @@
-import { JSON_API_MEDIA_TYPE, toErrorDocument } from '@zeroxsolutions/response';
-import { errorObjectByStatus } from './error-handler.js';
-/** The `notFound` handler a JSON:API surface installs, so a route nobody declared answers an error document. */
+import { RequestForbidden } from '@zeroxsolutions/response';
+import { HTTPException } from 'hono/http-exception';
+import { METHOD_NAME_ALL } from 'hono/router';
+import { TrieRouter } from 'hono/router/trie-router';
+/**
+ * The `notFound` handler a JSON:API surface installs; it throws, so the surface's `onError` renders and logs the
+ * answer. A surface installing it installs `createErrorHandler` as its `onError`, or hono answers the throw
+ * with its own text 500.
+ *
+ * A PATCH to a path some route in {@link NotFoundOptions.routes} serves for another method throws
+ * `RequestForbidden` at `/data`, which JSON:API 1.1 answers 403; anything else throws a 404 `HTTPException`,
+ * answered `<namespace>.not_found`. Without `routes`, every request is the 404.
+ */
 export function jsonApiNotFound(options) {
-    return (c) => c.body(JSON.stringify(toErrorDocument(errorObjectByStatus(new Error('Not Found'), 404, options.namespace))), 404, {
-        'Content-Type': JSON_API_MEDIA_TYPE,
-    });
+    // Built on the first unmatched request, because `routes` is the app's own array and fills as routes mount.
+    // TrieRouter matches strictly, as the app's default router does; PatternRouter and LinearRouter also match
+    // `/things/1/` against `/things/:id`, which the app answers 404.
+    let served;
+    return (c) => {
+        if (c.req.method === 'PATCH' && options.routes !== undefined) {
+            served ??= routerServing(options.routes);
+            if (served.match(c.req.method, c.req.path)[0].length > 0) {
+                throw new RequestForbidden('/data', 'This resource does not support an update.');
+            }
+        }
+        throw new HTTPException(404);
+    };
+}
+// Middleware mounts with method `ALL`, so leaving those out keeps a path only middleware covers a 404.
+function routerServing(routes) {
+    const router = new TrieRouter();
+    for (const route of routes) {
+        if (route.method !== METHOD_NAME_ALL)
+            router.add(METHOD_NAME_ALL, route.path, true);
+    }
+    return router;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/server",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -21,9 +21,9 @@
   },
   "dependencies": {
     "tslib": "^2.3.0",
-    "@zeroxsolutions/query": "0.7.3",
     "@zeroxsolutions/jsonapi": "0.13.1",
-    "@zeroxsolutions/response": "0.14.3"
+    "@zeroxsolutions/response": "0.14.3",
+    "@zeroxsolutions/query": "0.7.3"
   },
   "peerDependencies": {
     "@hono/zod-openapi": "^1.0.0",