Servie provides standard, framework-agnostic HTTP interfaces for servers and clients.
Installation
npm install servie --save
Usage
Common
Base HTTP class for common request and response logic.
import { Common } from 'servie'
Options
headers?
HTTP headers (Headers | HeadersObject | string[]
)trailers?
HTTP trailers (Headers | HeadersObject | string[]
)events?
An event emitter object (EventEmitter
)body?
Allowed HTTP bodies (string | Buffer | Readable | object
)
Properties
events
An event emitter for listening to the request and response lifecyclesheaders
The headers as a Headers
instancetrailers
The trailers as a Headers
instancebody
The request or response payloadbodyUsed
A boolean indicating whether the body has been readtype
A shorthand property for reading and writing the Content-Type
headerlength
A shorthand property for reading and writing Content-Length
as a numberstarted
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
buffer(maxBufferSize): Promise<Buffer>
Read the body into a Buffer
objecttext(maxBufferSize): Promise<string>
Read the body as a string
stream(): Readable
Read the body as a Readable
stream
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
is incremented
Request
HTTP class for encapsulating a Request
, extends Common
.
import { Request } from 'servie'
Options
const request = new Request({
url: '/',
method: 'GET'
})
Extends Common
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
The HTTP request url (string
)method
The HTTP request method upper-cased (string
)Url
The HTTP request url as a read-only parsed object (object
)connection
Connection information ({}
)
Methods
abort(): boolean
Emit an abort eventerror(message, code, status?, original?): HttpError
Create a HTTP error instance
Events
abort
Emitted when the request is aborted and MUST be handled by transporterror
Emitted when an out-of-band error occurs (e.g. abort) and MUST be handled by the transportresponse
Emitted when the response object is being handled
Response
HTTP class for encapsulating a Response
, extends Common
.
import { Response } from 'servie'
Options
const response = new Response({})
Extends Common
options.
status?
The HTTP response status code (number
)statusText?
The HTTP response status message (string
)
Properties
status?
The HTTP response status code (number
)statusText?
The HTTP response status message (string
)
Used by Common
for Request
and Response
objects.
Options
Take a single parameter with the headers in object, array or Headers
format.
Properties
raw
The raw HTTP headers list (string[]
)
Methods
object(obj?: HeadersObject | null): HeadersObject | void
A getter/setter method for reading the headers as a lower-cased object (like node.js)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 header
HttpError
Internally and externally triggered HTTP errors.
Properties
code
A unique error code (string
)status
A HTTP status code (number
)request
The Request
instance that triggered the error (Request
)message
Standard error message (string
)cause
Specified when the HTTP error was triggered by an underlying error
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 - 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 ES5 environments, but also requires Promise
to be available.
TypeScript
This project is written using TypeScript and publishes the definitions directly to NPM.
License
Apache 2.0