zero-http 0.2.0

package/documentation/controllers/uploads.js

@@ -0,0 +1,289 @@
+const fs = require('fs');
+const path = require('path');
+
+// --- Shared Constants & Helpers ---
+
+const IMAGE_RE = /\.(png|jpe?g|gif|webp|svg|jfif)$/i;
+const HIDDEN_DIRS = new Set(['.trash', '.thumbs']);
+
+/** Build the thumbnail filename for a given stored name */
+const thumbName = (storedName) => storedName + '-thumb.svg';
+
+/** Ensure a directory exists (no-op if it already does) */
+const ensureDir = (dir) => { try { if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true }); } catch (e) { } };
+
+/** Resolve common paths relative to uploadsDir */
+const dirs = (uploadsDir) => ({
+    thumbs:      path.join(uploadsDir, '.thumbs'),
+    trash:       path.join(uploadsDir, '.trash'),
+    trashThumbs: path.join(uploadsDir, '.trash', '.thumbs'),
+});
+
+/**
+ * Read file entries from a directory, returning metadata objects.
+ * Skips hidden dirs (.trash, .thumbs).
+ */
+function readFileEntries(dir, uploadsDir)
+{
+    if (!fs.existsSync(dir)) return [];
+    const { thumbs } = dirs(uploadsDir || dir);
+    const entries = [];
+    for (const fn of fs.readdirSync(dir))
+    {
+        if (HIDDEN_DIRS.has(fn)) continue;
+        try
+        {
+            const st = fs.statSync(path.join(dir, fn));
+            const isImage = IMAGE_RE.test(fn);
+            const tn = thumbName(fn);
+            const thumbExists = fs.existsSync(path.join(thumbs, tn));
+            entries.push({
+                name: fn,
+                url: '/uploads/' + encodeURIComponent(fn),
+                size: st.size,
+                mtime: st.mtimeMs,
+                isImage,
+                thumb: thumbExists ? '/uploads/.thumbs/' + encodeURIComponent(tn) : null,
+            });
+        } catch (e) { }
+    }
+    return entries;
+}
+
+/** Move a thumbnail between two directories (if it exists) */
+function moveThumb(srcDir, destDir, storedName)
+{
+    try
+    {
+        const tn = thumbName(storedName);
+        const src = path.join(srcDir, tn);
+        if (!fs.existsSync(src)) return;
+        ensureDir(destDir);
+        fs.renameSync(src, path.join(destDir, tn));
+    } catch (e) { }
+}
+
+/** Delete a thumbnail from a directory (if it exists) */
+function deleteThumb(dir, storedName)
+{
+    try
+    {
+        const p = path.join(dir, thumbName(storedName));
+        if (fs.existsSync(p)) fs.unlinkSync(p);
+    } catch (e) { }
+}
+
+// --- Exports ---
+
+exports.ensureUploadsDir = (uploadsDir) =>
+{
+    const { trash } = dirs(uploadsDir);
+    ensureDir(uploadsDir);
+    ensureDir(trash);
+};
+
+/** Handle multipart upload (generate SVG thumbnails for images) */
+exports.upload = (uploadsDir) => (req, res) =>
+{
+    if (req._multipartErrorHandled) return;
+    const { thumbs } = dirs(uploadsDir);
+    const files = req.body.files || {};
+    const outFiles = {};
+
+    for (const key of Object.keys(files))
+    {
+        const f = files[key];
+        outFiles[key] = {
+            originalFilename: f.originalFilename,
+            storedName:       f.storedName,
+            size:             f.size,
+            url:              '/uploads/' + encodeURIComponent(f.storedName),
+        };
+
+        if (!IMAGE_RE.test(f.originalFilename || '')) continue;
+
+        // Generate a simple SVG placeholder thumbnail
+        try
+        {
+            ensureDir(thumbs);
+            const tn = thumbName(f.storedName);
+            const safeName = (f.originalFilename || '').replace(/[&<>"']/g, c =>
+                ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+            const sizeText = typeof f.size === 'number' ? Math.round(f.size / 1024) + ' KB' : '';
+            const svg = [
+                '<?xml version="1.0" encoding="utf-8"?>',
+                '<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128">',
+                '  <rect width="100%" height="100%" fill="#eef2ff" rx="8" ry="8"/>',
+                `  <text x="50%" y="50%" font-family="Arial, Helvetica, sans-serif" font-size="12" fill="#111827" dominant-baseline="middle" text-anchor="middle">${safeName}</text>`,
+                `  <text x="50%" y="72%" font-family="Arial, Helvetica, sans-serif" font-size="10" fill="#6b7280" dominant-baseline="middle" text-anchor="middle">${sizeText}</text>`,
+                '</svg>',
+            ].join('\n');
+            fs.writeFileSync(path.join(thumbs, tn), svg, 'utf8');
+            outFiles[key].thumbUrl = '/uploads/.thumbs/' + encodeURIComponent(tn);
+        } catch (e) { }
+    }
+
+    return res.json({ fields: req.body.fields || {}, files: outFiles });
+};
+
+/** Move a single upload to trash */
+exports.deleteUpload = (uploadsDir) => (req, res) =>
+{
+    const name = req.params.name;
+    const { thumbs, trash, trashThumbs } = dirs(uploadsDir);
+    const src = path.join(uploadsDir, name);
+
+    if (!fs.existsSync(src)) return res.status(404).json({ error: 'Not found' });
+    try
+    {
+        fs.renameSync(src, path.join(trash, name));
+        moveThumb(thumbs, trashThumbs, name);
+        return res.json({ trashed: name });
+    } catch (e) { return res.status(500).json({ error: String(e) }); }
+};
+
+/** Delete all uploads (optionally keep first via ?keep=1) */
+exports.deleteAllUploads = (uploadsDir) => (req, res) =>
+{
+    const keep = Number(req.query.keep) || 0;
+    const { thumbs } = dirs(uploadsDir);
+
+    if (!fs.existsSync(uploadsDir)) return res.json({ removed: [] });
+    try
+    {
+        const files = fs.readdirSync(uploadsDir).filter(n => !HIDDEN_DIRS.has(n)).sort();
+        const removed = [];
+        for (let i = 0; i < files.length; i++)
+        {
+            if (keep && i === 0) continue;
+            try { fs.unlinkSync(path.join(uploadsDir, files[i])); removed.push(files[i]); } catch (e) { }
+        }
+        for (const n of removed) deleteThumb(thumbs, n);
+        return res.json({ removed });
+    } catch (e) { return res.status(500).json({ error: String(e) }); }
+};
+
+/** Restore a trashed file back to uploads */
+exports.restoreUpload = (uploadsDir) => (req, res) =>
+{
+    const name = req.params.name;
+    const { thumbs, trash, trashThumbs } = dirs(uploadsDir);
+    const src = path.join(trash, name);
+
+    if (!fs.existsSync(src)) return res.status(404).json({ error: 'Not found in trash' });
+    try
+    {
+        fs.renameSync(src, path.join(uploadsDir, name));
+        moveThumb(trashThumbs, thumbs, name);
+        return res.json({ restored: name });
+    } catch (e) { return res.status(500).json({ error: String(e) }); }
+};
+
+/** List files currently in trash */
+exports.listTrash = (uploadsDir) => (req, res) =>
+{
+    const { trash } = dirs(uploadsDir);
+    try
+    {
+        const files = !fs.existsSync(trash) ? [] :
+            fs.readdirSync(trash)
+                .filter(fn => fn !== '.thumbs')
+                .map(fn => ({ name: fn, url: '/uploads/.trash/' + encodeURIComponent(fn) }));
+        res.json({ files });
+    } catch (e) { res.status(500).json({ error: String(e) }); }
+};
+
+/** Permanently delete a single trash item */
+exports.deleteTrashItem = (uploadsDir) => (req, res) =>
+{
+    const name = req.params.name;
+    const { trash, trashThumbs } = dirs(uploadsDir);
+    const p = path.join(trash, name);
+
+    if (!fs.existsSync(p)) return res.status(404).json({ error: 'Not found' });
+    try
+    {
+        fs.unlinkSync(p);
+        deleteThumb(trashThumbs, name);
+        return res.json({ deleted: name });
+    } catch (e) { return res.status(500).json({ error: String(e) }); }
+};
+
+/** Empty the entire trash folder */
+exports.emptyTrash = (uploadsDir) => (req, res) =>
+{
+    const { trash, trashThumbs } = dirs(uploadsDir);
+    try
+    {
+        const removed = [];
+        if (fs.existsSync(trash))
+        {
+            for (const f of fs.readdirSync(trash))
+            {
+                if (f === '.thumbs') continue;
+                try { fs.unlinkSync(path.join(trash, f)); removed.push(f); } catch (e) { }
+            }
+            // clear all trash thumbnails
+            if (fs.existsSync(trashThumbs))
+            {
+                for (const tf of fs.readdirSync(trashThumbs))
+                {
+                    try { fs.unlinkSync(path.join(trashThumbs, tf)); } catch (e) { }
+                }
+            }
+        }
+        return res.json({ removed });
+    } catch (e) { return res.status(500).json({ error: String(e) }); }
+};
+
+/** List uploaded files with pagination and sorting */
+exports.listUploads = (uploadsDir) => (req, res) =>
+{
+    try
+    {
+        const page     = Math.max(1, Number(req.query.page) || 1);
+        const pageSize = Math.max(1, Math.min(200, Number(req.query.pageSize) || 20));
+        const sort     = req.query.sort || 'mtime';
+        const order    = (req.query.order || 'desc').toLowerCase() === 'asc' ? 'asc' : 'desc';
+
+        const list = readFileEntries(uploadsDir, uploadsDir);
+        list.sort((a, b) =>
+        {
+            let v = 0;
+            if (sort === 'name')      v = a.name.localeCompare(b.name);
+            else if (sort === 'size') v = (a.size || 0) - (b.size || 0);
+            else                      v = (a.mtime || 0) - (b.mtime || 0);
+            return order === 'asc' ? v : -v;
+        });
+
+        const total = list.length;
+        const start = (page - 1) * pageSize;
+        res.json({ files: list.slice(start, start + pageSize), total, page, pageSize });
+    } catch (e) { res.status(500).json({ error: String(e) }); }
+};
+
+/** List all uploads and trash together (no pagination) for the demo UI */
+exports.listAll = (uploadsDir) => (req, res) =>
+{
+    const { trash } = dirs(uploadsDir);
+    try
+    {
+        const uploads = readFileEntries(uploadsDir, uploadsDir);
+
+        const trashItems = [];
+        if (fs.existsSync(trash))
+        {
+            for (const fn of fs.readdirSync(trash))
+            {
+                if (fn === '.thumbs') continue;
+                try
+                {
+                    const st = fs.statSync(path.join(trash, fn));
+                    trashItems.push({ name: fn, url: '/uploads/.trash/' + encodeURIComponent(fn), size: st.size, mtime: st.mtimeMs });
+                } catch (e) { }
+            }
+        }
+
+        res.json({ uploads, trash: trashItems });
+    } catch (e) { res.status(500).json({ error: String(e) }); }
+};

package/documentation/full-server.js

@@ -0,0 +1,129 @@
+/**
+ * zero-http full-server example
+ * Organized with controllers and JSDoc comments for clarity and maintainability.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+const { createApp, cors, json, urlencoded, text, raw, multipart, static: serveStatic, fetch, logger } = require('..');
+
+// --- App Initialization ---
+const app = createApp();
+app.use(logger({ format: 'dev' }));
+app.use(cors());
+app.use(json());
+app.use(urlencoded());
+app.use(text());
+app.use(serveStatic(path.join(__dirname, 'public')));
+
+// --- Controllers ---
+const rootController = require('./controllers/root');
+const headersController = require('./controllers/headers');
+const echoController = require('./controllers/echo');
+const uploadsController = require('./controllers/uploads');
+
+// --- Core Routes ---
+app.get('/', rootController.getRoot);
+app.get('/headers', headersController.getHeaders);
+app.post('/echo-json', echoController.echoJson);
+app.post('/echo', echoController.echo);
+app.post('/echo-urlencoded', echoController.echoUrlencoded);
+app.post('/echo-text', echoController.echoText);
+app.post('/echo-raw', raw(), echoController.echoRaw);
+
+// --- Uploads and Trash ---
+const uploadsDir = path.join(__dirname, 'uploads');
+uploadsController.ensureUploadsDir(uploadsDir);
+
+// Serve uploaded files from /uploads path using built-in path-prefix middleware
+app.use('/uploads', serveStatic(uploadsDir));
+
+// Upload, delete, restore, and trash routes
+app.post('/upload', multipart({ maxFileSize: 5 * 1024 * 1024, dir: uploadsDir }), uploadsController.upload(uploadsDir));
+app.delete('/uploads/:name', uploadsController.deleteUpload(uploadsDir));
+app.delete('/uploads', uploadsController.deleteAllUploads(uploadsDir));
+app.post('/uploads/:name/restore', uploadsController.restoreUpload(uploadsDir));
+app.get('/uploads-trash-list', uploadsController.listTrash(uploadsDir));
+app.delete('/uploads-trash/:name', uploadsController.deleteTrashItem(uploadsDir));
+app.delete('/uploads-trash', uploadsController.emptyTrash(uploadsDir));
+
+// --- Trash Retention ---
+const TRASH_RETENTION_DAYS = Number(process.env.TRASH_RETENTION_DAYS || 7);
+const TRASH_RETENTION_MS = TRASH_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+
+function autoEmptyTrash()
+{
+    try
+    {
+        const trash = path.join(uploadsDir, '.trash');
+        if (!fs.existsSync(trash)) return;
+        const now = Date.now();
+        const removed = [];
+        for (const f of fs.readdirSync(trash))
+        {
+            try
+            {
+                const p = path.join(trash, f);
+                const st = fs.statSync(p);
+                if (now - st.mtimeMs > TRASH_RETENTION_MS)
+                {
+                    fs.unlinkSync(p);
+                    removed.push(f);
+                    try { fs.unlinkSync(path.join(trash, '.thumbs', f + '-thumb.svg')); } catch (e) { }
+                }
+            } catch (e) { }
+        }
+        if (removed.length) console.log(`autoEmptyTrash: removed ${removed.length} file(s)`);
+    } catch (e) { console.error('autoEmptyTrash error:', e); }
+}
+
+autoEmptyTrash();
+setInterval(autoEmptyTrash, 24 * 60 * 60 * 1000).unref();
+
+// --- Uploads Listings ---
+app.get('/uploads-list', uploadsController.listUploads(uploadsDir));
+app.get('/uploads-all', uploadsController.listAll(uploadsDir));
+
+// --- Temp Cleanup ---
+const cleanupController = require('./controllers/cleanup');
+app.post('/cleanup', cleanupController.cleanup(path.join(os.tmpdir(), 'zero-http-uploads')));
+
+// --- Proxy ---
+const proxyController = require('./controllers/proxy');
+const proxyFetch = (typeof globalThis !== 'undefined' && globalThis.fetch) || fetch;
+app.get('/proxy', proxyController.proxy(proxyFetch));
+
+// --- Server Startup ---
+const port = process.env.PORT || 3000;
+const server = app.listen(port, () =>
+{
+    console.log(`zero-http full-server listening on http://localhost:${port}`);
+    if (process.argv.includes('--test')) runTests(port).catch(console.error);
+});
+
+/** Quick smoke tests using built-in fetch */
+async function runTests(port)
+{
+    const base = `http://localhost:${port}`;
+    console.log('running smoke tests against', base);
+
+    const doReq = async (label, promise) =>
+    {
+        try
+        {
+            const r = await promise;
+            const ct = r.headers.get('content-type') || '';
+            const body = ct.includes('json') ? await r.json() : await r.text();
+            console.log(` ${label}`, r.status, JSON.stringify(body));
+        }
+        catch (e) { console.error(` ${label} error:`, e.message); }
+    };
+
+    await doReq('GET /', fetch(base + '/'));
+    await doReq('POST /echo-json', fetch(base + '/echo-json', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ a: 1 }) }));
+    await doReq('POST /echo-urlencoded', fetch(base + '/echo-urlencoded', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: 'foo=bar' }));
+    await doReq('POST /echo-text', fetch(base + '/echo-text', { method: 'POST', headers: { 'Content-Type': 'text/plain' }, body: 'hello' }));
+    await doReq('GET /headers', fetch(base + '/headers'));
+    console.log('smoke tests complete');
+}

package/documentation/public/data/api.json

@@ -0,0 +1,167 @@
+[
+  {
+    "name": "createApp()",
+    "description": "Returns an application instance with Express-like routing, middleware support, error handling, and an HTTP server.",
+    "example": "const { createApp, json, cors, logger, static: serveStatic } = require('zero-http')\nconst app = createApp()\n\napp.use(logger({ format: 'dev' }))\napp.use(cors())\napp.use(json({ limit: '10kb' }))\napp.use(serveStatic(path.join(__dirname, 'public')))\n\napp.get('/', (req, res) => res.json({ hello: 'world' }))\n\napp.onError((err, req, res, next) => {\n\tconsole.error(err)\n\tres.status(500).json({ error: err.message })\n})\n\napp.listen(3000, () => console.log('listening on :3000'))",
+    "methods": [
+      { "method": "use", "signature": "use(fn)", "description": "Register global middleware; fn(req, res, next)." },
+      { "method": "use", "signature": "use(prefix, fn)", "description": "Register path-scoped middleware. The prefix is stripped from req.url before calling fn." },
+      { "method": "get", "signature": "get(path, ...handlers)", "description": "Register GET route handlers." },
+      { "method": "post", "signature": "post(path, ...handlers)", "description": "Register POST route handlers." },
+      { "method": "put", "signature": "put(path, ...handlers)", "description": "Register PUT route handlers." },
+      { "method": "delete", "signature": "delete(path, ...handlers)", "description": "Register DELETE route handlers." },
+      { "method": "patch", "signature": "patch(path, ...handlers)", "description": "Register PATCH route handlers." },
+      { "method": "options", "signature": "options(path, ...handlers)", "description": "Register OPTIONS route handlers." },
+      { "method": "head", "signature": "head(path, ...handlers)", "description": "Register HEAD route handlers." },
+      { "method": "all", "signature": "all(path, ...handlers)", "description": "Register handlers for ALL HTTP methods." },
+      { "method": "onError", "signature": "onError(fn)", "description": "Register a global error handler: fn(err, req, res, next). Only one at a time." },
+      { "method": "listen", "signature": "listen(port = 3000, cb)", "description": "Start the HTTP server. Returns the http.Server instance." },
+      { "method": "handler", "signature": "(property)", "description": "Bound request handler suitable for http.createServer(app.handler)." }
+    ],
+    "options": []
+  },
+  {
+    "name": "Request (req)",
+    "description": "Wraps the incoming Node http.IncomingMessage with convenient properties and helpers. Populated by the middleware chain.",
+    "example": "app.get('/info', (req, res) => {\n\tconsole.log(req.method)           // 'GET'\n\tconsole.log(req.url)              // '/info?foo=bar'\n\tconsole.log(req.query)            // { foo: 'bar' }\n\tconsole.log(req.ip)               // '127.0.0.1'\n\tconsole.log(req.get('host'))      // 'localhost:3000'\n\tconsole.log(req.is('json'))       // false\n\tres.json({ ok: true })\n})",
+    "methods": [
+      { "method": "method", "signature": "(string)", "description": "HTTP method (GET, POST, etc.)." },
+      { "method": "url", "signature": "(string)", "description": "Request URL path + query string." },
+      { "method": "headers", "signature": "(object)", "description": "Raw request headers (lowercased keys)." },
+      { "method": "query", "signature": "(object)", "description": "Parsed query string via URLSearchParams." },
+      { "method": "params", "signature": "(object)", "description": "Route parameters populated by the router (e.g. { id: '42' })." },
+      { "method": "body", "signature": "(any)", "description": "Parsed request body (null until a body parser runs)." },
+      { "method": "ip", "signature": "(string|null)", "description": "Remote IP address from req.socket.remoteAddress." },
+      { "method": "raw", "signature": "(object)", "description": "The underlying http.IncomingMessage." },
+      { "method": "get", "signature": "get(name)", "description": "Get a request header (case-insensitive)." },
+      { "method": "is", "signature": "is(type)", "description": "Check if Content-Type contains the given type string (e.g. 'json', 'text/html')." }
+    ],
+    "options": []
+  },
+  {
+    "name": "Response (res)",
+    "description": "Wraps the outgoing Node http.ServerResponse with chainable helpers for setting status, headers, and sending responses.",
+    "example": "app.get('/demo', (req, res) => {\n\tres.status(200)\n\t   .set('X-Custom', 'hello')\n\t   .type('json')\n\t   .json({ message: 'ok' })\n})\n\napp.get('/page', (req, res) => res.html('<h1>Hello</h1>'))\napp.get('/go', (req, res) => res.redirect(301, '/new-location'))",
+    "methods": [
+      { "method": "status", "signature": "status(code)", "description": "Set HTTP status code. Returns this (chainable)." },
+      { "method": "set", "signature": "set(name, value)", "description": "Set a response header. Returns this (chainable)." },
+      { "method": "get", "signature": "get(name)", "description": "Get a previously-set response header (case-insensitive)." },
+      { "method": "type", "signature": "type(ct)", "description": "Set Content-Type. Accepts shorthands: 'json', 'html', 'text', 'xml', 'form', 'bin'. Chainable." },
+      { "method": "send", "signature": "send(body)", "description": "Send the response. Auto-detects Content-Type: Buffer→octet-stream, '<…'→html, string→text, object→json." },
+      { "method": "json", "signature": "json(obj)", "description": "Set Content-Type to application/json and send the object." },
+      { "method": "text", "signature": "text(str)", "description": "Set Content-Type to text/plain and send the string." },
+      { "method": "html", "signature": "html(str)", "description": "Set Content-Type to text/html and send the string." },
+      { "method": "redirect", "signature": "redirect([status], url)", "description": "Redirect to URL. Default status is 302." }
+    ],
+    "options": []
+  },
+  {
+    "name": "json([opts])",
+    "description": "Parses JSON request bodies and populates req.body. Skips non-matching Content-Types and calls next().",
+    "example": "app.use(json({\n\tlimit: '10kb',\n\tstrict: true,\n\treviver: (k, v) => {\n\t\tif (typeof v === 'string' && /^\\d{4}-\\d{2}-\\d{2}T/.test(v)) return new Date(v)\n\t\treturn v\n\t},\n\ttype: 'application/json'\n}))",
+    "options": [
+      { "option": "limit", "type": "number|string", "default": "null (no limit)", "notes": "Maximum body size. Accepts bytes or unit strings like '100kb', '1mb', '1gb'." },
+      { "option": "strict", "type": "boolean", "default": "true", "notes": "When true, only accepts objects and arrays (rejects primitives)." },
+      { "option": "reviver", "type": "function", "default": "—", "notes": "Optional function passed to JSON.parse for custom reviving." },
+      { "option": "type", "type": "string|function", "default": "application/json", "notes": "MIME type to match. Supports wildcards ('*/*') or a custom predicate function." }
+    ]
+  },
+  {
+    "name": "urlencoded([opts])",
+    "description": "Parses application/x-www-form-urlencoded bodies into req.body.",
+    "example": "// Simple flat parsing\napp.use(urlencoded())\n\n// Extended mode with nested bracket syntax\napp.use(urlencoded({\n\textended: true,\n\tlimit: '20kb'\n}))\n// a[b][c]=1  → { a: { b: { c: '1' } } }\n// a[]=1&a[]=2 → { a: ['1', '2'] }",
+    "options": [
+      { "option": "extended", "type": "boolean", "default": "false", "notes": "When true, supports rich nested bracket syntax (a[b]=1, a[]=1). When false, returns flat key/value pairs." },
+      { "option": "limit", "type": "number|string", "default": "null (no limit)", "notes": "Maximum body size (bytes or unit string)." },
+      { "option": "type", "type": "string|function", "default": "application/x-www-form-urlencoded", "notes": "MIME type to match." }
+    ]
+  },
+  {
+    "name": "text([opts])",
+    "description": "Reads plain text request bodies into req.body as a string.",
+    "example": "app.use(text({ type: 'text/*', limit: '50kb', encoding: 'utf8' }))\n\napp.post('/echo-text', (req, res) => {\n\tres.text(req.body) // echo back the plain text\n})",
+    "options": [
+      { "option": "type", "type": "string|function", "default": "text/*", "notes": "MIME matcher — uses wildcard by default so it matches text/plain, text/html, etc." },
+      { "option": "limit", "type": "number|string", "default": "null (no limit)", "notes": "Maximum body size." },
+      { "option": "encoding", "type": "string", "default": "utf8", "notes": "Character encoding used to decode the incoming bytes." }
+    ]
+  },
+  {
+    "name": "raw([opts])",
+    "description": "Receives raw bytes as a Buffer on req.body. Useful for binary payloads.",
+    "example": "app.post('/binary', raw({ limit: '5mb' }), (req, res) => {\n\tconsole.log(req.body)        // <Buffer ...>\n\tconsole.log(req.body.length) // byte count\n\tres.json({ size: req.body.length })\n})",
+    "options": [
+      { "option": "type", "type": "string|function", "default": "application/octet-stream", "notes": "MIME type to match for the raw parser." },
+      { "option": "limit", "type": "number|string", "default": "null (no limit)", "notes": "Maximum body size. Returns 413 if exceeded." }
+    ]
+  },
+  {
+    "name": "multipart([opts])",
+    "description": "Streaming multipart parser that writes file parts to disk and collects text fields. Sets req.body to { fields, files }. Files are named upload-<timestamp>-<random>.<ext> and streamed via fs.createWriteStream.",
+    "example": "const uploadsDir = path.join(os.tmpdir(), 'my-uploads')\n\napp.post('/upload', multipart({\n\tdir: uploadsDir,\n\tmaxFileSize: 10 * 1024 * 1024\n}), (req, res) => {\n\t// req.body.fields  → { desc: 'a photo' }\n\t// req.body.files   → { file: { originalFilename, storedName, path, contentType, size } }\n\tres.json({ files: req.body.files, fields: req.body.fields })\n})",
+    "options": [
+      { "option": "dir", "type": "string", "default": "os.tmpdir()/zero-http-uploads", "notes": "Directory to store uploaded files. Relative paths resolve from process.cwd(). Created automatically if missing." },
+      { "option": "maxFileSize", "type": "number", "default": "null (no limit)", "notes": "Maximum file size in bytes. Exceeding this aborts the upload and returns HTTP 413." }
+    ]
+  },
+  {
+    "name": "static(rootPath, [opts])",
+    "description": "Serves static files from a filesystem directory with Content-Type detection (60+ MIME types), dotfile policy, caching, extension fallback, and custom header hooks. Only handles GET and HEAD requests.",
+    "example": "// Basic static serving\napp.use(static(path.join(__dirname, 'public')))\n\n// Full options\napp.use(static(path.join(__dirname, 'public'), {\n\tindex: 'index.html',\n\tmaxAge: 3600000,   // 1 hour in ms\n\tdotfiles: 'ignore',\n\textensions: ['html', 'htm'],\n\tsetHeaders: (res, filePath) => {\n\t\tres.setHeader('X-Served-By', 'zero-http')\n\t}\n}))",
+    "options": [
+      { "option": "index", "type": "string|false", "default": "index.html", "notes": "File to serve for directory requests. Set false to disable auto-index." },
+      { "option": "maxAge", "type": "number", "default": "0", "notes": "Cache-Control max-age in milliseconds. Converted to seconds internally." },
+      { "option": "dotfiles", "type": "string", "default": "ignore", "notes": "'allow' | 'deny' | 'ignore'. deny→403, ignore→skip to next middleware, allow→serve normally." },
+      { "option": "extensions", "type": "string[]", "default": "null", "notes": "Fallback extensions to try when a file is not found (e.g. ['html', 'htm'])." },
+      { "option": "setHeaders", "type": "function", "default": "null", "notes": "Hook (res, filePath) => {} to set custom headers before streaming the file." }
+    ]
+  },
+  {
+    "name": "cors([opts])",
+    "description": "Small CORS middleware. Handles preflight OPTIONS requests automatically with 204 and sets standard CORS headers on all responses. Supports suffix-based origin matching for subdomains.",
+    "example": "// Allow everything (default)\napp.use(cors())\n\n// Restrict to specific origins with credentials\napp.use(cors({\n\torigin: ['https://example.com', '.mysite.com'],\n\tcredentials: true,\n\tmethods: 'GET,POST'\n}))\n// Origins starting with '.' enable suffix matching:\n// '.mysite.com' matches 'api.mysite.com', 'www.mysite.com', etc.",
+    "options": [
+      { "option": "origin", "type": "string|string[]|falsy", "default": "'*'", "notes": "Allowed origins. '*' allows any. Array entries starting with '.' do suffix matching. Set falsy to disable." },
+      { "option": "methods", "type": "string", "default": "GET,POST,PUT,DELETE,OPTIONS", "notes": "Allowed HTTP methods for Access-Control-Allow-Methods." },
+      { "option": "allowedHeaders", "type": "string", "default": "Content-Type,Authorization", "notes": "Allowed headers for Access-Control-Allow-Headers." },
+      { "option": "credentials", "type": "boolean", "default": "false", "notes": "When true and a specific origin matches, sets Access-Control-Allow-Credentials: true." }
+    ]
+  },
+  {
+    "name": "fetch(url, [opts])",
+    "description": "Small Node HTTP/HTTPS client returning a response with status, ok, statusText, headers.get(), and helpers: text(), json(), arrayBuffer(). Supports timeouts, AbortSignal, progress callbacks, and auto-serialization of request bodies.",
+    "example": "const { fetch } = require('zero-http')\n\n// Simple GET with timeout\nconst r = await fetch('https://jsonplaceholder.typicode.com/todos/1', {\n\ttimeout: 5000\n})\nconst data = await r.json()\nconsole.log(r.ok, r.status, data)\n\n// POST with auto-serialized JSON body\nawait fetch('https://httpbin.org/post', {\n\tmethod: 'POST',\n\tbody: { hello: 'world' }\n})\n\n// Download with progress tracking\nawait fetch('https://example.com/big-file.zip', {\n\tonDownloadProgress: ({ loaded, total }) =>\n\t\tconsole.log(`${loaded}/${total} bytes`)\n})",
+    "options": [
+      { "option": "method", "type": "string", "default": "GET", "notes": "HTTP method (uppercased internally)." },
+      { "option": "headers", "type": "object", "default": "{}", "notes": "Request headers." },
+      { "option": "body", "type": "string|Buffer|object|URLSearchParams|Stream", "default": "undefined", "notes": "Request body. Plain objects are auto-JSON-encoded. URLSearchParams produce urlencoded bodies. Streams are piped." },
+      { "option": "timeout", "type": "number", "default": "undefined", "notes": "Request timeout in milliseconds. Creates an ETIMEOUT error on expiry." },
+      { "option": "signal", "type": "AbortSignal", "default": "undefined", "notes": "AbortController signal to cancel the request." },
+      { "option": "agent", "type": "http.Agent", "default": "undefined", "notes": "Optional agent for connection pooling or proxies." },
+      { "option": "onDownloadProgress", "type": "function", "default": "—", "notes": "Callback receiving { loaded, total } on each response chunk." },
+      { "option": "onUploadProgress", "type": "function", "default": "—", "notes": "Callback receiving { loaded, total } during body upload. Buffer bodies are chunked at 64KB to enable tracking." }
+    ]
+  },
+  {
+    "name": "rateLimit([opts])",
+    "description": "In-memory, per-IP rate-limiting middleware. Sets standard X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers on every response. Returns 429 JSON error when the limit is exceeded. Expired entries are cleaned up automatically.",
+    "example": "const { rateLimit } = require('zero-http')\n\n// 100 requests per 15 minutes\napp.use(rateLimit({\n\twindowMs: 15 * 60 * 1000,\n\tmax: 100,\n\tmessage: 'Slow down!'\n}))\n\n// Per-route limiting with custom key\napp.post('/login', rateLimit({\n\twindowMs: 60000,\n\tmax: 5,\n\tkeyGenerator: (req) => req.body?.username || req.ip\n}), (req, res) => {\n\tres.json({ ok: true })\n})",
+    "options": [
+      { "option": "windowMs", "type": "number", "default": "60000", "notes": "Time window in milliseconds (default: 1 minute)." },
+      { "option": "max", "type": "number", "default": "100", "notes": "Maximum requests per window per key." },
+      { "option": "statusCode", "type": "number", "default": "429", "notes": "HTTP status code for rate-limited responses." },
+      { "option": "message", "type": "string", "default": "Too many requests, please try again later.", "notes": "Error message returned in the JSON response body when limit is exceeded." },
+      { "option": "keyGenerator", "type": "function", "default": "(req) => req.ip || 'unknown'", "notes": "Custom function to extract a rate-limit key from the request." }
+    ]
+  },
+  {
+    "name": "logger([opts])",
+    "description": "Request-logging middleware that prints method, URL, status code, and response time. Supports three output formats with optional ANSI colorization. Hooks into the response 'finish' event to capture final status.",
+    "example": "const { logger } = require('zero-http')\n\n// Colorized dev output (default)\napp.use(logger())\n\n// Short format with custom log function\napp.use(logger({\n\tformat: 'short',\n\tlogger: (msg) => fs.appendFileSync('access.log', msg + '\\n')\n}))\n\n// Tiny format, no colors\napp.use(logger({ format: 'tiny', colors: false }))",
+    "options": [
+      { "option": "format", "type": "string", "default": "dev", "notes": "'dev' (colorized method/status/time), 'short' (IP + method + url + status + time), or 'tiny' (method + url + status + time)." },
+      { "option": "logger", "type": "function", "default": "console.log", "notes": "Custom log output function." },
+      { "option": "colors", "type": "boolean", "default": "auto (TTY detection)", "notes": "Enable or disable ANSI color codes. Auto-detected from process.stdout.isTTY." }
+    ]
+  }
+]