@standardserver/node

@standardserver/node adapts Node.js HTTP request and response objects to the transport-agnostic request and response model defined by Standard Server.

Standard Server provides a unified interface for client-server communication across HTTP and message-based transports. It lets you write handlers against the same request, response, body, and streaming primitives whether the underlying transport is the Fetch API, Node.js HTTP, HTTP/2, or a peer-style message channel.

Standard Server ships as a small ecosystem of packages:

| Package | Description | | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | @standardserver/core | The shared contract: types, body parsing rules, validators, and SSE helpers | | @standardserver/fetch | Fetch API adapter for browsers, workers, and other Fetch-based runtimes | | @standardserver/node | Node.js HTTP and HTTP/2 adapter | | @standardserver/fastify | Fastify adapter built on the Node.js adapter | | @standardserver/aws-lambda | AWS Lambda adapter with response streaming | | @standardserver/peer | Message-based adapter for WebSocket, MessagePort, and custom transports | | @standardserver/shared | Internal utilities shared across the ecosystem |

This package is the Node.js adapter for that model. It converts between native Node request and response objects and the corresponding Standard Server shapes from @standardserver/core, while also exposing lower-level utilities for body parsing, URL normalization, abort signals, and server-sent events.

Package overview

The package exposes four groups of helpers:

| Group | Exports | Purpose | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | Request and response | toStandardLazyRequest(), sendStandardResponse() | Adapt Node request and response objects to Standard Server | | Body and event streams | toStandardBody(), toNodeHttpBody(), toAsyncIteratorObject(), toEventStream() | Parse incoming bodies and serialize outgoing bodies, including SSE | | Request utilities | toStandardMethod(), toStandardUrl(), toAbortSignal() | Normalize Node request metadata and connection lifecycle state | | Types and option shapes | NodeHttpRequest, NodeHttpResponse, ToStandardBodyOptions, ToNodeHttpBodyOptions, SendStandardResponseOptions | Type request/response inputs and serializer options |

Use these helpers when you want Standard Server handlers to run in Node runtimes such as node:http, node:http2, Express-style middleware, or frameworks that expose Node-compatible request and response objects.

Server-side request handling

Use toStandardLazyRequest() to convert an incoming Node request into a StandardLazyRequest, then sendStandardResponse() to write the resulting StandardResponse back to the client.

import type { StandardLazyRequest, StandardResponse } from '@standardserver/core'
import { createServer } from 'node:http'
import { sendStandardResponse, toStandardLazyRequest } from '@standardserver/node'

async function handle(request: StandardLazyRequest): Promise<StandardResponse> {
  const body = await request.resolveBody()

  return {
    status: 200,
    headers: { 'content-type': 'application/json' },
    body: {
      ok: true,
      method: request.method,
      url: request.url,
      received: body,
    },
  }
}

createServer(async (req, res) => {
  const standardRequest = toStandardLazyRequest(req, res)
  const standardResponse = await handle(standardRequest)

  await sendStandardResponse(res, standardResponse, {/** options */})
}).listen(3000)

[!TIP] When sending responses, you can pass additional options such as event-stream keep-alive.

Resolving Body

resolveBody(hint?) follows the shared Standard Server resolution rules: an explicit hint wins, then the standard-server header, then inference from the content headers. See how body parsing works in the core README for the full algorithm.

[!TIP] For efficient communication, set the standard-server header to explicitly hint the body type, especially for file or binary streaming. For example, if you upload a file with a common content-type such as application/json but omit the standard-server header, the server may interpret it as JSON and parse it unexpectedly.

Learn more

For the project overview and the shared contract this adapter implements, see the core documentation.

Sponsors

Like what we build over at middleapi? You can help keep it going here: GitHub Sponsors. Every bit helps! 🚀

🏆 Platinum Sponsor

🥈 Silver Sponsor

Generous Sponsors

Sponsors

Backers

With thanks to 37 past sponsors who helped get us here.

License

Distributed under the MIT License. See LICENCE for more information.