@zeroxsolutions/server 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 0.3.2 (2026-09-18)
+
+This was a version bump only for @zeroxsolutions/server to align it with other projects, there were no code changes.
+
+## 0.3.1 (2026-09-18)
+
+### 🚀 Features
+
+- **server:** log every error the handler answers ([c003f8e](https://github.com/zeroxsolutions/zeroxsolutions/commit/c003f8e))
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
 ## 0.3.0 (2026-09-13)
 
 ### 💅 Refactors

package/README.md

@@ -82,8 +82,13 @@ why `Content-Type` is read on a write only, and why an empty `Accept` is refused
    `@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.
+4. otherwise the status alone - a hono `HTTPException` at its own, anything else as a 500.
+
+Whichever step answers, the handler writes one `http.error.answered` line under `category` before the
+document goes out, at the level the answered status class decides: a 5xx at error, anything else at
+warn. The line carries the request id, the method, the path, the answered status, the step that claimed
+the failure (`resolve`, `validation`, `jsonapi`, `status`) and the error's type and message. Without it
+a mapped 500 or a guard's 403 reaches the client with nothing in the log for an operator to join it to.
 
 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.

package/dist/error-handler.d.ts

@@ -4,7 +4,7 @@ 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
+     * The ISOLATE's own logging category, which every answered failure's 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.
      */
@@ -19,8 +19,9 @@ export interface ErrorHandlerOptions extends SurfaceVocabulary {
  * `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.
+ * Every answer is written to the log before it goes out, at the level its status class decides: a 5xx at error,
+ * because this side went wrong, anything else at warn, because the request was refused. Without the line, a
+ * mapped 500 and a guard's 401 reach the client leaving no trace that the request arrived.
  */
 export declare function createErrorHandler(options: ErrorHandlerOptions): ErrorHandler;
 //# sourceMappingURL=error-handler.d.ts.map

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;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"}
+{"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;AAkCjE,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;AAmBD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CA+B7E"}

package/dist/error-handler.js

@@ -9,9 +9,10 @@ for (const [name, meta] of Object.entries(BASE_ERROR_CODES)) {
         META_BY_STATUS.set(meta.status, { code: name.toLowerCase(), title: meta.title });
     }
 }
+// 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.
-function errorObjectByStatus(err, namespace) {
-    const status = err instanceof HTTPException ? err.status : 500;
+function errorObjectByStatus(err, status, namespace) {
     const meta = META_BY_STATUS.get(status) ?? { code: 'error', title: 'Error' };
     const detail = err instanceof HTTPException ? err.message : 'Internal server error';
     return {
@@ -21,37 +22,54 @@ function errorObjectByStatus(err, namespace) {
         ...(detail && detail !== meta.title ? { detail } : {}),
     };
 }
+// Asks each step of the dispatch in turn: `resolve`, a request the validation hook rejected, a `JsonApiError` as
+// thrown, the HTTP status alone.
+function claimError(err, c, options) {
+    const resolved = options.resolve?.(err, c);
+    if (resolved) {
+        return { claimedBy: 'resolve', resolved };
+    }
+    if (err instanceof RequestInvalid) {
+        return { claimedBy: 'validation', resolved: { status: err.status, errors: err.errors } };
+    }
+    if (err instanceof JsonApiError) {
+        return { claimedBy: 'jsonapi', resolved: { status: err.status, errors: [toErrorObject(err)] } };
+    }
+    const status = err instanceof HTTPException ? err.status : 500;
+    return { claimedBy: 'status', resolved: { status, errors: [errorObjectByStatus(err, status, options.namespace)] } };
+}
 /**
  * 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.
+ * Every answer is written to the log before it goes out, at the level its status class decides: a 5xx at error,
+ * because this side went wrong, anything else at warn, because the request was refused. Without the line, a
+ * mapped 500 and a guard's 401 reach the client leaving no trace that the request arrived.
  */
 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 { claimedBy, resolved } = claimError(err, c, options);
+        const line = {
+            // 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,
+            status: resolved.status,
+            claimedBy,
+            type: err.name,
+            message: err.message,
         };
+        if (resolved.status >= 500) {
+            logger.error(ANSWERED_LINE, line);
+        }
+        else {
+            logger.warn(ANSWERED_LINE, line);
+        }
         const doc = toErrorDocument(resolved.errors.map(stamp));
         return c.body(JSON.stringify(doc), resolved.status, {
             'Content-Type': JSON_API_MEDIA_TYPE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/server",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -21,8 +21,8 @@
   },
   "dependencies": {
     "tslib": "^2.3.0",
-    "@zeroxsolutions/jsonapi": "0.11.0",
-    "@zeroxsolutions/response": "0.12.0"
+    "@zeroxsolutions/response": "0.12.1",
+    "@zeroxsolutions/jsonapi": "0.11.1"
   },
   "peerDependencies": {
     "@hono/zod-openapi": "^1.0.0",