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

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.2",
+  "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/index.ts

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

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/src/logging/logger.ts

@@ -7,10 +7,11 @@ import {
 } from 'pino-lambda';
 
 /**
- * Middleware to track AWS Lambda requests
+ * Logger middleware which adds AWS Lambda attributes to log messages.
+ *
  * @example
  * ```typescript
- * import { withRequestTracking } from '@utils/logging/logger';
+ * import { withRequestTracking } from '@leanstacks/lambda-utils';
  *
  * export const handler = async (event, context) => {
  *   withRequestTracking(event, context);
@@ -22,7 +23,7 @@ import {
 export const withRequestTracking = lambdaRequestTracker();
 
 /**
- * Configuration options for the Pino Lambda logger
+ * Configuration options for the Logger
  */
 export interface LoggerConfig {
   /** Whether logging is enabled */
@@ -34,82 +35,70 @@ export interface LoggerConfig {
 }
 
 /**
- * Module-level state to store logger configuration
- */
-let _loggerConfig: LoggerConfig = {
-  enabled: true,
-  level: 'info',
-  format: 'json',
-};
-
-/**
- * Module-level cache for the logger instance
- */
-let _loggerInstance: pino.Logger | null = null;
-
-/**
- * Create and return the Pino Lambda logger instance
- * Uses the configuration set by initializeLogger
- * Logger instance is cached after first creation
- */
-const _createLogger = (): pino.Logger => {
-  const formatter = _loggerConfig.format === 'json' ? new StructuredLogFormatter() : new CloudwatchLogFormatter();
-
-  const lambdaDestination = pinoLambdaDestination({
-    formatter,
-  });
-
-  return pino(
-    {
-      enabled: _loggerConfig.enabled,
-      level: _loggerConfig.level,
-    },
-    lambdaDestination,
-  );
-};
-
-/**
- * Initialize the logger with configuration
- * Should be called once at Lambda handler entry point
- * Invalidates the cached logger instance so a new one is created with the updated config
- *
- * @param config Logger configuration options
- * @returns void
+ * Logger class which provides a Pino logger instance with AWS Lambda attributes.
  *
  * @example
  * ```typescript
- * import { initializeLogger } from '@utils/logging/logger';
+ * import { Logger } from '@leanstacks/lambda-utils';
+ * const logger = new Logger().instance;
  *
- * initializeLogger({
- *   enabled: true,
- *   level: 'debug',
- *   format: 'json',
- * });
+ * logger.info('Hello, world!');
  * ```
  */
-export const initializeLogger = (config: LoggerConfig): void => {
-  _loggerConfig = {
-    enabled: config.enabled ?? true,
-    level: config.level ?? 'info',
-    format: config.format ?? 'json',
+export class Logger {
+  private _loggerConfig: LoggerConfig = {
+    enabled: true,
+    level: 'info',
+    format: 'json',
   };
-  // Invalidate the cached logger instance so a new one is created with updated config
-  _loggerInstance = null;
-};
 
-/**
- * Get the logger instance
- *
- * @example
- * ```typescript
- * import { logger } from '@utils/logging/logger';
- *
- * logger.info('Hello, world!');
- * ```
- */
-export const getLogger = (): pino.Logger => {
-  if (_loggerInstance === null) {
-    _loggerInstance = _createLogger();
+  private _instance: pino.Logger | null = null;
+
+  constructor(config?: LoggerConfig) {
+    if (config) {
+      this._loggerConfig = {
+        enabled: config.enabled ?? true,
+        level: config.level ?? 'info',
+        format: config.format ?? 'json',
+      };
+    }
   }
-  return _loggerInstance;
-};
+
+  /**
+   * Creates a new, fully configured Pino logger instance.
+   */
+  private _createLogger = (): pino.Logger => {
+    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,
+    );
+  };
+
+  /**
+   * 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 {
+    if (this._instance === null) {
+      this._instance = this._createLogger();
+    }
+    return this._instance;
+  }
+}

package/dist/index.d.ts

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