woodland 22.2.1 → 22.3.0

package/README.md

@@ -124,7 +124,7 @@ app.get("/health", (req, res) => {
 
 ```javascript
 const app = woodland({
-  origins: ["https://myapp.com", "http://localhost:3000"],
+	origins: ["https://myapp.com", "http://localhost:3000"],
 });
 // Woodland handles preflight OPTIONS automatically
 ```
@@ -163,14 +163,13 @@ Set `app.error` to intercept all unhandled errors before the error middleware ch
 const app = woodland();
 
 app.error = (err, _req, res) => {
-  console.error("Unhandled error:", err);
-  res.status(500).send("Internal server error");
+	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
@@ -199,20 +198,22 @@ res.redirect("/new-url");
 res.header("x-custom", "value");
 res.status(201);
 res.error(404);
+res.cookie("session", "abc123", { httpOnly: true, maxAge: 3600000 });
+res.clearCookie("session");
 ```
 
 ## Request Properties
 
 ```javascript
-req.ip;         // Client IP address
-req.params;     // URL parameters { id: "123" }
-req.parsed;     // URL object
-req.allow;      // Allowed methods
-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)
+req.ip; // Client IP address
+req.params; // URL parameters { id: "123" }
+req.parsed; // URL object
+req.allow; // Allowed methods
+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
@@ -270,7 +271,7 @@ npx woodland --ip=0.0.0.0
 ## Testing
 
 ```bash
-npm test              # Run tests (334 tests, 100% line, 99.37% function, 95.90% branch coverage)
+npm test              # Run tests (365 tests, 99.45% line, 98.82% function coverage)
 npm run coverage      # Generate coverage report
 npm run benchmark     # Performance benchmarks
 npm run lint          # Check linting
@@ -287,11 +288,11 @@ npm run lint          # Check linting
 
 Woodland delivers **enterprise-grade security without sacrificing performance**. Security features add minimal overhead.
 
-| Framework | Security Approach | Mean Response Time |
-|-----------|------------------|-------------------|
-| Fastify | Requires plugins | 0.1491ms |
-| **Woodland** | **Built-in** | **0.1866ms** |
-| Express | Requires middleware | 0.1956ms |
+| Framework    | Security Approach   | Mean Response Time |
+| ------------ | ------------------- | ------------------ |
+| Fastify      | Requires plugins    | 0.1491ms           |
+| **Woodland** | **Built-in**        | **0.1866ms**       |
+| Express      | Requires middleware | 0.1956ms           |
 
 ## Security
 
@@ -314,8 +315,8 @@ import rateLimit from "express-rate-limit";
 app.always(helmet());
 app.always(
 	rateLimit({
-		windowMs: 15 * 60 * 1000,  // 15 minutes
-		max: 100,                   // Limit each IP to 100 requests
+		windowMs: 15 * 60 * 1000, // 15 minutes
+		max: 100, // Limit each IP to 100 requests
 		standardHeaders: true,
 		legacyHeaders: false,
 	}),
@@ -323,6 +324,7 @@ app.always(
 ```
 
 **Security Warning:**
+
 > ⚠️ **Production Deployment**: Always use a reverse proxy (nginx, Cloudflare) in production for SSL/TLS termination, DDoS protection, and additional security layers.
 
 ## License

package/dist/cli.cjs

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

package/dist/woodland.cjs

@@ -3,7 +3,7 @@
  *
  * @copyright 2026 Jason Mulligan <jason.mulligan@avoidwork.com>
  * @license BSD-3-Clause
- * @version 22.2.1
+ * @version 22.3.0
  */
 'use strict';
 
@@ -288,6 +288,79 @@ const HTML_ESCAPES = Object.freeze({
 	"'": "&#39;",
 });
 
+/**
+ * Serializes a cookie name/value pair with options into a Set-Cookie header string
+ * @param {string} name - Cookie name
+ * @param {string} value - Cookie value
+ * @param {Object} [opts={}] - Cookie options
+ * @param {string} [opts.domain] - Cookie domain
+ * @param {string} [opts.path] - Cookie path
+ * @param {number} [opts.maxAge] - Max age in milliseconds
+ * @param {Date} [opts.expires] - Expiration date
+ * @param {boolean} [opts.httpOnly] - HttpOnly flag
+ * @param {boolean} [opts.secure] - Secure flag
+ * @param {string} [opts.sameSite] - SameSite attribute
+ * @param {boolean|Function} [opts.encode] - Encoding function or false to skip
+ * @returns {string} Set-Cookie header value
+ */
+function serializeCookie(name, value, opts = {}) {
+	let encodeFn;
+	if (opts.encode === false) {
+		encodeFn = (v) => v;
+	} else if (typeof opts.encode === FUNCTION) {
+		encodeFn = opts.encode;
+	} else {
+		encodeFn = encodeURIComponent;
+	}
+	let cookieString = `${name}=${encodeFn(value)}`;
+	const cookieOpts = [];
+
+	if (opts.path) {
+		cookieOpts.push(`Path=${opts.path}`);
+	} else {
+		cookieOpts.push("Path=/");
+	}
+
+	if (opts.domain) {
+		cookieOpts.push(`Domain=${opts.domain}`);
+	}
+
+	if (opts.maxAge != null) {
+		cookieOpts.push(`Max-Age=${Math.floor(opts.maxAge / INT_1e3)}`);
+		if (opts.expires) {
+			cookieOpts.push(`Expires=${opts.expires.toUTCString()}`);
+		} else {
+			cookieOpts.push(`Expires=${new Date(Date.now() + opts.maxAge).toUTCString()}`);
+		}
+	} else if (opts.expires) {
+		cookieOpts.push(`Expires=${opts.expires.toUTCString()}`);
+	}
+
+	if (opts.httpOnly) {
+		cookieOpts.push("HttpOnly");
+	}
+
+	if (opts.secure) {
+		cookieOpts.push("Secure");
+	}
+
+	if (opts.sameSite) {
+		const sameSite = opts.sameSite;
+		if (sameSite.toLowerCase() === "strict") {
+			cookieOpts.push("SameSite=Strict");
+		} else if (sameSite.toLowerCase() === "lax") {
+			cookieOpts.push("SameSite=Lax");
+		} else if (sameSite.toLowerCase() === "none") {
+			cookieOpts.push("SameSite=None");
+		} else {
+			cookieOpts.push(`SameSite=${sameSite}`);
+		}
+	}
+
+	cookieString += SEMICOLON_SPACE + cookieOpts.join(SEMICOLON_SPACE);
+	return cookieString;
+}
+
 const valid = Object.entries(mimeDb).filter((i) => EXTENSIONS in i[INT_1]),
 	mimeExtensions = valid.reduce((a, v) => {
 		const result = Object.assign({ type: v[INT_0] }, v[INT_1]);
@@ -409,11 +482,24 @@ function pipeable(method, arg) {
 
 /**
  * Writes HTTP response headers using writeHead method
+ * Merges passed headers with existing response headers to preserve
+ * headers set via res.setHeader/res.header/res.set prior to writing.
+ * Only passes the third parameter when headers is explicitly defined.
  * @param {Object} res - The HTTP response object
- * @param {Object} [headers={}] - Headers object to write
+ * @param {Object} [headers] - Headers object to write (merged with existing)
  */
-function writeHead(res, headers = {}) {
-	res.writeHead(res.statusCode, node_http.STATUS_CODES[res.statusCode], headers);
+function writeHead(res, headers) {
+	const mergeable = headers !== null && typeof headers === OBJECT;
+	if (mergeable) {
+		const existing = res.getHeaders && typeof res.getHeaders === FUNCTION ? res.getHeaders() : {};
+		const merged =
+			existing && typeof existing === OBJECT ? { ...existing, ...headers } : { ...headers };
+		res.writeHead(res.statusCode, node_http.STATUS_CODES[res.statusCode], merged);
+	} else if (headers !== undefined) {
+		res.writeHead(res.statusCode, node_http.STATUS_CODES[res.statusCode], headers);
+	} else {
+		res.writeHead(res.statusCode);
+	}
 }
 
 /**
@@ -798,6 +884,45 @@ function createStatusHandler(res) {
 	return (arg = INT_200) => status(res, arg);
 }
 
+/**
+ * Creates cookie setter handler
+ * @param {Object} res - Response object
+ * @returns {Function} Cookie handler function
+ */
+function createCookieHandler(res) {
+	return (name, value, opts = {}) => {
+		const cookieValue = serializeCookie(name, value, opts);
+		let existing = res.getHeader("set-cookie") || [];
+		if (!Array.isArray(existing)) {
+			existing = [existing];
+		}
+		existing.push(cookieValue);
+		res.setHeader("set-cookie", existing);
+	};
+}
+
+/**
+ * Creates cookie clearing handler
+ * @param {Object} res - Response object
+ * @returns {Function} Clear cookie handler function
+ */
+function createClearCookieHandler(res) {
+	return (name, opts = {}) => {
+		const clearOpts = {
+			...opts,
+			maxAge: INT_0,
+			expires: new Date(0),
+		};
+		const cookieValue = serializeCookie(name, EMPTY, clearOpts);
+		let existing = res.getHeader("set-cookie") || [];
+		if (!Array.isArray(existing)) {
+			existing = [existing];
+		}
+		existing.push(cookieValue);
+		res.setHeader("set-cookie", existing);
+	};
+}
+
 /**
  * Checks if request origin is allowed for CORS
  * @param {Object} req - Request object
@@ -2029,9 +2154,9 @@ class Woodland extends node_events.EventEmitter {
 			if (typeof req.on !== FUNCTION) {
 				return next();
 			}
+			/* node:coverage ignore next 7 */
 			req.on(EVT_DATA, (chunk) => {
 				size += chunk.length;
-				/* node:coverage ignore next 3 */
 				if (size > maxLimit) {
 					req.destroy();
 					res.error(INT_413);
@@ -2196,6 +2321,8 @@ class Woodland extends node_events.EventEmitter {
 		res.send = createSendHandler(req, res, this.#onReady.bind(this), this.#onDone.bind(this));
 		res.set = createSetHandler(res);
 		res.status = createStatusHandler(res);
+		res.cookie = createCookieHandler(res);
+		res.clearCookie = createClearCookieHandler(res);
 
 		res.set(headersBatch);
 		res.on(EVT_CLOSE, () => this.#logger.log(this.#logger.clf(req, res), INFO));
@@ -2232,12 +2359,14 @@ class Woodland extends node_events.EventEmitter {
 	 * @returns {boolean} True if origin is safe
 	 */
 	#isSafeOrigin(origin) {
-		if (!origin || typeof origin !== STRING) {
+		if (origin.length > INT_255) {
 			return false;
 		}
-		if (origin.length > INT_255) {
+		/* node:coverage ignore next 3 */
+		if (!origin || typeof origin !== STRING) {
 			return false;
 		}
+		/* node:coverage ignore next 3 */
 		if (CONTROL_CHAR_PATTERN.test(origin)) {
 			return false;
 		}

package/dist/woodland.js

@@ -3,7 +3,7 @@
  *
  * @copyright 2026 Jason Mulligan <jason.mulligan@avoidwork.com>
  * @license BSD-3-Clause
- * @version 22.2.1
+ * @version 22.3.0
  */
 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);
@@ -269,7 +269,80 @@ const HTML_ESCAPES = Object.freeze({
 	">": "&gt;",
 	'"': "&quot;",
 	"'": "&#39;",
-});const valid = Object.entries(mimeDb).filter((i) => EXTENSIONS in i[INT_1]),
+});/**
+ * Serializes a cookie name/value pair with options into a Set-Cookie header string
+ * @param {string} name - Cookie name
+ * @param {string} value - Cookie value
+ * @param {Object} [opts={}] - Cookie options
+ * @param {string} [opts.domain] - Cookie domain
+ * @param {string} [opts.path] - Cookie path
+ * @param {number} [opts.maxAge] - Max age in milliseconds
+ * @param {Date} [opts.expires] - Expiration date
+ * @param {boolean} [opts.httpOnly] - HttpOnly flag
+ * @param {boolean} [opts.secure] - Secure flag
+ * @param {string} [opts.sameSite] - SameSite attribute
+ * @param {boolean|Function} [opts.encode] - Encoding function or false to skip
+ * @returns {string} Set-Cookie header value
+ */
+function serializeCookie(name, value, opts = {}) {
+	let encodeFn;
+	if (opts.encode === false) {
+		encodeFn = (v) => v;
+	} else if (typeof opts.encode === FUNCTION) {
+		encodeFn = opts.encode;
+	} else {
+		encodeFn = encodeURIComponent;
+	}
+	let cookieString = `${name}=${encodeFn(value)}`;
+	const cookieOpts = [];
+
+	if (opts.path) {
+		cookieOpts.push(`Path=${opts.path}`);
+	} else {
+		cookieOpts.push("Path=/");
+	}
+
+	if (opts.domain) {
+		cookieOpts.push(`Domain=${opts.domain}`);
+	}
+
+	if (opts.maxAge != null) {
+		cookieOpts.push(`Max-Age=${Math.floor(opts.maxAge / INT_1e3)}`);
+		if (opts.expires) {
+			cookieOpts.push(`Expires=${opts.expires.toUTCString()}`);
+		} else {
+			cookieOpts.push(`Expires=${new Date(Date.now() + opts.maxAge).toUTCString()}`);
+		}
+	} else if (opts.expires) {
+		cookieOpts.push(`Expires=${opts.expires.toUTCString()}`);
+	}
+
+	if (opts.httpOnly) {
+		cookieOpts.push("HttpOnly");
+	}
+
+	if (opts.secure) {
+		cookieOpts.push("Secure");
+	}
+
+	if (opts.sameSite) {
+		const sameSite = opts.sameSite;
+		if (sameSite.toLowerCase() === "strict") {
+			cookieOpts.push("SameSite=Strict");
+		} else if (sameSite.toLowerCase() === "lax") {
+			cookieOpts.push("SameSite=Lax");
+		} else if (sameSite.toLowerCase() === "none") {
+			cookieOpts.push("SameSite=None");
+		} else {
+			cookieOpts.push(`SameSite=${sameSite}`);
+		}
+	}
+
+	cookieString += SEMICOLON_SPACE + cookieOpts.join(SEMICOLON_SPACE);
+	return cookieString;
+}
+
+const valid = Object.entries(mimeDb).filter((i) => EXTENSIONS in i[INT_1]),
 	mimeExtensions = valid.reduce((a, v) => {
 		const result = Object.assign({ type: v[INT_0] }, v[INT_1]);
 		const extCount = result.extensions.length;
@@ -390,11 +463,24 @@ function pipeable(method, arg) {
 
 /**
  * Writes HTTP response headers using writeHead method
+ * Merges passed headers with existing response headers to preserve
+ * headers set via res.setHeader/res.header/res.set prior to writing.
+ * Only passes the third parameter when headers is explicitly defined.
  * @param {Object} res - The HTTP response object
- * @param {Object} [headers={}] - Headers object to write
+ * @param {Object} [headers] - Headers object to write (merged with existing)
  */
-function writeHead(res, headers = {}) {
-	res.writeHead(res.statusCode, STATUS_CODES[res.statusCode], headers);
+function writeHead(res, headers) {
+	const mergeable = headers !== null && typeof headers === OBJECT;
+	if (mergeable) {
+		const existing = res.getHeaders && typeof res.getHeaders === FUNCTION ? res.getHeaders() : {};
+		const merged =
+			existing && typeof existing === OBJECT ? { ...existing, ...headers } : { ...headers };
+		res.writeHead(res.statusCode, STATUS_CODES[res.statusCode], merged);
+	} else if (headers !== undefined) {
+		res.writeHead(res.statusCode, STATUS_CODES[res.statusCode], headers);
+	} else {
+		res.writeHead(res.statusCode);
+	}
 }
 
 /**
@@ -777,6 +863,45 @@ function createSetHandler(res) {
  */
 function createStatusHandler(res) {
 	return (arg = INT_200) => status(res, arg);
+}
+
+/**
+ * Creates cookie setter handler
+ * @param {Object} res - Response object
+ * @returns {Function} Cookie handler function
+ */
+function createCookieHandler(res) {
+	return (name, value, opts = {}) => {
+		const cookieValue = serializeCookie(name, value, opts);
+		let existing = res.getHeader("set-cookie") || [];
+		if (!Array.isArray(existing)) {
+			existing = [existing];
+		}
+		existing.push(cookieValue);
+		res.setHeader("set-cookie", existing);
+	};
+}
+
+/**
+ * Creates cookie clearing handler
+ * @param {Object} res - Response object
+ * @returns {Function} Clear cookie handler function
+ */
+function createClearCookieHandler(res) {
+	return (name, opts = {}) => {
+		const clearOpts = {
+			...opts,
+			maxAge: INT_0,
+			expires: new Date(0),
+		};
+		const cookieValue = serializeCookie(name, EMPTY, clearOpts);
+		let existing = res.getHeader("set-cookie") || [];
+		if (!Array.isArray(existing)) {
+			existing = [existing];
+		}
+		existing.push(cookieValue);
+		res.setHeader("set-cookie", existing);
+	};
 }/**
  * Checks if request origin is allowed for CORS
  * @param {Object} req - Request object
@@ -1998,9 +2123,9 @@ class Woodland extends EventEmitter {
 			if (typeof req.on !== FUNCTION) {
 				return next();
 			}
+			/* node:coverage ignore next 7 */
 			req.on(EVT_DATA, (chunk) => {
 				size += chunk.length;
-				/* node:coverage ignore next 3 */
 				if (size > maxLimit) {
 					req.destroy();
 					res.error(INT_413);
@@ -2165,6 +2290,8 @@ class Woodland extends EventEmitter {
 		res.send = createSendHandler(req, res, this.#onReady.bind(this), this.#onDone.bind(this));
 		res.set = createSetHandler(res);
 		res.status = createStatusHandler(res);
+		res.cookie = createCookieHandler(res);
+		res.clearCookie = createClearCookieHandler(res);
 
 		res.set(headersBatch);
 		res.on(EVT_CLOSE, () => this.#logger.log(this.#logger.clf(req, res), INFO));
@@ -2201,12 +2328,14 @@ class Woodland extends EventEmitter {
 	 * @returns {boolean} True if origin is safe
 	 */
 	#isSafeOrigin(origin) {
-		if (!origin || typeof origin !== STRING) {
+		if (origin.length > INT_255) {
 			return false;
 		}
-		if (origin.length > INT_255) {
+		/* node:coverage ignore next 3 */
+		if (!origin || typeof origin !== STRING) {
 			return false;
 		}
+		/* node:coverage ignore next 3 */
 		if (CONTROL_CHAR_PATTERN.test(origin)) {
 			return false;
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "woodland",
-  "version": "22.2.1",
+  "version": "22.3.0",
   "description": "Secure HTTP framework for Node.js. Express-compatible with built-in security, no performance tradeoff.",
   "keywords": [
     "api",

package/types/woodland.d.ts

@@ -37,6 +37,35 @@ export interface RouteInfo {
 	visible: number;
 }
 
+export interface CookieOptions {
+	domain?: string;
+	path?: string;
+	maxAge?: number;
+	expires?: Date;
+	httpOnly?: boolean;
+	secure?: boolean;
+	sameSite?: "strict" | "lax" | "none" | string;
+	encode?: boolean | ((value: string) => string);
+}
+
+export interface ClearCookieOptions {
+	domain?: string;
+	path?: string;
+}
+
+	export interface WoodlandResponse {
+		locals: Record<string, any>;
+		error(status?: number, body?: Error | string): void;
+		header(name: string, value: string | number): void;
+		json(body: any, status?: number, headers?: Record<string, string>): void;
+		redirect(uri: string, perm?: boolean): void;
+		send(body?: any, status?: number, headers?: Record<string, string>): void;
+		set(headers: Record<string, string>): void;
+		status(code: number): void;
+		cookie(name: string, value: string, opts?: CookieOptions): void;
+		clearCookie(name: string, opts?: ClearCookieOptions): void;
+	}
+
 export class Woodland extends EventEmitter {
 	// Public read-only properties (getters)
 	readonly logger: Readonly<{