woodland 22.1.1 → 22.2.1

package/README.md

@@ -155,6 +155,22 @@ app.use((error, req, res, next) => {
 });
 ```
 
+### Global Error Handling
+
+Set `app.error` to intercept all unhandled errors before the error middleware chain:
+
+```javascript
+const app = woodland();
+
+app.error = (err, _req, res) => {
+  console.error("Unhandled error:", err);
+  res.status(500).send("Internal server error");
+};
+```
+
+The handler receives 3 arguments `(err, req, res)` and must terminate the request itself. When set, the error middleware chain is skipped.
+
+
 ## Configuration
 
 ```javascript
@@ -196,6 +212,7 @@ req.cors;       // CORS enabled
 req.body;       // Request body
 req.host;       // Hostname
 req.valid;      // Request validity
+req.app;        // Woodland application instance (provides access to app.error)
 ```
 
 ## Event Handlers
@@ -262,7 +279,7 @@ npm run lint          # Check linting
 ## Documentation
 
 - [API Reference](docs/API.md) - Complete method documentation
-- [Technical Documentation](docs/TECHNICAL_DOCUMENTATION.md) - Architecture, OWASP security, internals
+- [Framework Overview](docs/OVERVIEW.md) - Architecture, OWASP security, internals
 - [Code Style Guide](docs/CODE_STYLE_GUIDE.md) - Conventions and best practices
 - [Benchmarks](docs/BENCHMARKS.md) - Performance testing results
 

package/dist/cli.cjs

@@ -4,7 +4,7 @@
  *
  * @copyright 2026 Jason Mulligan <jason.mulligan@avoidwork.com>
  * @license BSD-3-Clause
- * @version 22.1.1
+ * @version 22.2.1
  */
 'use strict';
 

package/dist/woodland.cjs

@@ -3,7 +3,7 @@
  *
  * @copyright 2026 Jason Mulligan <jason.mulligan@avoidwork.com>
  * @license BSD-3-Clause
- * @version 22.1.1
+ * @version 22.2.1
  */
 'use strict';
 
@@ -165,6 +165,7 @@ const NEWLINE = "\n";
 const ROUTE_PATTERN = "(/.*)?";
 const MSG_USE_MIDDLEWARE_REQUIRED =
 	"useMiddleware is required or config.use must be a function";
+const MSG_MIDDLEWARE_REQUIRED = "Expected a function in the parameters";
 const EXTRACT_PATH_REPLACE = "(?<$1>[^/]+)";
 const TPL_DIR = "tpl";
 const INDEX_HTML_FILE = "index.html";
@@ -1163,6 +1164,10 @@ function next(req, res, middleware, immediate = false) {
 	 */
 	const execute = (err) => {
 		if (err !== void 0) {
+			if (typeof req.app?.error === FUNCTION) {
+				req.app.error(err, req, res);
+				return;
+			}
 			handleError(err, execute);
 		} else {
 			handleMiddleware(execute);
@@ -1471,10 +1476,15 @@ function validateLogging(logging = {}) {
 	const envLogFormat = process.env.WOODLAND_LOG_FORMAT;
 	const envLogLevel = process.env.WOODLAND_LOG_LEVEL;
 
-	const enabled = logging.enabled ?? (envLogEnabled ?? TRUE) !== FALSE;
+	const enabled =
+		envLogEnabled !== undefined
+			? envLogEnabled !== FALSE
+			: logging.enabled !== undefined
+				? logging.enabled !== false
+				: TRUE !== FALSE;
 
-	const format = resolveLoggingValue(logging.format, envLogFormat, LOG_FORMAT);
-	const level = resolveLoggingValue(logging.level, envLogLevel, INFO);
+	const format = resolveLoggingValue(envLogFormat, logging.format, LOG_FORMAT);
+	const level = resolveLoggingValue(envLogLevel, logging.level, INFO);
 
 	if (!VALID_LOG_LEVELS.has(level)) {
 		return Object.freeze({ enabled, format, level: INFO });
@@ -1884,6 +1894,7 @@ class Woodland extends node_events.EventEmitter {
 	#logger;
 	#fileServer;
 	#middleware;
+	#error;
 
 	/**
 	 * Creates a new Woodland instance
@@ -1930,6 +1941,7 @@ class Woodland extends node_events.EventEmitter {
 		this.#logger = this.#createLogger();
 		this.#fileServer = this.#createFileServer();
 		this.#middleware = createMiddlewareRegistry(this.#methods, this.#cache);
+		this.#error = null;
 
 		this.#setupMiddleware();
 		this.#setupErrorHandling();
@@ -2103,6 +2115,10 @@ class Woodland extends node_events.EventEmitter {
 	 * @returns {Woodland} Returns self for chaining
 	 */
 	#registerMethod(method, ...args) {
+		if (args.length === INT_1 && typeof args[INT_0] === STRING) {
+			throw new TypeError(MSG_MIDDLEWARE_REQUIRED);
+		}
+
 		return this.use(...args, method);
 	}
 
@@ -2133,7 +2149,7 @@ class Woodland extends node_events.EventEmitter {
 		req.host = parsed.hostname;
 		req.params = {};
 		req.valid = true;
-		req.app = { get: (key) => (key === "trust proxy" ? false : undefined) };
+		req.app = this;
 
 		const allowString = this.#allows(parsed.pathname);
 		const headersBatch = Object.create(null);
@@ -2550,6 +2566,19 @@ class Woodland extends node_events.EventEmitter {
 	get logger() {
 		return this.#logger;
 	}
+
+	/**
+	 * Global error handler property
+	 * @param {Function} [fn] - Error handler function
+	 * @returns {Function|null} Current error handler or null
+	 */
+	get error() {
+		return this.#error;
+	}
+
+	set error(fn) {
+		this.#error = typeof fn === FUNCTION ? fn : null;
+	}
 }
 
 /**

package/dist/woodland.js

@@ -3,7 +3,7 @@
  *
  * @copyright 2026 Jason Mulligan <jason.mulligan@avoidwork.com>
  * @license BSD-3-Clause
- * @version 22.1.1
+ * @version 22.2.1
  */
 import {STATUS_CODES}from'node:http';import {EventEmitter}from'node:events';import {readFileSync,createReadStream}from'node:fs';import {etag}from'tiny-etag';import {lru}from'tiny-lru';import {precise}from'precise';import {createRequire}from'node:module';import {join,extname,resolve,sep}from'node:path';import {fileURLToPath,URL as URL$1}from'node:url';import mimeDb from'mime-db';import {coerce}from'tiny-coerce';import {Validator}from'jsonschema';import {realpath,stat,readdir}from'node:fs/promises';const __dirname$2 = fileURLToPath(new URL$1(".", import.meta.url));
 const require$1 = createRequire(import.meta.url);
@@ -148,6 +148,7 @@ const NEWLINE = "\n";
 const ROUTE_PATTERN = "(/.*)?";
 const MSG_USE_MIDDLEWARE_REQUIRED =
 	"useMiddleware is required or config.use must be a function";
+const MSG_MIDDLEWARE_REQUIRED = "Expected a function in the parameters";
 const EXTRACT_PATH_REPLACE = "(?<$1>[^/]+)";
 const TPL_DIR = "tpl";
 const INDEX_HTML_FILE = "index.html";
@@ -1140,6 +1141,10 @@ function next(req, res, middleware, immediate = false) {
 	 */
 	const execute = (err) => {
 		if (err !== void 0) {
+			if (typeof req.app?.error === FUNCTION) {
+				req.app.error(err, req, res);
+				return;
+			}
 			handleError(err, execute);
 		} else {
 			handleMiddleware(execute);
@@ -1446,10 +1451,15 @@ function validateLogging(logging = {}) {
 	const envLogFormat = process.env.WOODLAND_LOG_FORMAT;
 	const envLogLevel = process.env.WOODLAND_LOG_LEVEL;
 
-	const enabled = logging.enabled ?? (envLogEnabled ?? TRUE) !== FALSE;
+	const enabled =
+		envLogEnabled !== undefined
+			? envLogEnabled !== FALSE
+			: logging.enabled !== undefined
+				? logging.enabled !== false
+				: TRUE !== FALSE;
 
-	const format = resolveLoggingValue(logging.format, envLogFormat, LOG_FORMAT);
-	const level = resolveLoggingValue(logging.level, envLogLevel, INFO);
+	const format = resolveLoggingValue(envLogFormat, logging.format, LOG_FORMAT);
+	const level = resolveLoggingValue(envLogLevel, logging.level, INFO);
 
 	if (!VALID_LOG_LEVELS.has(level)) {
 		return Object.freeze({ enabled, format, level: INFO });
@@ -1853,6 +1863,7 @@ class Woodland extends EventEmitter {
 	#logger;
 	#fileServer;
 	#middleware;
+	#error;
 
 	/**
 	 * Creates a new Woodland instance
@@ -1899,6 +1910,7 @@ class Woodland extends EventEmitter {
 		this.#logger = this.#createLogger();
 		this.#fileServer = this.#createFileServer();
 		this.#middleware = createMiddlewareRegistry(this.#methods, this.#cache);
+		this.#error = null;
 
 		this.#setupMiddleware();
 		this.#setupErrorHandling();
@@ -2072,6 +2084,10 @@ class Woodland extends EventEmitter {
 	 * @returns {Woodland} Returns self for chaining
 	 */
 	#registerMethod(method, ...args) {
+		if (args.length === INT_1 && typeof args[INT_0] === STRING) {
+			throw new TypeError(MSG_MIDDLEWARE_REQUIRED);
+		}
+
 		return this.use(...args, method);
 	}
 
@@ -2102,7 +2118,7 @@ class Woodland extends EventEmitter {
 		req.host = parsed.hostname;
 		req.params = {};
 		req.valid = true;
-		req.app = { get: (key) => (key === "trust proxy" ? false : undefined) };
+		req.app = this;
 
 		const allowString = this.#allows(parsed.pathname);
 		const headersBatch = Object.create(null);
@@ -2519,6 +2535,19 @@ class Woodland extends EventEmitter {
 	get logger() {
 		return this.#logger;
 	}
+
+	/**
+	 * Global error handler property
+	 * @param {Function} [fn] - Error handler function
+	 * @returns {Function|null} Current error handler or null
+	 */
+	get error() {
+		return this.#error;
+	}
+
+	set error(fn) {
+		this.#error = typeof fn === FUNCTION ? fn : null;
+	}
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "woodland",
-  "version": "22.1.1",
+  "version": "22.2.1",
   "description": "Secure HTTP framework for Node.js. Express-compatible with built-in security, no performance tradeoff.",
   "keywords": [
     "api",
@@ -58,7 +58,7 @@
     "prebuild": "npm run clean",
     "rollup": "rollup --config",
     "sample": "node sample.js",
-    "test": "npm run lint && node --test tests/**/*.test.js",
+    "test": "npm run lint && WOODLAND_LOG_ENABLED=false node --test tests/**/*.test.js",
     "test:cli": "node --test tests/unit/cli.test.js",
     "test:watch": "node --test --watch tests/**/*.test.js"
   },
@@ -73,7 +73,7 @@
   "devDependencies": {
     "auto-changelog": "^2.5.0",
     "husky": "^9.1.7",
-    "oxfmt": "^0.49.0",
+    "oxfmt": "^0.51.0",
     "oxlint": "^1.57.0",
     "rimraf": "^6.1.3",
     "rollup": "^4.60.0"

package/types/woodland.d.ts

@@ -49,6 +49,9 @@ export class Woodland extends EventEmitter {
 		clf: (...args: any[]) => string;
 	}>;
 
+	// Public error handler property (getter/setter)
+	error: ((err: Error, req: any, res: any) => void) | null;
+
 	constructor(config?: WoodlandConfig);
 
 	// Public routing methods - with path