@vsaas/error-handler 10.0.0

package/LICENSE.md

@@ -0,0 +1,25 @@
+Copyright (c) IBM Corp. 2016,2017. All Rights Reserved.
+Node module: strong-error-handler
+This project is licensed under the MIT License, full text below.
+
+---
+
+MIT license
+
+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,89 @@
+# @vsaas/error-handler
+
+HTTP error writer for Express and LoopBack 3 style applications.
+
+`@vsaas/error-handler` is a fork of `strong-error-handler`. The goal of this fork is to stay compatible with the original package for the common LoopBack 3 / Strong Remoting use cases, while making the codebase smaller and easier to maintain.
+
+Compared with the upstream package, this fork intentionally removes a number of legacy concerns:
+
+- TypeScript source with build output in `dist/`
+- English-only messages
+- No i18n catalogs or `strong-globalize`
+- Several legacy files and dependencies removed
+- Modern tooling with `tsdown`, `vitest`, and `oxlint`
+
+The public behavior is still meant to be familiar for applications that already depended on `strong-error-handler`, but the internals were simplified on purpose to reduce maintenance overhead.
+
+## Installation
+
+```bash
+npm install @vsaas/error-handler
+```
+
+## Usage
+
+### Express middleware
+
+```js
+const express = require('express');
+const errorHandler = require('@vsaas/error-handler');
+
+const app = express();
+
+app.use(
+  errorHandler({
+    debug: process.env.NODE_ENV !== 'production',
+    log: true,
+  }),
+);
+```
+
+### Direct response writer
+
+```js
+const errorHandler = require('@vsaas/error-handler');
+
+errorHandler.writeErrorToResponse(new Error('something went wrong'), req, res, {
+  debug: false,
+});
+```
+
+## Response formats
+
+The handler supports:
+
+- `application/json` / `json`
+- `text/html` / `html`
+- `text/xml` / `xml`
+
+Content type is negotiated from the request `Accept` header. You can also override it with the `_format` query parameter.
+
+## Options
+
+| Option                 | Default   | Description                                                                 |
+| ---------------------- | --------- | --------------------------------------------------------------------------- |
+| `debug`                | `false`   | Include full error details and stack traces in responses.                   |
+| `log`                  | `true`    | Log errors to `console.error`.                                              |
+| `safeFields`           | `[]`      | Extra error properties allowed through for safe responses.                  |
+| `defaultType`          | `"json"`  | Fallback response type when negotiation does not resolve one.               |
+| `rootProperty`         | `"error"` | Root property for JSON/XML responses. Use `false` to omit the JSON wrapper. |
+| `negotiateContentType` | `true`    | When `false`, always use `defaultType` unless `_format` overrides it.       |
+
+## Behavior
+
+- `4xx` responses keep safe client-facing fields such as `message`, `details`, and `code`.
+- `5xx` responses are sanitized by default to avoid leaking internals.
+- When `debug: true`, the full error payload is returned.
+
+## Development
+
+```bash
+npm run build
+npm run typecheck
+npm run lint
+npm test
+```
+
+## License
+
+MIT. See [LICENSE.md](./LICENSE.md).

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+//#region src/types.d.ts
+interface RequestLike {
+  headers?: Record<string, string | string[] | undefined>;
+  method?: string;
+  query?: Record<string, unknown>;
+  socket?: {
+    destroy?: () => void;
+  };
+  url?: string;
+}
+interface ResponseLike {
+  headersSent?: boolean;
+  statusCode: number;
+  end: (content?: string, encoding?: BufferEncoding) => void;
+  setHeader: (name: string, value: string) => void;
+}
+type ErrorHandlerNext = (error?: unknown) => void;
+interface ErrorWriterOptions {
+  debug?: boolean;
+  defaultType?: string;
+  negotiateContentType?: boolean;
+  rootProperty?: string | false;
+  safeFields?: string | string[];
+}
+interface ErrorHandlerOptions extends ErrorWriterOptions {
+  log?: boolean;
+}
+type StrongErrorHandler = (error: unknown, req: RequestLike, res: ResponseLike, next?: ErrorHandlerNext) => void;
+interface StrongErrorHandlerFactory {
+  (options?: ErrorHandlerOptions): StrongErrorHandler;
+  writeErrorToResponse: (error: unknown, req: RequestLike, res: ResponseLike, options?: ErrorWriterOptions) => void;
+}
+//#endregion
+//#region src/index.d.ts
+declare const strongErrorHandler: StrongErrorHandlerFactory;
+export = strongErrorHandler;

package/dist/index.js

@@ -0,0 +1,279 @@
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let debug = require("debug");
+debug = __toESM(debug);
+let node_http = require("node:http");
+let node_util = require("node:util");
+node_util = __toESM(node_util);
+let accepts = require("accepts");
+accepts = __toESM(accepts);
+let node_fs = require("node:fs");
+node_fs = __toESM(node_fs);
+let node_path = require("node:path");
+node_path = __toESM(node_path);
+let handlebars = require("handlebars");
+handlebars = __toESM(handlebars);
+//#region src/lib/clone.ts
+function cloneAllProperties(data, error) {
+	data.name = error.name;
+	data.message = error.message;
+	for (const key in error) {
+		if (key in data) continue;
+		data[key] = error[key];
+	}
+	data.stack = error.stack;
+}
+//#endregion
+//#region src/lib/data-builder.ts
+function buildResponseData(error, options = {}) {
+	if (Array.isArray(error)) return serializeArrayOfErrors(error, options);
+	const normalizedError = normalizeError(error);
+	const data = { statusCode: resolveStatusCode(normalizedError) };
+	if (options.debug) {
+		cloneAllProperties(data, normalizedError);
+		return data;
+	}
+	if (data.statusCode >= 400 && data.statusCode <= 499) fillClientError(data, normalizedError);
+	else fillServerError(data, normalizedError);
+	fillSafeFields(data, normalizedError, options.safeFields);
+	return data;
+}
+function serializeArrayOfErrors(errors, options) {
+	const details = new Array(errors.length);
+	for (let index = 0; index < errors.length; index += 1) details[index] = buildResponseData(errors[index], options);
+	return {
+		statusCode: 500,
+		message: "Failed with multiple errors, see `details` for more information.",
+		details
+	};
+}
+function normalizeError(error) {
+	if (typeof error === "object" && error !== null) return error;
+	return {
+		statusCode: 500,
+		message: String(error)
+	};
+}
+function resolveStatusCode(error) {
+	const statusCode = error.statusCode || error.status;
+	if (!statusCode || statusCode < 400) return 500;
+	return statusCode;
+}
+function fillClientError(data, error) {
+	data.name = error.name;
+	data.message = error.message;
+	data.code = error.code;
+	data.details = error.details;
+}
+function fillServerError(data, error) {
+	if (error.expose) {
+		data.name = node_http.STATUS_CODES[data.statusCode] || "Unknown Error";
+		data.message = error.message;
+	} else data.message = node_http.STATUS_CODES[data.statusCode] || "Unknown Error";
+}
+function fillSafeFields(data, error, safeFields) {
+	if (!safeFields) return;
+	const fields = Array.isArray(safeFields) ? safeFields : [safeFields];
+	for (let index = 0; index < fields.length; index += 1) {
+		const field = fields[index];
+		if (error[field] !== void 0) data[field] = error[field];
+	}
+}
+//#endregion
+//#region src/lib/logger.ts
+function logToConsole(req, error) {
+	if (!Array.isArray(error)) {
+		console.error("Request %s %s failed: %s", req.method, req.url, formatError(error));
+		return;
+	}
+	const errors = error.map(formatError).join("\n");
+	console.error("Request %s %s failed with multiple errors:\n%s", req.method, req.url, errors);
+}
+function formatError(error) {
+	if (typeof error === "object" && error !== null && "stack" in error) return node_util.default.format("%s", error.stack || error);
+	return node_util.default.format("%s", error);
+}
+//#endregion
+//#region src/lib/send-html.ts
+const assetDir = node_path.default.resolve(__dirname, "../views");
+const standardProps = new Set([
+	"name",
+	"statusCode",
+	"message",
+	"stack"
+]);
+const stylesPartial = node_fs.default.readFileSync(node_path.default.join(assetDir, "style.hbs"), "utf8");
+const defaultTemplate = handlebars.default.compile(node_fs.default.readFileSync(node_path.default.join(assetDir, "default-error.hbs"), "utf8"));
+handlebars.default.registerHelper("partial", function partial(name) {
+	if (name === "style") return stylesPartial;
+	return "";
+});
+handlebars.default.registerHelper("standardProps", function standardPropsHelper(property, options) {
+	if (!standardProps.has(property)) return options.fn(this);
+	return options.inverse(this);
+});
+function sendHtml(res, data, options = {}) {
+	const filteredData = {};
+	for (const key in data) {
+		const value = data[key];
+		if (value !== void 0 && value !== null || standardProps.has(key)) filteredData[key] = value;
+	}
+	const body = defaultTemplate({
+		options,
+		data: filteredData
+	});
+	res.setHeader("Content-Type", "text/html; charset=utf-8");
+	res.end(body, "utf-8");
+}
+//#endregion
+//#region src/lib/safe-json-stringify.ts
+const circularMarker = "[Circular]";
+function safeJsonStringify(value) {
+	try {
+		return JSON.stringify(value);
+	} catch (error) {
+		if (!isCircularJsonStringifyError(error)) throw error;
+	}
+	return JSON.stringify(value, createCircularReplacer());
+}
+function createCircularReplacer() {
+	const ancestors = [];
+	const activeAncestors = /* @__PURE__ */ new WeakSet();
+	return function circularReplacer(_key, value) {
+		if (typeof value !== "object" || value === null) return value;
+		while (ancestors.length > 0 && ancestors[ancestors.length - 1] !== this) {
+			const ancestor = ancestors.pop();
+			if (ancestor) activeAncestors.delete(ancestor);
+		}
+		if (activeAncestors.has(value)) return circularMarker;
+		ancestors.push(value);
+		activeAncestors.add(value);
+		return value;
+	};
+}
+function isCircularJsonStringifyError(error) {
+	return error instanceof TypeError && (error.message.includes("circular") || error.message.includes("Circular"));
+}
+//#endregion
+//#region src/lib/send-json.ts
+function sendJson(res, data, options = {}) {
+	const content = options.rootProperty === false ? safeJsonStringify(data) : safeJsonStringify({ [options.rootProperty || "error"]: data });
+	res.setHeader("Content-Type", "application/json; charset=utf-8");
+	res.end(content, "utf-8");
+}
+//#endregion
+//#region src/lib/send-xml.ts
+const js2xmlparser = require("js2xmlparser");
+function sendXml(res, data, options = {}) {
+	const root = options.rootProperty || "error";
+	const content = js2xmlparser.parse(root, data);
+	res.setHeader("Content-Type", "text/xml; charset=utf-8");
+	res.end(content, "utf-8");
+}
+//#endregion
+//#region src/lib/content-negotiation.ts
+const debug$2 = (0, debug.default)("strong-error-handler:http-response");
+const supportedTypes = [
+	"application/json",
+	"json",
+	"text/html",
+	"html",
+	"text/xml",
+	"xml"
+];
+const supportedTypeSet = new Set(supportedTypes);
+function negotiateContentProducer(req, logWarning, options = {}) {
+	let defaultType = "json";
+	if (typeof options.defaultType === "string" && supportedTypeSet.has(options.defaultType)) {
+		debug$2("Accepting options.defaultType `%s`", options.defaultType);
+		defaultType = options.defaultType;
+	} else if (options.defaultType) debug$2("defaultType: `%s` is not supported, falling back to defaultType: `%s`", options.defaultType, defaultType);
+	let contentType = (0, accepts.default)(req).types([...supportedTypes]) || defaultType;
+	if (options.negotiateContentType === false) if (typeof options.defaultType === "string" && supportedTypeSet.has(options.defaultType)) {
+		contentType = options.defaultType;
+		debug$2("Forcing options.defaultType `%s`", options.defaultType);
+	} else debug$2("contentType: `%s` is not supported, falling back to contentType: `%s`", options.defaultType, contentType);
+	const query = req.query || {};
+	if (typeof query._format === "string") if (supportedTypeSet.has(query._format)) contentType = query._format;
+	else logWarning(node_util.default.format("Response _format \"%s\" is not supported, used \"%s\" instead", query._format, defaultType));
+	debug$2("Content-negotiation: req.headers.accept: `%s` resolved as: `%s`", req.headers?.accept, contentType);
+	return resolveOperation(contentType);
+}
+function resolveOperation(contentType) {
+	switch (contentType) {
+		case "application/json":
+		case "json": return sendJson;
+		case "text/html":
+		case "html": return sendHtml;
+		case "text/xml":
+		case "xml": return sendXml;
+		default: return sendJson;
+	}
+}
+//#endregion
+//#region src/lib/handler.ts
+const debug$1 = (0, debug.default)("strong-error-handler");
+function createStrongErrorHandler(options = {}) {
+	debug$1("Initializing with options %j", options);
+	const logError = options.log !== false ? logToConsole : noop;
+	return function strongErrorHandler(error, req, res) {
+		logError(req, error);
+		writeErrorToResponse(error, req, res, options);
+	};
+}
+function writeErrorToResponse(error, req, res, options = {}) {
+	debug$1("Handling %s", getDebugValue(error));
+	if (res.headersSent) {
+		debug$1("Response was already sent, closing the underlying connection");
+		req.socket?.destroy?.();
+		return;
+	}
+	const data = buildResponseData(coerceWritableError(error, res.statusCode), options);
+	debug$1("Response status %s data %j", data.statusCode, data);
+	res.setHeader("X-Content-Type-Options", "nosniff");
+	res.statusCode = data.statusCode;
+	negotiateContentProducer(req, warn, options)(res, data, options);
+	function warn(message) {
+		res.setHeader("X-Warning", message);
+		debug$1(message);
+	}
+}
+function noop() {}
+function getDebugValue(error) {
+	if (typeof error === "object" && error !== null && "stack" in error) return error.stack || error;
+	return error;
+}
+function coerceWritableError(error, responseStatusCode) {
+	if (typeof error !== "object" || error === null) return {
+		statusCode: responseStatusCode >= 400 ? responseStatusCode : 500,
+		message: String(error)
+	};
+	const writableError = error;
+	if (!writableError.status && !writableError.statusCode && responseStatusCode >= 400) writableError.statusCode = responseStatusCode;
+	return writableError;
+}
+//#endregion
+//#region src/index.ts
+const strongErrorHandler = Object.assign(createStrongErrorHandler, { writeErrorToResponse });
+module.exports = strongErrorHandler;
+//#endregion

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@vsaas/error-handler",
+  "version": "10.0.0",
+  "description": "Error handler for use in development and production environments.",
+  "license": "MIT",
+  "author": "IBM Corp.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xompass/strong-error-handler"
+  },
+  "files": [
+    "dist",
+    "views",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "accepts": "^1.3.8",
+    "debug": "^4.4.3",
+    "handlebars": "^4.7.9",
+    "js2xmlparser": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "25.5.0",
+    "oxfmt": "0.42.0",
+    "oxlint": "1.57.0",
+    "supertest": "7.2.2",
+    "tsdown": "0.21.5",
+    "typescript": "6.0.2",
+    "vitest": "4.1.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "fmt": "oxfmt -c ../.oxfmtrc.json .",
+    "lint": "oxlint -c ../.oxlintrc.json src test",
+    "lint:fix": "oxlint -c ../.oxlintrc.json src test --fix",
+    "test:run": "vitest run",
+    "test": "pnpm run build && vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}

package/views/default-error.hbs

@@ -0,0 +1,26 @@
+<html>
+  <head>
+    <meta charset='utf-8' />
+    <title>{{data.name}}{{#unless data.name}}{{data.message}}{{/unless}}</title>
+    <style>
+      {{partial 'style'}}
+    </style>
+  </head>
+  <body>
+    <div id='wrapper'>
+      <h1>{{data.name}}</h1>
+      <h2>
+        <em>{{data.statusCode}}</em>
+        {{data.message}}
+      </h2>
+      {{#each data}}
+        {{#standardProps @key}}
+          <div><b>{{@key}}</b>: {{this}}</div>
+        {{/standardProps}}
+      {{/each}}
+      {{#if data.stack}}
+        <pre id='stacktrace'>{{{data.stack}}}</pre>
+      {{/if}}
+    </div>
+  </body>
+</html>

package/views/style.hbs

@@ -0,0 +1,7 @@
+* { margin: 0; padding: 0; outline: 0; } body { padding: 80px 100px; font: 13px
+"Helvetica Neue", "Lucida Grande", "Arial"; background: #ECE9E9
+-webkit-gradient(linear, 0% 0%, 0% 100%, from(#fff), to(#ECE9E9)); background:
+#ECE9E9 -moz-linear-gradient(top, #fff, #ECE9E9); background-repeat: no-repeat;
+color: #555; -webkit-font-smoothing: antialiased; } h1, h2 { font-size: 22px;
+color: #343434; } h1 em, h2 em { padding: 0 5px; font-weight: normal; } h1 {
+font-size: 60px; } h2 { margin: 10px 0; } ul li { list-style: none; }