@pawsteam/ts-jsonrpc-server

Typescript JSONRPC server

Installation

For MacOS Catalina, please follow this link

All the rest, npm install.

The Framework

The framework is aimed at making life easier when writing JSON-RPC servers. It is Promise-based, so everything will return a promise, except for validators. It is revolving around stages/hooks in the life of a request:

1. Input validators

   They check the request for required data and types. It's a place to define what parameters are needed for a method to be called.

   Any number of Input Validators can be assigned for one method. Generic ones as well;

   @AppConfigDecorator({
       port: 2000,
       services: [SomeService],
       genericValidators: [
           new HeaderExistsValidator('content-type'),
           new HeaderValueContainsValidator('user-agent', 'Mozilla/5.0')
       ]
   })
   export class AppMain {
       ...
   }
   export class HeaderExistsValidator implements ValidatorInterface {
       headerName: string;
       constructor(headerName: string) {
           this.headerName = headerName;
       }
       validate(params: any, request): boolean {
           ...
       }
   }
   

   The input validators implement ValidatorInterface and return a boolean value.

2. Input transformers - they transform the request data into objects that are passed to the methods Any number of input transformer can exist per method.

   It must return a promise of one parameter.

   The order of validators will give the order of parameters in the method call.

   The transformers implement the TransformerInterface and return a Promise to the type of object they are for.

   export class BucketTransformer implements TransformerInterface {
   /**
   * The ParsedRpcObjectType is an object created from the body of the request, parsed,
   * and put into the form of a JSONRPC object:
   * {
   *    id: <id>,
   *    method: <methodname>,
   *    jsonrpc: '2.0',
   *    params: {...}
   * }
   */
      transform(request: IncomingMessage, jsonrpcObj: ParsedRpcObjectType): Promise<BucketType> {
          const newBucket = new BucketType(jsonrpcObj.params.path);
          return Promise.resolve(newBucket);
      }
   }
   

   The reason this method needs to return a promise is because we might need to fetch additional data in order to create the object. For instance, we might need to query a DB.

   Validation can also be done in the transformer. If the transformer rejects the promise or throws, the transformation is interpreted as failed, so validation failed.

   To use a transformer, you simply instantiate a new instance of your transformer:

   @TransformerDecorator(new CarTransformer())
   @TransformerDecorator(new EngineTransformer())
   method3(car: CarType, engine: EngineType, request: IncomingMessage, response: ServerResponse) {
       return Promise.resolve(car.wheels * engine.power);
   }
   

3. The method itself - this is where the app logic lives

   It must also return a promise of a HttpResponse type of object, this object will be returned to the user.

   @ValidatorDecorator(new BucketValidator())
   @TransformerDecorator(new BucketTransformer())
   createBucket(bucket: BucketType, context: RequestContextType): Promise<any> {
      return Promise.resolve({created: bucket.path});
   }
   

4. TODO: Response serializer - this is where you can decide what exactly ends up in the response.

In the near future, a functionality to make the server emit events will be implemented.