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
trailers?
An instance of Headers
body?
An instance of Body
Properties
events
An event emitter for listening to the request and response lifecycleheaders
The headers as a Headers
instancetrailers
The trailers as 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/response
Methods
getHeaders()
Returns the combined Request
and Body
headers (Headers
)
Events
headers
Emitted when the headers
object is availabletrailers
Emitted when the trailers
object is availablestarted
Emitted when started === true
finished
Emitted when finished === true
progress
Emitted when bytesTransferred
increments
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.
Options
Take a single parameter with the headers in raw array format.
Tip: Use createHeaders(value?: any)
to create a Headers
instance from raw data (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]
clone()
Clones the current headers instance
Static Methods
is(obj: any): boolean
Checks if an object is Headers
Body
Immutable representation of body used by Request
and Response
.
Options
const body = new Body({})
rawBody
Supported body type (any
)headers?
Headers related to the body, e.g. Content-Type
(Headers
)
Tip: Use createBody(value?: any)
to create a Body
instance from raw data (e.g. Readable | ReadableStream | Buffer | ArrayBuffer | object | string | null
).
Body
is the most complex part of Servie due to support for node.js and browsers. TypeScript is also missing a good story for universal modules with code paths offering different features (e.g. Buffer
in node.js, ReadableStream
in browsers), so there's some logic duplication to support require via servie/dist/body/node
and servie/dist/body/browser
. If you are a module author only supporting browsers or node.js, feel free to use the NodeBody
or BrowserBody
exports to provide a better DX.
Properties
buffered
Indicates the raw body is entirely in memory (boolean
)bodyUsed
Indicates the body has already been read (boolean
)hasBody
Indicates the body has been set (not undefined
) (boolean
)headers
Set 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)
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 and emit yourself:
- Listen to the
error
event on Request
for out-of-band errors and respond accordingly (e.g. app-level logging) - Listen to the
abort
event on Request
to destroy the HTTP request/response - Emit the
response
event on Request
when handling the response - 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