woodland 21.0.9 → 22.0.0

package/README.md

@@ -3,12 +3,11 @@
 
 # Woodland
 
-High-performance HTTP framework for Node.js. Express-compatible, optimized for speed.
+Secure HTTP framework for Node.js. Express-compatible with built-in security, no performance tradeoff.
 
 [![npm version](https://badge.fury.io/js/woodland.svg)](https://badge.fury.io/js/woodland)
 [![Node.js Version](https://img.shields.io/node/v/woodland.svg)](https://nodejs.org/)
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
-[![Build Status](https://github.com/avoidwork/woodland/actions/workflows/ci.yml/badge.svg)](https://github.com/avoidwork/woodland/actions)
 [![Test Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/avoidwork/woodland)
 
 </div>
@@ -19,7 +18,7 @@ High-performance HTTP framework for Node.js. Express-compatible, optimized for s
 npm install woodland
 ```
 
-### ECMAScript Modules (ESM)
+### ESM
 
 ```javascript
 import { createServer } from "node:http";
@@ -49,29 +48,24 @@ createServer(app.route).listen(3000, () => console.log("Server running at http:/
 
 ## Why Woodland?
 
-**Benefits:**
+**Security-First Design:**
 
-- **Zero learning curve** - Express-compatible middleware and routing patterns
-- **Production-ready** - 100% test coverage, battle-tested security
+- **Zero learning curve** - Express-compatible patterns
+- **Built-in security** - CORS, path traversal, XSS prevention (no additional packages)
+- **Secure by default** - CORS deny-all, path traversal blocked, HTML escaping automatic
 - **TypeScript first** - Full type definitions included
-- **Zero config** - Works out of the box, tune when you need to
-- **Lightweight** - Minimal dependencies, no bloat
-- **Dual module support** - Works with CommonJS and ECMAScript Modules (ESM)
-
-**Built-in Features (No Additional Packages Needed):**
-
-- **Automatic `Allow` header** - Every response includes `Allow: GET, POST, OPTIONS` (or relevant methods) for REST compliance
-- **CORS support** - Configure allowed origins with automatic preflight handling (OPTIONS)
-- **X-Content-Type-Options** - Automatic `nosniff` header on all responses
-- **ETag generation** - Built-in ETag support via `tiny-etag` for caching
-- **Response timing** - Optional `X-Response-Time` header for monitoring
-- **Directory indexing** - Auto-generated HTML directory listings (optional)
-- **Range request support** - Automatic handling of `Range` headers for file streaming
-- **HEAD request handling** - GET routes automatically support HEAD
-- **Error event emission** - Built-in error logging and event hooks
-- **Request decoration** - IP extraction, URL parsing, parameter extraction built-in
-- **Logger with CLF** - Common Log Format logging with configurable levels
-- **Cache control** - LRU caching for routes (configurable size and TTL)
+- **No performance tradeoff** - Security features add ~0.02ms overhead per request
+- **Lightweight** - Minimal dependencies (6 packages)
+- **Dual module support** - CommonJS and ESM
+
+**Built-in Security Features:**
+
+- **CORS enforcement** - Default deny-all, explicit allowlist required
+- **Path traversal protection** - Resolved paths validated against allowed directories
+- **XSS prevention** - Automatic HTML escaping for user output
+- **IP validation** - Protects against header spoofing
+- **X-Content-Type-Options** - Automatic `nosniff` header
+- **Secure error handling** - No sensitive data exposure
 
 ## Common Patterns
 
@@ -121,27 +115,13 @@ app.always((req, res, next) => {
 // Route-specific middleware
 app.get("/protected", authenticate, handler);
 
-// Error handler (register last)
+// Error handler (register last, 4 params)
 app.use("/(.*)", (error, req, res, next) => {
   console.error(error);
   res.error(500);
 });
 ```
 
-### Routing
-
-```javascript
-// Parameters
-app.get("/users/:id", handler);
-app.get("/users/:userId/posts/:postId", handler);
-
-// RegExp patterns
-app.get("/files/:path(.*)", handler);
-
-// Wildcards
-app.get("/api/*", apiMiddleware);
-```
-
 ## Configuration
 
 ```javascript
@@ -152,349 +132,96 @@ const app = woodland({
   cacheSize: 1000, // Route cache size
   cacheTTL: 10000, // Cache TTL in ms
   charset: "utf-8", // Default charset
-  corsExpose: "", // CORS expose headers
-  defaultHeaders: {}, // Additional default headers
-  digit: 3, // Timing digit precision
-  indexes: ["index.htm", "index.html"], // Index files
   logging: {
     enabled: true,
-    level: "info", // debug, info, warn, error, crit, alert, emerg, notice
-    format: "%h %l %u %t \"%r\" %>s %b",
+    level: "info",
   },
-  silent: false, // Disable server headers
   time: false, // X-Response-Time header
+  silent: false, // Disable server headers
 });
 ```
 
-**Environment Variables:**
-
-```bash
-export WOODLAND_LOG_LEVEL=debug
-export WOODLAND_LOG_FORMAT="%h %t \"%r\" %>s %b"
-export WOODLAND_LOG_ENABLED=true
-```
-
 ## Response Helpers
 
 ```javascript
-// JSON
 res.json({ data: "value" });
-res.json({ data: "value" }, 201); // Custom status
-
-// Text
 res.send("Hello World");
-
-// Redirect
 res.redirect("/new-url");
-res.redirect("/new-url", false); // Temporary (307)
-
-// Headers
 res.header("x-custom", "value");
-res.set({ "x-one": "1", "x-two": "2" });
-
-// Error
-res.error(404);
-res.error(500, "Server Error");
-
-// Status
 res.status(201);
+res.error(404);
 ```
 
 ## Request Properties
 
 ```javascript
-app.get("/users/:id", (req, res) => {
-  req.ip;         // Client IP address (from X-Forwarded-For or connection)
-  req.method;     // HTTP method
-  req.parsed;     // URL object with pathname, search, hostname, etc.
-  req.params;     // URL parameters { id: "123" }
-  req.allow;      // Allowed methods string (e.g., "GET, OPTIONS")
-  req.cors;       // CORS enabled for this request
-  req.corsHost;   // Origin host differs from request host
-  req.body;       // Request body (parsed by middleware)
-  req.headers;    // Request headers
-  req.host;       // Hostname
-  req.valid;      // Request validation status
-  req.exit;       // Exit iterator for middleware chain
-  req.precise;    // Precise timer instance (when timing enabled)
-});
+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
 ```
 
 ## Event Handlers
 
 ```javascript
-app.on("connect", (req, res) => {
-  console.log(`Connection from ${req.ip}`);
-});
-
-app.on("finish", (req, res) => {
-  analytics.track({ method: req.method, status: res.statusCode });
-});
-
-app.on("error", (req, res, err) => {
-  console.error(`Error ${res.statusCode}:`, err);
-});
-
-app.on("stream", (req, res) => {
-  console.log(`Streaming file`);
-});
-```
-
-## HTTP Methods
-
-```javascript
-app.get(path, ...handlers);      // GET
-app.post(path, ...handlers);     // POST
-app.put(path, ...handlers);      // PUT
-app.delete(path, ...handlers);   // DELETE
-app.patch(path, ...handlers);    // PATCH
-app.options(path, ...handlers);  // OPTIONS
-app.connect(path, ...handlers);  // CONNECT
-app.trace(path, ...handlers);    // TRACE
-app.always(...handlers);         // Wildcard (all methods)
-```
-
-## Class API (for larger apps)
-
-```javascript
-import { Woodland } from "woodland";
-
-class API extends Woodland {
-  constructor() {
-    super({ origins: ["https://myapp.com"] });
-    this.setupRoutes();
-  }
-
-  setupRoutes() {
-    this.get("/health", this.healthCheck);
-    this.get("/users", this.getUsers);
-  }
-
-  healthCheck(req, res) {
-    res.json({ status: "ok" });
-  }
-
-  getUsers(req, res) {
-    res.json([]);
-  }
-}
-
-const api = new API();
-```
-
-## Factory Pattern
-
-Woodland uses factories everywhere for testability:
-
-```javascript
-// Factories return objects with bound methods
-import { woodland, createLogger } from "woodland";
-
-const app = woodland(); // Factory creates Woodland instance
-const logger = createLogger({ enabled: true, level: "debug" });
-
-// Closures provide private state instead of class fields
-```
-
-## Middleware Registration
-
-```javascript
-// Middleware registration pattern: middleware.register(path, ...fn, method)
-app.get("/users", getUsers);           // Delegates to use()
-app.post("/users", createUser);        // Delegates to use()
-app.always(globalMiddleware);          // Wildcard for all methods
-
-// HEAD routes cannot be registered directly
-// GET routes implicitly allow HEAD
-app.get("/resource", handler);         // Handles both GET and HEAD
-```
-
-## Middleware Registry
-
-```javascript
-// Check if a method is allowed for a URI
-const allowed = app.allowed("GET", "/users"); // true
-
-// Get allowed methods for a URI
-const methods = app.allows("/users"); // "GET, OPTIONS"
-
-// List routes for a method
-const routes = app.list("get", "array"); // ["/", "/users", ...]
-const routesObj = app.list("get", "object"); // { "/": [...], "/users": [...] }
-
-// Get route information
-const info = app.routes("/users/:id", "GET");
-```
-
-## Error Handler Middleware
-
-Error handlers are automatically detected by their 4 parameters:
-
-```javascript
-// Error handler (register last)
-app.use("/(.*)", (err, req, res, next) => {
-  console.error(err);
-  res.error(500, err.message);
-});
-
-// Regular middleware has 3 parameters
-app.use((req, res, next) => {
-  next(); // Continue chain
-});
-```
-
-## Performance Patterns
-
-```javascript
-// Use for loops instead of for..of in hot paths
-for (let i = 0; i < files.length; i++) {
-  const file = files[i];
-  // Process file
-}
-
-// Use Set for O(1) lookups
-const ignored = new Set();
-if (!ignored.has(fn)) {
-  // Process
-}
-
-// Use Object.create(null) for null-prototype objects
-const headers = Object.create(null);
-```
-
-## File Server
-
-```javascript
-// Serve files from a directory
-app.files("/static", "./public");
-
-// Serve a specific file
-await app.serve(req, res, "/path/to/file.txt", "./public");
-
-// Stream a file
-app.stream(req, res, {
-  path: "./public/file.txt",
-  etag: "abc123",
-  charset: "utf-8",
-  stats: { size: 1024, mtime: new Date() }
-});
-```
-
-## Logger
-
-```javascript
-// Access logger
-app.logger.log("Custom log message");
-app.logger.logError("/path", "GET", "127.0.0.1");
-app.logger.logRoute("/path", "GET", "127.0.0.1");
-app.logger.logMiddleware("/path", handler);
-app.logger.logDecoration("/path", "GET", "127.0.0.1");
-app.logger.logServe(req, "Serving file");
-
-// Common Log Format
-app.logger.clf(req, res); // "127.0.0.1 - - [date] \"GET / HTTP/1.1\" 200 1234"
-
-// Time formatting
-app.logger.ms(1234567); // "1.234 ms"
-app.logger.timeOffset(300); // "-0500" (timezone offset)
+app.on("connect", (req, res) => console.log(`Connection from ${req.ip}`));
+app.on("finish", (req, res) => analytics.track({ method: req.method, status: res.statusCode }));
+app.on("error", (req, res, err) => console.error(`Error ${res.statusCode}:`, err));
+app.on("stream", (req, res) => console.log(`Streaming file`));
 ```
 
 ## CLI
 
 ```bash
-# Install globally
-npm install -g woodland
-
 # Serve directory (default: http://127.0.0.1:8000)
-woodland
+npx woodland
 
 # Custom port
-woodland --port=3000
+npx woodland --port=3000
 
 # Custom IP
-woodland --ip=0.0.0.0
-
-# Verbose logging
-woodland --verbose
+npx woodland --ip=0.0.0.0
 ```
 
 ## Testing
 
 ```bash
-npm test              # Run tests (100% coverage)
+npm test              # Run tests (100% line coverage)
 npm run coverage      # Generate coverage report
 npm run benchmark     # Performance benchmarks
 npm run lint          # Check linting
-npm run fix           # Fix linting issues
 ```
 
-## Benchmarks
-
-**Performance comparison (mean of 5 runs):**
-
-| Framework | Mean (ms) | Ops/sec |
-|-----------|-----------|---------|
-| Fastify | 0.0863ms | 11,698 |
-| **Woodland** | **0.0929ms** | **10,860** |
-| Node.js HTTP | 0.1092ms | 9,180 |
-| Express | 0.1043ms | 9,591 |
-
-Woodland is **11.5% faster than Express** and **14.8% faster than raw Node.js HTTP**.
-
-**Additional Performance Metrics:**
-
-| Category | Metric | Result |
-|----------|--------|--------|
-| **Routing** | Method validation (`allows()`) | 4.9M ops/sec |
-| | Route resolution (`routes()`) | 1.8M ops/sec |
-| **Middleware** | Registration | 43K+ ops/sec |
-| | Simple execution | 31K ops/sec |
-| **HTTP Server** | JSON responses | 13,225 ops/sec |
-| | CRUD operations | 10-14K ops/sec |
-| **File Serving** | Small files (< 1KB) | 44K ops/sec |
-| | Streaming with ETags | 370K ops/sec |
-| **Capacity** | Single instance (JSON API) | 5,000-7,000 RPS |
-| | Cluster (10 instances) | 50,000-70,000 RPS |
-
-[Full benchmark details](https://github.com/avoidwork/woodland/blob/main/docs/BENCHMARKS.md)
-
 ## Documentation
 
-- [API Reference](https://github.com/avoidwork/woodland/blob/main/docs/API.md) - Complete method documentation
-- [Technical Documentation](https://github.com/avoidwork/woodland/blob/main/docs/TECHNICAL_DOCUMENTATION.md) - Architecture, OWASP security, internals
-- [Code Style Guide](https://github.com/avoidwork/woodland/blob/main/docs/CODE_STYLE_GUIDE.md) - Conventions and best practices
-- [Benchmarks](https://github.com/avoidwork/woodland/blob/main/docs/BENCHMARKS.md) - Performance testing results
-
-## Security
+- [API Reference](https://github.com/avoidwork/woodland/tree/master/docs/API.md) - Complete method documentation
+- [Technical Documentation](https://github.com/avoidwork/woodland/tree/master/docs/TECHNICAL_DOCUMENTATION.md) - Architecture, OWASP security, internals
+- [Code Style Guide](https://github.com/avoidwork/woodland/tree/master/docs/CODE_STYLE_GUIDE.md) - Conventions and best practices
+- [Benchmarks](https://github.com/avoidwork/woodland/tree/master/docs/BENCHMARKS.md) - Performance testing results
 
-**Automatic Protection:**
+## Performance
 
-- Injection prevention - Input validation, HTML escaping
-- Path traversal protection - Secure file access
-- CORS enforcement - Origin validation
-- Secure defaults - Safe error handling
+Woodland delivers **enterprise-grade security without sacrificing performance**. Security features add minimal overhead (~0.02ms per request).
 
-**Security Best Practices:**
+| Framework | Security Approach | Mean Response Time |
+|-----------|------------------|-------------------|
+| Fastify | Requires plugins | 0.1491ms |
+| **Woodland** | **Built-in** | **0.1866ms** |
+| Express | Requires middleware | 0.1956ms |
 
-```javascript
-// Always validate IP addresses before use
-import { isValidIP } from "woodland";
-
-if (isValidIP(req.ip)) {
-	// Safe to use
-}
-
-// Escape HTML in dynamic content
-import { escapeHtml } from "woodland";
-
-const safeOutput = escapeHtml(userInput);
+## Security
 
-// Deny CORS by default (empty origins array)
-const app = woodland(); // No origins = deny all CORS
+Woodland implements multiple layers of protection:
 
-// Block path traversal in file serving
-app.files("/static", "./public"); // Automatically blocks ../ attempts
-```
+1. **CORS Validation** - Default deny-all policy
+2. **Path Traversal Protection** - Resolved paths validated
+3. **Input Validation** - IP addresses validated, URLs parsed securely
+4. **Output Encoding** - HTML escaping automatic
+5. **Secure Error Handling** - No internal paths exposed
 
 **Production Setup:**
 
@@ -506,43 +233,13 @@ app.always(helmet());
 app.always(rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));
 ```
 
-## Troubleshooting
-
-**CORS blocked?**
-
-```javascript
-const app = woodland({ origins: ["https://myapp.com"] });
-```
-
-**Route not matching?**
-
-```javascript
-// Check trailing slashes - be consistent
-app.get("/users/:id", handler); // ✅
-```
-
-**High memory?**
-
-```javascript
-const app = woodland({ cacheSize: 100, cacheTTL: 60000 });
-```
-
 ## License
 
 Copyright (c) 2026 Jason Mulligan
 
 Licensed under the **BSD-3-Clause** license.
 
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Add tests for new functionality
-4. Ensure all tests pass (`npm test`)
-5. Submit a pull request
-
 ## Support
 
 - **Issues**: [GitHub Issues](https://github.com/avoidwork/woodland/issues)
-- **Documentation**: [GitHub Wiki](https://github.com/avoidwork/woodland/tree/master/docs)
 - **Discussions**: [GitHub Discussions](https://github.com/avoidwork/woodland/discussions)

package/dist/cli.cjs

@@ -4,7 +4,7 @@
  *
  * @copyright 2026 Jason Mulligan <jason.mulligan@avoidwork.com>
  * @license BSD-3-Clause
- * @version 21.0.9
+ * @version 22.0.0
  */
 'use strict';
 
@@ -268,6 +268,7 @@ function main(args = process.argv) {
 	app.files();
 	const server = node_http.createServer(app.route);
 	server.listen(portValidation.port, ip);
+	/* node:coverage ignore next 6 */
 	server.on("listening", () => {
 		const actualPort = server.address().port;
 		app.logger.log(
@@ -281,6 +282,7 @@ function main(args = process.argv) {
 
 // CLI entry point - only run when executed directly
 const __filename$1 = node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli.cjs', document.baseURI).href)));
+/* node:coverage ignore next 3 */
 if (process.argv[1] && process.argv[1] === __filename$1) {
 	main();
 }