@ahadpvt.v3/resmake

A zero-dependency, environment-aware HTTP response builder — now with TCP and UDP response support — built as the response layer beneath a universal route dispatcher.

Two modes for HTTP: eager (write-style) for Node/Express, lazy (return-style) for CF Workers, Edge, and Deno. Plus dedicated response contexts for raw TCP and UDP so all protocols share the same ergonomic res API.

Installation

npm install @ahadpvt.v3/resmake

Import / Require

const { normalize, create, context, tcpContext, udpContext } = require("@ahadpvt.v3/resmake")

Two HTTP Modes

Eager — Node.js, Express, Fastify

const { normalize } = require("@ahadpvt.v3/resmake")

http.createServer((req, res) => {
  const r = normalize(res)
  r.status(200).header("x-id", "abc").json({ hello: "world" })
})

Lazy — CF Workers, Edge Runtime, Deno

const { create } = require("@ahadpvt.v3/resmake")

// Cloudflare Workers — app is the export directly
export default {
  async fetch(request, env, ctx) {
    const res = create()
    res.status(200).json({ hello: "cf" })
    return res.toResponse()
  }
}

// Edge Runtime
export async function middleware(request) {
  const res = create()
  res.json({ ok: true })
  return res.toResponse()
}

// Deno
Deno.serve(async (req) => {
  const res = create()
  res.json({ hello: "deno" })
  return res.toResponse()
})

toResponse() is synchronous for all methods except file() which returns Promise<Response>.

Lambda

exports.handler = async (event) => new Promise(resolve => {
  const res = context(null, { resolve, _adapter: adapters.lambda(resolve) })
  res.json({ hello: "lambda" })
})

All HTTP Response Methods

Same API in both eager and lazy mode.

res.json(data, code?)

res.json({ user: "Abdul" })
res.json({ error: "not found" }, 404)

res.html(str, code?)

res.html("<h1>Hello</h1>")

res.text(str, code?)

res.text("OK")
res.text("Unauthorized", 401)

res.binary(buf, mime?)

res.binary(imageBuffer, "image/png")

res.send(body, mime?)

res.header("content-type", "application/xml").send("<root/>")
res.send(buffer, "application/pdf")

res.stream(readable, mime?)

Node/Express: zero-copy pipe. Edge/Lambda: buffers first.

res.stream(fs.createReadStream("./video.mp4"), "video/mp4")

res.file(filePath, opts?)

Full HTTP caching — ETag, Last-Modified, Range requests, 304, 206.

res.file("./public/logo.png")

res.file("./dist/bundle.js", {
  rangeHeader : req.headers["range"],
  ifNoneMatch : req.headers["if-none-match"],
  ifModified  : req.headers["if-modified-since"],
})

res.file("./report.pdf", { download: true, filename: "monthly-report.pdf" })

Lazy mode: toResponse() returns Promise<Response> when file() was called.

return await res.toResponse()

res.redirect(url, code?)

res.redirect("/login")
res.redirect("https://example.com", 301)

res.end(code?)

res.end(204)

Header Methods — all chainable

res.status(201)
res.header("x-request-id", "abc-123")
res.headers({ "x-foo": "1", "x-bar": "2" })
res.type("json")           // shorthand
res.type("image/avif")     // full mime string
res.vary("Accept-Encoding")

res.type() shorthands: json, html, text, plain, binary, form, xml, svg, pdf, js, css

Cookies

RFC-correct — multiple Set-Cookie headers kept separate.

res.cookie("session", "abc123", {
  httpOnly : true,
  secure   : true,
  sameSite : "Lax",
  maxAge   : 3600,
})

res.clearCookie("session")

Options: maxAge, domain, path, expires, httpOnly, secure, sameSite, partitioned

Server-Sent Events

// Eager (Node)
const sse = res.sse()
sse.send("hello")
sse.send({ type: "update", data }, "update", "msg-1", 3000)
const interval = setInterval(() => sse.ping(), 20_000)  // keepalive
sse.close()

// Lazy (CF Workers / Edge)
const res = create()
const sse = res.sse()
sse.send("first message")
return res.toResponse()  // returns streaming Response immediately

TCP Response Context

For raw TCP, TLS, and Unix socket connections. Used internally by dispex.tcp(), dispex.tls(), dispex.unix(). Also usable standalone.

const { tcpContext } = require("@ahadpvt.v3/resmake")
const net = require("net")

net.createServer(socket => {
  const res = tcpContext(socket)

  res.send("hello\n")                // write string
  res.send(Buffer.from([0x01]))      // write Buffer
  res.pipe(fs.createReadStream("./file.bin"))  // pipe stream
  res.keepAlive(true, 30000)         // TCP keep-alive
  res.noDelay(true)                  // disable Nagle
  res.setTimeout(30000)              // 30s timeout
  res.close("bye\n")                 // send final data and close
  res.close()                        // close immediately
})

In framed mode via dispex.tcp({ framing }), res.sendFramed(data) writes a properly framed reply automatically.

UDP Response Context

const { udpContext } = require("@ahadpvt.v3/resmake")
const dgram = require("dgram")

const server = dgram.createSocket("udp4")
server.on("message", (msg, rinfo) => {
  const res = udpContext(server, rinfo)

  res.send(Buffer.from("pong"))                    // reply to sender
  res.sendTo(Buffer.from("x"), 5001, "10.0.0.2")  // arbitrary target
  res.broadcast(Buffer.from("announce"), 5000)     // broadcast
})
server.bind(5000)

Middleware Contract

res.sent flips to true after any send method. Dispatcher checks this after every middleware step.

async function authMiddleware(ctx, res, next) {
  if (!ctx.headers.authorization) {
    res.json({ error: "unauthorized" }, 401)
    return  // do not call next — res.sent is true
  }
  await next()
}

async function loggerMiddleware(ctx, res, next) {
  res.header("x-request-id", generateId())
  await next()
  console.log(res.statusCode, res.sent)
}

Chaining

res
  .status(201)
  .header("x-id", "abc")
  .vary("Accept")
  .cookie("session", "xyz", { httpOnly: true })
  .json({ created: true })

Error Handling

try {
  res.json({ ok: true })
  res.json({ again: true })  // throws ALREADY_SENT
} catch (err) {
  if (err.isResmake) {
    switch (err.code) {
      case "ALREADY_SENT":
      case "INVALID_RESPONSE":
    }
  }
}

Constants

const { MIME, MIME_ALIAS, EXT_MIME } = require("@ahadpvt.v3/resmake")

MIME.json    // "application/json; charset=utf-8"
MIME.sse     // "text/event-stream; charset=utf-8"

MIME_ALIAS.js   // "application/javascript; charset=utf-8"

EXT_MIME[".avif"]  // "image/avif"
EXT_MIME[".wasm"]  // "application/wasm"
EXT_MIME[".woff2"] // "font/woff2"

Runtime Adapter (Advanced)

Inject runtime primitives explicitly for non-standard or sandboxed environments.

const { setRuntimeAdapter } = require("@ahadpvt.v3/resmake")

setRuntimeAdapter({
  Buffer,
  Headers,
  Response,
  TransformStream,
  TextEncoder,
  requireBuiltin: (name) => require(name),
  reportError: (err, meta) => console.error("resmake runtime error", err, meta),
})

When a capability is unavailable, resmake throws UNSUPPORTED_RUNTIME instead of failing silently.

Testing

npm test

68 passed, 0 failed

License

MIT © Abdul Ahad