@standardserver/fetch

@standardserver/fetch

@standardserver/fetch adapts the Fetch API 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 and clients against the same request, response, body, and streaming primitives whether the underlying transport is Fetch, Node.js HTTP, 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 Fetch API adapter for that model. It converts between native Request, Response, Headers, and stream values and the corresponding Standard Server shapes from @standardserver/core.

Package overview

The package exposes three groups of helpers:

Group	Exports	Purpose
Request and response	toStandardLazyRequest(), toStandardLazyResponse(), toFetchResponse()	Convert between Fetch API objects and Standard Server
Body and stream helpers	toStandardBody(), toFetchBody(), toAsyncIteratorObject(), toEventStream()	Parse and serialize body values, including SSE
Header and URL helpers	toStandardHeaders(), toFetchHeaders(), toStandardUrl()	Normalize Fetch headers and URLs for Standard Server

Use these helpers when you want Standard Server handlers to run in Fetch-based runtimes such as browsers, Cloudflare Workers, Bun, Deno, service workers, or server frameworks that expose the standard Fetch API.

Server-side request handling

Use toStandardLazyRequest() to convert an incoming Fetch Request into a StandardLazyRequest, then toFetchResponse() to turn the resulting StandardResponse back into a Fetch Response.

import type { StandardLazyRequest, StandardResponse } from '@standardserver/core'
import { toFetchResponse, toStandardLazyRequest } from '@standardserver/fetch'

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,
    },
  }
}

export async function fetchHandler(request: Request): Promise<Response> {
  const standardRequest = toStandardLazyRequest(request)
  const standardResponse = await handle(standardRequest)
  return toFetchResponse(standardResponse, {/** options */})
}

Client-side response handling

Use toFetchBody() and toFetchHeaders() to serialize an outgoing request, and toStandardLazyResponse() when you receive a Fetch Response but want to work with the Standard Server response contract.

import { toFetchBody, toFetchHeaders, toStandardLazyResponse } from '@standardserver/fetch'

const standardRequest = {
  method: 'POST',
  url: '/echo',
  headers: { 'content-type': 'application/json' },
  body: { message: 'hello' },
}

const [body, headers] = toFetchBody(standardRequest.body, standardRequest.headers, {/** options */})
const response = await fetch(standardRequest.url, {
  method: standardRequest.method,
  headers: toFetchHeaders(headers),
  body,
})

const standardResponse = toStandardLazyResponse(response)
const payload = await standardResponse.resolveBody()

toFetchBody() also prepares the content headers for the body it serializes — for example, a Blob or File body gains standard-server: file, content-length, and a generated content-disposition, so the receiver reconstructs the same body type. See the standard-server header in the core README for why.

[!TIP] When sending requests or 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 through GitHub Sponsors or Open Collective. Every bit helps! 🚀

ScreenshotOne.com The screenshot API for developers

MisskeyHQ Decentralized microblogging SNS born on Earth

Organization Sponsors

LN Markets

Sponsors

Reece McDonald	あわわわとーにゅ	nk	supastarter	Dexter Miguel	herrfugbaum
Ryota Murakami	David Cramer	Valerii Petryniak	Valerii Strilets	Kyle Mistele	christ12938
Ryan Soderberg	shota	Ellis Driscoll	Hoang Nguyen	Orestis Ioannou

Backers

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

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

License

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