@standardserver/core

@standardserver/core

@standardserver/core is the shared contract package for Standard Server.

Standard Server provides 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.

This package is the foundation of that model. It defines the core request and response types, shared runtime validators, small utility helpers, and event stream (SSE) helpers.

Entry Points

Entry point	Purpose
@standardserver/core	Shared request/response types, utilities, and validators

Request and response types

The main entry point 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 hints and body values

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 payloads
file	File	any	Fixed-size binary payloads for both File and Blob
none	undefined		Empty body

Resolving Body

resolveBody(hint?) determines how to parse the body using the following priority:

• If the standard-server header is present, use it as the StandardBodyHint.
• Otherwise, if hint? is provided, use it as the StandardBodyHint.
• Otherwise, if content-type is one of the common types, parse accordingly.
• 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' }),
})

Utilities

The main entry point 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 entry point exposes:

• EventStreamMessageMeta 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 withEventIteratorEventMeta().

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

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

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

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

[!WARNING] 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 subpath also exports:

• EventStreamEncoderError for invalid outbound SSE messages
• EventStreamDecoderError for incomplete or invalid inbound stream decoding
• EventIteratorErrorEvent 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 { EventIteratorErrorEvent } from '@standardserver/core'

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

error.message
// 'stream error'

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

Learn more

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