@leanstacks/lambda-utils 0.1.0-alpha.2 → 0.1.0-alpha.4

package/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,47 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+---
+
+## Describe the bug
+
+_Provide a clear and concise description of what the bug is._
+
+## Steps to reproduce
+
+Steps to reproduce the behavior:
+
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+## Expected behavior
+
+_Provide a clear and concise description of what you expected to happen._
+
+## Screenshots
+
+_If applicable, add screenshots to help explain your problem._
+
+## Environment
+
+**Desktop (please complete the following information):**
+
+- OS: [e.g. iOS]
+- Browser [e.g. chrome, safari]
+- Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+
+- Device: [e.g. iPhone6]
+- OS: [e.g. iOS8.1]
+- Browser [e.g. stock browser, safari]
+- Version [e.g. 22]
+
+## Additional context
+
+_Add any other context about the problem here._

package/.github/ISSUE_TEMPLATE/story.md

@@ -0,0 +1,25 @@
+---
+name: Story
+about: New feature or improvement request
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+## Describe the story
+
+_Provide a clear description of the new feature or improvement to existing functionality._
+
+## Acceptance criteria
+
+_Provide clear acceptance criteria to validate the story is complete._
+
+[Gherkin syntax](https://cucumber.io/docs/gherkin/reference) example:
+
+> Given the 'PERSONA' has 'DONE SOMETHING'  
+> When the 'PERSONA' does 'ONE THING'  
+> Then the 'PERSONA' must do 'ANOTHER THING'
+
+## Additional context
+
+_Add any other context about the story here._

package/.github/ISSUE_TEMPLATE/task.md

@@ -0,0 +1,15 @@
+---
+name: Task
+about: A chore unrelated to features or problems
+title: ''
+labels: task
+assignees: ''
+---
+
+## Describe the task
+
+_Provide a clear description of the task._
+
+## Additional context
+
+_Add any other context about the task here._

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,39 @@
+:loudspeaker: **Instructions**
+
+- Begin with a **DRAFT** pull request.
+- Follow _italicized instructions_ to add detail to assist the reviewers.
+- After completing all checklist items, change the pull request to **READY**.
+
+---
+
+### :wrench: Change Summary
+
+_Describe the changes included in this pull request. Link to the associated [GitHub](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) or Jira issue(s)._
+
+- see #1234
+- Added the [...]
+- Updated the [...]
+- Fixed the [...]
+
+### :memo: Checklist
+
+_Pull request authors must complete the following tasks before marking the PR as ready to review._
+
+- [ ] Complete a self-review of changes
+- [ ] Unit tests have been created or updated
+- [ ] The code is free of [new] lint errors and warnings
+- [ ] Update project documentation as needed: README, /docs, JSDoc, etc.
+
+### :test_tube: Steps to Test
+
+_Describe the process to test the changes in this pull request._
+
+1. Go to [...]
+2. Click on [...]
+3. Verify that [...]
+
+### :link: Additional Information
+
+_Optionally, provide additional details, screenshots, or URLs that may assist the reviewer._
+
+- [...]

package/README.md

@@ -1,3 +1,180 @@
 # Lambda Utilities
 
-Lambda utilities
+[![npm version](https://badge.fury.io/js/@leanstacks%2Flambda-utils.svg)](https://badge.fury.io/js/@leanstacks%2Flambda-utils)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+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](#installation)
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
+- [Support](#support)
+
+## Installation
+
+```bash
+npm install @leanstacks/lambda-utils
+```
+
+### Requirements
+
+- Node.js 24.x or higher
+- TypeScript 5.0 or higher
+
+## Quick Start
+
+### Logging Example
+
+```typescript
+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
+
+```typescript
+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:
+
+| Guide                                                        | Description                                                            |
+| ------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| **[Logging Guide](./docs/LOGGING.md)**                       | Configure and use structured logging with automatic AWS Lambda context |
+| **[API Gateway Responses](./docs/API_GATEWAY_RESPONSES.md)** | Format responses for API Gateway with standard HTTP patterns           |
+| **[Configuration](./docs/CONFIGURATION.md)**                 | Validate and manage environment variables with type safety             |
+| **[AWS Clients](./docs/CLIENTS.md)**                         | Use pre-configured AWS SDK v3 clients in your handlers                 |
+| **[Getting Started](./docs/GETTING_STARTED.md)**             | Setup and first steps guide                                            |
+
+## Usage
+
+### Logging
+
+The Logger utility provides structured logging configured specifically for AWS Lambda:
+
+```typescript
+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](./docs/LOGGING.md) for detailed configuration and best practices**
+
+### API Responses
+
+Generate properly formatted responses for API Gateway:
+
+```typescript
+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](./docs/API_GATEWAY_RESPONSES.md) for all response types**
+
+### Configuration Validation
+
+Validate your Lambda environment configuration:
+
+```typescript
+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](./docs/CONFIGURATION.md) for validation patterns**
+
+### AWS Clients
+
+Use pre-configured AWS SDK v3 clients:
+
+```typescript
+import { getDynamoDBClient, getLambdaClient } from '@leanstacks/lambda-utils';
+
+const dynamoDB = getDynamoDBClient();
+const lambda = getLambdaClient();
+
+// Use clients for API calls
+```
+
+**→ See [AWS Clients](./docs/CLIENTS.md) 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](https://github.com/leanstacks/lambda-utils/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](./LICENSE) file for details.
+
+## Support
+
+- **Issues & Questions:** [GitHub Issues](https://github.com/leanstacks/lambda-utils/issues)
+- **Documentation:** [docs](./docs/README.md)
+- **NPM Package:** [@leanstacks/lambda-utils](https://www.npmjs.com/package/@leanstacks/lambda-utils)
+
+## Changelog
+
+See the project [releases](https://github.com/leanstacks/lambda-utils/releases) for version history and updates.

package/docs/LOGGING.md

@@ -0,0 +1,333 @@
+# Logging Guide
+
+This guide explains how to use the Logger utility to implement structured logging in your AWS Lambda functions using TypeScript.
+
+## Overview
+
+The Logger utility provides a thin wrapper around [Pino](https://getpino.io/) configured specifically for AWS Lambda. It automatically includes Lambda request context information in your logs and supports multiple output formats suitable for CloudWatch.
+
+## Installation
+
+The Logger utility is included in the `@leanstacks/lambda-utils` package:
+
+```bash
+npm install @leanstacks/lambda-utils
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { Logger } from '@leanstacks/lambda-utils';
+
+const logger = new Logger().instance;
+
+export const handler = async (event: any, context: any) => {
+  logger.info('[Handler] > Processing request');
+
+  // Your handler logic here
+
+  logger.info({ key: 'value' }, '[Handler] < Completed request');
+
+  return { statusCode: 200, body: 'Success' };
+};
+```
+
+## Configuration
+
+The Logger accepts a configuration object to customize its behavior:
+
+```typescript
+import { Logger } from '@leanstacks/lambda-utils';
+
+const logger = new Logger({
+  enabled: true, // Enable/disable logging (default: true)
+  level: 'info', // Minimum log level (default: 'info')
+  format: 'json', // Output format: 'json' or 'text' (default: 'json')
+}).instance;
+```
+
+### Configuration Options
+
+| Option    | Type                                     | Default  | Description                                                                                              |
+| --------- | ---------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
+| `enabled` | `boolean`                                | `true`   | Whether logging is enabled. Set to `false` to disable all logging output.                                |
+| `level`   | `'debug' \| 'info' \| 'warn' \| 'error'` | `'info'` | Minimum log level to output. Messages below this level are filtered out.                                 |
+| `format`  | `'json' \| 'text'`                       | `'json'` | Output format for log messages. Use `'json'` for structured logging or `'text'` for human-readable logs. |
+
+### Log Levels
+
+Log levels are ordered by severity:
+
+- **`debug`**: Detailed information for diagnosing problems (lowest severity)
+- **`info`**: General informational messages about application flow
+- **`warn`**: Warning messages for potentially harmful situations
+- **`error`**: Error messages for serious problems (highest severity)
+
+## Logging Examples
+
+### Basic Logging
+
+```typescript
+const logger = new Logger().instance;
+
+logger.debug('Detailed diagnostic information');
+logger.info('Application event or milestone');
+logger.warn('Warning: something unexpected occurred');
+logger.error('Error: operation failed');
+```
+
+When the log message contains a simple string, pass the string as the only aregument to the logger function.
+
+### Structured Logging with Objects
+
+```typescript
+const logger = new Logger().instance;
+
+const userId = '12345';
+const permissions = ['user:read', 'user:write'];
+
+logger.info(
+  {
+    userId,
+    permissions,
+  },
+  'User authenticated',
+);
+```
+
+When using structured logging, pass the context attributes object as the first parameter and the string log message as the second parameter. This allows the logger to properly format messages as either JSON or text.
+
+### Error Logging
+
+```typescript
+const logger = new Logger().instance;
+
+try {
+  // Your code here
+} catch (error) {
+  logger.error(
+    {
+      error: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined,
+    },
+    'Operation failed',
+  );
+}
+```
+
+## Advanced Usage
+
+### Request Tracking Middleware
+
+The `withRequestTracking` middleware automatically adds AWS Lambda context information to all log messages. This enriches your logs with request IDs, function names, and other Lambda metadata.
+
+```typescript
+import { Logger, withRequestTracking } from '@leanstacks/lambda-utils';
+
+const logger = new Logger().instance;
+
+export const handler = async (event: any, context: any) => {
+  // Add Lambda context to all subsequent log messages
+  withRequestTracking(event, context);
+
+  logger.info('Request started');
+
+  // Your handler logic here
+
+  return { statusCode: 200 };
+};
+```
+
+### Environment-Based Configuration
+
+Configure logging based on your environment:
+
+```typescript
+import { Logger } from '@leanstacks/lambda-utils';
+
+const isProduction = process.env.NODE_ENV === 'production';
+const isDevelopment = process.env.NODE_ENV === 'development';
+
+const logger = new Logger({
+  level: isDevelopment ? 'debug' : 'info',
+  format: isProduction ? 'json' : 'text',
+}).instance;
+```
+
+### Singleton Pattern for Reusable Logger
+
+For best performance, create a single logger instance and reuse it throughout your application:
+
+```typescript
+// logger.ts
+import { Logger } from '@leanstacks/lambda-utils';
+
+export const logger = new Logger({
+  level: (process.env.LOG_LEVEL as 'debug' | 'info' | 'warn' | 'error') || 'info',
+  format: (process.env.LOG_FORMAT as 'json' | 'text') || 'json',
+}).instance;
+```
+
+Then import it in your handlers:
+
+```typescript
+// handler.ts
+import { logger } from './logger';
+
+export const handler = async (event: any) => {
+  logger.info({ message: 'Processing event', event });
+
+  // Your handler logic here
+
+  return { statusCode: 200 };
+};
+```
+
+## Best Practices
+
+### 1. Use Structured Logging
+
+Prefer objects over string concatenation:
+
+```typescript
+// ✅ Good: Structured logging
+logger.info(
+  {
+    userId: user.id,
+  },
+  'User login',
+);
+
+// ❌ Avoid: String concatenation
+logger.info(`User ${user.id} logged in at ${new Date().toISOString()}`);
+```
+
+### 2. Include Relevant Context
+
+Include all relevant information that will help with debugging and monitoring:
+
+```typescript
+logger.info(
+  {
+    orderId: order.id,
+    amount: order.total,
+    paymentMethod: order.paymentMethod,
+    duration: endTime - startTime,
+  },
+  'Payment processed',
+);
+```
+
+### 3. Use Appropriate Log Levels
+
+Choose log levels that match the severity and importance of the event:
+
+```typescript
+logger.debug('Cache hit for user profile'); // Development diagnostics
+logger.info('User registered successfully'); // Normal operations
+logger.warn('API rate limit approaching'); // Potential issues
+logger.error('Database connection failed'); // Critical failures
+```
+
+### 4. Avoid Logging Sensitive Information
+
+Never log passwords, API keys, tokens, or personally identifiable information (PII):
+
+```typescript
+// ❌ Never do this
+logger.info({ password: user.password });
+
+// ✅ Log safe information
+logger.info({ userId: user.id, email: user.email });
+```
+
+### 5. Performance Considerations
+
+The logger is optimized for Lambda and uses lazy evaluation. Only use `debug` level logs in development:
+
+```typescript
+// Disable debug logs in production for better performance
+const logger = new Logger({
+  level: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
+}).instance;
+```
+
+## Output Formats
+
+### JSON Format (Default)
+
+Best for production environments and log aggregation services like CloudWatch, Datadog, or Splunk:
+
+```json
+{
+  "timestamp": "2025-12-18T13:42:40.502Z",
+  "level": "INFO",
+  "requestId": "req-abc-123",
+  "message": {
+    "awsRequestId": "req-def-456",
+    "x-correlation-trace-id": "Root=1-2a-28ab;Parent=1e6;Sampled=0;Lineage=1:bf3:0",
+    "x-correlation-id": "crl-abc-123",
+    "time": 1702900123456,
+    "pid": 1,
+    "hostname": "lambda-container",
+    "key": "value",
+    "msg": "User authenticated"
+  }
+}
+```
+
+### Text Format
+
+Best for local development and human-readable output:
+
+```
+[2024-12-18T12:34:56.789Z] INFO: User authenticated userId=12345 requestId=req-abc-123
+```
+
+## Testing
+
+When testing Lambda functions that use the logger, you can mock or configure the logger:
+
+```typescript
+import { Logger } from '@leanstacks/lambda-utils';
+
+describe('MyHandler', () => {
+  it('should log info message', () => {
+    const logger = new Logger({
+      enabled: true,
+      level: 'info',
+    }).instance;
+
+    const spyLog = jest.spyOn(logger, 'info');
+
+    // Your test code here
+
+    expect(spyLog).toHaveBeenCalledWith({
+      message: 'Expected message',
+    });
+  });
+});
+```
+
+## Troubleshooting
+
+### Logs Not Appearing
+
+1. **Check if logging is enabled**: Verify `enabled: true` in configuration
+2. **Check log level**: Ensure the message log level meets the configured minimum level. Check the Lambda function [Logging configuration application log level](https://docs.aws.amazon.com/lambda/latest/dg/monitoring-cloudwatchlogs-log-level.html).
+3. **Check CloudWatch**: Logs appear in CloudWatch Logs under `/aws/lambda/[function-name]`
+
+### Performance Issues
+
+1. **Use appropriate log level**: Reduce logs in production by using `level: 'info'`
+2. **Limit object size**: Avoid logging very large objects that could impact performance
+3. **Use singleton pattern**: Create one logger instance and reuse it
+
+## Further reading
+
+- [Pino Documentation](https://getpino.io/)
+- [AWS Lambda Environment and Context](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-handler.html)
+- [CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)
+- [Back to the project documentation](README.md)