AWS Lambda Integration with HeliosJS

This document provides a detailed overview and example of integrating HeliosJS with AWS Lambda using the LambdaAdapter. The example demonstrates how to use a controller, plugin, and adapter to expose a Lambda handler suitable for AWS Lambda environments.

---

Example: Lambda Integration

import { Helios } from "@heliosjs/aws";
import { Any, Controller, Req } from "@heliosjs/core";

@Controller({ prefix: "metric" })
export class MetricsController {
  @Any()
  async any(@Req() req: any) {}
}

const adapter = new Helios(MetricsController);
export const handler = adapter.handler;

---

Overview

This example shows how to create a Lambda handler using HeliosJS's AWS Lambda integration utilities.

• Helios (the Lambda adapter): This class adapts HeliosJS controllers and plugins to AWS Lambda's event-driven model. It exposes a handler function compatible with AWS Lambda.

• MetricsController: A simple controller with a prefix metric and an Any route handler method. The Any decorator allows this route to handle any HTTP method.

• Instantiates the Helios adapter with the MetricsController.

• Exposes the Lambda-compatible handler function from the adapter.

Adapter Options (RBAC & Fingerprint)

The adapter constructor accepts an optional second argument to configure cross-cutting request features. The options are backward-compatible — existing new Helios(controller) calls are unaffected.

import { Helios } from "@heliosjs/aws";

const adapter = new Helios(RootController, {
  // Role-based access control extractor (see the @Roles decorator).
  rbac: {
    getRoles: (req) => req.getState("user")?.roles ?? [],
  },
  // Request fingerprinting (see the @Fingerprint / @UseFingerprint decorators).
  fingerprint: {
    secret: process.env.FP_SECRET,
    components: ["ip", "userAgent"],
  },
});

export const handler = adapter.handler;

Option	Type	Description
rbac	{ getRoles: (req) => string | string[] | undefined | Promise<...> }	Roles extractor consumed by the @Roles decorator.
fingerprint	{ secret?: string; components?: FingerprintComponent[]; compute?: (req) => string }	Fingerprinting config consumed by @Fingerprint / @UseFingerprint.

These mirror the HTTP @Server({ rbac, fingerprint }) options, so the same @Roles and @Fingerprint decorators work identically across HTTP servers and Lambda handlers.

Usage Notes

• The exported handler can be used directly as the AWS Lambda function handler.
• The adapter handles the translation between AWS Lambda events and HeliosJS's controller/plugin architecture.
• Plugins allow extending the server lifecycle and adding middleware-like hooks.
• Controllers define routes and handlers similarly to traditional HTTP servers but adapted for Lambda.

---

This setup provides a clean and modular way to build AWS Lambda functions using HeliosJS, leveraging its controller and plugin system for maintainable and scalable serverless applications.