@leanstacks/lambda-utils 0.1.0-alpha.3 → 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)

package/docs/README.md

@@ -2,47 +2,26 @@
 
 Welcome to the Lambda Utilities documentation. This library provides a comprehensive set of utilities and helper functions to streamline the development of AWS Lambda functions using TypeScript.
 
-## Table of Contents
+## Overview
 
-- [Getting Started](./GETTING_STARTED.md)
-- [Logging](./LOGGING.md)
-- [API Gateway Responses](./API_GATEWAY_RESPONSES.md)
-- [Configuration](./CONFIGURATION.md)
-- [Clients](./CLIENTS.md)
+Lambda Utilities is a collection of pre-configured tools and helpers designed to reduce boilerplate code when developing AWS Lambda functions. It provides utilities for logging, API responses, configuration validation, and AWS SDK client management—all with full TypeScript support.
 
-## Quick Start
+## Documentation
 
-Install the package:
-
-```bash
-npm install @leanstacks/lambda-utils
-```
-
-Use a utility in your Lambda function:
-
-```typescript
-import { getLogger } from '@leanstacks/lambda-utils';
-import { success } from '@leanstacks/lambda-utils';
-
-const logger = getLogger();
-
-export const handler = async (event: any) => {
-  logger.info({ message: 'Processing event', event });
-
-  // Your handler logic here
-
-  return success({ message: 'Success' });
-};
-```
+- **[Logging Guide](./LOGGING.md)** – Implement structured logging in your Lambda functions with Pino and automatic AWS context enrichment
+- **[API Gateway Responses](./API_GATEWAY_RESPONSES.md)** – Format Lambda responses for API Gateway with standard HTTP status codes and headers
+- **[Configuration](./CONFIGURATION.md)** – Validate environment variables and configuration with Zod type safety
+- **[AWS Clients](./CLIENTS.md)** – Pre-configured AWS SDK v3 clients optimized for Lambda
+- **[Getting Started](./GETTING_STARTED.md)** – Quick setup and installation instructions
 
 ## Features
 
-- **Logging:** Structured logging with Pino configured for Lambda
-- **API Responses:** Standard response formatting for API Gateway
-- **Configuration:** Environment variable validation with Zod
-- **AWS Clients:** Pre-configured AWS SDK v3 clients
-- **Type Safe:** Full TypeScript support with comprehensive types
+- 📝 **Structured Logging** – Pino logger pre-configured for Lambda with automatic request context
+- 📤 **API Response Helpers** – Standard response formatting for API Gateway integration
+- ⚙️ **Configuration Validation** – Environment variable validation with Zod schema support
+- 🔌 **AWS Clients** – Pre-configured AWS SDK v3 clients for common services
+- 🔒 **Type Safe** – Full TypeScript support with comprehensive type definitions
 
 ## Support
 
-For issues or questions, please visit the [GitHub repository](https://github.com/leanstacks/lambda-utils).
+For issues or questions, visit the [GitHub repository](https://github.com/leanstacks/lambda-utils).

package/jest.config.ts

@@ -3,13 +3,13 @@ import type { Config } from 'jest';
 const config: Config = {
   preset: 'ts-jest',
   testEnvironment: 'node',
-  rootDir: 'src',
-  testMatch: ['**/*.test.ts'],
+  testMatch: ['<rootDir>/src/**/*.test.ts'],
   moduleNameMapper: {
     '^@/(.*)$': '<rootDir>/$1',
   },
-  collectCoverageFrom: ['**/*.ts', '!**/*.test.ts'],
-  coveragePathIgnorePatterns: ['/node_modules/'],
+  coverageDirectory: 'coverage',
+  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.test.ts', '!src/**/index.ts'],
+  coverageReporters: ['json', 'json-summary', 'lcov', 'text', 'clover'],
 };
 
 export default config;

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@leanstacks/lambda-utils",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "description": "A collection of utilities and helper functions designed to streamline the development of AWS Lambda functions using TypeScript.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "rollup -c",
     "build:watch": "rollup -c -w",
-    "clean": "rimraf dist",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
+    "clean": "rimraf coverage dist",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "format:check": "prettier --check \"src/**/*.ts\""
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
   },
   "keywords": [
     "lambda",
@@ -44,7 +44,6 @@
   },
   "dependencies": {
     "pino": "10.1.0",
-    "pino-lambda": "4.4.1",
-    "zod": "4.2.1"
+    "pino-lambda": "4.4.1"
   }
 }

package/src/logging/logger.test.ts

@@ -0,0 +1,400 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import pino from 'pino';
+import { CloudwatchLogFormatter, pinoLambdaDestination, StructuredLogFormatter } from 'pino-lambda';
+import { Logger, withRequestTracking } from './logger';
+
+// Mock pino-lambda module
+jest.mock('pino-lambda');
+
+// Mock pino module
+jest.mock('pino');
+
+describe('Logger', () => {
+  // Setup and cleanup
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('withRequestTracking', () => {
+    it('should be exported from logger module', () => {
+      // Arrange
+      // withRequestTracking is exported from logger.ts and is the result of calling lambdaRequestTracker()
+      // from pino-lambda. Jest mocks mean it will be the mocked value.
+
+      // Act & Assert
+      // We just verify that it was exported (defined by the import statement at the top)
+      // The actual functionality of lambdaRequestTracker is tested in pino-lambda
+      expect(typeof withRequestTracking === 'function' || withRequestTracking === undefined).toBe(true);
+    });
+  });
+
+  describe('constructor', () => {
+    it('should create Logger with default configuration', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      // Act
+      const logger = new Logger();
+
+      // Assert
+      expect(logger).toBeDefined();
+    });
+
+    it('should create Logger with custom enabled configuration', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      // Act
+      const logger = new Logger({ enabled: false });
+      const _instance = logger.instance;
+
+      // Assert
+      expect(pino).toHaveBeenCalledWith(
+        expect.objectContaining({
+          enabled: false,
+        }),
+        expect.anything(),
+      );
+    });
+
+    it('should create Logger with custom log level configuration', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      // Act
+      const logger = new Logger({ level: 'debug' });
+      const _instance = logger.instance;
+
+      // Assert
+      expect(pino).toHaveBeenCalledWith(
+        expect.objectContaining({
+          level: 'debug',
+        }),
+        expect.anything(),
+      );
+    });
+
+    it('should create Logger with custom format configuration (json)', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      // Act
+      const logger = new Logger({ format: 'json' });
+      const _instance = logger.instance;
+
+      // Assert
+      expect(StructuredLogFormatter).toHaveBeenCalled();
+    });
+
+    it('should create Logger with custom format configuration (text)', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      // Act
+      const logger = new Logger({ format: 'text' });
+      const _instance = logger.instance;
+
+      // Assert
+      expect(CloudwatchLogFormatter).toHaveBeenCalled();
+    });
+
+    it('should merge provided config with defaults', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      // Act
+      const logger = new Logger({ level: 'error' });
+      const _instance = logger.instance;
+
+      // Assert
+      expect(pino).toHaveBeenCalledWith(
+        expect.objectContaining({
+          enabled: true,
+          level: 'error',
+        }),
+        expect.anything(),
+      );
+    });
+  });
+
+  describe('instance getter', () => {
+    it('should return a Pino logger instance', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+      const logger = new Logger();
+
+      // Act
+      const instance = logger.instance;
+
+      // Assert
+      expect(instance).toBe(mockLogger);
+      expect(instance).toHaveProperty('info');
+      expect(instance).toHaveProperty('warn');
+      expect(instance).toHaveProperty('error');
+      expect(instance).toHaveProperty('debug');
+    });
+
+    it('should create logger instance only once (lazy initialization)', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+      const logger = new Logger();
+
+      // Act
+      const instance1 = logger.instance;
+      const instance2 = logger.instance;
+
+      // Assert
+      expect(instance1).toBe(instance2);
+      expect(pino).toHaveBeenCalledTimes(1);
+    });
+
+    it('should configure pino with enabled flag', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      // Act
+      const logger = new Logger({ enabled: false });
+      const _instance = logger.instance;
+
+      // Assert
+      expect(pino).toHaveBeenCalledWith(
+        expect.objectContaining({
+          enabled: false,
+        }),
+        expect.anything(),
+      );
+    });
+
+    it('should configure pino with log level', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      // Act
+      const logger = new Logger({ level: 'warn' });
+      const _instance = logger.instance;
+
+      // Assert
+      expect(pino).toHaveBeenCalledWith(
+        expect.objectContaining({
+          level: 'warn',
+        }),
+        expect.anything(),
+      );
+    });
+
+    it('should call pinoLambdaDestination with selected formatter', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      // Act
+      const logger = new Logger({ format: 'json' });
+      const _instance = logger.instance;
+
+      // Assert
+      expect(pinoLambdaDestination).toHaveBeenCalledWith(
+        expect.objectContaining({
+          formatter: expect.any(StructuredLogFormatter),
+        }),
+      );
+    });
+
+    it('should use StructuredLogFormatter when format is json', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      // Act
+      const logger = new Logger({ format: 'json' });
+      const _instance = logger.instance;
+
+      // Assert
+      expect(StructuredLogFormatter).toHaveBeenCalled();
+    });
+
+    it('should use CloudwatchLogFormatter when format is text', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      // Act
+      const logger = new Logger({ format: 'text' });
+      const _instance = logger.instance;
+
+      // Assert
+      expect(CloudwatchLogFormatter).toHaveBeenCalled();
+    });
+  });
+
+  describe('Logger configurations', () => {
+    it('should support all log levels', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+      const levels: Array<'debug' | 'info' | 'warn' | 'error'> = ['debug', 'info', 'warn', 'error'];
+
+      // Act & Assert
+      levels.forEach((level) => {
+        jest.clearAllMocks();
+        jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+        (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+        const logger = new Logger({ level });
+        const _instance = logger.instance;
+
+        expect(pino).toHaveBeenCalledWith(
+          expect.objectContaining({
+            level,
+          }),
+          expect.anything(),
+        );
+      });
+    });
+
+    it('should support both json and text formats', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      // Act
+      const jsonLogger = new Logger({ format: 'json' });
+      const _jsonInstance = jsonLogger.instance;
+      const structuredFormatterCallCount = (StructuredLogFormatter as jest.Mock).mock.calls.length;
+
+      jest.clearAllMocks();
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      const textLogger = new Logger({ format: 'text' });
+      const _textInstance = textLogger.instance;
+
+      // Assert
+      expect(structuredFormatterCallCount).toBeGreaterThan(0);
+      expect(CloudwatchLogFormatter).toHaveBeenCalled();
+    });
+
+    it('should support enabled and disabled logging', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      // Act
+      const enabledLogger = new Logger({ enabled: true });
+      const _enabledInstance = enabledLogger.instance;
+      const firstCallArgs = jest.mocked(pino).mock.calls[0];
+
+      jest.clearAllMocks();
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      const disabledLogger = new Logger({ enabled: false });
+      const _disabledInstance = disabledLogger.instance;
+      const secondCallArgs = jest.mocked(pino).mock.calls[0];
+
+      // Assert
+      expect(firstCallArgs[0]).toEqual(expect.objectContaining({ enabled: true }));
+      expect(secondCallArgs[0]).toEqual(expect.objectContaining({ enabled: false }));
+    });
+  });
+
+  describe('integration scenarios', () => {
+    it('should create multiple logger instances with different configurations', () => {
+      // Arrange
+      const mockLogger1 = { info: jest.fn(), level: 'debug' };
+      const mockLogger2 = { info: jest.fn(), level: 'error' };
+      jest
+        .mocked(pino)
+        .mockReturnValueOnce(mockLogger1 as unknown as any)
+        .mockReturnValueOnce(mockLogger2 as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      // Act
+      const debugLogger = new Logger({ level: 'debug', format: 'json' });
+      const errorLogger = new Logger({ level: 'error', format: 'text' });
+
+      const instance1 = debugLogger.instance;
+      const instance2 = errorLogger.instance;
+
+      // Assert
+      expect(instance1).toBe(mockLogger1);
+      expect(instance2).toBe(mockLogger2);
+      expect(pino).toHaveBeenCalledTimes(2);
+    });
+
+    it('should handle partial configuration overrides', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      // Act
+      const logger = new Logger({ level: 'warn' });
+      const _instance = logger.instance;
+
+      // Assert - should have custom level but default enabled and format
+      expect(pino).toHaveBeenCalledWith(
+        expect.objectContaining({
+          enabled: true,
+          level: 'warn',
+        }),
+        expect.anything(),
+      );
+      expect(StructuredLogFormatter).toHaveBeenCalled();
+    });
+
+    it('should handle full configuration override', () => {
+      // Arrange
+      const mockLogger = { info: jest.fn() };
+      jest.mocked(pino).mockReturnValue(mockLogger as unknown as any);
+      (pinoLambdaDestination as jest.Mock).mockReturnValue({});
+
+      // Act
+      const logger = new Logger({
+        enabled: false,
+        level: 'error',
+        format: 'text',
+      });
+      const _instance = logger.instance;
+
+      // Assert
+      expect(pino).toHaveBeenCalledWith(
+        expect.objectContaining({
+          enabled: false,
+          level: 'error',
+        }),
+        expect.anything(),
+      );
+      expect(CloudwatchLogFormatter).toHaveBeenCalled();
+    });
+  });
+});

package/dist/index.d.ts

@@ -1 +0,0 @@
-export { Logger, LoggerConfig, withRequestTracking } from './logging/logger';

package/dist/index.js

@@ -1,78 +0,0 @@
-import pino from 'pino';
-import { lambdaRequestTracker, StructuredLogFormatter, CloudwatchLogFormatter, pinoLambdaDestination } from 'pino-lambda';
-
-/**
- * Logger middleware which adds AWS Lambda attributes to log messages.
- *
- * @example
- * ```typescript
- * import { withRequestTracking } from '@leanstacks/lambda-utils';
- *
- * export const handler = async (event, context) => {
- *   withRequestTracking(event, context);
- *
- *   // Your Lambda handler logic here
- * };
- * ```
- */
-const withRequestTracking = lambdaRequestTracker();
-/**
- * Logger class which provides a Pino logger instance with AWS Lambda attributes.
- *
- * @example
- * ```typescript
- * import { Logger } from '@leanstacks/lambda-utils';
- * const logger = new Logger().instance;
- *
- * logger.info('Hello, world!');
- * ```
- */
-class Logger {
-    constructor(config) {
-        this._loggerConfig = {
-            enabled: true,
-            level: 'info',
-            format: 'json',
-        };
-        this._instance = null;
-        /**
-         * Creates a new, fully configured Pino logger instance.
-         */
-        this._createLogger = () => {
-            const formatter = this._loggerConfig.format === 'json' ? new StructuredLogFormatter() : new CloudwatchLogFormatter();
-            const lambdaDestination = pinoLambdaDestination({
-                formatter,
-            });
-            return pino({
-                enabled: this._loggerConfig.enabled,
-                level: this._loggerConfig.level,
-            }, lambdaDestination);
-        };
-        if (config) {
-            this._loggerConfig = {
-                enabled: config.enabled ?? true,
-                level: config.level ?? 'info',
-                format: config.format ?? 'json',
-            };
-        }
-    }
-    /**
-     * Get the logger instance.
-     *
-     * @example
-     * ```typescript
-     * import { Logger } from '@leanstacks/lambda-utils';
-     * const logger = new Logger().instance;
-     *
-     * logger.info('Hello, world!');
-     * ```
-     */
-    get instance() {
-        if (this._instance === null) {
-            this._instance = this._createLogger();
-        }
-        return this._instance;
-    }
-}
-
-export { Logger, withRequestTracking };

package/dist/logging/logger.d.ts

@@ -1,59 +0,0 @@
-import pino from 'pino';
-/**
- * Logger middleware which adds AWS Lambda attributes to log messages.
- *
- * @example
- * ```typescript
- * import { withRequestTracking } from '@leanstacks/lambda-utils';
- *
- * export const handler = async (event, context) => {
- *   withRequestTracking(event, context);
- *
- *   // Your Lambda handler logic here
- * };
- * ```
- */
-export declare const withRequestTracking: (event: import("pino-lambda").LambdaEvent, context: import("pino-lambda").LambdaContext) => void;
-/**
- * Configuration options for the Logger
- */
-export interface LoggerConfig {
-    /** Whether logging is enabled */
-    enabled?: boolean;
-    /** Minimum log level (e.g., 'debug', 'info', 'warn', 'error') */
-    level?: 'debug' | 'info' | 'warn' | 'error';
-    /** Output format: 'json' for StructuredLogFormatter, 'text' for CloudwatchLogFormatter */
-    format?: 'json' | 'text';
-}
-/**
- * Logger class which provides a Pino logger instance with AWS Lambda attributes.
- *
- * @example
- * ```typescript
- * import { Logger } from '@leanstacks/lambda-utils';
- * const logger = new Logger().instance;
- *
- * logger.info('Hello, world!');
- * ```
- */
-export declare class Logger {
-    private _loggerConfig;
-    private _instance;
-    constructor(config?: LoggerConfig);
-    /**
-     * Creates a new, fully configured Pino logger instance.
-     */
-    private _createLogger;
-    /**
-     * Get the logger instance.
-     *
-     * @example
-     * ```typescript
-     * import { Logger } from '@leanstacks/lambda-utils';
-     * const logger = new Logger().instance;
-     *
-     * logger.info('Hello, world!');
-     * ```
-     */
-    get instance(): pino.Logger;
-}