![\"zero-http](\"documentation/public/icons/logo-animated.svg\"){kind=icon}
\r\n\r\n \r\n
\r\n \r\n 📖 Full Documentation & Live Playground →\r\n \r\n
\r\n\r\n---\r\n\r\n## Install\r\n\r\n```bash\r\nnpm install zero-http\r\n```\r\n\r\nRequires Node.js 18+. No external dependencies — everything is built on Node.js core APIs.\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n```js\r\nconst { createApp, json } = require('zero-http')\r\nconst app = createApp()\r\n\r\napp.use(json())\r\napp.post('/echo', (req, res) => res.json({ received: req.body }))\r\napp.listen(3000, () => console.log('Listening on :3000'))\r\n```\r\n\r\n---\r\n\r\n## Features\r\n\r\n### Routing\r\n\r\n`get`, `post`, `put`, `delete`, `patch`, `head`, `options`, `all`, plus `Router()` sub-apps with `use()` mounting. Route chaining via `chain(path)`, route grouping via `group(prefix, ...mw, cb)`, wildcard & parameter patterns, and `param()` pre-processing. Full route introspection with `routes()`.\r\n\r\n### Body Parsers\r\n\r\n`json()`, `urlencoded()`, `text()`, `raw()`, and `multipart()` with streaming file uploads, size limits, and progress tracking.\r\n\r\n### Middleware\r\n\r\n20+ built-in middleware — all zero-dependency:\r\n\r\n| Middleware | Purpose |\r\n|---|---|\r\n| `cors()` | Cross-origin resource sharing |\r\n| `helmet()` | Security headers |\r\n| `compress()` | Gzip, Brotli, and deflate compression |\r\n| `rateLimit()` | Per-IP request throttling |\r\n| `logger()` | Request logging with timing and colors |\r\n| `timeout()` | Request timeout enforcement |\r\n| `requestId()` | Unique request IDs |\r\n| `cookieParser()` | Cookie parsing with signed cookie support |\r\n| `csrf()` | CSRF token protection |\r\n| `validate()` | Schema-based request validation |\r\n| `errorHandler()` | Centralized error handling |\r\n| `static()` | Static file serving with ETags and HTTP/2 push |\r\n\r\n### Authentication & Authorization\r\n\r\nFull auth stack with no external libraries:\r\n\r\n- **JWT** — `jwt()` middleware, `jwtSign()`, `jwtVerify()`, `jwtDecode()`, JWKS key sets, access/refresh token pairs\r\n- **Sessions** — `session()` middleware with in-memory store (pluggable)\r\n- **OAuth 2.0** — `oauth()` middleware with PKCE, pre-configured providers (Google, GitHub, Microsoft, etc.)\r\n- **Authorization** — `authorize()` policies, `can()` / `canAny()` permission checks, `gate()` middleware\r\n\r\n### ORM & Database\r\n\r\nFull-featured ORM with 7 adapters — memory, JSON file, SQLite, MySQL, PostgreSQL, MongoDB, and Redis:\r\n\r\n```js\r\nconst { Database, Model, TYPES } = require('zero-http')\r\n\r\nconst db = Database.connect('sqlite', { filename: 'app.db' })\r\n\r\nclass User extends Model {\r\n static table = 'users'\r\n static schema = {\r\n name: { type: TYPES.STRING, required: true },\r\n email: { type: TYPES.STRING, unique: true },\r\n }\r\n}\r\n\r\ndb.register(User)\r\nawait db.sync()\r\n\r\nawait User.create({ name: 'Alice', email: 'alice@example.com' })\r\nconst users = await User.find({ name: 'Alice' })\r\n```\r\n\r\n**Query builder** — `where()`, `select()`, `orderBy()`, `limit()`, `offset()`, `join()`, `groupBy()`, `having()`, `paginate()`, `findOrCreate()`\r\n\r\n**Advanced ORM features:**\r\n\r\n| Feature | Description |\r\n|---|---|\r\n| Migrations | `Migrator` with up/down, rollback, and status tracking |\r\n| Seeding | `Seeder`, `Factory`, and `Fake` for test data generation |\r\n| Query caching | In-memory LRU cache with TTL and write-through invalidation |\r\n| Read replicas | `ReplicaManager` with automatic primary/replica routing |\r\n| Full-text search | `FullTextSearch` with indexing and ranked results |\r\n| Geo queries | `GeoQuery` with distance, bounding box, and nearest-neighbor |\r\n| Multi-tenancy | `TenantManager` with isolated per-tenant scoping |\r\n| Audit logging | `AuditLog` for change tracking with diffs and user attribution |\r\n| Schema snapshots | EF Core-style snapshot diffing with auto-generated migrations |\r\n| Query profiler | N+1 detection, slow query tracking, and execution analysis |\r\n| Views & procedures | `DatabaseView`, `StoredProcedure`, `StoredFunction`, `TriggerManager` |\r\n| Plugins | `PluginManager` for extending ORM behavior |\r\n\r\n### Real-Time\r\n\r\n- **WebSocket** — `app.ws(path, handler)` with RFC 6455, `WebSocketPool` for rooms, broadcasting, and sub-protocols\r\n- **Server-Sent Events** — `res.sse()` with auto-IDs, named events, and keep-alive\r\n\r\n### Observability\r\n\r\nBuilt-in Prometheus metrics, health checks, distributed tracing, and structured logging — zero dependencies.\r\n\r\n```js\r\nconst { createApp, metricsMiddleware } = require('zero-http')\r\nconst app = createApp()\r\n\r\n// Auto-instrument all HTTP requests (counters, histograms, active connections)\r\napp.use(metricsMiddleware({ registry: app.metrics() }))\r\n\r\n// Expose endpoints\r\napp.metricsEndpoint() // GET /metrics (Prometheus scrape target)\r\napp.health() // GET /healthz (liveness probe)\r\napp.ready() // GET /readyz (readiness probe)\r\n\r\n// Custom metrics\r\nconst logins = app.metrics().counter({\r\n name: 'user_logins_total',\r\n help: 'Total login attempts',\r\n labels: ['provider'],\r\n})\r\nlogins.inc({ provider: 'github' })\r\n\r\napp.listen(3000)\r\n```\r\n\r\n**Scrape with Prometheus** — create a `prometheus.yml`:\r\n\r\n```yaml\r\nscrape_configs:\r\n - job_name: 'my-app'\r\n scrape_interval: 5s\r\n static_configs:\r\n - targets: ['localhost:3000']\r\n```\r\n\r\n```bash\r\ndocker run -d -p 9090:9090 -v ./prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus\r\n# Open http://localhost:9090 → Graph → query http_requests_total\r\n```\r\n\r\n**Also includes:**\r\n- **Distributed tracing** — `Tracer` and `Span` with W3C Trace Context (`traceparent` propagation), `instrumentFetch()` for outgoing requests\r\n- **Structured logging** — `Logger` with levels, JSON output, and namespaced `debug()` logger\r\n\r\n### Lifecycle & Clustering\r\n\r\n- **Graceful shutdown** — signal handlers (SIGTERM/SIGINT), in-flight request draining, automatic WebSocket/SSE/database cleanup\r\n- **Clustering** — `clusterize()` for multi-worker processes with auto-respawn and exponential backoff\r\n\r\n### CLI\r\n\r\nScaffolding and database management via `npx zh`:\r\n\r\n```bash\r\nnpx zh migrate # run pending migrations\r\nnpx zh migrate:rollback # rollback last migration\r\nnpx zh migrate:status # show migration status\r\nnpx zh seed # run seeders\r\nnpx zh make:model User # scaffold a model\r\nnpx zh make:migration name # create migration file\r\nnpx zh make:seeder User # create seeder file\r\n```\r\n\r\n### Environment Config\r\n\r\nTyped `.env` loader with schema validation, multi-file support (`.env`, `.env.local`, `.env.{NODE_ENV}`), variable interpolation, and type coercion (string, number, boolean, integer, array, json, url, port, enum).\r\n\r\n### HTTP Client\r\n\r\nBuilt-in `fetch()` with HTTPS/mTLS support, timeouts, `AbortSignal`, progress callbacks, and JSON/form/stream bodies.\r\n\r\n### HTTPS & HTTP/2\r\n\r\n```js\r\napp.listen(443, {\r\n key: fs.readFileSync('key.pem'),\r\n cert: fs.readFileSync('cert.pem'),\r\n}, () => console.log('HTTPS on 443'))\r\n```\r\n\r\nNative HTTP/2 with automatic HTTP/1.1 fallback. `req.secure`, `req.protocol`, `ws.secure`, and `sse.secure` everywhere.\r\n\r\n### Error Handling\r\n\r\n20+ typed error classes (`NotFoundError`, `ValidationError`, `ForbiddenError`, `PayloadTooLargeError`, `DatabaseError`, `MigrationError`, etc.) plus `createError(status, message)` factory and `isHttpError()` check. Built-in CRLF injection prevention, prototype pollution filtering, path traversal guards, and filename sanitization.\r\n\r\n### TypeScript\r\n\r\nFull type definitions for every API, middleware option, ORM model, auth flow, and plugin interface.\r\n\r\n---\r\n\r\n## Production Example\r\n\r\n```js\r\nconst path = require('path')\r\nconst {\r\n createApp, Router, cors, json, urlencoded, compress,\r\n helmet, timeout, requestId, cookieParser, logger,\r\n static: serveStatic, rateLimit, jwt, session,\r\n Database, Model, TYPES, env, clusterize,\r\n WebSocketPool,\r\n} = require('zero-http')\r\n\r\nenv.load({\r\n PORT: { type: 'port', default: 3000 },\r\n JWT_SECRET: { type: 'string', required: true },\r\n DB_PATH: { type: 'string', default: './data.db' },\r\n})\r\n\r\nclusterize(() => {\r\n const app = createApp()\r\n const db = Database.connect('sqlite', { filename: env.DB_PATH })\r\n\r\n // Middleware stack\r\n app.use(helmet())\r\n app.use(logger())\r\n app.use(cors())\r\n app.use(compress())\r\n app.use(timeout(30_000))\r\n app.use(rateLimit())\r\n app.use(cookieParser())\r\n app.use(session({ secret: env.JWT_SECRET }))\r\n app.use(json())\r\n app.use(urlencoded())\r\n app.use(serveStatic(path.join(__dirname, 'public')))\r\n\r\n // Observability\r\n app.health()\r\n app.ready()\r\n app.metricsEndpoint()\r\n\r\n // API routes\r\n const api = Router()\r\n api.get('/health', (req, res) => res.json({ status: 'ok' }))\r\n api.get('/users/:id', jwt({ secret: env.JWT_SECRET }), (req, res) => {\r\n res.json({ id: req.params.id, user: req.user })\r\n })\r\n app.use('/api', api)\r\n\r\n // WebSocket\r\n const pool = new WebSocketPool()\r\n app.ws('/chat', (ws) => {\r\n pool.add(ws)\r\n pool.join(ws, 'lobby')\r\n ws.on('message', msg => pool.toRoom('lobby', msg, ws))\r\n })\r\n\r\n // SSE\r\n app.get('/events', (req, res) => {\r\n const sse = res.sse({ retry: 3000, autoId: true })\r\n sse.send('connected')\r\n })\r\n\r\n app.listen(env.PORT, () => console.log(`Worker ${process.pid} on :${env.PORT}`))\r\n})\r\n```\r\n\r\n---\r\n\r\n## Exports\r\n\r\nAll exports from the package root:\r\n\r\n```js\r\nconst {\r\n // Core\r\n createApp, Router, version,\r\n\r\n // Body parsers\r\n json, urlencoded, text, raw, multipart,\r\n\r\n // Middleware\r\n cors, helmet, compress, rateLimit, logger,\r\n timeout, requestId, cookieParser, csrf,\r\n validate, errorHandler, static: serveStatic,\r\n\r\n // Auth\r\n jwt, jwtSign, jwtVerify, jwtDecode, jwks, tokenPair,\r\n session, Session, MemoryStore,\r\n oauth, generatePKCE, generateState, OAUTH_PROVIDERS,\r\n authorize, can, canAny, Policy, gate,\r\n\r\n // ORM\r\n Database, Model, TYPES, Query,\r\n Migrator, defineMigration,\r\n Seeder, SeederRunner, Factory, Fake,\r\n QueryCache, QueryProfiler, ReplicaManager,\r\n FullTextSearch, GeoQuery, TenantManager, AuditLog,\r\n DatabaseView, StoredProcedure, StoredFunction, TriggerManager,\r\n PluginManager, buildSnapshot, diffSnapshots,\r\n\r\n // Observability\r\n Logger, structuredLogger,\r\n Counter, Gauge, Histogram, MetricsRegistry,\r\n metricsMiddleware, metricsEndpoint,\r\n Span, Tracer, tracingMiddleware, instrumentFetch,\r\n healthCheck, memoryCheck, eventLoopCheck, diskSpaceCheck,\r\n\r\n // Real-time\r\n WebSocketConnection, WebSocketPool, SSEStream,\r\n\r\n // Utilities\r\n fetch, env, debug,\r\n ClusterManager, clusterize,\r\n LifecycleManager, LIFECYCLE_STATE,\r\n\r\n // Errors\r\n HttpError, BadRequestError, UnauthorizedError,\r\n ForbiddenError, NotFoundError, ValidationError,\r\n ConflictError, PayloadTooLargeError, TooManyRequestsError,\r\n TimeoutError, DatabaseError, MigrationError,\r\n createError, isHttpError,\r\n\r\n // CLI\r\n CLI, runCLI,\r\n} = require('zero-http')\r\n```\r\n\r\n---\r\n\r\n## Documentation\r\n\r\n| Resource | Description |\r\n|---|---|\r\n| **[z-http.com](https://z-http.com)** | Interactive documentation with live playground, search, and examples |\r\n| **[API.md](API.md)** | Full API reference with tables, examples, and options for every export |\r\n\r\n### Run docs locally\r\n\r\n```bash\r\ncp documentation/.env.example documentation/.env\r\nnpm run docs\r\n# open http://localhost:7273\r\n```\r\n\r\n---\r\n\r\n## File Layout\r\n\r\n```\r\nlib/\r\n app.js — App class (middleware, routing, listen, ws upgrade, lifecycle)\r\n auth/ — JWT, OAuth 2.0, sessions, and authorization policies\r\n body/ — body parsers (json, urlencoded, text, raw, multipart)\r\n cli.js — CLI runner (migrate, seed, scaffold commands)\r\n cluster.js — multi-worker clustering with auto-respawn\r\n debug.js — namespaced debug logger\r\n env/ — typed .env loader with schema validation\r\n errors.js — 20+ HttpError classes and factory\r\n fetch/ — HTTP/HTTPS client\r\n http/ — Request & Response wrappers\r\n lifecycle.js — graceful shutdown and lifecycle management\r\n middleware/ — cors, helmet, logger, rateLimit, compress, static, timeout,\r\n requestId, cookieParser, csrf, validate, errorHandler\r\n observe/ — Prometheus metrics, W3C tracing, health checks, structured logging\r\n orm/ — Database, Model, Query, adapters, migrations, seeds, cache,\r\n replicas, search, geo, tenancy, audit, views, procedures, plugins\r\n router/ — Router with sub-app mounting and pattern matching\r\n sse/ — SSE stream controller\r\n ws/ — WebSocket connection, handshake, and room management\r\ntypes/ — full TypeScript definitions\r\ndocumentation/ — live demo server, controllers, and playground UI\r\ntest/ — vitest test suite (6000+ tests, 95%+ coverage)\r\n```\r\n\r\n## Testing\r\n\r\n```bash\r\nnpm test # vitest run (single pass)\r\nnpm run test:watch # vitest (watch mode)\r\n```\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md"}