Standard, framework-agnostic HTTP interfaces for JavaScript servers and clients.

Installation

npm install servie --save

Usage

• throwback Compose middleware functions into a single function
• servie-lambda Servie transport layer for AWS Lambda
• servie-http Servie transport layer for node.js HTTP
• busboy A streaming parser for HTML form data
• qs and querystring Parse HTTP query string to object
• get-body General body parser for forms, JSON and text
• servie-cors CORS middleware for Servie
• servie-route Routing middleware for Servie
• servie-mount Mount Servie middleware on a path prefix
• servie-compat-http Mimic node.js HTTP using Servie
• servie-redirect Create response objects for redirection
• servie-cookie-store API for managing client-side cookies
• servie-errorhandler Standard error handler for transport layers
• servie-finalhandler Standard final handler for transport layers
• http-errors Create HTTP errors
• boom HTTP-friendly error objects
• consolidate Template rendering

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 lifecycle
• headers The headers as a Headers instance
• trailers The trailers as a Headers instance
• body The request or response payload
• started Boolean indicating if a request/response has started
• finished Boolean indicating if a request/response has finished
• bytesTransferred 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 available
• trailers Emitted when the trailers object is available
• started 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 handle
• error An out-of-band error occurred and transport MUST handle
• response The corresponding Response has started
• connection 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)

Headers

Used by Servie for Request, Response and Body objects.

import { Headers, createHeaders } from 'servie'

Options

const headers = createHeaders(...) // new Headers([...])

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 name
• append(name: string, value: string | string[]): this Append a HTTP header
• get(name: string): string | undefined Retrieve a case-insensitive HTTP header
• getAll(name: string): string[] Retrieve a list of matching case-insensitive HTTP headers
• has(name: string): boolean Check if a case-insensitive header is already set
• delete(name: string): this Delete a case-insensitive header
• asObject(toLower?: boolean): HeadersObject Return the headers as a plain object
• extend(obj: HeadersObject): this Extends the current headers with an object
• keys() Iterable of the available header names
• values() Iterable of header values
• entries() 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 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(...) // new Body({ rawBody: ... })

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 string
• json(): Promise<any> Returns body parsed as JSON
• arrayBuffer(): Promise<ArrayBuffer> Returns the body as an ArrayBuffer instance
• buffer(): 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:

1. Listen to the error event on Request for out-of-band errors and respond accordingly (e.g. app-level logging)
2. Listen to the abort event on Request to destroy the HTTP request/response
3. Emit the response event on Request when handling the response
4. Set started === true and finished === true on Request and Response, as appropriate
5. 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