@alt-javascript/boot-lambda

AWS Lambda adapter for the @alt-javascript framework. Handles API Gateway HTTP API v2 events with CDI-managed controllers and a CDI middleware pipeline for cross-cutting concerns.

CDI boots once on cold start and is reused on warm invocations — the same pattern as Spring's ApplicationContext in a serverless launcher.

Part of the @alt-javascript monorepo.

Install

npm install @alt-javascript/boot-lambda

Usage

// handler.js (your Lambda entry point)
import { Boot } from '@alt-javascript/boot';
import { Context, Singleton } from '@alt-javascript/cdi';
import { lambdaStarter } from '@alt-javascript/boot-lambda';
import { TodoService } from './services.js';
import { TodoController } from './controllers.js';

const context = new Context([
  ...lambdaStarter(),
  new Singleton(TodoService),
  new Singleton(TodoController),
]);

// Boot once — CDI is wired on cold start; run: false skips any HTTP server lifecycle
const appCtxPromise = Boot.boot({ contexts: [context], run: false });

export async function handler(event, lambdaContext) {
  const appCtx = await appCtxPromise;
  return appCtx.get('lambdaAdapter').handle(event, lambdaContext);
}

Controller Convention

Controllers use the same __routes metadata as all other adapters. Path parameters use API Gateway {param} syntax (Express-style :param is auto-converted):

class TodoController {
  static __routes = [
    { method: 'GET',    path: '/todos',      handler: 'list'   },
    { method: 'POST',   path: '/todos',      handler: 'create' },
    { method: 'GET',    path: '/todos/{id}', handler: 'get'    },
    { method: 'DELETE', path: '/todos/{id}', handler: 'remove' },
  ];

  constructor() { this.todoService = null; } // autowired

  async list(request)   { return this.todoService.findAll(); }
  async create(request) { return this.todoService.create(request.body); }
  async get(request)    { return this.todoService.findById(request.params.id); }
  async remove(request) { return this.todoService.delete(request.params.id); }
}

Handlers return a plain object (200 JSON), { statusCode, body } (explicit status), or null / undefined (204 No Content).

Middleware Pipeline

lambdaStarter() registers three built-in middleware components:

| Component | Order | Behaviour | |---|---|---| | RequestLoggerMiddleware | 10 | Logs [METHOD] /path → status (Xms) | | ErrorHandlerMiddleware | 20 | Converts thrown errors to JSON error responses | | NotFoundMiddleware | 30 | Returns 404 for unmatched routes |

Add custom middleware by declaring static __middleware = { order: N }:

class AuthMiddleware {
  static __middleware = { order: 5 };

  async handle(request, next) {
    const token = request.headers.authorization?.replace('Bearer ', '');
    if (!token) return { statusCode: 401, body: { error: 'Unauthorized' } };
    return next({ ...request, user: { token } });
  }
}

const context = new Context([
  ...lambdaStarter(),
  new Singleton(AuthMiddleware), // auto-detected — no extra wiring
  new Singleton(TodoController),
]);

Configuration

Config comes from process.env via EnvPropertySource. Use AWS SSM Parameter Store or Secrets Manager to inject environment variables at deploy time.

| Key | Default | Description | |---|---|---| | middleware.requestLogger.enabled | true | Enable request logging | | middleware.errorHandler.enabled | true | Enable error handler | | middleware.notFound.enabled | true | Enable 404 handler |

Testing

Test the handler directly with API Gateway v2 event shapes — no AWS account needed:

import { handler } from '../handler.js';

const event = {
  routeKey: 'GET /todos',
  pathParameters: {},
  queryStringParameters: {},
  headers: { authorization: 'Bearer mytoken' },
  body: null,
  isBase64Encoded: false,
};

const res = await handler(event, {});
assert.equal(res.statusCode, 200);

Spring Attribution

The cold-start / warm-reuse pattern maps to a Spring ApplicationContext held in a static field inside a serverless launcher — a common pattern for running Spring Boot in AWS Lambda.

License

MIT