{"_id":"@ahadpvt.v3/fastserve","_rev":"3-d009bc091f970c9bf306f5eacb4f0e01","name":"@ahadpvt.v3/fastserve","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@ahadpvt.v3/fastserve","version":"1.0.0","keywords":["http","https","router","dispatcher","framework","middleware","websocket","sse","tcp","udp","unix","tls","http2","cron","proxy","cors","rest","graphql","edge","lambda","cloudflare","workers"],"author":{"name":"Abdul Ahad"},"license":"MIT","_id":"@ahadpvt.v3/fastserve@1.0.0","maintainers":[{"name":"ahadpvt.v3","email":"ahadpvt.v3@gmail.com"}],"dist":{"shasum":"850055929f065b1a42e3c5d9a2d6021d1d48bb3b","tarball":"https://registry.npmjs.org/@ahadpvt.v3/fastserve/-/fastserve-1.0.0.tgz","fileCount":6,"integrity":"sha512-OBmfr7ij67I+7ICl9vvNCzHBDYdhkOs+64I7mghtBeYPHnj2Z92FJ64PTzeAr7OSBkZlsu8Z6zAO2KeZjdFdZg==","signatures":[{"sig":"MEUCIGK+xn8vBlWlg7JCpLDhrz0qSb3xf5Y3EWjz/LTNorGaAiEAzlRwHwoUr2cVhBFrrnqmr6LhO1QnmW/YVgjpmHrGB4o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":90137},"main":"index.js","types":"index.d.ts","engines":{"node":">=14"},"exports":{".":{"import":"./index.mjs","require":"./index.js"}},"scripts":{"test":"node test.js"},"_npmUser":{"name":"ahadpvt.v3","email":"ahadpvt.v3@gmail.com"},"_npmVersion":"9.2.0","description":"Ultra-fast, environment-aware HTTP dispatcher. The last backend framework any developer or enterprise will ever need.","directories":{},"_nodeVersion":"18.19.1","dependencies":{"@ahadpvt.v3/reqex":"^2.0.0","@ahadpvt.v3/urlex":"^1.0.0","@ahadpvt.v3/resmake":"^2.0.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/fastserve_1.0.0_1773527792532_0.6408983437082763","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@ahadpvt.v3/fastserve","version":"1.0.1","keywords":["http","https","router","dispatcher","framework","middleware","websocket","sse","tcp","udp","unix","tls","http2","cron","proxy","cors","rest","graphql","edge","lambda","cloudflare","workers"],"author":{"name":"Abdul Ahad"},"license":"MIT","_id":"@ahadpvt.v3/fastserve@1.0.1","maintainers":[{"name":"ahadpvt.v3","email":"ahadpvt.v3@gmail.com"}],"dist":{"shasum":"d9ab05ac040ca2493e146d7ef7f2ca58299be274","tarball":"https://registry.npmjs.org/@ahadpvt.v3/fastserve/-/fastserve-1.0.1.tgz","fileCount":6,"integrity":"sha512-gOXzaapJ84iwC/BzHFP6/xU8HN2ucOuW+MB3G+lRtKGk07j+VGr+kYAaMiwncFWzWG1nFcpLSojOn6MMQymxhg==","signatures":[{"sig":"MEYCIQDpHbH5wQiwvtN31LzfMPnlhppGnBNLNVQuaRsB4fSafQIhALh08hX1auc/r/c0UAbnJJIqkz5L2MYUUGMJ5SxhBtG7","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":90631},"main":"index.js","types":"index.d.ts","engines":{"node":">=14"},"exports":{".":{"import":"./index.mjs","require":"./index.js"}},"scripts":{"test":"node test.js"},"_npmUser":{"name":"ahadpvt.v3","email":"ahadpvt.v3@gmail.com"},"_npmVersion":"10.9.4","description":"Ultra-fast, environment-aware HTTP dispatcher. The last backend framework any developer or enterprise will ever need.","directories":{},"_nodeVersion":"22.22.1","dependencies":{"@ahadpvt.v3/reqex":"^2.0.0","@ahadpvt.v3/urlex":"^1.0.0","@ahadpvt.v3/resmake":"^2.0.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/fastserve_1.0.1_1774163495403_0.0058639354515876985","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@ahadpvt.v3/fastserve","version":"1.0.2","description":"Ultra-fast, environment-aware HTTP dispatcher. The last backend framework any developer or enterprise will ever need.","main":"index.js","types":"index.d.ts","exports":{".":{"types":"./index.d.ts","require":"./index.js","import":"./index.mjs","default":"./index.js"}},"scripts":{"test":"node test.js"},"keywords":["http","https","router","dispatcher","framework","middleware","websocket","sse","tcp","udp","unix","tls","http2","cron","proxy","cors","rest","graphql","edge","lambda","cloudflare","workers"],"dependencies":{"@ahadpvt.v3/urlex":"^1.0.0","@ahadpvt.v3/reqex":"^2.0.0","@ahadpvt.v3/resmake":"^2.0.0"},"author":{"name":"Abdul Ahad"},"license":"MIT","engines":{"node":">=14"},"type":"commonjs","sideEffects":false,"_id":"@ahadpvt.v3/fastserve@1.0.2","_nodeVersion":"22.22.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-3WCnBACwu1lS/VGQDZ4fSOgJ4aivIQzB5maDqZPCcHSCU0Ca9y7upRKSwXjUuJM0/64JO+Ajxd4mfIhZxeErOA==","shasum":"2224a0146b9210aa124cd726e610c27fd793ba0e","tarball":"https://registry.npmjs.org/@ahadpvt.v3/fastserve/-/fastserve-1.0.2.tgz","fileCount":6,"unpackedSize":97129,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCtDKmUqYv6Ru2KcW7KgQSyjPysbu2WQTkIqbsvEoLYiAIgVKa/ghJwUviHmQ/f1pYYCYX/7D+eky1CiPk4LBGKj2c="}]},"_npmUser":{"name":"ahadpvt.v3","email":"ahadpvt.v3@gmail.com"},"directories":{},"maintainers":[{"name":"ahadpvt.v3","email":"ahadpvt.v3@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/fastserve_1.0.2_1774166998448_0.5239181822923109"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-14T22:36:32.406Z","modified":"2026-03-22T08:09:58.700Z","1.0.0":"2026-03-14T22:36:32.697Z","1.0.1":"2026-03-22T07:11:35.561Z","1.0.2":"2026-03-22T08:09:58.607Z"},"author":{"name":"Abdul Ahad"},"license":"MIT","keywords":["http","https","router","dispatcher","framework","middleware","websocket","sse","tcp","udp","unix","tls","http2","cron","proxy","cors","rest","graphql","edge","lambda","cloudflare","workers"],"description":"Ultra-fast, environment-aware HTTP dispatcher. The last backend framework any developer or enterprise will ever need.","maintainers":[{"name":"ahadpvt.v3","email":"ahadpvt.v3@gmail.com"}],"readme":"# @ahadpvt.v3/fastserve\n\nThe **last backend framework any developer or enterprise will ever need.**\n\nZero-dependency, ultra-fast, environment-aware HTTP dispatcher. Built on `urlex` (routing), `reqex` (request parsing), and `resmake` (response building). Covers every backend family — REST, GraphQL, WebSocket, SSE, file server, reverse proxy, auth, webhooks, job server, multitenancy, API gateway, URL shortener, admin, microservices, cron jobs, and raw TCP/UDP.\n\nWorks on Node.js, HTTPS, HTTP/2, Cloudflare Workers, Edge Runtime, AWS Lambda, Deno, and any raw TCP/UDP socket.\n\n---\n\n## Installation\n\n```bash\nnpm install @ahadpvt.v3/fastserve\n```\n\n---\n\n## Quick Start\n\n```js\nconst { createApp } = require(\"@ahadpvt.v3/fastserve\")\n\nconst app = createApp()\n\napp.get(\"/\", (ctx, res) => res.json({ hello: \"world\" }))\napp.get(\"/users/:id\", (ctx, res) => res.json({ id: ctx._params.id }))\n\napp.listen(3000)\n```\n\n---\n\n## Handler Signature\n\nEvery handler and middleware receives the same four arguments:\n\n```js\n(ctx, res, next, ...extras)\n```\n\n- `ctx` — reqex `RequestContext` — method, path, query, cookies, headers, body, ip, params\n- `res` — resmake `ResponseContext` — json, html, send, stream, file, sse, redirect\n- `next` — advance the chain, or `next(err)` to trigger error handling\n- `...extras` — user-configured platform-specific args (CF Workers env/ctx, Lambda event, etc)\n\n---\n\n## Route Registration\n\n### Express-style\n\n```js\napp.get(\"/users\", handler)\napp.post(\"/users\", middleware, handler)\napp.put(\"/users/:id\", handler)\napp.patch(\"/users/:id\", handler)\napp.delete(\"/users/:id\", handler)\napp.head(\"/ping\", handler)\napp.options(\"/cors\", handler)\napp.any(\"/catch-all\", handler)   // any HTTP method\n```\n\n### Object-style\n\n```js\napp.add({\n  method     : \"POST\",\n  pattern    : \"/users\",\n  middleware : [authMiddleware],\n  handler    : createUserHandler,\n  preset     : \"api\",\n  when       : (r) => r.host === \"api.example.com\",\n})\n```\n\n---\n\n## Pattern Syntax — urlex full power\n\n```\n/users/:id              named param         → ctx._params.id\n/api/*:version/users    optional param      → ctx._params.version\n/files/*/download       single wildcard\n/static/**              unlimited glob      → ctx._params[\"**\"][0]\n/files/[1,3]/**         ranged segments     → ctx._params[\"**\"]\n/media/{jpg,png,gif}    literal set (OR)\n*.example.com/page      wildcard host\napi.example.com/v1/**   specific host\n```\n\nPatterns can include both host and path. Path-only patterns match any host.\n\n---\n\n## Middleware\n\n```js\n// Global — runs before every route\napp.use(authMiddleware)\napp.use(loggerMiddleware, metricsMiddleware)\n\n// Pattern-scoped global middleware\napp.use(\"/api/**\", apiKeyMiddleware)\n\n// Per-route\napp.get(\"/admin\", requireAdmin, handler)\n\n// Error handler — detected by 4-argument signature\napp.get(\"/risky\", handler, (err, ctx, res, next) => {\n  res.json({ error: err.message }, 500)\n})\n\n// Global error handler\napp.onError((err, ctx, res) => {\n  res.json({ error: \"Internal Server Error\" }, 500)\n})\n```\n\n### next(err) — error forwarding\n\n```js\napp.get(\"/data\", async (ctx, res, next) => {\n  try {\n    const data = await db.query()\n    res.json(data)\n  } catch (err) {\n    next(err)   // forwards to error handler\n  }\n})\n```\n\n---\n\n## Route Groups\n\n```js\n// Prefix only\napp.group(\"/api/v1\", (g) => {\n  g.get(\"/users\", handler)\n  g.post(\"/users\", handler)\n  g.get(\"/posts/:id\", handler)\n})\n\n// Prefix + group middleware\napp.group(\"/admin\", [requireAdmin], (g) => {\n  g.get(\"/dashboard\", handler)\n  g.get(\"/users\", handler)\n})\n\n// Nested groups\napp.group(\"/api\", (g) => {\n  g.group(\"/v2\", (g2) => {\n    g2.get(\"/resource\", handler)  // → /api/v2/resource\n  })\n})\n```\n\n---\n\n## Sub-application Mounting\n\n```js\nconst usersApp = createApp()\nusersApp.get(\"/\", listUsers)\nusersApp.get(\"/:id\", getUser)\nusersApp.post(\"/\", createUser)\n\nconst app = createApp()\napp.mount(\"/users\", usersApp)  // /users, /users/:id, /users POST\n```\n\n---\n\n## WebSocket\n\n```js\napp.ws(\"/chat/:room\", {\n  onConnect(ws, ctx) {\n    console.log(\"connected\", ctx._params.id)\n    ws.send(\"welcome\")\n  },\n  onMessage(ws, msg, ctx) {\n    ws.send(\"echo: \" + msg)\n  },\n  onClose(ws, code, reason, ctx) {\n    console.log(\"disconnected\", code)\n  },\n  onError(ws, err, ctx) {\n    console.error(err)\n  },\n})\n```\n\n`ws` object: `send(data)`, `ping(data?)`, `close(code?, reason?)`, `id`, `ctx`, `closed`\n\n---\n\n## Server-Sent Events\n\n```js\napp.get(\"/events\", (ctx, res) => {\n  const sse = res.sse()\n\n  sse.send({ type: \"connected\" })\n  sse.send({ type: \"update\", data }, \"update\", \"msg-1\")\n\n  const interval = setInterval(() => sse.ping(), 20_000)\n\n  ctx.socket.on(\"close\", () => {\n    clearInterval(interval)\n    sse.close()\n  })\n})\n```\n\n---\n\n## Raw TCP Server\n\n```js\n// Raw chunk mode\napp.tcp({\n  port    : 4000,\n  onConnect(socket, ctx) { console.log(\"connected\", ctx.ip) },\n  onData(socket, chunk, ctx, res) {\n    res.send(\"echo: \" + chunk.toString())\n  },\n  onClose(socket, ctx) { },\n})\n\n// Framed mode — newline delimited JSON RPC\napp.tcp({\n  port    : 4001,\n  framing : \"newline\",\n  onMessage(socket, frame, ctx, res) {\n    const req = JSON.parse(frame)\n    res.sendFramed(JSON.stringify({ result: \"ok\", id: req.id }))\n  },\n})\n```\n\nFramings: `\"newline\"`, `\"null\"`, `\"length-prefix\"` (4-byte uint32), `\"length-prefix-2\"` (2-byte uint16), or custom function.\n\nIn framed mode `res.sendFramed(data)` writes a properly framed reply automatically.\n\n---\n\n## TLS Raw Server\n\n```js\napp.tls({\n  port    : 4443,\n  key     : fs.readFileSync(\"key.pem\"),\n  cert    : fs.readFileSync(\"cert.pem\"),\n  framing : \"length-prefix\",\n  onMessage(socket, frame, ctx, res) {\n    res.sendFramed(processFrame(frame))\n  },\n})\n```\n\n---\n\n## UDP Server\n\n```js\napp.udp({\n  port      : 5000,\n  onMessage(msg, ctx, res) {\n    console.log(\"from\", ctx.ip, ctx.port)\n    res.send(Buffer.from(\"pong\"))          // reply to sender\n    res.sendTo(Buffer.from(\"x\"), 5001, \"10.0.0.2\")  // arbitrary target\n  },\n})\n```\n\n---\n\n## Unix Domain Socket (IPC)\n\n```js\napp.unix({\n  path    : \"/tmp/myapp.sock\",\n  framing : \"newline\",\n  onMessage(socket, frame, ctx, res) {\n    const cmd = JSON.parse(frame)\n    res.sendFramed(JSON.stringify({ ack: cmd.id }))\n  },\n})\n```\n\n---\n\n## HTTP/2\n\nRoutes are shared with HTTP — no changes needed.\n\n```js\napp.http2({\n  port : 443,\n  key  : fs.readFileSync(\"key.pem\"),\n  cert : fs.readFileSync(\"cert.pem\"),\n})\n\n// Same routes work over HTTP/1.1 and H2\napp.get(\"/api/users\", handler)\n```\n\n---\n\n## Cron Jobs\n\n```js\napp.cron(\"*/5 * * * *\",  async () => { /* every 5 minutes */ })\napp.cron(\"0 9 * * 1-5\",  async () => { /* weekdays at 9am */ })\napp.cron(\"0 0 1 * *\",    async () => { /* first of month  */ })\n```\n\nStandard 5-field cron expression. Supports `*`, `,`, `-`, `/`.\n\n---\n\n## Named Upstreams + Proxy\n\n```js\napp.upstream(\"api\",  \"https://api.internal:3000\")\napp.upstream(\"auth\", \"https://auth.internal:4000\")\n\napp.get(\"/api/**\",  proxy(\"api\",  { rewrite: p => p.replace(\"/api\", \"\") }))\napp.get(\"/auth/**\", proxy(\"auth\"))\n```\n\n---\n\n## Conditional Routing\n\nRoute by host, header value, content-type, or any custom logic:\n\n```js\napp.add({\n  method  : \"POST\",\n  pattern : \"/webhook\",\n  when    : (r) => r.host === \"hooks.example.com\",\n  handler : webhookHandler,\n})\n\napp.add({\n  method  : \"GET\",\n  pattern : \"/api\",\n  when    : (r) => r.path.startsWith(\"/api\"),\n  preset  : \"api\",\n  handler : apiHandler,\n})\n```\n\n---\n\n## Lifecycle Hooks\n\n```js\napp.onRequest((ctx, res) => {\n  // fires before routing — can short-circuit\n  res.header(\"x-powered-by\", \"fastserve\")\n})\n\napp.onResponse((ctx, res) => {\n  // fires after response sent — for logging, metrics\n  console.log(ctx.method, ctx.path, res.statusCode)\n})\n\napp.onError((err, ctx, res) => {\n  // unhandled errors\n  console.error(err)\n  if (!res.sent) res.json({ error: \"Internal Server Error\" }, 500)\n})\n\napp.onNotFound((ctx, res) => {\n  res.json({ error: \"Not Found\", path: ctx.path }, 404)\n})\n\napp.onClose(() => {\n  // server shutting down — close DB connections etc\n})\n\napp.onRoute((def) => {\n  // fired when a route is registered — for discovery, docs generation\n  console.log(\"registered\", def.method, def.pattern)\n})\n```\n\n---\n\n## Health Check\n\nBuilt-in `/healthz` endpoint — zero config, returns `{ status: \"ok\", uptime: N }`.\n\n```js\n// Disable if not needed\nconst app = createApp({ health: false })\n```\n\n---\n\n## Cloudflare Workers / Edge Runtime\n\n`app` is directly exportable — no wrapper needed:\n\n```js\nimport { createApp } from \"@ahadpvt.v3/fastserve\"\n\nconst app = createApp({\n  extras: (req, env, ctx) => [env, ctx]   // forward CF env and ctx to handlers\n})\n\napp.get(\"/api/users\", async (ctx, res, next, env, cfCtx) => {\n  const users = await env.DB.prepare(\"SELECT * FROM users\").all()\n  res.json(users)\n})\n\nexport default app  // ← CF Workers default export\n```\n\nEdge Runtime / Next.js middleware:\n\n```js\nexport async function middleware(request) {\n  return app.fetch(request)\n}\n```\n\nDeno:\n\n```js\nDeno.serve((req) => app.fetch(req))\n```\n\n---\n\n## AWS Lambda\n\n```js\nconst { createApp } = require(\"@ahadpvt.v3/fastserve\")\nconst { adapters: reqexAdapters } = require(\"@ahadpvt.v3/reqex\")\nconst { adapters: resmakeAdapters } = require(\"@ahadpvt.v3/resmake\")\n\nconst app = createApp()\napp.get(\"/api/hello\", (ctx, res) => res.json({ hello: \"lambda\" }))\n\nexports.handler = (event, lambdaCtx) => new Promise(resolve => {\n  const nr  = reqexAdapters.lambda(event)\n  const res = resmakeAdapters.lambda(resolve)\n  // Wire manually for Lambda\n})\n```\n\n---\n\n## Built-in Middleware\n\n### CORS\n\n```js\napp.use(cors({\n  origin      : [\"https://app.example.com\", \"https://admin.example.com\"],\n  methods     : \"GET,POST,PUT,DELETE\",\n  credentials : true,\n  maxAge      : 86400,\n}))\n\n// Dynamic origin\napp.use(cors({ origin: (origin) => origin?.endsWith(\".example.com\") }))\n```\n\n### Body Size Limit\n\n```js\napp.use(bodyLimit({ limit: 512 * 1024 }))  // 512kb\n```\n\n### Static File Serving\n\n```js\napp.use(static(\"./public\", {\n  index    : \"index.html\",\n  maxAge   : 3600,     // cache-control max-age\n  dotFiles : false,\n}))\n```\n\nAutomatically handles `Range`, `ETag`, `If-None-Match`, `If-Modified-Since`.\n\n### Request Validation\n\n```js\napp.use(validate({\n  query  : (q)    => q.page   ? true : \"page is required\",\n  params : (p)    => p.id     ? true : \"id is required\",\n  body   : (body) => body?.name ? true : \"name is required\",\n}))\n```\n\n### Rate Limiting\n\n```js\napp.use(rateLimit({\n  max    : 100,\n  window : 60,\n  keyBy  : (ctx) => ctx.ip,\n}))\n\n// With Redis store\napp.use(rateLimit({\n  max    : 1000,\n  window : 3600,\n  store  : redisStore,\n}))\n```\n\n### CSRF Protection\n\n```js\napp.use(csrf({\n  cookie  : \"_csrf\",\n  header  : \"x-csrf-token\",\n  exclude : [\"GET\", \"HEAD\", \"OPTIONS\"],\n}))\n```\n\nUses double-submit cookie pattern — stateless, no session required.\n\n---\n\n## App Options\n\n```js\nconst app = createApp({\n  preset     : \"api\",      // default reqex preset for all routes\n  extras     : (req, env, ctx) => [env, ctx],  // platform extras\n  trustProxy : true,       // trust x-forwarded-* headers\n  health     : true,       // expose /healthz\n  timeout    : 30000,      // request timeout ms\n  maxBody    : 1048576,    // global body limit bytes (1mb)\n  https      : { key, cert },  // enables HTTPS\n})\n```\n\n---\n\n## Runtime Adapter (Advanced)\n\nInject runtime dependencies (builtins, timers, Buffer, URL) explicitly when needed.\n\n```js\nconst { setRuntimeAdapter } = require(\"@ahadpvt.v3/fastserve\")\n\nsetRuntimeAdapter({\n  requireBuiltin: (name) => require(name),\n  Buffer,\n  URL,\n  setTimeout,\n  clearTimeout,\n  setInterval,\n  clearInterval,\n  uptime: () => process.uptime(),\n  reportError: (err, meta) => console.error(\"fastserve runtime error\", err, meta),\n})\n```\n\nFastserve now throws explicit `UNSUPPORTED_RUNTIME` errors for missing capabilities instead of implicit crashes.\n\n---\n\n## Graceful Shutdown\n\n```js\nprocess.on(\"SIGTERM\", () => {\n  app.close(() => {\n    console.log(\"all servers closed\")\n    process.exit(0)\n  })\n})\n```\n\nCloses HTTP, HTTPS, TCP, TLS, UDP, Unix socket, and HTTP/2 servers. Fires `onClose` hooks. Stops cron scheduler.\n\n---\n\n## Testing\n\n```bash\nnpm test\n```\n\n```\n60 passed, 0 failed\n```\n\n---\n\n## License\n\nMIT © Abdul Ahad\n","readmeFilename":"README.md"}