Standard, framework-agnostic HTTP interfaces for JavaScript servers and clients.
Installation
npm install servie --save
Usage
Servie
Base HTTP class for common request and response logic.
import { Servie } from 'servie'
Options
events?
An instance of EventEmitter
headers?
An instance of Headers
trailer?
An instance of Promise<Headers>
body?
An instance of Body
Properties
events
An event emitter for listening to the request and response lifecycleheaders
The headers as a Headers
instancetrailer
A promise that resolves to a Headers
instancebody
The request or response payloadstarted
Boolean indicating if a request/response has startedfinished
Boolean indicating if a request/response has finishedbytesTransferred
The number of bytes sent in the HTTP request/responseallHeaders
Combined Request
and Body
headers instance
Methods
clone()
Abstract method implemented by Request
and Response
to clone the instance (throws TypeError
when started == true
)
Events
started
when started == true
finished
when finished == true
progress
when bytesTransferred
incrementsconnection
when Request
connection is availableabort
when Request
is abortingaborted
when Request
has aborted successfully
Request
HTTP class for encapsulating a Request
, extends Servie
.
import { Request } from 'servie'
Options
const request = new Request({
url: '/',
method: 'GET'
})
Extends Servie
options.
url
The HTTP request url (string
)method?
The HTTP request method (string
, default: GET
)connection?
Connection information ({ remoteAddress?: string, remotePort?: number, localAddress?: string, localPort?: number, encrypted?: boolean }
)
Properties
url
Requested url (string
)method
Requested method (string
)Url
Request url parsed into individual parts (object
)connection
HTTP connection information when available (object
)
Methods
abort(): boolean
Aborts the HTTP connection
Events
abort
Request aborted and transport MUST handleerror
An out-of-band error occurred and transport MUST handleresponse
The corresponding Response
has startedconnection
Emitted when connection information becomes available
Response
HTTP class for encapsulating a Response
, extends Servie
.
import { Response } from 'servie'
Options
const response = new Response({})
Extends Servie
options.
statusCode?
The HTTP response status code (number
)statusMessage?
The HTTP response status message (string
)
Properties
statusCode
The HTTP response status code (number
)statusMessage?
The HTTP response status message (string
)ok
Returns whether response was successful (status in range 200-299) (boolean
)
Used by Servie
for Request
, Response
and Body
objects.
import { Headers, createHeaders } from 'servie'
Options
const headers = createHeaders(...)
Create Headers
instance from raw value (e.g. HeadersObject | string[] | null
).
Properties
rawHeaders
The raw HTTP headers list (string[]
)
Methods
set(name: string, value: string | string[]): this
Set a HTTP header by overriding case-insensitive headers of the same nameappend(name: string, value: string | string[]): this
Append a HTTP headerget(name: string): string | undefined
Retrieve a case-insensitive HTTP headergetAll(name: string): string[]
Retrieve a list of matching case-insensitive HTTP headershas(name: string): boolean
Check if a case-insensitive header is already setdelete(name: string): this
Delete a case-insensitive headerasObject(toLower?: boolean): HeadersObject
Return the headers as a plain objectextend(obj: HeadersObject): this
Extends the current headers with an objectkeys()
Iterable of the available header namesvalues()
Iterable of header valuesentries()
Iterable of headers as [key, value]
clear()
Clears the headers instanceclone()
Clones the Headers
instance
Static Methods
is(obj: any): boolean
Checks if an object is Headers
Body
Immutable representation of the body used by Request
and Response
.
import { Body, createBody } from 'servie/dist/body/{node,browser,universal}'
Body
is a complex part of Servie due to support for browsers and node.js together. TypeScript is also missing a good story for universal modules with code paths offering different features (e.g. streams in node.js, native ReadableStream
in browsers), so it's required that you import a specific version for your environment.
Note: Each endpoint (body/node
, body/browser
, body/universal
) offers the same basic API (Body
, createBody
). Universal relies on module bundlers (e.g. webpack) and package.json#browser
to switch the node.js API with the browser API at bundle time. TypeScript will require dom
types since the interface returns a union of possible bodies (node
and browser
).
Options
const body = createBody(...)
Create a Body
instance from raw data (e.g. Readable | ReadableStream | Buffer | ArrayBuffer | object | string | null
).
Properties
buffered
Indicates the raw body is entirely in memory (boolean
)bodyUsed
Indicates the body has been read (boolean
)hasBody
Indicates the body is not empty (boolean
)headers
Instance of body-related HTTP headers (Headers
)
Methods
text(): Promise<string>
Returns body as a UTF-8 stringjson(): Promise<any>
Returns body parsed as JSONarrayBuffer(): Promise<ArrayBuffer>
Returns the body as an ArrayBuffer
instancebuffer(): Promise<Buffer>
Returns the body as a Buffer
instance (node.js)stream(): Readable
Returns a readable node.js stream (node.js)readableStream(): ReadableStream
Returns a readable WHATWG stream (browsers)clone(): this
Clones the Body
instance (allowing body re-use, throws TypeError
when bodyUsed == true
)
Static Methods
is(obj: any): boolean
Checks if an object is Body
Implementers
If you're building the transports for Servie, there are some life cycle events you need to be aware of:
- Listen to the
error
event on Request
and Response
for errors - Listen to the
abort
event on Request
and destroy the HTTP request - Resolve
trailer
promise and append to HTTP request - Emit the
response
event (with Response
arg) on Request
when server responds - Set
started = true
and finished = true
on Request
and Response
(as appropriate) - Set
bytesTransferred
on Request
and Response
when monitoring HTTP transfer progress
JavaScript
This module is designed for ES2015 environments and published with TypeScript definitions on NPM.
License
Apache 2.0