I worked as a full stack dev for a couple of years before I ever had to touch any cloud stuff. Then I moved to a startup with some pretty strict cloud requirements. So I got some AWS certs and shortly became the cloud expert at the company.

Until then, I'd only ever used AWS Lambda functions for small scheduled tasks like triggering emails, reading files from S3 etc. But in this new role I had the opportunity to build a complex step functions system for handling events and sending notifications through various channels to users. They still use this system today as far as I know.

I then briefly moved to a company that used Lambdas for absolutely everything. The company did aviation operations and every single piece of code was run in a Lambda function. I mean, I like lambda functions but jeez that's a bit much.

While working with Lambdas in complex systems I realized that it's a pain to handle building them in big projects with multiple dependencies, common middleware, parsing HTTP properties for HTTP APIs and so much more. The aviation company I worked for had a 1,000+ line single function wrapper for every one of their lambdas. This function was messy and there was no chance we were ever going to write any unit tests for it.

After my short stint in the aviation field I moved elsewhere with less involvement with serverless functions. But my lambda experience always made me feel like more could be done to make that experience better.

Hello Nest JS


In comes NestJS - an opinionated framework for REST APIs in NodeJS. I used this framework for a small project I worked on and instantly loved it. It had all the things I wanted for setting up robust APIs. I wondered how hard it would be to apply the same concepts to the lambda world.

The Vision

The vision I had for this project, is to create lambda functions that look like this:

@Lambda()
class GetDataHandler {
  constructor(@Inject(MyService) private myService: MyService) {}

  async main(@Param('id') id: string) {
    return this.myService.getData(id)
  }
}


So how do we do this?

We needed:

  • Service/dependency injection
  • HTTP schema validation
  • Common HTTP request parsing functions (e.g. get query parameters, get headers etc.)
  • Middleware for common functionality between functions

The Forge

The first thing we need to do is create the wrapper: the thing that will actually wrap every function. This will handle the whole lifecycle from start to end. It looks something like this: 

export class LambdaForge {
  private container: DependencyContainer
  private services: (new (...args: any[]) => any)[]
  middlewares: (new (...args: any[]) => ForgeMiddleware)[]

  constructor({ services, middlewares = [] }: ForgeOptions) {
    this.container = container
    this.services = services
    this.middlewares = middlewares
  }

  handleBodyInjection(bodyParameter: BodyParam, req: Request) {
    // Validate the request body
  }

  validateReturn(result: any, returnType: any, returnsMany: boolean) {
    // Validate the return type
  }

  async executeMiddlewares(req: Request, res: Response, middlewares: (new (...args: any[]) => ForgeMiddleware)[]) {
    for (const Middleware of middlewares) {
      const middlewareInstance = await this.container.resolve(Middleware)
      // use the middleware
    }
  }

  createHttpHandler(HandlerClass: new (...args: any[]) => LambdaHandler) {
    return async (event: APIGatewayProxyEvent, context: Context): Promise<APIGatewayProxyResult | void> => {
      const handlerInstance = await container.resolve(HandlerClass)
      try {
        const request = new Request(event)
        const response = new Response()

        const method = handlerInstance.main
        const paramsMeta = Reflect.getMetadata('params', handlerInstance, 'main') || []
        const paramsPipesMeta = Reflect.getMetadata('paramPipes', handlerInstance, 'main') || []
        const bodyMeta = Reflect.getMetadata('body', handlerInstance, 'main')
        const queryMeta = Reflect.getMetadata('query', handlerInstance, 'main')
        const eventMeta = Reflect.getMetadata('event', handlerInstance, 'main')
        const returnType = Reflect.getMetadata('returns', handlerInstance, 'main')
        const returnStatusCode = Reflect.getMetadata('statusCode', handlerInstance, 'main')
        const returnsMany = Reflect.getMetadata('returnsMany', handlerInstance, 'main')
        const requestMeta = Reflect.getMetadata('request', handlerInstance, 'main')
        const responseMeta = Reflect.getMetadata('response', handlerInstance, 'main')
        const middlewares = Reflect.getMetadata('middlewares', handlerInstance, 'main') || []
        const args: any[] = []

        // Inject body parameter
        if (bodyMeta) {
          args[bodyMeta.index] = this.handleBodyInjection(bodyMeta, request)
        }

        // Inject query parameters
        if (queryMeta) {
          args[queryMeta.index] = request.query || {}
        }

        // Extract path parameters and run through pipe functions if any
        if (paramsMeta.length > 0) {
          paramsMeta.forEach((param: { index: number; name: string }) => {
            const pipes = paramsPipesMeta.filter((pipe: { index: number }) => pipe.index === param.index)
            let value = request.params[param.name]
            if (pipes.length > 0) {
              pipes.forEach((pipe: { transform: (p: any) => any }) => {
                value = pipe.transform(value)
              })
            }
            args[param.index] = value
          })
        }

        // Inject raw event object
        if (eventMeta) {
          args[eventMeta.index] = event
        }

        await this.executeMiddlewares(request, response, [...this.middlewares, ...middlewares])

        // Inject request object after middleware
        if (requestMeta) {
          args[requestMeta.index] = request
        }

        // Inject response object after middleware
        if (responseMeta) {
          args[responseMeta.index] = response
        }

        const result = await method.apply(handlerInstance, args)
        if (returnType === undefined) {
          response.statusCode = 200
          response.body = this.formatResponseBody(result)
          return response.send()
        }
        this.validateReturn(result, returnType, returnsMany)
        response.statusCode = returnStatusCode
        response.body = this.formatResponseBody(result)
        return response.send()
      } catch (error) {
        if (error instanceof GenericError) {
          return error.toResponse()
        } else {
          console.log(error)
          throw new InternalServerError('Internal server error')
        }
      }
    }
  }
}

View the full code here.

This factory is the core wrapper around each lambda. It uses Reflect.getMetadata to get the parameter decorators of the function and its arguments. It then uses that information to run the wrapper functions like validating the request body based on the @Body decorator, or gett path params using the @Param decorator.

One thing to notice, is that we're actually taking the lambda event, and creating a Request object from it. This request object is actually a child class of the Express JS Request object! That means it should be relatively familiar to JS backend devs, and makes it easy to access core request using @Request to get request information if needed. I also created an @Event decorator in case you need access to the AWS APIGateway event directly.

The Decorators

A typical decorator looks something like this:

/**
 * Decorator to inject the body of the request into the handler method
 * @param dto The DTO class to validate the body against
 * @returns The decorated class
 */
export function Body(dto?: new (...args: any[]) => any) {
  return function (target: any, propertyKey: string, parameterIndex: number) {
    Reflect.defineMetadata('body', { index: parameterIndex, bodyType: dto }, target, propertyKey)
  }
}

As you can see it's very simple. The decorator actually has no functionality at all. It just 'tags' the function so that the factory function knows what to do.


Services and Dependency Injection

Now we need to add our functionality for dependency injection. Dependency injection makes it much easier to test our code. Since it's just a parameter to the function, we can easily mock it out and test the lambda as a pure function. Here's our @Service decorator:

import { injectable, singleton as Singleton } from '@launchtray/tsyringe-async'

export function Service({ singleton = false }: { singleton?: boolean } = {}) {
  return function (target: any) {
    return singleton ? Singleton()(target) : injectable()(target)
  }
}

Once again, extremely simple. We only have one property that will change anything - the singleton param which just tells our dependency container if it should treat it as a singleton.
Now in our factory when we use the tsyringe container, it'll automatically inject the service into the function, like magic.



Middlware

Lastly we have to implement some kind of middlware, essential functionality for any API. To do this, we create a simple Middleware interface and decorator. Then we handle it in our factory like this:

  async executeMiddlewares(req: Request, res: Response, middlewares: (new (...args: any[]) => ForgeMiddleware)[]) {
    for (const Middleware of middlewares) {
      // make sure we can also inject any dependencies into our middleware
      const middlewareInstance = await this.container.resolve(Middleware)
      await new Promise<void>((resolve, reject) => {
        middlewareInstance.use(req, res, (error: any) => {
          if (error) {
            reject(error)
          } else {
            resolve()
          }
        })
      })
    }
  }


Now we can use this to run any function before the request reaches our lambda. Here's how it's used:

@Middleware
export class AuthMiddleware implements ForgeMiddleware {
  constructor(@Inject(AuthService) private authService) {}

  async use(req: Request, res: Response, next: (error?: any) => void) {
    // Validate authentication
    const user = await this.authService.getUser(req.headers['Authorization']);
    if (!user) {
      throw new UnauthorizedError('Unauthorized')
    }
    next()
  }
}



Last Few Things

After a bit of testing, it was clear there were a couple of issues that can pop up when using this library in reality. One thing I noticed is that if you had one service like DatabaseService and one like UsersService which depends on the DatabaseService you would need to make sure the db service is connected before using the users service.
To do this I implemented the @OnExecutionStart decorator, which calls a function before the lambda handler starts up, along with the singleton option that can be passed to the service decorator. This ensures the correct order of operations, and prevents some functionality from having to be done multiple times.
In practice it looks like this:

@Service({ singleton: true })
class DatabaseService {
  private connection: any;

  @OnExecutionStart()
  async initialize() {
    // This will run once when the service is first used
    this.connection = await createDatabaseConnection();
    console.log('Database connection initialized');
  }

  async query(sql: string) {
    return this.connection.query(sql);
  }
}

@Service()
class UserService {
  constructor(
    @Inject(DatabaseService) private db: DatabaseService,
    @Inject(AuthService) private auth: AuthService
  ) {}
}

This is an obviously very common use-case in backend applications which we can now do successfully.



What's left to do?

While it's usable in it's current state, there's still more that can be improved on:

  1. Testing utilities to make it easy to test lambda functions with mocked classes.

  2. Handling circular dependencies - determine how circular dependencies should be handled (usually this can be solved by just de-coupling code a bit more so maybe not necessarily a bad thing, but will surely come up)

  3. More rigorous testing for production readiness - I've only tested this library with smaller projects. It'd be great to see it be used in more complex projects to see how it holds up. Maybe I'll be using it for a larger project down the line.



If anyone's still reading this (I'd be surprised) feel free to try it out and let me know how it goes via github or in a comment on this post.