rpc-controllers

rpc-controllers

Allows to create controller classes with methods as JSON-RPC methods that handle JSON-RPC 2.0 requests. You can use rpc-controllers with express.js or koa.js.

Table of contents

• Installation

• Example of usage

• More examples

Installation

• Install module:

  npm install rpc-controllers --save

• reflect-metadata shim is required:

  npm install reflect-metadata --save

  and make sure to import it before you use rpc-controllers:

  import "reflect-metadata";
  

• Install framework:

  a. If you want to use rpc-controllers with express.js, then install it and all required dependencies:

  npm install express body-parser --save

  Optionally you can also install their typings:

  npm install @types/express @types/body-parser --save

  b. If you want to use rpc-controllers with koa.js, then install it and all required dependencies:

  npm install koa koa-router koa-bodyparser --save

  Optionally you can also install their typings:

  npm install @types/koa @types/koa-router @types/koa-bodyparser --save

• Its important to set these options in tsconfig.json file of your project:

  {
   "emitDecoratorMetadata": true,
   "experimentalDecorators": true
  }
  

Example of usage

• Create a file MathController.ts

  import {Controller, Method, Params} from "rpc-controllers";
  
  @Controller("math")
  export class MathController {
  
      @Method("add")
      add(@Params() params: Array<number>) {
          return params.reduce((prev, curr) => prev + curr);
      }
  
      @Method("test")
      test(@Params() params: any[]) {
          return params;
      }
  }
  

  This class will register JSON-PRC methods specified in method decorators in your server framework (express.js or koa).

• Create a file app.ts

  import "reflect-metadata"; // don't forget import this shim!
  import {createExpressServer} from "rpc-controllers";
  import {MathController} from "./MathController";
  
  // creates express app, registers all controller methods and returns you express app instance
  const app = createExpressServer({
     controllers: [MathController] // we specify controllers we want to use
  });
  
  // run express application on port 3000
  app.listen(3000);
  

  if you are koa user you just need to use createKoaServer instead of createExpressServer

• Send a JSON-RPC 2.0 request to http://localhost:3000 using the method math.add and the params [1, 1]. You will get the result 2.

More usage examples

Load all controllers from the given directory

import "reflect-metadata"; // don't forget import this shim!
import {createExpressServer} from "rpc-controllers";

const app = createExpressServer({
  controllers: [__dirname + "/controllers/*.js"] // registers all given controllers
});

// run express application on port 3000
app.listen(3000);

Pre-configure express/koa

If you have, or if you want to create and configure express app separately, you can use useExpressServer instead of createExpressServer function:

import "reflect-metadata";
import {useExpressServer} from "rpc-controllers";
import {MathController} from "./MathController";

let express = require("express"); // or you can import it if you have installed typings
let app = express(); // your created express server
// app.use() // you can configure it the way you want
useExpressServer(app, { // register created express server in rpc-controllers
    controllers: [MathController] // and configure it the way you need (controllers, validation, etc.)
});
app.listen(3000); // run your express server

Using DI container

rpc-controllers supports a DI container out of the box. You can inject your services into your controllers. Container must be setup during application bootstrap. Here is example how to integrate rpc-controllers with typedi:

import "reflect-metadata";
import {createExpressServer, useContainer} from "rpc-controllers";
import {Container} from "typedi";

// its important to set container before any operation you do with rpc-controllers,
// including importing controllers
useContainer(Container);

// create and run express server
let app = createExpressServer(3000, {
    controllers: [__dirname + "/controllers/*.js"],
});

That's it, now you can inject your services into your controllers:

@Controller()
export class MessageController {

    constructor(private messageRepository: MessageRepository) {
    }

    // ... controller methods

}