Esx-rs NPM | npm.io

ESX-RS

A library inspired by JAX-RS, allowing the description of REST endpoints through simple TypeScript decorators.

It has currently been integrated with:

Integration	Type	Description
esx-rs-client	Client	Proxy generator to access remote ESX-RS endpoints through a class instance.
esx-rs-client-angular	Client	`esx-rs-client` network transport based on Angular HttpClient.
esx-rs-client-fetch	Client	`esx-rs-client` network transport based on Fetch.
esx-rs-client-http	Client	`esx-rs-client` network transport based on Node http.
esx-rs-client-xhr	Client	`esx-rs-client` network transport based on XMLHttpRequest.
esx-rs-server	Server	Dispatch incoming HTTP requests to ESX-RS decorated class methods.
esx-rs-router-express	Server	`esx-rs-server`-based router middleware for Express.
esx-rs-router-koa	Server	`esx-rs-server`-based router middleware for Koa.
esx-rs-validation	Validation	Validation layer based on es-validation.
esx-rs-schema-openapi	Schema	Schema generation for OpenAPI 3.0.

Getting Started

The library can be installed using npm:

npm install esx-rs --save

Or using yarn:

yarn add esx-rs

Endpoints can then be described using decorators:

@Path('/users')
@Produces('application/json')
@Consumes('application/json')
class UsersEndpoint {

    @POST
    async createUser(user: User): Promise<User> {
        // ...
    }

    @PUT @Path('/:userId')
    async updateUser(@PathParam('userId') userId: string, user: User): Promise<User> {
        // ...
    }

    @GET @Path('/:userId')
    async getUser(@PathParam('userId') userId: string): Promise<User> {
        // ...
    }

    @DELETE @Path('/:userId')
    async deleteUser(@PathParam('userId') userId: string): Promise<void> {
        // ...
    }

}

Usage

Various decorators are available, each targetting a subset of the typical REST properties for a service.

Method

The HTTP method(s) can be specified using:

@DELETE
@GET
@HEAD
@OPTIONS
@PATCH
@POST
@PUT
@HttpMethod

Path

The resource path can be specified using:

@Path

Note: the path-to-regexp format is used, e.g. /path/to/:resourceId/subpath/:subresourceId.

Resource Type

The type of resource, either consumed by the operation (mapped to content-type) or produced by the operation (mapped to accept), can be specified using:

@Consumes
@Produces

Multiple media types may be specified.

Parameters

Operation parameters and resource properties are mapped using a specific decorator for each parameter type:

@CookieParam
@FormParam
@HeaderParam
@MatrixParam
@QueryParam
@PathParam

Context

It is also possible to map the following context information to a parameter using the @ContextParam decorator:

HttpContext
HttpRequest
HttpResponse

Endpoint vs. Operation

Many decorators can be applied to both a class and its methods.

In this scenario, the OperationInfo object returned for a method contains merged information that includes both the operation and the endpoint information.

The following decorators can be applied to both classes and methods: