Skip to content
Velt
velt/net/http exports

velt/net/http

API reference

fetch, Request, Response and Headers are global, as in Node: no import. They follow the WHATWG Fetch standard, which TypeScript's lib.dom.d.ts types. For a walkthrough, read the guide.

import { fetch, BodyStream } from "velt/net/http";

Exports

fetchSends a request.requestSourceThe source of a request a server received (serverRequest), null for one made with new Request: the server reads what is its own from it (a connection to upgrade, the client's address).serverRequestThe Request a handler reads for a request a server received from source.statusTextThe reason phrase of HTTP status status, as Node's http.STATUS_CODES has it ("Not Found" for 404), "Unknown" for a status it does not list.responsePartsThe parts of res to write: its status, headers and body, the body as the response holds it (no copy of a text or bytes).switchingProtocolsA 101 Switching Protocols response with headers, for a server's upgrade.BodyStreamA body as a stream of byte chunks, read with for await (JS: a ReadableStream of Uint8Arrays): res.body and req.body, or BodyStream.from(chunks) for a body made while it is sent.HeadersNo doc comment yetRequestNo doc comment yetResponseNo doc comment yetRequestInitThe options of fetch(input, init) and new Request(input, init).ResponseInitnew Response(body, init) and Response.json(data, init): default status 200.RequestSourceWhat a server gives the Request a handler reads (serverRequest).ResponsePartsA response as a server writes it (responseParts).BodyKindWhere a response's body is (ResponseParts.kind).BodyInitA body: text, bytes (a typed array, an ArrayBuffer, a DataView, or Velt's u8[]), form fields (sent as application/x-www-form-urlencoded), or a stream (a BodyStream, or a ReadableStream of Uint8Array chunks).HeadersInitHeaders, an object literal ({ "content-type": "text/plain" }), or name-value pairs ([["accept", "text/html"], ["accept", "application/json"]], repeats kept).RequestRedirectWhat fetch does with a redirect: follow it (default, up to 20), fail, or return it.
functionasync

fetch

#std/net/http/fetch/fetch.vlt:45

Re-exported from velt/net/http/fetch/fetch

async function fetch(
  input: string | URL | Request,
  init: RequestInit = {},
): Promise<Response, IoError | AbortError>

Sends a request. Rejects with IoError when there is no response (ECONNREFUSED, ETIMEDOUT, a TLS failure, an invalid URL or header: EINVAL), and with the signal's AbortError (TimeoutError for AbortSignal.timeout) when it is aborted. An HTTP error status is a response, not an error: check res.ok.

function

requestSource

#std/net/http/fetch/source.vlt:41

Re-exported from velt/net/http/fetch/source

function requestSource(req: Request): RequestSource | null

The source of a request a server received (serverRequest), null for one made with new Request: the server reads what is its own from it (a connection to upgrade, the client's address).

function

serverRequest

#std/net/http/fetch/source.vlt:32

Re-exported from velt/net/http/fetch/source

function serverRequest(source: RequestSource): Request

The Request a handler reads for a request a server received from source.

function

statusText

#std/net/http/fetch/status.vlt:8

Re-exported from velt/net/http/fetch/status

function statusText(status: number): string

The reason phrase of HTTP status status, as Node's http.STATUS_CODES has it ("Not Found" for 404), "Unknown" for a status it does not list.

function

responseParts

#std/net/http/fetch/parts.vlt:42

Re-exported from velt/net/http/fetch/parts

function responseParts(res: Response): ResponseParts throws IoError

The parts of res to write: its status, headers and body, the body as the response holds it (no copy of a text or bytes). A streamed body (one made from a stream, or a fetched response's body) is used up, as sending it does in JS: IoError "EINVAL" if it was read already. A fetched body arrives decoded, so its content-encoding is not among the headers.

function

switchingProtocols

#std/net/http/fetch/parts.vlt:47

Re-exported from velt/net/http/fetch/parts

function switchingProtocols(headers: HeadersInit | null = null): Response

A 101 Switching Protocols response with headers, for a server's upgrade.

class

BodyStream

#std/net/http/fetch/body_stream.vlt:12

Re-exported from velt/net/http/fetch/body_stream

A body as a stream of byte chunks, read with for await (JS: a ReadableStream of Uint8Arrays): res.body and req.body, or BodyStream.from(chunks) for a body made while it is sent. It is read once: reading it uses its body up.

Returned byvelt/jsxrenderToStreamUsed byBodyInitResponseParts.stream

static from<E>(chunks: AsyncIterable<u8[], E>): BodyStream

A stream of the chunks chunks yields (JS: ReadableStream.from), e.g. an async generator's: new Response(BodyStream.from(rows())) sends each chunk as it is made. The stream reads chunks as it is read; an error chunks throws reaches the reader as an IoError ("EIO") with its text.

[Symbol.asyncIterator](): AsyncIterator<u8[], IoError | AbortError>No doc comment yet
[ [INSPECT](): string

How console.log shows the stream: as Node shows a body's ReadableStream.

class

Headers

#std/net/http/fetch/headers.vlt:37

Re-exported from velt/net/http/fetch/headers

Returned byRequest.headersResponse.headersUsed byHeadersInitNo doc comment yet: add one

constructor(init: HeadersInit | null = null)No doc comment yet
append(name: string, value: string)

Adds a value; a header that already has one gets another.

set(name: string, value: string)

Replaces every value of name with value.

delete(name: string)

Removes every value of name.

get(name: string): string | null

The values of name joined with ", ", or null when there is none.

getSetCookie(): string[]

Every set-cookie value, in order (they can't be joined with commas).

has(name: string): boolNo doc comment yet
forEach(f: (value: string, name: string) => void)

Calls f(value, name) for each entry, in iteration order.

* entries(): IterableIterator<[string, string]>No doc comment yet
* keys(): IterableIterator<string>No doc comment yet
* values(): IterableIterator<string>No doc comment yet
* [Symbol.iterator](): IterableIterator<[string, string]>No doc comment yet
[ [INSPECT](): Record<string, string>

How console.log shows the headers, like Node: Headers { 'content-type': 'text/plain' }, in insertion order with repeats joined (Node keeps the case a name was first added with; Velt's names are lowercase).

class

Request

#std/net/http/fetch/request.vlt:35

Re-exported from velt/net/http/fetch/request

Parameter offetchrequestSourceReturned byserverRequestNo doc comment yet: add one

constructor(input: string | URL | Request, init?: RequestInit) throws IoError

Throws IoError "EINVAL" (JS: TypeError) for a GET or HEAD request with a body, and for a Request input whose body was already used.

clone(): Request throws IoError

A copy of the request whose body can be read on its own: a streamed or received body is teed, each chunk going to both. Throws IoError "EINVAL" (JS: TypeError) when the body was already read.

get url(): string

The URL; a received request's is absolute (http://host/path?query), as in Deno and Bun.

get method(): stringNo doc comment yet
get headers(): Headers

The headers; a received request's are immutable.

get redirect(): RequestRedirectNo doc comment yet
get signal(): AbortSignal

The signal passed in init; without one, a signal that is never aborted (as in JS).

get bodyUsed(): boolNo doc comment yet
async text(): Promise<string, IoError | AbortError>

The body as text (invalid UTF-8 becomes U+FFFD, as in JS).

async json<T>(): Promise<T, IoError | AbortError | JsonError>

JSON.parse<T> of the body (see Response.json).

[ [INSPECT]()

How console.log shows the request, like Node: its state, with Node's values for the options Velt's fetch does not have (mode: 'cors', cache: 'default', …).

class

Response

#std/net/http/fetch/response.vlt:45

Re-exported from velt/net/http/fetch/response

Parameter ofresponsePartsReturned byfetchswitchingProtocolsNo doc comment yet: add one

constructor(body: BodyInit | null = null, init?: ResponseInit)No doc comment yet
static json<T>(data: T, init?: ResponseInit): Response

A response whose body is JSON.stringify(data), with content-type: application/json unless init sets one.

static error(): Response

A network error: status 0, type "error".

static redirect(url: string, status: i64 = 302): Response

A redirect to url (status 301, 302, 303, 307 or 308).

get headers(): Headers

The headers; a fetched response's are immutable.

get status(): i64No doc comment yet
get ok(): bool

Whether the status is 200–299.

get statusText(): string

The status message (OK, Not Found): the server's reason phrase, else the standard one for the status ("" for a status without one, and for a constructed response by default).

get url(): string

The URL the response came from, after redirects ("" for a constructed response).

get redirected(): bool

Whether fetch followed a redirect to get it.

get type(): string

"basic" (fetched), "default" (constructed) or "error" (Response.error()).

clone(): Response throws IoError

A copy of the response whose body can be read on its own: a streamed or fetched body is teed, each chunk going to both. Throws IoError "EINVAL" (JS: TypeError) when the body was already read.

get bodyUsed(): bool

Whether the body has been read.

async text(): Promise<string, IoError | AbortError>

The body as text (invalid UTF-8 becomes U+FFFD, as in JS).

async json<T>(): Promise<T, IoError | AbortError | JsonError>

JSON.parse<T> of the body: the JSON is checked against T (JsonError if it doesn't match). Velt has no any: name the type, await res.json<User[]>(), or annotate the variable that receives it.

[ [INSPECT]()

How console.log shows the response, like Node: its public state.

[Symbol.dispose]()

Drop hook: closes the connection of a fetched body nobody finished reading.

struct

RequestInit

#std/net/http/fetch/request_init.vlt:12

Re-exported from velt/net/http/fetch/request_init

The options of fetch(input, init) and new Request(input, init).

Parameter offetchRequest.constructor

FieldTypeDescription
method? stringDefault "GET"; get, post, put, delete, head and options are uppercased.
headers? HeadersInit—
body? BodyInit—
redirect? RequestRedirect—
signal? AbortSignalAborting it rejects the fetch (and a body read in progress) with its AbortError (TimeoutError for AbortSignal.timeout(ms)), and cancels the request.
ca? stringVelt: extra trusted CA certificates (PEM) for https://, e.g. a private or test CA.
struct

ResponseInit

#std/net/http/fetch/response_init.vlt:7

Re-exported from velt/net/http/fetch/response_init

new Response(body, init) and Response.json(data, init): default status 200.

Parameter ofResponse.constructor

FieldTypeDescription
status? number—
statusText? string—
headers? HeadersInit—
interface

RequestSource

#std/net/http/fetch/source.vlt:14

Re-exported from velt/net/http/fetch/source

What a server gives the Request a handler reads (serverRequest). Each method is called when the handler first asks for that part, so a server can keep the request where it read it (in its connection's buffer) until then.

Parameter ofserverRequestReturned byrequestSource

method(): stringNo doc comment yet
url(): string

The absolute URL, http://host/path?query (as in Deno and Bun).

header(name: string): string | null

The values of header name (any case) joined with ", ", as Headers.get reads them.

hasHeader(name: string): boolNo doc comment yet
headers(): [string, string][]

Every header as it came, in order.

hasBody(): bool

Whether a body is left to read.

read(): Promise<u8[] | null, IoError>

The next piece of the body, or null at its end.

body(): Promise<u8[], IoError>

The rest of the body.

interface

ResponseParts

#std/net/http/fetch/parts.vlt:24

Re-exported from velt/net/http/fetch/parts

A response as a server writes it (responseParts).

Returned byresponseParts

status: i64No doc comment yet
headers: string[]

[name, value, …], lowercase names.

type: string | null

The content-type the body implies, written unless headers names one.

kind: BodyKindNo doc comment yet
text: stringNo doc comment yet
bytes: u8[]No doc comment yet
stream: BodyStream | nullNo doc comment yet
enum

BodyKind

#std/net/http/fetch/parts.vlt:12

Re-exported from velt/net/http/fetch/parts

Where a response's body is (ResponseParts.kind).

Used byResponseParts.kind

None

No body.

Text

ResponseParts.text.

Bytes

ResponseParts.bytes.

Stream

ResponseParts.stream, read as it is sent.

type

BodyInit

#std/net/http/fetch/body.vlt:19

Re-exported from velt/net/http/fetch/body

type BodyInit = string | u8[] | BufferView | ArrayBuffer | URLSearchParams | BodyStream | ByteSource

A body: text, bytes (a typed array, an ArrayBuffer, a DataView, or Velt's u8[]), form fields (sent as application/x-www-form-urlencoded), or a stream (a BodyStream, or a ReadableStream of Uint8Array chunks).

Parameter ofResponse.constructorUsed byRequestInit.body

type

HeadersInit

#std/net/http/fetch/headers.vlt:35

Re-exported from velt/net/http/fetch/headers

type HeadersInit = Headers | Record<string, string> | [string, string][]

Headers, an object literal ({ "content-type": "text/plain" }), or name-value pairs ([["accept", "text/html"], ["accept", "application/json"]], repeats kept).

Parameter ofHeaders.constructorswitchingProtocolsUsed byRequestInit.headersResponseInit.headers

type

RequestRedirect

#std/net/http/fetch/request_init.vlt:9

Re-exported from velt/net/http/fetch/request_init

type RequestRedirect = "follow" | "error" | "manual"

What fetch does with a redirect: follow it (default, up to 20), fail, or return it.

Returned byRequest.redirectUsed byRequestInit.redirect