TsEDPlugin for Serverless Framework

This plugin integrates Ts.ED with the Serverless Framework, allowing you to automatically generate Serverless functions from your Ts.ED controllers.

Installation

First, ensure you have Node.js installed. Then, you can install the plugin via npm:

npm install tsed-plugin-serverless --save-dev

Configuration

To configure the plugin in your Serverless Framework project, you need to add it to your serverless.yml file:

service: my-service

plugins:
  - tsed-plugin-serverless

custom:
  tsedPlugin:
    patterns:
      module: 
        - "src/modules/**/*module.ts"
      controller: 
        - "src/modules/**/*controller.ts"
    environment:
      STAGE: ${opt:stage, 'dev'}
    memorySize: 128
    events:
      http:
        cors: true
    authorizer:
      functionName: myAuthorizerFunction
      HeaderName: Authorization

provider:
  name: aws
  runtime: nodejs18.x

functions:
  # The functions will be auto-generated by the plugin

Usage

The TsEDPlugin will automatically scan your project for Ts.ED controllers and generate corresponding Serverless functions. Here’s an example of how to structure your Ts.ED controllers:

Example Ts.ED Module

import { PlatformServerless } from "@tsed/platform-serverless";
import { ExampleController } from "./example-controller";

export = PlatformServerless.bootstrap({
	lambda: [ExampleController]
}).callbacks();

Example Ts.ED Controller

import { Controller, Get, Post, BodyParams } from "@tsed/common";
import { Summary, Description, Returns } from "@tsed/schema";

@Controller("/example")
export class ExampleController {
  @Get("/")
  @Summary("Get example")
  @Description("Retrieve an example item")
  @Returns(200, TSEDModel)
  getExample(): string {
    return "example";
  }

  @Post("/")
  @Summary("Create example")
  @Description("Create a new example item")
  @Returns(201, { description: "Item created" })
  createExample(@BodyParams() body: any): string {
    return "created";
  }
}

Running Serverless Offline

To run your Serverless project offline, use the following command:

serverless offline

The plugin will hook into the before:offline:start event to ensure all necessary functions are generated before starting the offline server.

How It Works

The plugin scans for Ts.ED controller files matching the patterns specified in your serverless.yml configuration. It extracts route information and generates Serverless functions based on the HTTP methods and paths defined in your controllers.

Parsing Decorators

The plugin parses decorators from your Ts.ED controllers to generate Serverless function definitions. It supports nested and complex decorators, allowing for advanced routing and documentation setups.

Generating Function Names

Function names are generated based on the HTTP method, controller path, and method path. This ensures unique and descriptive function names for your Serverless functions.

Example Generated Function

Given the ExampleController above, the following function might be generated:

functions:
  get-example:
    handler: src/controllers/examplecontroller.getExample
    memorySize: 128
    environment:
      STAGE: dev
    events:
      - http:
          path: example
          method: get
          cors: true
          documentation:
            summary: "Get example"
            description: "Retrieve an example item"
            methodResponses:
              - statusCode: 200
                responseBody:
                  description: "Successful response"

  create-example:
    handler: src/controllers/examplecontroller.createExample
    memorySize: 128
    environment:
      STAGE: dev
    events:
      - http:
          path: example
          method: post
          cors: true
          documentation:
            summary: "Create example"
            description: "Create a new example item"
            methodResponses:
              - statusCode: 201
                responseBody:
                  description: "Item created"
          request:
            schemas:
              "application/json": 
                $ref: "#/definitions/CreateExample"

Additional Configuration

Environment Variables

You can pass environment variables to your functions using the environment configuration:

custom:
  tsedPlugin:
    environment:
      MY_VAR: my-value

Memory Size

Set the memory size for your functions:

custom:
  tsedPlugin:
    memorySize: 256

CORS

Enable CORS for your functions:

custom:
  tsedPlugin:
    events:
      http:
        cors: true

Authorizer

Configure an authorizer for your functions:

custom:
  tsedPlugin:
    authorizer:
      functionName: myAuthorizerFunction
      HeaderName: Authorization

Example

You can see an example at the following URL: https://github.com/mecanizou-eco/serverless-tsed-plugin/tree/master/example.

Additionally, ensure to rename the env-model.yml file to env.yml