Lambda Utilities

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.

Table of Contents

• Installation
• Quick Start
• Features
• Documentation
• Contributing
• License
• Support

Installation

npm install @leanstacks/lambda-utils

Requirements

• Node.js 24.x or higher
• TypeScript 5.0 or higher

Quick Start

Logging Example

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' };
};

API Response Example

import { success, badRequest } from '@leanstacks/lambda-utils';

export const handler = async (event: any) => {
  if (!event.body) {
    return badRequest({ message: 'Body is required' });
  }

  // Process request

  return success({ message: 'Request processed successfully' });
};

Features

• 📝 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 for DynamoDB, Lambda, and more
• 🔒 Full TypeScript Support – Complete type definitions and IDE autocomplete
• ⚡ Lambda Optimized – Designed for performance in serverless environments

Documentation

Comprehensive guides and examples are available in the docs directory:

Usage

Logging

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

API Responses

Generate properly formatted responses for API Gateway:

import { success, error, created, badRequest } from '@leanstacks/lambda-utils';

export const handler = async (event: any) => {
  return success({
    data: { id: '123', name: 'Example' },
  });
};

→ See API Gateway Responses for all response types

Configuration Validation

Validate your Lambda environment configuration:

import { validateConfig } from '@leanstacks/lambda-utils';
import { z } from 'zod';

const configSchema = z.object({
  DATABASE_URL: z.string().url(),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']),
  API_KEY: z.string(),
});

const config = validateConfig(configSchema);

→ See Configuration for validation patterns

AWS Clients

Use pre-configured AWS SDK v3 clients:

import { getDynamoDBClient, getLambdaClient } from '@leanstacks/lambda-utils';

const dynamoDB = getDynamoDBClient();
const lambda = getLambdaClient();

// Use clients for API calls

→ See AWS Clients for available clients and examples

Examples

Example Lambda functions using Lambda Utilities are available in the repository:

• API Gateway with logging and response formatting
• Configuration validation and DynamoDB integration
• Error handling and structured logging

Reporting Issues

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.

License

This project is licensed under the MIT License - see LICENSE file for details.

Support

• Issues & Questions: GitHub Issues
• Documentation: docs
• NPM Package: @leanstacks/lambda-utils

Changelog

See the project releases for version history and updates.