xaerodegreaz/ts-spring-rest

Spring-like TypeScript decorators for NodeJS HTTP request mapping

Request Handling in TypeScript

This README provides instructions on how to use various decorators, Handler implementations, and the handleRequest function in TypeScript to handle HTTP requests effectively.

Decorators

@PostMapping

• Description: Binds a method to handle POST requests at a specific path.

import { PostMapping } from '@xaerodegreaz/ts-spring-rest';

class ExampleController {
  @PostMapping( { path: '/example' } )
  handlePostRequest()
  {
    // Handle POST request logic
  }
}

There are decorators for @GetMapping, @DeleteMapping, etc.

@RequestBody

• Description: Binds the request body to a suitable object of your choice.

import { RequestBody } from '@xaerodegreaz/ts-spring-rest';

class MyObject {
  name: string
  age: number
}

class ExampleController {
  @PostMapping( { path: '/example' } )
  handlePostRequest( @RequestBody body: MyObject )
  {
    // Use request body
  }
}

@RequestParameter

• Description: Binds a single request parameter (from a query string) to a method parameter and attempts to convert it to a primitive type if possible.

import { RequestParameter } from '@xaerodegreaz/ts-spring-rest';

class ExampleController {
  @GetMapping( { path: '/example' } )
  handleGetRequest( @RequestParameter( 'id' ) id: number )
  {
    // Use request parameter
  }
}

@RequestParameters

• Description: Binds all request parameters (from the query string) to a suitable object of your choice.

import { RequestParameters } from '@xaerodegreaz/ts-spring-rest';

class ExampleController {
  @GetMapping( { path: '/example' } )
  handleGetRequest( @RequestParameters params: Record<string, string> )
  {
    // Use request parameters
  }
}

@Header

• Description: Binds a single header to a single parameter and attempts to convert it to a primitive type if possible.

import { Header } from '@xaerodegreaz/ts-spring-rest';

class ExampleController {
  @GetMapping( { path: '/example' } )
  handleGetRequest( @Header( 'Authorization' ) token: string )
  {
    // Use request header
  }
}

@Headers

• Description: Binds all headers to an object, such as a custom one or a Record.

import { Headers } from '@xaerodegreaz/ts-spring-rest';

class ExampleController {
  @GetMapping( { path: '/example' } )
  handleGetRequest( @Headers headers: Record<string, string> )
  {
    // Use request headers
  }
}

@ExceptionHandler

• Description: This decorator will throw a DecoratedMethodException inside the handleRequest request function and will contain a statusCode for you to use in your exception handling. See the handleRequest function below for an example.

import { ExceptionHandler } from '@xaerodegreaz/ts-spring-rest';

class ExampleController {
  @GetMapping( { path: '/example' } )
  @ExceptionHandler( { errorType: [TypeError], statusCode: 400 } )
  @ExceptionHandler( { errorType: [ReferenceError], statusCode: 404 } )
  handleGetRequest(  )
  {
    // Your function that can potentially throw errors
  }
}

Handler Implementations

AwsLambdaHandler

• Description: A handler for AWS Lambda events that translates them and passes them to the handleRequest function internally.

import { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
import { AwsLambdaHandler } from '@xaerodegreaz/ts-spring-rest';

export const lambdaHandler = async ( event: APIGatewayProxyEvent, context: any ): Promise<APIGatewayProxyResult> => {
  const controller = new YourControllerClass();
  const handler = new AwsLambdaHandler( controller );
  return await handler.handle( event );
};

Handler implementations also gain access to the withIocContainerGetMethod that can can be used with IOC containers such as tsyringe, or typescriot-ioc in order to construct your controller with its dependencies. No IOC packages are included with this one, so refer to your vendor for documentation.

import { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
import { Container } from 'typescript-ioc';
import { AwsLambdaHandler } from '@xaerodegreaz/ts-spring-rest';

class YourControllerClass {
  constructor(
    private readonly dependency1: Dependency1, 
    private readonly dependency2: Dependency2){}
  
  @RequestMapping({path:'/example/get'})
  handleGet(
    @RequestHeaders headers: Record<string, string>, 
    @RequestParameter('someParam') someParam: int) {
    // handle your get
  }

  @PostMapping({path:'/example/post'})
  handleGet(@RequestBody myRecord: MyRecord) {
    // handle your post
  }
}

export const lambdaHandler = async ( event: APIGatewayProxyEvent, context: any ): Promise<APIGatewayProxyResult> => {
  // Using the typescript-ioc package for dependency injection
  const handler = new AwsLambdaHandler( YourControllerClass )
    .withIocContainerGetMethod( Container.get );
  return await handler.handle( event );
};

handleRequest Function

Description

The handleRequest function is an internal utility function designed to handle HTTP requests based on metadata defined through decorators. It can be used as an alternative to the provided Handler implementations.

Usage

import { handleRequest } from '@xaerodegreaz/ts-spring-rest';

const exampleRequest = {
  method: 'GET',
  path: '/example',
  body: '{"key":"value"}',
  headers: {
    'Content-Type': 'application/json',
  },
};

const targetClass = new YourControllerClass();

try
{
  const response = await handleRequest( exampleRequest, targetClass );
  console.log( 'Response:', response );
}
catch ( error )
{
  if ( error instanceof DecoratedMethodException )
  {
    console.error( `Error: message:${error.message}, statusCode:${error.statusCode}` );
  }
  else
  {
    console.error( 'Unhandled Error:', error );
  }
}

ts-spring-rest's Issues

Add documentations to request mapping decorators

https://github.com/XaeroDegreaz/ts-spring/blob/c94f4d9cedd0cda83ea7ceb69815a81e3783ca79/src/decorators/PostMapping.ts#L23

Write tests for path parameters

https://github.com/XaeroDegreaz/ts-spring/blob/d7dfd4f7cd4fbf473007ac654dec95e760225f75/test/app.test.ts#L117

Work on decorators for returning status code via handler instead of returning here

https://github.com/XaeroDegreaz/ts-spring/blob/d7dfd4f7cd4fbf473007ac654dec95e760225f75/src/Handlers.ts#L48

Add README

This is not safe when there is no key data. Throws error when no RequestParam or Header decorators are used

https://github.com/XaeroDegreaz/ts-spring/blob/9ebfe8791389c49c71c968411110c0fe0d83e412/src/requestHandler.ts#L105