0.8.0 • Published 1 week ago

@standardserver/core

Licence

MIT

Version

0.8.0

Deps

Size

60 kB

Vulns

Weekly

Stars

Summary Dependency Versions

Standard Server

@standardserver/core is the shared contract package for Standard Server — a unified interface for client-server communication across HTTP and message-based transports. It lets you keep handler and client code transport-agnostic by working with the same request, response, body, and streaming abstractions whether the 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 foundation of that model. It defines the request and response types every adapter converts to and from, the body parsing rules they all share, runtime validators, header and URL utilities, and event stream (SSE) helpers.

Request and response types

The package exposes four transport-agnostic shapes:

Export	Description
`StandardRequest`	Eager request object with a parsed `body`
`StandardLazyRequest`	Request object with `resolveBody(hint?)` for lazy body parsing
`StandardResponse`	Eager response object with a parsed `body`
`StandardLazyResponse`	Response object with `resolveBody(hint?)` for lazy body parsing

Supporting primitives:

Export	Description
`StandardMethod`	Common HTTP verbs plus any custom string value
`StandardUrl`	A request URL that must start with `/` and exclude the origin
`StandardHeaders`	`Record<string, string \| string[] \| undefined>`
`StandardBodyHint`	Parsing hint for lazy body resolution
`StandardBody`	Shared body union used by requests and responses

By convention, adapters normalize headers to lowercase keys. signal is part of StandardRequest only and is used to propagate request cancellation.

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

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

Body types

StandardBodyHint and StandardBody describe the shared body contract used across adapters:

Hint	`StandardBody` value	Typical content type	Notes
`json`	`unknown`	`application/json`	Primitives, objects, and arrays
`form-data`	`FormData`	`multipart/form-data`	Multipart form submissions
`url-search-params`	`URLSearchParams`	`application/x-www-form-urlencoded`	URL-encoded forms
`event-stream`	`AsyncIteratorObject<unknown>`	`text/event-stream`	Server-Sent Events (SSE)
`octet-stream`	`ReadableStream<Uint8Array>`	any	Binary streaming
`file`	`File`	any	Fixed-size binary payloads for both `File` and `Blob`
`none`	`undefined`		Empty body

JSON body

Standard Server treats primitive values, objects, and arrays as JSON.

import type { StandardRequest } from '@standardserver/core'

const request: StandardRequest = {
  method: 'POST',
  url: '/submit',
  headers: {},
  body: { name: 'John Doe', email: 'john.doe@example.com' },
}

FormData and URLSearchParams body

Standard Server treats FormData and URLSearchParams as form submissions.

import type { StandardRequest } from '@standardserver/core'

const requestWithURLSearchParams: StandardRequest = {
  method: 'POST',
  url: '/submit',
  headers: {},
  body: new URLSearchParams({ name: 'John Doe', email: 'john.doe@example.com' }),
}

const formData = new FormData()
formData.append('name', 'John Doe')
formData.append('file', new Blob(['Hello, World!'], { type: 'text/plain' }), 'hello.txt')

const requestWithFormData: StandardRequest = {
  method: 'POST',
  url: '/submit',
  headers: {},
  body: formData,
}

HTML forms submit data as application/x-www-form-urlencoded or multipart/form-data, so these body types are especially helpful there.

File and Blob body

Standard Server treats File and Blob as fixed-size binary payloads.

Since File extends Blob, resolveBody always returns a File when representing either File or Blob bodies.

import type { StandardResponse } from '@standardserver/core'

const response: StandardResponse = {
  status: 200,
  headers: {
    'content-disposition': [], // <- remove auto-set header
  },
  body: new File(['Hello, World!'], 'hello.txt', { type: 'text/plain' }),
}

When sending a file or blob body, adapters automatically set the content-length, content-type, content-disposition, and standard-server headers based on the provided body. You can override any of them by explicitly providing a header value, or remove one entirely by assigning an empty array.

Event-stream body

Standard Server uses AsyncIteratorObject to represent an event stream body, and you can use withEventMeta() to attach additional SSE event metadata to each emitted event.

import type { StandardResponse } from '@standardserver/core'
import { ErrorEvent, withEventMeta } from '@standardserver/core'

const response: StandardResponse = {
  status: 200,
  headers: {},
  async* body() {
    yield withEventMeta(
      { message: 'Hello, World!' },
      { id: '1', retry: 3000, comments: ['hidden'] },
    )

    throw new ErrorEvent({ message: 'Something went wrong' })

    return { message: 'This is the end of the stream' }
  },
}

Events are interpreted as follows: yield emits a message, throw emits an error, and return emits a close event. Note that close does not cause EventSource to close the connection because it is not part of the SSE specification. However, when using Standard Server for client-side streaming, close is treated as the end of the stream, so the connection is closed and no reconnection is attempted.

For explicit SSE encoding, decoding, and metadata handling, see the Event-Stream Helpers below.

Octet-stream body

Standard Server uses ReadableStream to represent a binary streaming body.

import type { StandardResponse } from '@standardserver/core'

const response: StandardResponse = {
  status: 200,
  headers: {
    'content-type': 'application/octet-stream',
  },
  body: new ReadableStream<Uint8Array>({
    start(controller) {
      const encoder = new TextEncoder()
      controller.enqueue(encoder.encode('Hello, World!'))
      controller.close()
    },
  }),
}

When sending a binary streaming body, adapters automatically set the content-type and standard-server headers. You can override content-type by providing an explicit header value, or remove it entirely by assigning an empty array.

How body parsing works

This section applies to the HTTP adapters (Fetch, Node.js, Fastify, AWS Lambda). It does not apply to the peer adapter, which identifies body types through its own message protocol — a different but fairly similar mechanism.

resolveBody(hint?) on StandardLazyRequest and StandardLazyResponse resolves the body lazily — the underlying stream is only consumed once you call it. The StandardBodyHint that decides how the raw body is parsed comes from three places: an explicit hint argument, the standard-server header, or inference from the content headers.

The `standard-server` header

A StandardBody is richer than what HTTP content headers can describe. content-type tells the receiver the media type of the bytes, but not which StandardBody representation the sender intended:

A file upload can legitimately carry content-type: application/json. Without more information, the receiver would parse it into a JSON value when the sender meant a File to be stored as-is.
A fixed-size binary payload (file) and a binary stream (octet-stream) can share any content type. Telling them apart otherwise depends on content-length, which proxies may rewrite and some runtimes drop when the payload is empty.

The standard-server header closes this gap. It carries the sender's StandardBodyHint verbatim — json, form-data, url-search-params, event-stream, octet-stream, file, or none — so the receiver reconstructs exactly the body representation the sender had.

Adapters set the header automatically for the ambiguous body types: a Blob or File body is sent with standard-server: file, and a ReadableStream body with standard-server: octet-stream, alongside the usual content headers. A header you set yourself always wins, and assigning an empty array removes it entirely. For the other body types, the content headers are enough, so adapters clear it.

The header is optional: when it is absent or invalid, the receiver falls back to content-header inference, so plain HTTP clients work as-is. Just set the header yourself whenever the content type alone could be misread:

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

Resolution order

The hint is chosen in this order:

Explicit hint argument. If you pass a hint to resolveBody(hint), it always wins.
The standard-server header. If present and holding a valid hint value, it is used verbatim. Unknown values are ignored.
Content-header inference:
1. No content-type, and content-length absent or 0 → none.
2. A common content-type → application/json parses as json, multipart/form-data as form-data, application/x-www-form-urlencoded as url-search-params, and text/event-stream as event-stream. Media type casing and parameters such as ; charset=utf-8 are ignored.
3. A content-disposition carrying a filename, or any content-length → file.
4. Anything else → octet-stream.

This resolution is implemented once in this package as resolveStandardBodyHint(headers) and shared by every HTTP adapter, so the same body parses the same way regardless of which HTTP transport carried it:

import { resolveStandardBodyHint } from '@standardserver/core'

resolveStandardBodyHint({ 'content-type': 'application/json' })
// 'json'

resolveStandardBodyHint({
  'content-type': 'application/json',
  'standard-server': 'file',
})
// 'file'

resolveStandardBodyHint({})
// 'none'

Use it when building a custom adapter, or when you need to know how a body will parse without consuming it.

Utilities

The package also exports a small set of helpers for common header and URL operations.

Content-Disposition helpers

Use generateContentDisposition() to produce a safe Content-Disposition value and getFilenameFromContentDisposition() to read a filename back from an existing header.

import {
  generateContentDisposition,
  getFilenameFromContentDisposition,
} from '@standardserver/core'

const disposition = generateContentDisposition('report "Q2".csv')
// inline; filename="report \"Q2\".csv"; filename*=utf-8''report%20%22Q2%22.csv

const filename = getFilenameFromContentDisposition(disposition)
// 'report "Q2".csv'

generateContentDisposition() preserves an ASCII-safe filename="..." value and also emits filename*= for UTF-8 aware clients.

Header helpers

mergeStandardHeaders() combines two StandardHeaders objects while preserving duplicate values, and flattenStandardHeader() turns a single header value into a plain string when needed.

import {
  flattenStandardHeader,
  mergeStandardHeaders,
} from '@standardserver/core'

const headers = mergeStandardHeaders(
  { 'accept': 'application/json', 'set-cookie': ['a=1'] },
  { 'set-cookie': 'b=2', 'vary': 'accept', 'warning': undefined },
)
// {
//   accept: 'application/json',
//   'set-cookie': ['a=1', 'b=2'],
//   vary: 'accept',
// }

const cookieHeader = flattenStandardHeader(headers['set-cookie'])
// 'a=1, b=2'

URL parsing

parseStandardUrl() splits a StandardUrl into [pathname, search, hash] without requiring a full origin.

import { parseStandardUrl } from '@standardserver/core'

const [pathname, search, hash] = parseStandardUrl('/users/123?tab=settings#profile')
// pathname => '/users/123'
// search => '?tab=settings'
// hash => '#profile'

Validators

Runtime type guards are useful when requests or responses cross process, transport, or message boundaries.

Export	Checks
`isStandardMethod()`	Any string value
`isStandardUrl()`	A string starting with `/`
`isStandardHeaders()`	Object values are `string`, `string[]`, or `undefined`
`isStandardRequest()`
`isStandardResponse()`

import { isStandardRequest } from '@standardserver/core'

export function expectStandardRequest(input: unknown) {
  if (!isStandardRequest(input)) {
    throw new TypeError('Expected a StandardRequest-compatible value')
  }

  return input
}

Event-Stream Helpers

Use Event-Stream Helpers when you need explicit SSE encoding, decoding, or metadata handling.

Message types and codecs

The event-stream helpers include:

EventMeta for id, retry, and comments
EventStreamMessage for complete SSE messages
encodeEventStreamMessage() and decodeEventStreamMessage() for single-message codec operations
EventStreamDecoder and EventStreamDecoderStream for chunked stream decoding

import {
  decodeEventStreamMessage,
  encodeEventStreamMessage,
} from '@standardserver/core'

const encoded = encodeEventStreamMessage({
  comments: ['bootstrap'],
  event: 'message',
  id: '42',
  retry: 3000,
  data: 'hello\nworld',
})

const decoded = decodeEventStreamMessage(encoded)
// {
//   comments: ['bootstrap'],
//   event: 'message',
//   id: '42',
//   retry: 3000,
//   data: 'hello\nworld',
// }

For streaming decode, pipe text chunks through EventStreamDecoderStream:

import { EventStreamDecoderStream } from '@standardserver/core'

const messages = response.body!
  .pipeThrough(new TextDecoderStream())
  .pipeThrough(new EventStreamDecoderStream())

Iterator metadata helpers

StandardBody uses async iterators for event-stream bodies. To attach SSE metadata to a yielded value without changing its visible shape, use withEventMeta().

import type { StandardResponse } from '@standardserver/core'
import { getEventMeta, unwrapEvent, withEventMeta } from '@standardserver/core'

const event = withEventMeta(
  { message: 'hello' },
  { id: '1', retry: 3000, comments: ['bootstrap'] },
)

const [data, meta] = unwrapEvent(event)
// data => { message: 'hello' }
// meta => { id: '1', retry: 3000, comments: ['bootstrap'] }

const extractedMeta = getEventMeta(event)
// { id: '1', retry: 3000, comments: ['bootstrap'] }

const response: StandardResponse = {
  status: 200,
  headers: {},
  async* body() {
    yield event
  },
}

Metadata is validated before it is attached: id, event, and comments must not contain line breaks, and retry must be a non-negative integer.

Errors and low-level assertions

The package also exports:

EventStreamEncoderError for invalid outbound SSE messages
EventStreamDecoderError for incomplete or invalid inbound stream decoding
ErrorEvent for wrapping structured event-stream error payloads in an Error
assertEventStreamMessageId(), assertEventStreamMessageName(), assertEventStreamMessageRetry(), and assertEventStreamMessageComment() for low-level validation when building custom SSE tooling

import { ErrorEvent } from '@standardserver/core'

const error = new ErrorEvent(
  { code: 'E_STREAM', detail: 'Connection lost' },
  { message: 'stream error' },
)

error.message
// 'stream error'

error.data
// { code: 'E_STREAM', detail: 'Connection lost' }

Learn more

For transport-specific quick-starts and options, see the adapter documentation: Fetch · Node.js · Fastify · AWS Lambda · Peer

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

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