npm package: @mecanizou/serverless-tsed-plugin
Description: This plugin integrates [Ts.ED](https://tsed.io/) with the Serverless Framework, allowing you to automatically generate Serverless functions from your Ts.ED controllers.
Author: mecanizou
Latest version: 0.2.7
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# TsEDPlugin for Serverless Framework

This plugin integrates [Ts.ED](https://tsed.io/) with the Serverless Framework, allowing you to automatically generate Serverless functions from your Ts.ED controllers.

## Installation

First, ensure you have [Node.js](https://nodejs.org/) installed. Then, you can install the plugin via npm:

```sh
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