Skip to content

Latest commit

 

History

History
442 lines (340 loc) · 17.1 KB

Documentation.md

File metadata and controls

442 lines (340 loc) · 17.1 KB
Raw

API

class HTTPServer

Properties

<HTTPServer>.port -> number

The port on which the server is listening.

Other properties

The HTTPServer class extends the Router class, please see router properties for the inherited properties.

Methods

new HTTPServer(options) -> HTTPServer

Creates a new HTTP server.

Parameter Type Description
options ?HTTPServerOptions The options for the server

Example

const port = 3000;
const server = new HTTPServer({ port });

<HTTPServer>.on(event, callback) -> void

Adds an event listener on the server.

Parameter Type Description
event HTTPServerEvent The event to listen for
callback function The listener for the event

Notes
Don't add listeners for HTTPServerEvent.Request as this event is already handled internally.
Don't add listeners for HTTPServerEvent.Listening, instead use the callback of <HTTPServer>.start().

<HTTPServer>.start(listeningCallback) -> void

Starts the server on the port specified in the server options (see <HTTPServer>.port).

Parameter Type Description
listeningCallback function Triggered when the server is ready

Examples

server.start(() => {
    console.log(`Server started at http://localhost:${port}`);
});

<HTTPServer>.close() -> void

Closes the server.

Other methods

The HTTPServer class extends the Router class, please see router methods for the inherited methods.

class Router

Properties

<Router>.routers -> Router[]

All the routers mounted on this router.

<Router>.routes -> Route[]

All the handlers and their specific path and method on this router. See Route for more details.

<Router>.type -> HandlerType.Router

The type of the Handler. It is always HandlerType.Router. See HandlerType for more details.

<Router>.path -> string

The path where the router is mounted.

<Router>.method -> HTTPMethod.Any

The methods handled by this router. It is always HTTPMethod.Any. See HTTPMethod for more details.

Methods

new Router() -> Router

Creates a new router.

<Router>.get(path, handler) -> void

Adds a new handler for GET requests.

Parameter Type Description
path string The path where to add the handler
handler HandlerFunction The handler to add

<Router>.post(path, handler) -> void

Adds a new handler for POST requests.

Parameter Type Description
path string The path where to add the handler
handler HandlerFunction The handler to add

<Router>.patch(path, handler) -> void

Adds a new handler for PATCH requests.

Parameter Type Description
path string The path where to add the handler
handler HandlerFunction The handler to add

<Router>.delete(path, handler) -> void

Adds a new handler for DELETE requests.

Parameter Type Description
path string The path where to add the handler
handler HandlerFunction The handler to add

<Router>.use(path, handler) -> void

Adds a new handler for any request method.

Parameter Type Description
path string The path where to add the handler
handler HandlerFunction | Router The handler to add

class Request

Properties

<Request>.body -> string | Buffer

The body of the request. It is a string or a Buffer, depending on the Content-Type header.

<Request>.headers -> IncomingHttpHeaders

The raw headers of the request. See https://nodejs.org/docs/latest/api/http.html#messageheaders for more details.

<Request>.method -> HTTPMethod

The http method of the request. See HTTPMethod for all possible values.

<Request>.url -> URL

The url of the request. See https://nodejs.org/docs/latest/api/url.html#class-url for more details.

<Request>.params -> { [key: string]: string }

The params in the request's path.

Example

server.get('/users/:username', (req, res) => {
    console.log(req.params.username);
    return RequestStatus.Done;
});

Here we declare a route with a param (:username). Whenever in the path of a handler there is a slash followed by a colon (/:), it marks a param. There can be multiple params in the same handler path, but their name must be different. The corresponding part of the request's pathname will be the value of the param.

With the previous code, if the request's pathname is /users/jean, req.params.username will be jean, and therefore jean will be logged in the console.

<Request>.query -> URLSearchParams

The query/search-params of the request. See https://nodejs.org/docs/latest/api/url.html#class-urlsearchparams for more details.

<Request>.data -> {}

This property is used to store any data you want to pass to the next handlers that will handle the request.

Example

server.use('/*', (req, res) => {
    req.data.authenticated = false; // default to false
    if (isAuthValid(req.headers.authorization)) { // perform some auth validation
        req.data.authenticated = true; // set the auth to true if the validation success
    }
    return RequestStatus.Next;
});

server.get('/protected', (req, res) => {
    if (req.data.authenticated) { // if the validation successed
        res.send('Welcome to the protected page');
    } else { // otherwise the user is not allowed
        res.status(401);
        res.send('Invalid auth');
    }
    return RequestStatus.Done;
});

<Request>.cookies -> { [key: string]: string }

The cookies sent with the request.

<Request>.timestamp -> number

The timestamp at which the server received the request.

class Response

Properties

<Response>.checkContentType -> boolean

Whether or not the content-type checking when sending data is enabled. Use <Response>.setContentTypeCheck() to modify this value.

<Response>.headers -> OutgoingHttpHeaders

The currently set headers for this reponse. The Set-Cookie headers are not included. To view the cookies, see <Response>.cookies.

<Response>.headSent -> boolean

Whether or not the head of the response has been sent. If true, the headers and the status code cannot be changed.

<Response>.sent -> boolean

Whether or not the body of the response has been sent. See <Response>.end() for more details.

<Response>.contentType -> ?ContentType

The content-type of the response's body. If no data has been send yet, the value is null. See ContentType for more details.

<Response>.code -> number

The status code of the response. By default it is 200. Use <Response>.status() to modify it.

<Response>.cookies -> { [name: string]: Cookie }

The cookies that have been set on this response. See <Response>.setCookie() for more details.

<Response>.sentTimestamp -> ?number

The timestamp when the <Response>.end() method has been called. This property is null before <Response>.end() has been called. View <Response>.end() for more details.

Methods

<Response>.setContentTypeCheck(value) -> void

Enable or disable the content-type checking.

Parameter Type Description
value boolean The new state of the content-type checking

<Response>.send(data) -> void

Send some data.

Parameter Type Description
data string | Buffer The data to send

<Response>.setHeader(name, value) -> void

Set or modify a header. Do not use this to set cookies, as the last set cookie will overwrite all the other previously set. To set cookies, use <Response>.setCookie().

Parameter Type Description
name string The name of the header to set
value string The value of the header

<Response>.setCookie(name, value, attributes) -> void

Set a cookie on the response.

Parameter Type Description
name string The cookie's name
value string The cookie's value
attributes ?CookieAttributes The cookie's attributes

<Response>.status(code) -> void

Set the status code of the response. See <Response>.code for more details.

Parameter Type Description
code number The new status code

<Response>.end(data) -> void

End the response. Optionally send data, then set <Response>.sent to true.

Parameter Type Description
data ?(string | Buffer) The data to send before ending the response

<Response>.onSent(callback) -> void

Adds a function to be called just after the request is sent. Useful for logging middlewares.

Parameter Type Description
callback function The function to be called

Examples

server.use('/*', function logger(req, res) {
    res.onSent(() => {
        console.log(`timestamp: ${res.sentTimestamp} | code: ${res.code}`);
    });
    return RequestStatus.Next;
});

enum RequestStatus

The possible status for a request in the handling process, returned by the handler functions.

Member Description
RequestStatus.Done The request has been handled and the response is sent
RequestStatus.Next The handler has finished his job and passes the request to the next handler
RequestStatus.Error An error occured during the handling process

enum HTTPServerEvent

The different events that the server can encounter. See <HTTPServer>.on().

See the Node.js documentation for more details about each event.

Member Description
HTTPServerEvent.CheckContinue -
HTTPServerEvent.CheckExpectation -
HTTPServerEvent.ClientError -
HTTPServerEvent.Close -
HTTPServerEvent.Connect -
HTTPServerEvent.Connection -
HTTPServerEvent.DropRequest -
HTTPServerEvent.Error -
HTTPServerEvent.Listening -
HTTPServerEvent.Request -
HTTPServerEvent.Upgrade -

Notes
Don't add listeners for HTTPServerEvent.Request as this event is already handled internally.
Don't add listeners for HTTPServerEvent.Listening, instead use the callback of <HTTPServer>.start().

enum HTTPMethod

The different http methods handled.

Member Description
HTTPMethod.Get -
HTTPMethod.Post -
HTTPMethod.Patch -
HTTPMethod.Delete -
HTTPMethod.Any Special value used when <Router>.use() is called

enum ContentType

The different content-types.

Member Description
ContentType.Text Used for textual content (i.e. html)
ContentType.JSON Used for JSON body
ContentType.OctetStream Used for all other data types

enum HandlerType

The two possible types of handler.

Member Description
HandlerType.Router Used for Router
HandlerType.RouterFunction Used for Route

type HTTPServerOptions

The options passed to new HTTPServer().

Property Type Description
HTTPServerOptions.httpServer ?Server A preexisting server object (from node:http)
HTTPServerOptions.port ?number The port on which the server listens (see <HTTPServer>.start())

type Cookie

Represents a cookie value and attributes. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie for more details.

Property Type Description
Cookie.value string The value of the cookie
Cookie.attributes ?CookieAttributes The attributes of the cookie

type CookieAttributes

Represents the attributes of a cookie. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#attributes for more details.

Property Type Description
CookieAttributes.secure ?boolean -
CookieAttributes.maxAge ?number -
CookieAttributes.httpOnly ?boolean -

type HandlerFunction

Functions used to handle requests.

Parameter Type Description
request Request The incoming request
response Response The outgoing response

Return value

RequestStatus

type Route

Internal wrapper for HandlerFunction so they have common internally required properties with Router.

Property Type Description
Route.path string the path of the route
Route.method HTTPMethod the method this route handles
Route.type HandlerType.RouterFunction the type of the route
Route._handle HandlerFunction the wrapped handler function