Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rraziel/esx-rs
ECMAScript decorators for REST endpoint description, inspired by JAX-RS.
https://github.com/rraziel/esx-rs
decorator ecmascript jax-rs rest typescript
Last synced: 12 days ago
JSON representation
ECMAScript decorators for REST endpoint description, inspired by JAX-RS.
- Host: GitHub
- URL: https://github.com/rraziel/esx-rs
- Owner: rraziel
- License: mit
- Archived: true
- Created: 2017-11-25T20:37:39.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2020-05-30T20:02:02.000Z (over 4 years ago)
- Last Synced: 2025-01-16T11:43:55.709Z (17 days ago)
- Topics: decorator, ecmascript, jax-rs, rest, typescript
- Language: TypeScript
- Homepage:
- Size: 4.19 MB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ESX-RS
[](https://www.npmjs.com/package/@esx-rs/core)
[](https://www.npmjs.com/package/@esx-rs/core)
A library inspired by [JAX-RS](https://en.wikipedia.org/wiki/Java_API_for_RESTful_Web_Services), allowing the description of REST endpoints through simple [TypeScript](https://www.typescriptlang.org/) 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:
```typescript
@Path('/users')
@Produces('application/json') @Consumes('application/json')
class UsersEndpoint {
@POST
async createUser(user: User): Promise {
// ...
}
@PUT @Path('/:userId')
async updateUser(@PathParam('userId') userId: string, user: User): Promise {
// ...
}
@GET @Path('/:userId')
async getUser(@PathParam('userId') userId: string): Promise {
// ...
}
@DELETE @Path('/:userId')
async deleteUser(@PathParam('userId') userId: string): Promise {
// ...
}
}
```
## 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](https://github.com/pillarjs/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:
```typescript
@Path('/example')
interface MyInterface {
@GET @Path('/resource')
myMethod(): Promise;
}
```
Becomes:
```typescript
@Path('/example')
abstract class MyInterface {
@GET @Path('/resource')
abstract myMethod(): Promise;
}
```
## Development
[](https://ci.appveyor.com/project/rraziel/esx-rs)
[](https://circleci.com/gh/rraziel/esx-rs)
[](https://travis-ci.org/rraziel/esx-rs)
[](https://ci.appveyor.com/project/rraziel/esx-rs/build/tests)
[](https://codecov.io/gh/rraziel/esx-rs)
[](https://codeclimate.com/github/rraziel/esx-rs)
[](https://codeclimate.com/github/rraziel/esx-rs/issues)