npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

js-restful-express

v3.1.0

Published

Create a RESTful service with ES6 decorators for your express based node.js application.

Downloads

136

Readme

js-restful-express

Create a RESTful service with ES7 decorators for your express based node.js application.

CI Status npm version Coverage Status Code Climate Test Coverage Issue Count Issue Stats

Installation

npm install js-restful-express --save

You need to use a es7 reflect metadata shim (reflect-metadat or core-js). This is essential to make the decorators working. It must be ensured that this module is only loaded once. Otherwise the decorated information will be lost at runtime. Keep in mind that this is a shim and until now not a language feature!

Prerequisites

  • You use TypeScript for your app
  • You use express 4.x as your http framework for your node.js application

Usage

Decorate your service class with the decorators from the js-restful Github-project. So far there are the following decorators available:

| Decorator | Description | | ------------- | ------------- | | @Path | The path under which the service will be published. The decorator can be used at class and method level. You need to provide a path as string.| | @GET | Decorator that indicates a HTTP GET method.| | @POST | Decorator that indicates a HTTP POST method.| | @PUT | Decorator that indicates a HTTP PUT method.| | @DELETE | Decorator that indicates a HTTP DELETE method.| | @PathParam | A method parameter may be decorated with the @PathParam decorator. The decorator requires a string parameter - the name of the parameter. The name must be present within the Path. For example /books/:id. One can access the id parameter parameter with @PathParam('id')| | @HeaderParam | You can access the http header information in the same way as a path parameter. The difference is, that the value will be determined by a http header entry at runtime. For example if you want to access a token that is stored in the http header use: @HeaderParam('token)| | @QueryParam | If you want to access url query parameters from your service use this decorator. For example in a url like this: /books?readed=true you can use @QueryParam('readed')| | @Context (HttpRequest, HttpResponse) | Sometime it may be necessary to play around with the original HttpRequest or the HttpResponse. In this case you can use the @Context decorator. For Example @Context(ContextTpyes.HttpRequest)| | @SecurityContext | This module provides decorators that can deal with security concerns out of the box. If this doesn't fits your needs you can inject the SecurityContext manually. For example: withSecContext(@SecurityContext() context:ISecurityContext) | | @RolesAllowed | You may restrict the access to all methods of a class or a specific method. Just use the @RolesAllowed decorator: @RolesAllowed(['admin'])| | @PermitAll | If you want you service or service methods to be called by everyone use @PermitAll|

Remarks

  • The HTTP Method decorators are only marker decorators. They don't have a parameter. The request path must be defined by the @Path decorator.
  • If you use any of the build in security capabilities you need to register a ISecurityContextFactory. See below.
  • If you specify @RolesAllowed or @PermitAll at class level and method level, the decorator at the method overwrites the decorator at class level.

This npm modul adds the following decorators:

| Decorator | Description | | ------------- | ------------- | | @RenderWith | The decorator expects a string as parameter. This is the view that should be used to render the result. For example: @RenderWith('index') will render the result of the service method with a view named index. You need to configure express with your preferred render engine: app.set('view engine', 'pug');. | | @ExpressContext (HttpNextFunction) | The express framework provides a next function. If you need access to this function from within your service you may use this decorator for a method parameter. |

A more elaborate example:

import { GET, POST, PUT, DELETE, Path, PathParam, HeaderParam } from 'js-restful';


@Path('/books')
class BookService {

    @GET()
    allBooks() : Book[]{
       return [];
    }

    @Path('/:name')
    @POST()
    createBook(@PathParam('name') name:string, @HeaderParam('token') token:string) :Book {
        return {id:1, name:name};
    }

    @Path('/:id/:name')
    @PUT()
    updateBook(@PathParam('id') id:number, @PathParam('name') name:string) : Book {
        return {id:id, name:name};
    }

    @Path('/:id')
    @DELETE()
    deleteBook(@PathParam('id') id:number): boolean {
        return true;
    }
}

After you have done this, setup your express app as you usually would. Then you can register a decorated instance of your service:

import { ExpressServiceRegistry } from './service-registry';
import * as express from 'express';

let app = express();
ExpressServiceRegistry.registerService(app, new BookService());

That's it. Now your service is published as an RESTful service in your express app.

If you start your app you can access the urls:

Supported Return Types

So far we have seen that all service methods are synchronous. You can return simple javascript types or complex objects. If you simply return a boolean, number, string these values will be returned as text/plain. null or undefined are returned as text/plain if no HttpResponse-object is injected in the service method (in this case you have full control what should be returned to the client). If you returns a complex object the result will be send as application/json.

But what if your service method is asynchronous? In this case you can use es6 promises. For example:

import {Promise} from 'es6-promise';

@Path('/')
class TestService {

    @GET()
    get(){
        const p: Promise<any> = new Promise ((resolve, reject) => {
          resolve([{foo:'bar'}]);
        });
        return p;
    }
}

If you access the url '/' you will get [{foo:'bar'}] as the result. May be this is too much code for you - for me it is :smirk: . Keep in mind that there are a lot of node modules that already use promises. For example mongoose. With this you service could be as short as:

import {Path, GET, RolesAllowed} from 'js-restful';
import {User} from './../models/userModel';

@Path('/users')
@RolesAllowed(['admin'])
export class UserService {

  @GET()
  users(){
    return User.find({}).exec();
  }

}

Providing a ISecurityContextFactory

If you decorate your service with @RolesAllowed, @PermitAll or you are using @SecurityContext as a parameter decorator you need to provide a ISecurityContextFactory. js-restful-express need this factory to create a ISecurityContext to decide who is permitted to access the service or service method.

This Factory must be registered at the ExpressServiceRegistry before you register your service classes:

ExpressServiceRegistry.registerSecurityContextFactory(app, new SecurityContextFactory());

Here is a sample implementation that assumes you are using passport for authentication:

class SecurityContextFactory implements ISecurityContextFactory {

  createSecurityContext(req:express.Request):ISecurityContext {
    return new SecurityContext(req);
  }

}

The SecurityContext needs to be created for every request!

class SecurityContext implements ISecurityContext {

  user:User;

  constructor(req:express.Request){
    this.user = new User(req);
  }

  isUserInRole(roleName:string):boolean {
    if(!this.user.isLoggedIn()){
      return false;
    }
    return this.user.hasRole(roleName);
  }
}
export default class User implements IUser {

  private passportUser:any;
  private roles:string[] = [];

  constructor(req:express.Request){

    if (req.isAuthenticated()){
      this.passportUser = req.user;
    }
  }

  isLoggedIn():boolean{
    return this.passportUser ? true : false;
  }

  hasRole(roleName:string):boolean {
    return this.passportUser.roles.indexOf(roleName) != -1;
  }
}

Passing in a custom logger instance

js-restful-express uses winston for logging. You can override the default logger by initializing the registry with a config object before registering any services:

import { ExpressServiceRegistry } from 'js-restful-express';
import * as express from 'express';
import { Logger, transports } from 'winston';

const app = express();
const logger = new Logger({...});

ExpressServiceRegistry.initJsRestfulRegistry(app, {logger});
ExpressServiceRegistry.registerService(app, {...});

Advantages

You may ask: what is the advantage of using decorators and TypeScript for your app? Here are some thoughts why it is useful:

  • You may write less code you need to maintain and test.
  • You can refactor your code with minimal impact at other parts of your application. Just move or rename your service class will not break how your service may be accessed.
  • You can change who is allowed to access your service or service method without modifying your code. You just change the decorator.
  • You can test your services more easily - if you do not use HttpRequest or HttpResponse directly you don't need to mock these objects.
  • May be you have a background in Java and know what JAX-RS is. In this case you will be familiar with this approach.