zero-http 0.2.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,311 @@
+# zero-http
+
+[![npm version](https://img.shields.io/npm/v/zero-http.svg)](https://www.npmjs.com/package/zero-http)
+[![npm downloads](https://img.shields.io/npm/dm/zero-http.svg)](https://www.npmjs.com/package/zero-http)
+[![GitHub](https://img.shields.io/badge/GitHub-zero--http--npm-blue.svg)](https://github.com/tonywied17/zero-http-npm)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D14-brightgreen.svg)](https://nodejs.org)
+[![Dependencies](https://img.shields.io/badge/dependencies-0-success.svg)](package.json)
+
+> **Zero-dependency, minimal Express-like HTTP server with a tiny fetch replacement and streaming multipart parsing.**
+
+## Features
+
+- **Zero dependencies** — implemented using Node core APIs only
+- **Express-like API** — `createApp()`, `use()`, `get()`, `post()`, `put()`, `delete()`, `patch()`, `head()`, `options()`, `all()`, `listen()`
+- **Built-in middlewares** — `cors()`, `json()`, `urlencoded()`, `text()`, `raw()`, `multipart()`, `rateLimit()`, `logger()`
+- **Streaming multipart parser** — writes file parts to disk and exposes `req.body.files` and `req.body.fields`
+- **Tiny `fetch` replacement** — convenient server-side HTTP client with progress callbacks
+- **Static file serving** — 60+ MIME types, dotfile policy, caching, extension fallback
+- **Error handling** — automatic 500 responses for thrown errors, global error handler via `app.onError()`
+- **Path-prefix middleware** — `app.use('/api', handler)` with automatic URL rewriting
+- **Rate limiting** — in-memory IP-based rate limiter with configurable windows
+- **Request logger** — colorized dev/short/tiny log formats
+ 
+
+```bash
+npm install zero-http
+```
+
+## Quick start
+
+```js
+const { createApp, json } = require('zero-http')
+const app = createApp()
+
+app.use(json())
+app.post('/echo', (req, res) => res.json({ received: req.body }))
+app.listen(3000)
+```
+
+Demo
+
+You can view the live documentation and playground at https://zero-http.molex.cloud, or run the demo locally:
+
+```bash
+node documentation/full-server.js
+# open http://localhost:3000
+```
+
+## API Reference
+
+All exports are available from the package root:
+
+```js
+const { createApp, cors, fetch, json, urlencoded, text, raw, multipart, static: serveStatic, rateLimit, logger } = require('zero-http')
+```
+
+| Export | Type | Description |
+|---|---|---|
+| `createApp()` | function | Create a new application instance (router + middleware stack). |
+| `cors` | function | CORS middleware factory. |
+| `fetch` | function | Small Node HTTP client with progress callbacks. |
+| `json` | function | JSON body parser factory. |
+| `urlencoded` | function | urlencoded body parser factory. |
+| `text` | function | Text body parser factory. |
+| `raw` | function | Raw bytes parser factory. |
+| `multipart` | function | Streaming multipart parser factory. |
+| `static` | function | Static file serving middleware factory. |
+| `rateLimit` | function | In-memory rate-limiting middleware factory. |
+| `logger` | function | Request-logging middleware factory. |
+
+createApp() methods
+
+| Method | Signature | Description |
+|---|---|---|
+| `use` | `use(fn)` or `use(path, fn)` | Register middleware globally or scoped to a path prefix. |
+| `get` | `get(path, ...handlers)` | Register GET route handlers. |
+| `post` | `post(path, ...handlers)` | Register POST route handlers. |
+| `put` | `put(path, ...handlers)` | Register PUT route handlers. |
+| `delete` | `delete(path, ...handlers)` | Register DELETE route handlers. |
+| `patch` | `patch(path, ...handlers)` | Register PATCH route handlers. |
+| `options` | `options(path, ...handlers)` | Register OPTIONS route handlers. |
+| `head` | `head(path, ...handlers)` | Register HEAD route handlers. |
+| `all` | `all(path, ...handlers)` | Register handlers for ALL HTTP methods. |
+| `onError` | `onError(fn)` | Register a global error handler `fn(err, req, res, next)`. |
+| `listen` | `listen(port = 3000, cb)` | Start the HTTP server. Returns the server instance. |
+| `handler` | property | Bound request handler for `http.createServer(app.handler)`. |
+
+Request (`req`) properties & helpers
+
+| Property / Method | Type | Description |
+|---|---|---|
+| `method` | string | HTTP method (GET, POST, etc.). |
+| `url` | string | Request URL (path + query). |
+| `headers` | object | Raw request headers. |
+| `query` | object | Parsed query string. |
+| `params` | object | Route parameters (populated by router). |
+| `body` | any | Parsed body (populated by body parsers). |
+| `ip` | string | Remote IP address of the client. |
+| `get(name)` | function | Get a request header (case-insensitive). |
+| `is(type)` | function | Check if Content-Type matches a type (e.g. `'json'`, `'text/html'`). |
+| `raw` | object | Underlying `http.IncomingMessage`. |
+
+Response (`res`) helpers
+
+| Method | Signature | Description |
+|---|---|---|
+| `status` | `status(code)` | Set HTTP status code. Chainable. |
+| `set` | `set(name, value)` | Set a response header. Chainable. |
+| `get` | `get(name)` | Get a previously-set response header. |
+| `type` | `type(ct)` | Set Content-Type (accepts shorthand like `'json'`, `'html'`, `'text'`). Chainable. |
+| `send` | `send(body)` | Send a response; auto-detects Content-Type for strings, objects, and Buffers. |
+| `json` | `json(obj)` | Set JSON Content-Type and send object. |
+| `text` | `text(str)` | Set text/plain and send string. |
+| `html` | `html(str)` | Set text/html and send string. |
+| `redirect` | `redirect([status], url)` | Redirect to URL (default 302). |
+
+### Body parsers
+
+The package exposes parser factory functions under `json`, `urlencoded`, `text`, `raw`, and `multipart`.
+
+json([opts])
+
+| Option | Type | Default | Description |
+|---|---:|---|---|
+| `limit` | number|string | none | Maximum body size (bytes or unit string like `'1mb'`). |
+| `reviver` | function | — | Function passed to `JSON.parse` for custom reviving. |
+| `strict` | boolean | `true` | When `true` only accepts objects/arrays (rejects primitives). |
+| `type` | string|function | `'application/json'` | MIME matcher for the parser. |
+
+urlencoded([opts])
+
+| Option | Type | Default | Description |
+|---|---:|---|---|
+| `extended` | boolean | `false` | When `true` supports rich nested bracket syntax (a[b]=1, a[]=1). |
+| `limit` | number|string | none | Maximum body size. |
+| `type` | string|function | `'application/x-www-form-urlencoded'` | MIME matcher. |
+
+text([opts])
+
+| Option | Type | Default | Description |
+|---|---:|---|---|
+| `type` | string|function | `text/*` | MIME matcher for text bodies. |
+| `limit` | number|string | none | Maximum body size. |
+| `encoding` | string | `utf8` | Character encoding used to decode bytes. |
+
+raw([opts])
+
+| Option | Type | Default | Description |
+|---|---:|---|---|
+| `type` | string|function | `application/octet-stream` | MIME matcher for raw parser. |
+| `limit` | number|string | none | Maximum body size. |
+
+multipart(opts)
+
+Streaming multipart parser that writes file parts to disk and collects fields.
+
+| Option | Type | Default | Description |
+|---|---:|---|---|
+| `dir` | string | `os.tmpdir()/zero-http-uploads` | Directory to store uploaded files (absolute or relative to `process.cwd()`). |
+| `maxFileSize` | number | none | Maximum allowed file size in bytes. Exceeding this returns HTTP 413 and aborts the upload. |
+
+Behavior: `multipart` writes file parts to disk with a generated name preserving the original extension when possible. On completion `req.body` will be `{ fields, files }` where `files` contains metadata: `originalFilename`, `storedName`, `path`, `contentType`, `size`.
+
+### static(rootPath, opts)
+
+Serve static files from `rootPath`.
+
+| Option | Type | Default | Description |
+|---|---:|---|---|
+| `index` | string|false | `'index.html'` | File to serve for directory requests; set `false` to disable. |
+| `maxAge` | number|string | `0` | Cache-Control `max-age` (ms or unit string like `'1h'`). |
+| `dotfiles` | string | `'ignore'` | `'allow'|'deny'|'ignore'` — how to handle dotfiles. |
+| `extensions` | string[] | — | Fallback extensions to try when a request omits an extension. |
+| `setHeaders` | function | — | Hook `(res, filePath) => {}` to set custom headers per file. |
+
+### cors([opts])
+
+Small CORS middleware. Typical options:
+
+| Option | Type | Default | Description |
+|---|---:|---|---|
+| `origin` | string|boolean|array | `'*'` | Allowed origin(s). Use `false` to disable CORS. |
+| `methods` | string | `'GET,POST,PUT,DELETE,OPTIONS'` | Allowed methods. |
+| `credentials` | boolean | `false` | When true and a specific origin matches, sets `Access-Control-Allow-Credentials`.
+| `allowedHeaders` | string | — | Headers allowed in requests. |
+
+### fetch(url, opts)
+
+Small Node HTTP client returning an object with `status`, `headers` and helpers: `text()`, `json()`, `arrayBuffer()`.
+
+| Option | Type | Default | Description |
+|---|---:|---|---|
+| `method` | string | `GET` | HTTP method. |
+| `headers` | object | — | Request headers. |
+| `agent` | object | — | Optional `http`/`https` agent for connection pooling or proxies. |
+| `body` | Buffer|string|Stream|URLSearchParams|object | — | Request body. Plain objects are JSON-encoded and `Content-Type` is set to `application/json` if not provided; `URLSearchParams` produce urlencoded bodies. |
+| `timeout` | number | — | Request timeout in milliseconds. |
+| `signal` | AbortSignal | — | Optional `AbortSignal` to cancel the request. |
+| `onUploadProgress` / `onDownloadProgress` | function | — | Callbacks receiving `{ loaded, total }` during transfer. |
+
+Response: resolved value includes `ok`, `statusText`, and helpers `arrayBuffer()`, `text()`, `json()`.
+
+Example usage:
+
+```js
+const r = await fetch('https://jsonplaceholder.typicode.com/todos/1', { timeout: 5000 })
+const data = await r.json()
+```
+
+### rateLimit([opts])
+
+In-memory, per-IP rate-limiting middleware. Sets standard `X-RateLimit-*` headers.
+
+| Option | Type | Default | Description |
+|---|---:|---|---|
+| `windowMs` | number | `60000` | Time window in milliseconds. |
+| `max` | number | `100` | Maximum requests per window per key. |
+| `message` | string | `'Too many requests…'` | Error message returned when limit is exceeded. |
+| `statusCode` | number | `429` | HTTP status for rate-limited responses. |
+| `keyGenerator` | function | `(req) => req.ip` | Custom key extraction function. |
+
+Example:
+
+```js
+app.use(rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }))
+```
+
+### logger([opts])
+
+Request-logging middleware that prints method, url, status, and response time.
+
+| Option | Type | Default | Description |
+|---|---:|---|---|
+| `format` | string | `'dev'` | Log format: `'dev'` (colorized), `'short'`, or `'tiny'`. |
+| `logger` | function | `console.log` | Custom log function. |
+| `colors` | boolean | auto (TTY) | Enable/disable ANSI colors. |
+
+Example:
+
+```js
+app.use(logger({ format: 'dev' }))
+```
+
+### Error handling
+
+Thrown errors in route handlers are automatically caught and return a 500 JSON response. Register a custom error handler for more control:
+
+```js
+app.onError((err, req, res, next) => {
+    console.error(err)
+    res.status(500).json({ error: err.message })
+})
+```
+
+### Path-prefix middleware
+
+Mount middleware on a path prefix. The URL is rewritten so downstream middleware sees relative paths:
+
+```js
+app.use('/api', myApiRouter)
+```
+
+## Examples
+
+Small JSON API:
+
+```js
+const { createApp, json, cors } = require('zero-http')
+const app = createApp()
+
+app.use(cors({ origin: ['https://example.com'] }))
+app.use(json({ limit: '10kb' }))
+
+const items = []
+app.post('/items', (req, res) => {
+	items.push(req.body)
+	res.status(201)
+	res.json({ ok: true })
+})
+```
+
+Upload handler (writes files to disk by default):
+
+```js
+app.post('/upload', multipart({ dir: uploadsDir, maxFileSize: 10 * 1024 * 1024 }), (req, res) => {
+	res.json({ files: req.body.files })
+})
+```
+
+Static server example:
+
+```js
+app.use(static(path.join(__dirname, 'documentation', 'public'), { index: 'index.html', maxAge: '1h' }))
+```
+
+## File layout
+
+- `lib/` — core helpers and middleware (router, fetch, body parsers, static, rate limiter, logger)
+- `documentation/` — demo server, controllers and public UI used to showcase features
+- `test/` — integration tests
+
+## Testing
+
+```bash
+node test/test.js
+```
+
+## License
+
+MIT

package/documentation/controllers/cleanup.js

@@ -0,0 +1,25 @@
+/** Clean up temp files older than ?seconds (default 60) */
+const fs = require('fs');
+const path = require('path');
+
+exports.cleanup = (tmpDirPath) => (req, res) =>
+{
+    const olderThan = (Number(req.query.seconds) || 60) * 1000;
+    const now = Date.now();
+    const removed = [];
+    try
+    {
+        if (fs.existsSync(tmpDirPath))
+        {
+            for (const f of fs.readdirSync(tmpDirPath))
+            {
+                try
+                {
+                    const st = fs.statSync(path.join(tmpDirPath, f));
+                    if (now - st.mtimeMs > olderThan) { fs.unlinkSync(path.join(tmpDirPath, f)); removed.push(f); }
+                } catch (e) { }
+            }
+        }
+    } catch (e) { return res.status(500).json({ error: String(e) }); }
+    res.json({ removed });
+};

package/documentation/controllers/echo.js

@@ -0,0 +1,14 @@
+/** Echo JSON body back as { received: ... } */
+const echoBody = (req, res) => res.json({ received: req.body });
+
+exports.echoJson       = echoBody;
+exports.echo           = echoBody;
+exports.echoUrlencoded = echoBody;
+
+exports.echoText = (req, res) => res.text(req.body || '');
+
+exports.echoRaw = (req, res) =>
+{
+    const b = req.body || Buffer.alloc(0);
+    res.json({ length: b.length, preview: b.slice(0, 64).toString('hex') });
+};

package/documentation/controllers/headers.js

@@ -0,0 +1 @@
+exports.getHeaders = (req, res) => res.json({ headers: req.headers });

package/documentation/controllers/proxy.js

@@ -0,0 +1,112 @@
+/**
+ * Controller for proxy endpoint using built-in fetch.
+ * Proxies an external URL provided via ?url= query parameter.
+ */
+exports.proxy = (fetch) => async (req, res) =>
+{
+    const url = req.query.url;
+    if (!url || typeof url !== 'string' || !/^https?:\/\//.test(url))
+    {
+        return res.status(400).json({ error: 'Missing or invalid url query parameter (must start with http/https)' });
+    }
+
+    // helper: normalize headers object from various fetch implementations
+    const normalizeResponseHeaders = (headers) =>
+    {
+        const out = {};
+        if (!headers) return out;
+        if (typeof headers.raw === 'function')
+        {
+            try { Object.assign(out, headers.raw() || {}); } catch (e) { }
+            return out;
+        }
+        if (headers.raw && typeof headers.raw === 'object')
+        {
+            Object.assign(out, headers.raw);
+            return out;
+        }
+        if (typeof headers.entries === 'function')
+        {
+            for (const [k, v] of headers.entries()) { out[k] = out[k] ? out[k] + ', ' + v : v; }
+            return out;
+        }
+        if (typeof headers === 'object')
+        {
+            Object.assign(out, headers);
+        }
+        return out;
+    };
+
+    try
+    {
+        // forward client headers useful for media requests
+        const forwardHeaders = {};
+        try
+        {
+            const inHeaders = (req.raw && req.raw.headers) ? req.raw.headers : (req.headers || {});
+            ['range', 'if-range', 'accept', 'accept-encoding', 'user-agent'].forEach(h =>
+            {
+                const v = inHeaders[h] || inHeaders[h.toLowerCase()];
+                if (v) forwardHeaders[h] = v;
+            });
+        } catch (e) { }
+
+        const r = await fetch(url, { headers: forwardHeaders });
+
+        // if upstream returned an error status, try to show body (json or text)
+        if (r.status >= 400)
+        {
+            try
+            {
+                const j = await r.json();
+                return res.status(r.status).json(j);
+            } catch (e)
+            {
+                try { const txt = await r.text(); return res.status(r.status).send(txt); } catch (e2) { return res.status(r.status).send('Upstream error'); }
+            }
+        }
+
+        // If JSON response, parse and return JSON
+        const headersObj = normalizeResponseHeaders(r.headers);
+        const contentType = (headersObj['content-type'] || headersObj['Content-Type'] || '').toString();
+        if (contentType.includes('application/json'))
+        {
+            const body = await r.json();
+            return res.status(r.status).json(body);
+        }
+
+        // Forward headers to raw response before streaming
+        try { res.raw.statusCode = r.status; } catch (e) { }
+        try
+        {
+            Object.entries(headersObj).forEach(([k, v]) =>
+            {
+                try { res.raw.setHeader(k, Array.isArray(v) ? v.join(', ') : v); } catch (e) { }
+            });
+        } catch (e) { }
+
+        // If upstream exposes a readable stream, pipe it directly to client
+        if (r.body && typeof r.body.pipe === 'function')
+        {
+            try
+            {
+                r.body.on && r.body.on('error', () => { try { res.raw.end(); } catch (e) { } });
+                return r.body.pipe(res.raw);
+            } catch (e) { /* fallthrough to buffering */ }
+        }
+
+        // Fallback: buffer then send (some fetch implementations)
+        try
+        {
+            const ab = await r.arrayBuffer();
+            const buf = Buffer.from(ab);
+            return res.raw.end(buf);
+        } catch (e)
+        {
+            return res.status(500).json({ error: 'Failed to stream proxied response' });
+        }
+    } catch (e)
+    {
+        return res.status(500).json({ error: String(e) });
+    }
+};

package/documentation/controllers/root.js

@@ -0,0 +1 @@
+exports.getRoot = (req, res) => res.json({ ok: true, msg: 'zero-http full-server example' });