Registry / aws / serverless-compose

serverless-compose

JSON →
library2.4.0jsnpmunverified

serverless-compose is a lightweight, functional middleware framework specifically designed for AWS Lambda functions, enabling the creation of composable, "onion-style" middleware stacks. Currently at version 2.4.0, its release cadence is not explicitly stated in the provided documentation, but it appears actively maintained. A key differentiator is its zero-dependency philosophy, ensuring a minimal bundle size and avoiding dependency conflicts. Unlike more opinionated frameworks, serverless-compose focuses on providing a thin `compose` function and flexible patterns like `recoveryMiddleware` and `timingLogMiddleware` without enforcing specific architectural designs, allowing developers to define their middleware stack with explicit, functional wrappers around their Lambda handlers. It aims to prevent the "fossilization" of bad middleware habits by promoting a clear, functional approach for event processing.

awsweb-framework
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

The library primarily uses ES Modules (ESM). Using `require` will result in a runtime error in ESM-only environments.

import { compose } from 'serverless-compose'

Prefer named ESM imports. Direct CommonJS `require` might fail if your Lambda environment is configured for ESM or if transpilation doesn't handle it correctly.

import { recoveryMiddleware } from 'serverless-compose'

All core utilities are named exports from the main package entry point, not default exports or sub-path imports.

import { timingLogMiddleware } from 'serverless-compose'

Demonstrates basic setup with `compose`, `timingLogMiddleware` for logging duration, and `recoveryMiddleware` for graceful error handling in an AWS Lambda handler.

import { compose, recoveryMiddleware, timingLogMiddleware } from 'serverless-compose'; // Suppose this is a client that fetches the weather from some external API class WeatherClient { static async askBadAPIForWeather() { // Simulate a failing API call 50% of the time if (Math.random() > 0.5) { throw new Error('Weather API is down!'); } return { temperature: 25, unit: 'C' }; } } // Your actual handler code async function getWeather(request, context) { const response = await WeatherClient.askBadAPIForWeather(); return { statusCode: 200, body: JSON.stringify(response), }; } // Your own custom logging function async function logDuration(duration) { console.log(`It took: ${duration}ms to return the weather`); } // Your own custom error handler async function sendError(error) { console.error('Handler Error:', error); return { statusCode: 500, body: JSON.stringify({ error: `${error.message}`, message: 'The darn weather API failed me again!', }), }; } const TimingMiddleware = timingLogMiddleware(logDuration); const RecoveryMiddleware = recoveryMiddleware(sendError); const MyMiddlewareStack = compose( TimingMiddleware, RecoveryMiddleware, ); export const lambdaHandler = MyMiddlewareStack(getWeather);
Debug
Known footguns
gotchaMiddleware order is crucial in `serverless-compose`'s onion-style architecture. Middleware functions are applied from right to left (outermost to innermost) in the `compose` function, but execute in an 'onion' fashion (outer wraps inner). Misordering can lead to unexpected behavior or missed error handling.
gotchaWhen migrating older CommonJS (CJS) Lambda functions or integrating CJS dependencies, you might encounter issues with `serverless-compose` as it primarily uses ES Modules (ESM). AWS Lambda environments need proper configuration (`"type": "module"` in `package.json` or `.mjs` file extensions) to handle ESM correctly.
gotchaUnhandled promise rejections or uncaught exceptions within your Lambda handler or custom middleware can lead to generic `502 Internal Server Error` responses from API Gateway without informative bodies. `recoveryMiddleware` is designed to mitigate this, but must be configured correctly.
gotchaWhile the library itself is functional, complex Serverless Framework deployments using shared source directories or monorepos can suffer from path resolution and bundling issues, especially when coupled with plugins like `serverless-esbuild` or `serverless-plugin-typescript`.
Upgrade
Version history

Breaking-change detection hasn't run for this library yet.

Audit
Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity
0 hits · last 30 days

No traffic data recorded yet.

Resources