@leanstacks/lambda-utils 0.1.0-alpha.1

package/.editorconfig

@@ -0,0 +1,12 @@
+# This file is used to define coding styles and formatting rules for the project.
+# For more information, see https://editorconfig.org/
+root=true
+
+[*]
+charset=utf-8
+end_of_line=lf
+indent_style=space
+indent_size=2
+insert_final_newline=true
+max_line_length=120
+trim_trailing_whitespace=true

package/.github/copilot-instructions.md

@@ -0,0 +1,101 @@
+# Lambda Utilities Project Instructions
+
+This project contains a set of utilities and helper functions designed to streamline the development of AWS Lambda functions using TypeScript. The utilities cover common tasks such as input validation, response formatting, error handling, and logging. The project is packaged and published as an npm package for easy integration into other Lambda projects.
+
+---
+
+## Technology Stack
+
+Each pattern project uses the following technology stack:
+
+- **Language:** TypeScript
+- **Platform:** AWS Lambda
+- **Runtime:** Node.js 24.x
+- **AWS SDK:** v3 (modular packages)
+- **Testing:** Jest
+- **Linting/Formatting:** ESLint + Prettier
+- **Validation:** Zod
+- **Logging:** Pino + Pino-Lambda
+- **Package Manager:** npm
+- **Package Bundler:** rollup
+
+---
+
+## Pattern Project Structure
+
+Each pattern project follows a consistent directory and file structure to promote maintainability and scalability. Below is an example structure:
+
+```
+/docs                               # Project documentation
+  README.md                         # Documentation table of contents
+
+/src
+  /logging
+    logger.ts                       # Logger utility using Pino
+    logger.test.ts                  # Unit tests for logger
+  /clients
+    dynamodb-client.ts              # AWS SDK client for DynamoDB
+    dynamodb-client.test.ts         # Unit tests for DynamoDB client
+    lambda-client.ts                # AWS SDK client for Lambda
+    lambda-client.test.ts           # Unit tests for Lambda client
+  /validation
+    config.ts                       # Configuration validation with Zod
+    config.test.ts                  # Unit tests for config
+    validator.ts                    # Generic validator helpers
+    validator.test.ts               # Unit tests for validator
+  /responses
+    apigateway-response.ts          # Standard API response helpers
+    apigateway-response.test.ts     # Unit tests for API response helpers
+.editorconfig                       # Editor config
+.gitignore                          # Git ignore rules
+.nvmrc                              # Node version manager config
+.prettierrc                         # Prettier config
+eslint.config.mjs                   # ESLint config
+jest.config.ts                      # App Jest config
+jest.setup.ts                       # App Jest setup
+package.json                        # App NPM package config
+README.md                           # Project README
+tsconfig.json                       # Project TypeScript config
+```
+
+---
+
+## Source Code Guidelines
+
+Each pattern project follows best practices for source code organization, naming conventions, and coding standards. Below are the key guidelines:
+
+- Use **TypeScript** for all source and infrastructure code.
+- Use arrow functions for defining functions.
+- Use path aliases for cleaner imports (e.g., `@utils`, `@models`).
+- Organize import statements: external packages first, then internal modules.
+- Use async/await for asynchronous operations.
+- Document functions and modules with JSDoc comments.
+
+### Source Code Commands & Scripts
+
+- Use `npm run build` to compile TypeScript.
+- Use `npm run test` to run tests.
+- Use `npm run test:coverage` to run tests with coverage report.
+- Use `npm run lint` to run ESLint.
+- Use `npm run lint:fix` to fix ESLint issues.
+- Use `npm run format` to run Prettier to format code.
+- Use `npm run format:check` to check code formatting with Prettier.
+
+---
+
+## Unit Testing Guidelines
+
+Each pattern project includes comprehensive unit tests for both application and infrastructure code. Below are the key guidelines for writing unit tests:
+
+- Use the **Jest** testing framework.
+- Place test files next to the source file, with `.test.ts` suffix.
+- Use `describe` and `it` blocks for organization.
+- Use `beforeEach` for setup and `afterEach` for cleanup.
+- Use `expect` assertions for results.
+- Mock dependencies to isolate the component under test.
+- Mock external calls (e.g., AWS SDK, databases).
+- Structure your tests using the Arrange-Act-Assert pattern:
+  - **Arrange:** Set up the test environment, including any necessary mocks and test data.
+  - **Act:** Execute the function or service being tested.
+  - **Assert:** Verify that the results are as expected.
+  - Add comments to separate these sections for clarity.

package/.nvmrc

@@ -0,0 +1 @@
+24.11.1

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "plugins": [],
+  "printWidth": 120,
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "all"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 LeanStacks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# Lambda Utilities
+
+Lambda utilities

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,75 @@
+import pino from 'pino';
+import { StructuredLogFormatter, pinoLambdaDestination, CloudwatchLogFormatter } from 'pino-lambda';
+
+/**
+ * Module-level state to store logger configuration
+ */
+let _loggerConfig = {
+    enabled: true,
+    level: 'info',
+    format: 'json',
+};
+/**
+ * Module-level cache for the logger instance
+ */
+let _loggerInstance = null;
+/**
+ * Create and return the Pino Lambda logger instance
+ * Uses the configuration set by initializeLogger
+ * Logger instance is cached after first creation
+ */
+const _createLogger = () => {
+    const formatter = _loggerConfig.format === 'json' ? new StructuredLogFormatter() : new CloudwatchLogFormatter();
+    const lambdaDestination = pinoLambdaDestination({
+        formatter,
+    });
+    return pino({
+        enabled: _loggerConfig.enabled,
+        level: _loggerConfig.level,
+    }, lambdaDestination);
+};
+/**
+ * Get the cached logger instance, creating it if necessary
+ */
+const _getLogger = () => {
+    if (_loggerInstance === null) {
+        _loggerInstance = _createLogger();
+    }
+    return _loggerInstance;
+};
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * import { initializeLogger } from '@utils/logging/logger';
+ *
+ * initializeLogger({
+ *   enabled: true,
+ *   level: 'debug',
+ *   format: 'json',
+ * });
+ * ```
+ */
+const initializeLogger = (config) => {
+    _loggerConfig = {
+        enabled: config.enabled ?? true,
+        level: config.level ?? 'info',
+        format: config.format ?? 'json',
+    };
+    // Invalidate the cached logger instance so a new one is created with updated config
+    _loggerInstance = null;
+};
+/**
+ * Pino logger instance
+ * Configuration is supplied via initializeLogger() and persists across imports
+ * Logger instance is cached after first creation for reuse
+ */
+const logger = _getLogger();
+
+export { initializeLogger, logger };

package/dist/logging/logger.d.ts

@@ -0,0 +1,38 @@
+import pino from 'pino';
+/**
+ * Configuration options for the Pino Lambda 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';
+}
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * import { initializeLogger } from '@utils/logging/logger';
+ *
+ * initializeLogger({
+ *   enabled: true,
+ *   level: 'debug',
+ *   format: 'json',
+ * });
+ * ```
+ */
+export declare const initializeLogger: (config: LoggerConfig) => void;
+/**
+ * Pino logger instance
+ * Configuration is supplied via initializeLogger() and persists across imports
+ * Logger instance is cached after first creation for reuse
+ */
+export declare const logger: pino.Logger<never, boolean>;

package/docs/README.md

@@ -0,0 +1,48 @@
+# Lambda Utilities - Documentation
+
+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
+
+- [Getting Started](./GETTING_STARTED.md)
+- [Logging](./LOGGING.md)
+- [API Gateway Responses](./API_GATEWAY_RESPONSES.md)
+- [Configuration](./CONFIGURATION.md)
+- [Clients](./CLIENTS.md)
+
+## Quick Start
+
+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' });
+};
+```
+
+## 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
+
+## Support
+
+For issues or questions, please visit the [GitHub repository](https://github.com/leanstacks/lambda-utils).

package/eslint.config.mjs

@@ -0,0 +1,44 @@
+import js from '@eslint/js';
+import tsPlugin from '@typescript-eslint/eslint-plugin';
+import tsParser from '@typescript-eslint/parser';
+
+export default [
+  {
+    ignores: ['dist', 'node_modules'],
+  },
+  {
+    files: ['src/**/*.ts'],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        ecmaVersion: 2020,
+        sourceType: 'module',
+      },
+      globals: {
+        console: 'readonly',
+        process: 'readonly',
+        describe: 'readonly',
+        it: 'readonly',
+        expect: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+        jest: 'readonly',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tsPlugin,
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      ...tsPlugin.configs.recommended.rules,
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+        },
+      ],
+      '@typescript-eslint/no-explicit-any': 'warn',
+    },
+  },
+];

package/jest.config.ts

@@ -0,0 +1,15 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  rootDir: 'src',
+  testMatch: ['**/*.test.ts'],
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/$1',
+  },
+  collectCoverageFrom: ['**/*.ts', '!**/*.test.ts'],
+  coveragePathIgnorePatterns: ['/node_modules/'],
+};
+
+export default config;

package/jest.setup.ts

@@ -0,0 +1,9 @@
+// Jest setup file for global test configuration
+// Add any global test setup here
+
+// Mock pino-lambda for tests
+jest.mock('pino-lambda', () => {
+  return {
+    target: 'pino-lambda',
+  };
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@leanstacks/lambda-utils",
+  "version": "0.1.0-alpha.1",
+  "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",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\""
+  },
+  "keywords": [
+    "lambda",
+    "aws",
+    "utilities",
+    "nodejs",
+    "typescript"
+  ],
+  "author": "Matthew Warman <leanstacker@gmail.com> (https://leanstacks.com)",
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "9.39.2",
+    "@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",
+    "jest": "30.2.0",
+    "prettier": "3.7.4",
+    "rimraf": "6.1.2",
+    "rollup": "4.53.5",
+    "rollup-plugin-typescript2": "0.36.0",
+    "ts-jest": "29.4.6",
+    "ts-node": "10.9.2",
+    "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "pino": "10.1.0",
+    "pino-lambda": "4.4.1",
+    "zod": "4.2.1"
+  }
+}

package/rollup.config.js

@@ -0,0 +1,18 @@
+import typescript from 'rollup-plugin-typescript2';
+
+export default {
+  input: 'src/index.ts',
+  output: [
+    {
+      file: 'dist/index.js',
+      format: 'esm',
+    },
+  ],
+  external: ['pino', 'pino-lambda', 'zod', '@aws-sdk/client-dynamodb', '@aws-sdk/client-lambda'],
+  plugins: [
+    typescript({
+      tsconfig: 'tsconfig.json',
+      clean: true,
+    }),
+  ],
+};

package/src/index.ts

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

package/src/logging/logger.ts

@@ -0,0 +1,95 @@
+import pino from 'pino';
+import { CloudwatchLogFormatter, pinoLambdaDestination, StructuredLogFormatter } from 'pino-lambda';
+
+/**
+ * Configuration options for the Pino Lambda 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';
+}
+
+/**
+ * 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,
+  );
+};
+
+/**
+ * Get the cached logger instance, creating it if necessary
+ */
+const _getLogger = (): pino.Logger => {
+  if (_loggerInstance === null) {
+    _loggerInstance = _createLogger();
+  }
+  return _loggerInstance;
+};
+
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * import { initializeLogger } from '@utils/logging/logger';
+ *
+ * initializeLogger({
+ *   enabled: true,
+ *   level: 'debug',
+ *   format: 'json',
+ * });
+ * ```
+ */
+export const initializeLogger = (config: LoggerConfig): void => {
+  _loggerConfig = {
+    enabled: config.enabled ?? true,
+    level: config.level ?? 'info',
+    format: config.format ?? 'json',
+  };
+  // Invalidate the cached logger instance so a new one is created with updated config
+  _loggerInstance = null;
+};
+
+/**
+ * Pino logger instance
+ * Configuration is supplied via initializeLogger() and persists across imports
+ * Logger instance is cached after first creation for reuse
+ */
+export const logger = _getLogger();

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "baseUrl": "./src",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}