ESX-RS

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

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.

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:

• @DELETE, @GET, @HEAD, @OPTIONS, @PATCH, @POST and @PUT
• @Consumes and @Produces
• @Path

The @Path decorator is handled a bit differently: the operation path is appended to the endpoint path.

Known Limitations

At the moment, only concrete classes can be decorated.

This is due to the way ECMAScript gets generated, as interfaces no longer exist in the generated code.

To achieve a close equivalent, abstract classes can be used, so that the following interface:

@Path('/example')
interface MyInterface {
    @GET @Path('/resource')
    myMethod(): Promise<string>;
}

Becomes:

@Path('/example')
abstract class MyInterface {
    @GET @Path('/resource')
    abstract myMethod(): Promise<string>;
}

Development