@leanstacks/lambda-utils 0.1.0-alpha.3 → 0.1.0-alpha.5

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,22 @@
 {
   "name": "@leanstacks/lambda-utils",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.5",
   "description": "A collection of utilities and helper functions designed to streamline the development of AWS Lambda functions using TypeScript.",
   "main": "dist/index.js",
+  "module": "dist/index.esm.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\""
+    "prepare": "husky",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
   },
   "keywords": [
     "lambda",
@@ -27,16 +29,21 @@
   "license": "MIT",
   "devDependencies": {
     "@eslint/js": "9.39.2",
+    "@rollup/plugin-commonjs": "29.0.0",
+    "@rollup/plugin-node-resolve": "16.0.3",
+    "@rollup/plugin-terser": "0.4.4",
     "@types/aws-lambda": "8.10.159",
     "@types/jest": "30.0.0",
     "@types/node": "25.0.3",
     "@typescript-eslint/eslint-plugin": "8.50.0",
     "@typescript-eslint/parser": "8.50.0",
     "eslint": "9.39.2",
+    "husky": "9.1.7",
     "jest": "30.2.0",
     "prettier": "3.7.4",
     "rimraf": "6.1.2",
     "rollup": "4.53.5",
+    "rollup-plugin-peer-deps-external": "2.2.4",
     "rollup-plugin-typescript2": "0.36.0",
     "ts-jest": "29.4.6",
     "ts-node": "10.9.2",
@@ -44,7 +51,6 @@
   },
   "dependencies": {
     "pino": "10.1.0",
-    "pino-lambda": "4.4.1",
-    "zod": "4.2.1"
+    "pino-lambda": "4.4.1"
   }
 }

package/rollup.config.js

@@ -1,18 +1,34 @@
+import commonjs from '@rollup/plugin-commonjs';
+import { nodeResolve } from '@rollup/plugin-node-resolve';
+import terser from '@rollup/plugin-terser';
+import peerDepsExternal from 'rollup-plugin-peer-deps-external';
 import typescript from 'rollup-plugin-typescript2';
 
+import packageJson from './package.json' with { type: 'json' };
+
 export default {
   input: 'src/index.ts',
   output: [
     {
-      file: 'dist/index.js',
+      file: packageJson.main,
+      format: 'cjs',
+      sourcemap: true,
+    },
+    {
+      file: packageJson.module,
       format: 'esm',
+      sourcemap: true,
     },
   ],
-  external: ['pino', 'pino-lambda', 'zod', '@aws-sdk/client-dynamodb', '@aws-sdk/client-lambda'],
   plugins: [
+    peerDepsExternal(),
+    nodeResolve(),
+    commonjs(),
     typescript({
       tsconfig: 'tsconfig.json',
       clean: true,
     }),
+    terser(),
   ],
+  external: [...Object.keys(packageJson.dependencies || {})],
 };