@zero-server/middleware 0.9.0 → 0.9.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Tony Wiedman
-
-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.
+MIT License
+
+Copyright (c) 2026 Tony Wiedman
+
+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

@@ -30,7 +30,7 @@ This package narrows `@zero-server/sdk` to **12** exports. See the [scope page](
 
 - [Scope page](https://github.com/tonywied17/zero-server/blob/main/docs/scopes/middleware.md)
 - [Full API reference](https://github.com/tonywied17/zero-server/blob/main/API.md)
-- [Live docs](https://z-server.com)
+- [Live docs](https://z-server.dev)
 
 ## License
 

package/index.js

@@ -1,18 +1,18 @@
 // AUTO-GENERATED by .tools/generate-package-stubs.js — edit .tools/scope-manifest.js and re-run `npm run packages:generate`.
 'use strict';
-const sdk = require("@zero-server/sdk");
+const lib = require("./lib/middleware");
 
 module.exports = {
-    cors: sdk.cors,
-    helmet: sdk.helmet,
-    compress: sdk.compress,
-    rateLimit: sdk.rateLimit,
-    logger: sdk.logger,
-    timeout: sdk.timeout,
-    requestId: sdk.requestId,
-    cookieParser: sdk.cookieParser,
-    csrf: sdk.csrf,
-    validate: sdk.validate,
-    errorHandler: sdk.errorHandler,
-    static: sdk.static,
+    cors: lib.cors,
+    helmet: lib.helmet,
+    compress: lib.compress,
+    rateLimit: lib.rateLimit,
+    logger: lib.logger,
+    timeout: lib.timeout,
+    requestId: lib.requestId,
+    cookieParser: lib.cookieParser,
+    csrf: lib.csrf,
+    validate: lib.validate,
+    errorHandler: lib.errorHandler,
+    static: lib.static,
 };

package/lib/debug.js

@@ -0,0 +1,372 @@
+/**
+ * @module debug
+ * @description Lightweight namespaced debug logger with levels, colors, and timestamps.
+ *              Enable via DEBUG env variable: DEBUG=app:*,router (supports glob patterns).
+ *              Each namespace gets a unique color for easy visual scanning.
+ *
+ * Levels: trace (0), debug (1), info (2), warn (3), error (4), fatal (5), silent (6).
+ * Set level via DEBUG_LEVEL env var or programmatically.
+ *
+ * @example
+ *   const debug = require('@zero-server/sdk').debug;
+ *   const log = debug('app:routes');
+ *
+ *   log.info('server started on port %d', 3000);
+ *   log.warn('deprecation notice');
+ *   log.error('failed to connect', err);
+ *   log('shorthand for debug level');
+ *
+ *   // Set minimum level — anything below is silenced
+ *   debug.level('warn');   // only warn, error, fatal
+ *   debug.level('silent'); // suppress all output
+ *   debug.level('trace');  // show everything
+ *   debug.level(0);        // same as 'trace'
+ */
+
+const LEVELS = { trace: 0, debug: 1, info: 2, warn: 3, error: 4, fatal: 5, silent: 6 };
+const LEVEL_NAMES = ['TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL'];
+const LEVEL_COLORS = ['\x1b[2m', '\x1b[36m', '\x1b[32m', '\x1b[33m', '\x1b[31m', '\x1b[35;1m'];
+
+// Namespace colors (rotate through these)
+const NS_COLORS = [
+    '\x1b[36m', '\x1b[33m', '\x1b[32m', '\x1b[35m', '\x1b[34m',
+    '\x1b[36;1m', '\x1b[33;1m', '\x1b[32;1m', '\x1b[35;1m', '\x1b[34;1m',
+];
+
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+
+let _colorIdx = 0;
+const _nsColorMap = new Map();
+
+/**
+ * Global state
+ */
+let _globalLevel = LEVELS[process.env.DEBUG_LEVEL] !== undefined
+    ? LEVELS[process.env.DEBUG_LEVEL]
+    : LEVELS.debug;
+
+let _enabledPatterns = null;
+let _output = process.stdout;
+let _outputCustom = false;
+let _useColors = process.stdout.isTTY || false;
+let _timestamps = true;
+let _jsonMode = false;
+
+/**
+ * Parse DEBUG env var into patterns.
+ * @private
+ */
+function _parsePatterns()
+{
+    const raw = process.env.DEBUG;
+    if (!raw) return null;
+    return raw.split(/[\s,]+/).filter(Boolean).map(p =>
+    {
+        const neg = p.startsWith('-');
+        const pat = neg ? p.slice(1) : p;
+        // Convert glob to regex: * => .*, ? => .
+        const re = new RegExp('^' + pat.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$');
+        return { neg, re };
+    });
+}
+
+_enabledPatterns = _parsePatterns();
+
+/**
+ * Check if a namespace is enabled.
+ * @private
+ * @param {string} ns - Debug namespace.
+ * @returns {boolean} True if the namespace matches the DEBUG patterns.
+ */
+function _isEnabled(ns)
+{
+    if (!_enabledPatterns) return true; // No DEBUG set — enable all
+    let enabled = false;
+    for (const { neg, re } of _enabledPatterns)
+    {
+        if (re.test(ns)) enabled = !neg;
+    }
+    return enabled;
+}
+
+/**
+ * Get a color for a namespace.
+ * @private
+ */
+function _nsColor(ns)
+{
+    if (!_nsColorMap.has(ns))
+    {
+        _nsColorMap.set(ns, NS_COLORS[_colorIdx % NS_COLORS.length]);
+        _colorIdx++;
+    }
+    return _nsColorMap.get(ns);
+}
+
+/**
+ * Format a timestamp.
+ * @private
+ */
+function _ts()
+{
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${String(d.getMilliseconds()).padStart(3, '0')}`;
+}
+
+/**
+ * Format arguments (like console.log — supports %s, %d, %j, %o).
+ * @private
+ */
+function _format(args)
+{
+    if (args.length === 0) return '';
+    if (typeof args[0] === 'string' && args.length > 1)
+    {
+        let i = 1;
+        const str = args[0].replace(/%([sdjo%])/g, (_, f) =>
+        {
+            if (f === '%') return '%';
+            if (i >= args.length) return `%${f}`;
+            const v = args[i++];
+            if (f === 's') return String(v);
+            if (f === 'd') return Number(v);
+            if (f === 'j' || f === 'o')
+            {
+                try { return JSON.stringify(v); }
+                catch { return String(v); }
+            }
+            return String(v);
+        });
+        const rest = args.slice(i).map(a =>
+            typeof a === 'object' ? JSON.stringify(a) : String(a)
+        );
+        return rest.length > 0 ? str + ' ' + rest.join(' ') : str;
+    }
+    return args.map(a =>
+    {
+        if (a instanceof Error) return a.stack || a.message;
+        if (typeof a === 'object')
+        {
+            try { return JSON.stringify(a); }
+            catch { return String(a); }
+        }
+        return String(a);
+    }).join(' ');
+}
+
+/**
+ * Write a log entry.
+ * @private
+ */
+function _write(ns, level, args)
+{
+    const msg = _format(args);
+    const out = (_outputCustom || level < LEVELS.warn) ? _output : process.stderr;
+
+    if (_jsonMode)
+    {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level: LEVEL_NAMES[level],
+            namespace: ns,
+            message: msg,
+        };
+        // If last arg is an Error, attach stack
+        const last = args[args.length - 1];
+        if (last instanceof Error)
+        {
+            entry.error = { message: last.message, stack: last.stack, code: last.code };
+        }
+        out.write(JSON.stringify(entry) + '\n');
+        return;
+    }
+
+    // Pretty text output
+    const parts = [];
+    if (_timestamps)
+    {
+        parts.push(_useColors ? `${DIM}${_ts()}${RESET}` : _ts());
+    }
+    // Level
+    const lvlName = LEVEL_NAMES[level];
+    if (_useColors)
+    {
+        parts.push(`${LEVEL_COLORS[level]}${lvlName.padEnd(5)}${RESET}`);
+    }
+    else
+    {
+        parts.push(lvlName.padEnd(5));
+    }
+    // Namespace
+    if (_useColors)
+    {
+        parts.push(`${_nsColor(ns)}${ns}${RESET}`);
+    }
+    else
+    {
+        parts.push(ns);
+    }
+    parts.push(msg);
+
+    out.write(parts.join(' ') + '\n');
+}
+
+/**
+ * Create a namespaced debug logger.
+ *
+ * @param {string} namespace - Logger namespace (e.g. 'app:routes', 'db:queries').
+ * @returns {Function & { trace, debug, info, warn, error, fatal, enabled }} Logger function.
+ */
+function debug(namespace)
+{
+    const enabled = _isEnabled(namespace);
+
+    // Default call = debug level
+    const logger = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.debug) return;
+        _write(namespace, LEVELS.debug, args);
+    };
+
+    logger.trace = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.trace) return;
+        _write(namespace, LEVELS.trace, args);
+    };
+
+    logger.debug = logger;
+
+    logger.info = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.info) return;
+        _write(namespace, LEVELS.info, args);
+    };
+
+    logger.warn = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.warn) return;
+        _write(namespace, LEVELS.warn, args);
+    };
+
+    logger.error = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.error) return;
+        _write(namespace, LEVELS.error, args);
+    };
+
+    logger.fatal = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.fatal) return;
+        _write(namespace, LEVELS.fatal, args);
+    };
+
+    /** Whether this namespace is active. */
+    logger.enabled = enabled;
+
+    /** The namespace string */
+    logger.namespace = namespace;
+
+    return logger;
+}
+
+// --- Configuration API -------------------------------------------
+
+/**
+ * Set the minimum log level globally.
+ * Messages below this level are silenced.
+ *
+ * @param {string|number} level - Level name or number.
+ *   `'trace'` (0) — all output
+ *   `'debug'` (1) — debug and above
+ *   `'info'` (2) — info and above
+ *   `'warn'` (3) — warn and above
+ *   `'error'` (4) — error and fatal only
+ *   `'fatal'` (5) — fatal only
+ *   `'silent'` (6) — nothing
+ */
+debug.level = function(level)
+{
+    if (typeof level === 'string') _globalLevel = LEVELS[level.toLowerCase()] ?? LEVELS.debug;
+    else _globalLevel = level;
+};
+
+/**
+ * Enable/disable namespaces programmatically (same syntax as DEBUG env var).
+ * @param {string} patterns - Comma-separated patterns. Use '-ns' to exclude.
+ */
+debug.enable = function(patterns)
+{
+    process.env.DEBUG = patterns;
+    _enabledPatterns = _parsePatterns();
+};
+
+/**
+ * Disable all debug output.
+ */
+debug.disable = function()
+{
+    process.env.DEBUG = '';
+    _enabledPatterns = [{ neg: false, re: /^$/ }]; // match nothing
+};
+
+/**
+ * Enable structured JSON output.
+ * @param {boolean} [on=true] - Enable flag.
+ */
+debug.json = function(on = true)
+{
+    _jsonMode = on;
+};
+
+/**
+ * Enable/disable timestamps.
+ * @param {boolean} [on=true] - Enable flag.
+ */
+debug.timestamps = function(on = true)
+{
+    _timestamps = on;
+};
+
+/**
+ * Enable/disable colors.
+ * @param {boolean} [on=true] - Enable flag.
+ */
+debug.colors = function(on = true)
+{
+    _useColors = on;
+};
+
+/**
+ * Set custom output stream.
+ * @param {object} stream - Writable stream with write() method.
+ */
+debug.output = function(stream)
+{
+    _output = stream;
+    _outputCustom = true;
+};
+
+/**
+ * Reset all settings to defaults.
+ */
+debug.reset = function()
+{
+    _globalLevel = LEVELS[process.env.DEBUG_LEVEL] !== undefined
+        ? LEVELS[process.env.DEBUG_LEVEL]
+        : LEVELS.debug;
+    _enabledPatterns = _parsePatterns();
+    _output = process.stdout;
+    _outputCustom = false;
+    _useColors = process.stdout.isTTY || false;
+    _timestamps = true;
+    _jsonMode = false;
+    _colorIdx = 0;
+    _nsColorMap.clear();
+};
+
+/** Expose level constants. */
+debug.LEVELS = LEVELS;
+
+module.exports = debug;

package/lib/middleware/compress.js

@@ -0,0 +1,230 @@
+/**
+ * @module compress
+ * @description Response compression middleware using Node's built-in `zlib`.
+ *              Supports gzip, deflate, and brotli (Node >= 11.7).
+ *              Zero external dependencies.
+ */
+const zlib = require('zlib');
+const log = require('../debug')('zero:compress');
+
+/**
+ * Default minimum response size (in bytes) to bother compressing.
+ * Responses smaller than this are sent uncompressed.
+ * @type {number}
+ */
+const DEFAULT_THRESHOLD = 1024;
+
+/**
+ * MIME types that are worth compressing.
+ * Binary formats (images, video, zip) are already compressed and gain little.
+ * @type {RegExp}
+ */
+const COMPRESSIBLE = /^text\/|^application\/(json|javascript|xml|x-www-form-urlencoded|ld\+json|graphql|wasm)|^image\/svg\+xml/;
+
+/**
+ * Create a compression middleware.
+ *
+ * @param {object}  [opts] - Configuration options.
+ * @param {number}  [opts.threshold=1024]  - Minimum body size in bytes to compress.
+ * @param {number}  [opts.level]           - Compression level (zlib.constants.Z_DEFAULT_COMPRESSION).
+ * @param {string|string[]} [opts.encoding] - Force specific encoding(s). Default: auto-negotiate.
+ * @param {Function} [opts.filter]         - `(req, res) => boolean` — return false to skip compression.
+ * @returns {Function} Middleware `(req, res, next) => void`.
+ *
+ * @example
+ *   const { createApp, compress } = require('@zero-server/sdk');
+ *   const app = createApp();
+ *   app.use(compress());                // gzip/deflate/br auto-negotiated
+ *   app.use(compress({ threshold: 0 })) // compress everything
+ */
+function compress(opts = {})
+{
+    const threshold = opts.threshold !== undefined ? opts.threshold : DEFAULT_THRESHOLD;
+    const level = opts.level !== undefined ? opts.level : undefined;
+    const filterFn = typeof opts.filter === 'function' ? opts.filter : null;
+    const hasBrotli = typeof zlib.createBrotliCompress === 'function';
+
+    /**
+     * Choose the best encoding from the Accept-Encoding header.
+     * Parses quality values (RFC 7231) and picks the highest-priority match.
+     * Priority when equal quality: br > gzip > deflate.
+     * @private
+     * @param {string} header - HTTP header value.
+     * @returns {string|null} Best encoding name, or `null` if none acceptable.
+     */
+    function negotiate(header)
+    {
+        if (!header) return null;
+        const encodings = { br: 0, gzip: 0, deflate: 0 };
+        const parts = header.toLowerCase().split(',');
+        for (let i = 0; i < parts.length; i++)
+        {
+            const part = parts[i].trim();
+            const semi = part.indexOf(';');
+            const name = (semi !== -1 ? part.substring(0, semi).trim() : part);
+            let q = 1;
+            if (semi !== -1)
+            {
+                const qMatch = /q\s*=\s*([0-9.]+)/.exec(part.substring(semi));
+                if (qMatch) q = parseFloat(qMatch[1]);
+            }
+            if (name in encodings) encodings[name] = q;
+        }
+        // Filter available encodings
+        if (!hasBrotli) encodings.br = 0;
+        // Pick highest quality; break ties with priority order
+        let best = null;
+        let bestQ = 0;
+        const order = hasBrotli ? ['br', 'gzip', 'deflate'] : ['gzip', 'deflate'];
+        for (let i = 0; i < order.length; i++)
+        {
+            if (encodings[order[i]] > bestQ)
+            {
+                bestQ = encodings[order[i]];
+                best = order[i];
+            }
+        }
+        return best;
+    }
+
+    /**
+     * Create a compression stream for the chosen encoding.
+     * @private
+     * @param {string} encoding - Content encoding.
+     * @returns {import('stream').Transform} Compression transform stream.
+     */
+    function createStream(encoding)
+    {
+        const zlibOpts = {};
+        if (level !== undefined) zlibOpts.level = level;
+        switch (encoding)
+        {
+            case 'br':
+                return zlib.createBrotliCompress(level !== undefined
+                    ? { params: { [zlib.constants.BROTLI_PARAM_QUALITY]: level } }
+                    : undefined);
+            case 'gzip':
+                return zlib.createGzip(zlibOpts);
+            case 'deflate':
+                return zlib.createDeflate(zlibOpts);
+            default:
+                return null;
+        }
+    }
+
+    return (req, res, next) =>
+    {
+        // Skip if client doesn't accept encoding
+        const acceptEncoding = req.headers['accept-encoding'] || '';
+        const encoding = negotiate(acceptEncoding);
+        if (!encoding) return next();
+
+        // Allow user to skip compression
+        if (filterFn && !filterFn(req, res)) return next();
+
+        // Monkey-patch the raw response's write/end to pipe through compression
+        const raw = res.raw;
+        const origWrite = raw.write.bind(raw);
+        const origEnd = raw.end.bind(raw);
+        let compressStream = null;
+        let headersWritten = false;
+        const chunks = [];
+
+        /** @private */
+        function initCompress()
+        {
+            if (compressStream) return true;
+
+            // If headers were already committed (e.g. res.sse() calls
+            // writeHead before write), we can no longer modify them.
+            if (raw.headersSent) return false;
+
+            // Check Content-Type — skip non-compressible types
+            const ct = raw.getHeader('content-type') || '';
+            if (ct && !COMPRESSIBLE.test(ct))
+            {
+                return false;
+            }
+
+            // Never compress SSE streams — compression buffers
+            // the small frames and prevents real-time delivery.
+            if (ct.includes('text/event-stream'))
+            {
+                return false;
+            }
+
+            compressStream = createStream(encoding);
+            if (!compressStream) return false;
+
+            // Remove Content-Length (we don't know compressed size ahead of time)
+            raw.removeHeader('content-length');
+            raw.removeHeader('Content-Length');
+            raw.setHeader('Content-Encoding', encoding);
+            raw.setHeader('Vary', 'Accept-Encoding');
+            log.debug('compressing with %s', encoding);
+
+            compressStream.on('data', (chunk) => origWrite(chunk));
+            compressStream.on('end', () => origEnd());
+            compressStream.on('error', (err) =>
+            {                log.error('compression error: %s', err.message);                // On compression error, remove encoding header and end raw stream
+                try { raw.removeHeader('Content-Encoding'); } catch (e) { }
+                try { origEnd(); } catch (e) { }
+            });
+            return true;
+        }
+
+        raw.write = function (chunk, enc, callback)
+        {
+            if (!headersWritten)
+            {
+                headersWritten = true;
+                const ct = raw.getHeader('content-type') || '';
+                initCompress();
+                if (compressStream)
+                {
+                    compressStream.write(chunk, enc, callback);
+                    return true;
+                }
+            }
+            if (compressStream)
+            {
+                compressStream.write(chunk, enc, callback);
+                return true;
+            }
+            return origWrite(chunk, enc, callback);
+        };
+
+        raw.end = function (chunk, encoding, callback)
+        {
+            if (!headersWritten)
+            {
+                headersWritten = true;
+
+                // Check threshold — if the total body is small, skip compression
+                const totalChunk = chunk ? (Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))) : null;
+                if (totalChunk && totalChunk.length < threshold)
+                {
+                    return origEnd(chunk, encoding, callback);
+                }
+
+                if (initCompress())
+                {
+                    if (chunk) compressStream.end(chunk, encoding, callback);
+                    else compressStream.end(callback);
+                    return;
+                }
+            }
+            if (compressStream)
+            {
+                if (chunk) compressStream.end(chunk, encoding, callback);
+                else compressStream.end(callback);
+                return;
+            }
+            return origEnd(chunk, encoding, callback);
+        };
+
+        next();
+    };
+}
+
+module.exports = compress;