README.md

@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.

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.

Entry Point

The package exports a single entry point:

Export	Purpose
@standardserver/node	Node.js adapter helpers for requests, responses, and SSE

Package overview

The main entry point 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(), toEventIterator(), 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?) determines how to parse the body using the following priority:

1. If the standard-server header is present, use it as the StandardBodyHint.
2. Otherwise, if hint? is provided, use it as the StandardBodyHint.
3. Otherwise, if content-type is one of the common types, parse accordingly.
4. Otherwise, if content-length exists, treat the body as file; if not, treat it as octet-stream.

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.

const response = await fetch('/upload', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'standard-server': 'file', // <- hint the body type to avoid misinterpretation
  },
  body: new Blob(['{"message": "Hello, world!"}'], { type: 'application/json' }),
})

Learn more

For the higher-level project overview, see the root Standard Server README.

Sponsors

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

🏆 Platinum Sponsor

ScreenshotOne.com

🥈 Silver Sponsor

村上さん

Generous Sponsors

LN Markets

Sponsors

Reece McDonald	nk	supastarter	Dexter Miguel	herrfugbaum	Ryota Murakami
David Cramer	Valerii Petryniak	Valerii Strilets	Kyle Mistele	Andrew Peters	Ryan Vogel
christ12938	Peter Adam	Ryan Soderberg	shota

Backers

David Walsh	Nicholas	Robbe Vaes	Aidan Sunbury	soonoo	Kevin Porten	Denis
Christopher Kapic	Tom Ballinger	Sam	Titoine	Igor Makowski	hanayashiki	Lev Dubinets
Kelly Peilin Chan	Alex	Andrey Gubanov

Past Sponsors