A comprehensive TypeScript utility library for AWS Lambda functions. Provides pre-configured logging, API response formatting, configuration validation, and AWS SDK clients—reducing boilerplate and promoting best practices.
npm install @leanstacks/lambda-utils- Node.js 24.x or higher
- TypeScript 5.0 or higher
import { Logger, withRequestTracking } from '@leanstacks/lambda-utils';
const logger = new Logger().instance;
export const handler = async (event: any, context: any) => {
withRequestTracking(event, context);
logger.info('Processing request');
// Your Lambda handler logic here
return { statusCode: 200, body: 'Success' };
};import { z } from 'zod';
import { createConfigManager } from '@leanstacks/lambda-utils';
// Define your configuration schema
const configSchema = z.object({
TABLE_NAME: z.string().min(1),
AWS_REGION: z.string().default('us-east-1'),
LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
});
type Config = z.infer<typeof configSchema>;
const configManager = createConfigManager(configSchema);
const config = configManager.get();
export const handler = async (event: any) => {
console.log(`Using table: ${config.TABLE_NAME}`);
// Your Lambda handler logic here
return { statusCode: 200, body: 'Success' };
};import { ok, badRequest } from '@leanstacks/lambda-utils';
export const handler = async (event: APIGatewayProxyEvent) => {
if (!event.body) {
return badRequest('Body is required');
}
// Process request
return ok({ message: 'Request processed successfully' });
};- 📝 Structured Logging – Pino logger pre-configured for Lambda with automatic AWS request context enrichment
- 📤 API Response Helpers – Standard response formatting for API Gateway with proper HTTP status codes
- ⚙️ Configuration Validation – Environment variable validation with Zod schema support
- 🔌 AWS SDK Clients – Pre-configured AWS SDK v3 clients including DynamoDB, Lambda, SNS, and SQS with singleton patterns
- 🔒 Full TypeScript Support – Complete type definitions and IDE autocomplete
- ⚡ Lambda Optimized – Designed for performance in serverless environments
Comprehensive guides and examples are available in the docs directory:
| Guide | Description |
|---|---|
| Configuration Guide | Validate environment variables with Zod schemas and type safety |
| Logging Guide | Configure and use structured logging with automatic AWS Lambda context |
| API Gateway Responses | Format responses for API Gateway with standard HTTP patterns |
| DynamoDB Client | Use pre-configured DynamoDB clients with singleton pattern |
| Lambda Client | Invoke other Lambda functions synchronously or asynchronously |
| SNS Client | Publish messages to SNS topics with message attributes |
| SQS Client | Send messages to SQS queues with message attributes |
Validate and manage environment variables with type safety:
import { z } from 'zod';
import { createConfigManager } from '@leanstacks/lambda-utils';
const configManager = createConfigManager(
z.object({
TABLE_NAME: z.string().min(1),
AWS_REGION: z.string().default('us-east-1'),
}),
);
const config = configManager.get();
// TypeScript infers type from schema
// Validation errors thrown immediately→ See Configuration Guide for detailed validation patterns and best practices
The Logger utility provides structured logging configured specifically for AWS Lambda:
import { Logger } from '@leanstacks/lambda-utils';
const logger = new Logger({
level: 'info', // debug, info, warn, error
format: 'json', // json or text
}).instance;
logger.info({ message: 'User authenticated', userId: '12345' });
logger.error({ message: 'Operation failed', error: err.message });→ See Logging Guide for detailed configuration and best practices
Generate properly formatted responses for API Gateway:
import { ok, created, badRequest } from '@leanstacks/lambda-utils';
export const handler = async (event: APIGatewayProxyEvent) => {
return ok({
data: { id: '123', name: 'Example' },
});
};→ See API Gateway Responses for all response types
Use pre-configured AWS SDK v3 clients. Currently available:
Initialize the DynamoDB clients (base client and document client) once during handler initialization:
import { initializeDynamoDBClients, getDynamoDBDocumentClient } from '@leanstacks/lambda-utils';
export const handler = async (event: any, context: any) => {
// Initialize clients once
initializeDynamoDBClients({ region: 'us-east-1' });
// Use the document client for operations
const docClient = getDynamoDBDocumentClient();
const result = await docClient.get({
TableName: 'MyTable',
Key: { id: 'item-123' },
});
return { statusCode: 200, body: JSON.stringify(result) };
};→ See DynamoDB Client Guide for detailed configuration and examples
Invoke other Lambda functions synchronously or asynchronously:
import { invokeLambdaSync, invokeLambdaAsync } from '@leanstacks/lambda-utils';
export const handler = async (event: any) => {
// Synchronous invocation - wait for response
const response = await invokeLambdaSync('my-function-name', {
key: 'value',
data: { nested: true },
});
// Asynchronous invocation - fire and forget
await invokeLambdaAsync('my-async-function', {
eventType: 'process',
data: [1, 2, 3],
});
return { statusCode: 200, body: JSON.stringify(response) };
};→ See Lambda Client Guide for detailed configuration and examples
Publish messages to SNS topics with optional message attributes:
import { publishToTopic, SNSMessageAttributes } from '@leanstacks/lambda-utils';
export const handler = async (event: any) => {
const attributes: SNSMessageAttributes = {
priority: {
DataType: 'String',
StringValue: 'high',
},
};
const messageId = await publishToTopic(
'arn:aws:sns:us-east-1:123456789012:MyTopic',
{ orderId: '12345', status: 'completed' },
attributes,
);
return { statusCode: 200, body: JSON.stringify({ messageId }) };
};→ See SNS Client Guide for detailed configuration and examples
Send messages to SQS queues with optional message attributes:
import { sendToQueue, SQSMessageAttributes } from '@leanstacks/lambda-utils';
export const handler = async (event: any) => {
const attributes: SQSMessageAttributes = {
priority: {
DataType: 'String',
StringValue: 'high',
},
};
const messageId = await sendToQueue(
'https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue',
{ orderId: '12345', status: 'completed' },
attributes,
);
return { statusCode: 200, body: JSON.stringify({ messageId }) };
};→ See SQS Client Guide for detailed configuration and examples
To see an example Lambda microservice using the Lambda Utilities, see the LeanStacks lambda-starter 
GitHub repository.
- API Gateway with logging and response formatting
- Configuration validation and DynamoDB integration
- Error handling and structured logging
If you encounter a bug or have a feature request, please report it on GitHub Issues. Include as much detail as possible to help us investigate and resolve the issue quickly.
This project is licensed under the MIT License - see LICENSE file for details.
- Issues & Questions: GitHub Issues
- Documentation: docs
- NPM Package: @leanstacks/lambda-utils
See the project releases for version history and updates.