@leanstacks/lambda-utils 0.3.0-alpha.4 → 0.4.0-alpha.1

package/docs/CONFIGURATION.md

@@ -0,0 +1,348 @@
+# Configuration Guide
+
+This guide explains how to use the `createConfigManager` utility to validate and manage environment variables in your Lambda functions with full TypeScript type safety.
+
+## Overview
+
+The configuration utility provides:
+
+- **Schema-based validation** using Zod for environment variables
+- **Type-safe access** to your configuration with full TypeScript support
+- **Caching** of validated configuration for performance
+- **Flexible defaults** for optional environment variables
+- **Clear error messages** when validation fails
+
+## Quick Start
+
+### Define Your Schema
+
+Create a Zod schema that describes your environment variables:
+
+```typescript
+import { z } from 'zod';
+
+const configSchema = z.object({
+  // Required variables
+  TABLE_NAME: z.string().min(1, 'TABLE_NAME is required'),
+
+  // Optional with defaults
+  AWS_REGION: z.string().default('us-east-1'),
+  DEBUG_MODE: z
+    .enum(['true', 'false'])
+    .default('false')
+    .transform((val) => val === 'true'),
+});
+
+// Infer the TypeScript type from your schema
+type Config = z.infer<typeof configSchema>;
+```
+
+### Create and Use ConfigManager
+
+```typescript
+import { createConfigManager } from '@leanstacks/lambda-utils';
+
+// Create the manager
+const configManager = createConfigManager(configSchema);
+
+// Get validated config (cached after first call)
+const config = configManager.get();
+
+// Use your configuration
+console.log(config.TABLE_NAME); // Type-safe access
+console.log(config.AWS_REGION); // Automatically defaults to 'us-east-1'
+console.log(config.DEBUG_MODE); // Typed as boolean
+```
+
+## Complete Example
+
+Here's a realistic Lambda function configuration:
+
+```typescript
+import { z } from 'zod';
+import { createConfigManager } from '@leanstacks/lambda-utils';
+
+/**
+ * Schema for validating environment variables
+ */
+const envSchema = z.object({
+  // Required variables
+  TASKS_TABLE: z.string().min(1, 'TASKS_TABLE environment variable is required'),
+
+  // Optional variables with defaults
+  AWS_REGION: z.string().default('us-east-1'),
+
+  // Logging configuration
+  LOGGING_ENABLED: z
+    .enum(['true', 'false'] as const)
+    .default('true')
+    .transform((val) => val === 'true'),
+  LOGGING_LEVEL: z.enum(['debug', 'info', 'warn', 'error'] as const).default('debug'),
+  LOGGING_FORMAT: z.enum(['text', 'json'] as const).default('json'),
+
+  // CORS configuration
+  CORS_ALLOW_ORIGIN: z.string().default('*'),
+});
+
+/**
+ * Type representing our validated config
+ */
+export type Config = z.infer<typeof envSchema>;
+
+/**
+ * Configuration manager instance
+ */
+const configManager = createConfigManager(envSchema);
+
+/**
+ * Validated configuration object. Singleton.
+ */
+export const config = configManager.get();
+
+/**
+ * Refresh configuration (useful in tests)
+ */
+export const refreshConfig = () => configManager.refresh();
+```
+
+Then use it in your handler:
+
+```typescript
+import { config } from './config';
+import { Logger } from '@leanstacks/lambda-utils';
+
+const logger = new Logger({
+  level: config.LOGGING_LEVEL,
+  format: config.LOGGING_FORMAT,
+}).instance;
+
+export const handler = async (event: any) => {
+  logger.info({
+    message: 'Processing request',
+    table: config.TASKS_TABLE,
+    region: config.AWS_REGION,
+  });
+
+  // Your handler logic here
+};
+```
+
+## API Reference
+
+### `createConfigManager<T>(schema: T): ConfigManager<z.infer<T>>`
+
+Creates a configuration manager instance.
+
+**Parameters:**
+
+- `schema` - A Zod schema defining your environment variables
+
+**Returns:** A `ConfigManager` instance with two methods
+
+### `ConfigManager.get(): T`
+
+Gets the validated configuration (cached after the first call).
+
+**Throws:** `Error` if validation fails
+
+**Returns:** The validated configuration object
+
+```typescript
+const config = configManager.get();
+// First call: validates and caches
+// Subsequent calls: returns cached value
+```
+
+### `ConfigManager.refresh(): T`
+
+Refreshes the configuration by re-validating environment variables against the schema.
+
+**Throws:** `Error` if validation fails
+
+**Returns:** The newly validated configuration object
+
+Use this in tests when you need to change environment variables:
+
+```typescript
+beforeEach(() => {
+  process.env.TABLE_NAME = 'test-table';
+  configManager.refresh(); // Re-validate with new values
+});
+```
+
+## Best Practices
+
+### 1. Separate Configuration Module
+
+Create a dedicated configuration module for your Lambda function:
+
+```typescript
+// src/config.ts
+import { z } from 'zod';
+import { createConfigManager } from '@leanstacks/lambda-utils';
+
+const schema = z.object({
+  TABLE_NAME: z.string().min(1),
+  AWS_REGION: z.string().default('us-east-1'),
+});
+
+export type Config = z.infer<typeof schema>;
+
+const configManager = createConfigManager(schema);
+
+export const config = configManager.get();
+export const refresh = () => configManager.refresh();
+```
+
+### 2. Validate Early
+
+Call `config.get()` during handler initialization to validate configuration before processing requests:
+
+```typescript
+export const handler = async (event: any, context: any) => {
+  // Validation happens here, fails fast if config is invalid
+  const config = configManager.get();
+
+  // Handler logic with validated config
+};
+```
+
+### 3. Use Enums for Known Values
+
+Use `z.enum()` for configuration options with limited valid values:
+
+```typescript
+const schema = z.object({
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+  ENVIRONMENT: z.enum(['dev', 'staging', 'prod']),
+});
+
+// TypeScript autocomplete for config.LOG_LEVEL
+```
+
+### 4. Transform String to Boolean
+
+Since environment variables are always strings, use `transform()` to convert them:
+
+```typescript
+const schema = z.object({
+  ENABLE_FEATURE: z
+    .enum(['true', 'false'])
+    .default('false')
+    .transform((val) => val === 'true'),
+});
+
+// config.ENABLE_FEATURE is now a boolean
+if (config.ENABLE_FEATURE) {
+  // Feature is enabled
+}
+```
+
+### 5. Provide Helpful Error Messages
+
+Use Zod's second parameter to provide context-specific error messages:
+
+```typescript
+const schema = z.object({
+  DATABASE_URL: z.string().url('DATABASE_URL must be a valid URL'),
+  API_KEY: z.string().min(32, 'API_KEY must be at least 32 characters'),
+});
+```
+
+### 6. Test Configuration Validation
+
+Test that your schema properly validates configuration:
+
+```typescript
+import { config, refresh } from './config';
+
+describe('Configuration', () => {
+  it('should load default values', () => {
+    delete process.env.AWS_REGION;
+    refresh();
+    expect(config.AWS_REGION).toBe('us-east-1');
+  });
+
+  it('should validate required variables', () => {
+    delete process.env.TABLE_NAME;
+    expect(() => refresh()).toThrow();
+  });
+
+  it('should parse boolean values', () => {
+    process.env.DEBUG_MODE = 'true';
+    refresh();
+    expect(config.DEBUG_MODE).toBe(true);
+  });
+});
+```
+
+## Common Patterns
+
+### Database Configuration
+
+```typescript
+const schema = z.object({
+  DATABASE_URL: z.string().url(),
+  DATABASE_POOL_SIZE: z
+    .string()
+    .default('10')
+    .transform((val) => parseInt(val, 10)),
+  DATABASE_TIMEOUT: z
+    .string()
+    .default('5000')
+    .transform((val) => parseInt(val, 10)),
+});
+```
+
+### Feature Flags
+
+```typescript
+const schema = z.object({
+  FEATURE_NEW_UI: z
+    .enum(['true', 'false'])
+    .default('false')
+    .transform((val) => val === 'true'),
+  FEATURE_BETA_API: z
+    .enum(['true', 'false'])
+    .default('false')
+    .transform((val) => val === 'true'),
+});
+```
+
+### Multi-Environment Setup
+
+```typescript
+const schema = z.object({
+  ENVIRONMENT: z.enum(['development', 'staging', 'production']),
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+  DEBUG_MODE: z
+    .enum(['true', 'false'])
+    .refine(
+      (val) => (val === 'true' ? process.env.ENVIRONMENT === 'development' : true),
+      'DEBUG_MODE can only be true in development',
+    )
+    .transform((val) => val === 'true'),
+});
+```
+
+## Error Handling
+
+Configuration validation errors include detailed information about what failed:
+
+```typescript
+try {
+  const config = configManager.get();
+} catch (error) {
+  if (error instanceof Error) {
+    console.error(error.message);
+    // Output: "Configuration validation failed: TABLE_NAME: String must contain at least 1 character"
+  }
+}
+```
+
+Lambda will automatically fail fast if configuration is invalid, which is the desired behavior for Lambda functions.
+
+## Related Documentation
+
+- **[Zod Documentation](https://zod.dev/)** – Learn more about schema validation with Zod
+- **[Back to the project documentation](README.md)**

package/docs/LAMBDA_CLIENT.md

@@ -0,0 +1,292 @@
+# Lambda Client Utilities
+
+The Lambda client utilities provide a reusable singleton instance of `LambdaClient` for use in AWS Lambda functions. These utilities enable you to configure the client once and reuse it across invocations, following AWS best practices for Lambda performance optimization.
+
+## Overview
+
+The utility exports the following functions:
+
+- `initializeLambdaClient()` - Initialize the Lambda client with optional configuration
+- `getLambdaClient()` - Get the singleton Lambda client instance
+- `invokeLambdaSync()` - Invoke a Lambda function synchronously (RequestResponse)
+- `invokeLambdaAsync()` - Invoke a Lambda function asynchronously (Event)
+- `resetLambdaClient()` - Reset the client instance (useful for testing)
+
+## Usage
+
+### Synchronous Invocation (RequestResponse)
+
+Use synchronous invocation when you need to wait for the Lambda function to complete and return a response:
+
+```typescript
+import { invokeLambdaSync } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  // Invoke a Lambda function and wait for the response
+  const response = await invokeLambdaSync('my-function-name', {
+    key: 'value',
+    data: { nested: true },
+  });
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify(response),
+  };
+};
+```
+
+### Synchronous Invocation with Typed Response
+
+For better type safety, you can specify the expected response type:
+
+```typescript
+import { invokeLambdaSync } from '@leanstacks/lambda-utils';
+
+interface MyFunctionResponse {
+  result: string;
+  statusCode: number;
+  data: Record<string, unknown>;
+}
+
+export const handler = async (event: any) => {
+  const response = await invokeLambdaSync<MyFunctionResponse>('my-function-name', {
+    operation: 'getData',
+    id: '12345',
+  });
+
+  console.log(`Function returned: ${response.result}`);
+
+  return {
+    statusCode: response.statusCode,
+    body: JSON.stringify(response.data),
+  };
+};
+```
+
+### Asynchronous Invocation (Event)
+
+Use asynchronous invocation for fire-and-forget scenarios where you don't need to wait for the Lambda function to complete:
+
+```typescript
+import { invokeLambdaAsync } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  // Invoke a Lambda function asynchronously (fire and forget)
+  await invokeLambdaAsync('my-async-function', {
+    eventType: 'process',
+    data: [1, 2, 3],
+  });
+
+  // Returns immediately without waiting for the function to complete
+  return {
+    statusCode: 202,
+    body: JSON.stringify({ message: 'Processing initiated' }),
+  };
+};
+```
+
+### Using Function ARN
+
+You can invoke Lambda functions by name or ARN:
+
+```typescript
+import { invokeLambdaSync } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  // Using function ARN
+  const response = await invokeLambdaSync('arn:aws:lambda:us-east-1:123456789012:function:my-function', {
+    key: 'value',
+  });
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify(response),
+  };
+};
+```
+
+### Using the Lambda Client Directly
+
+For advanced use cases, you can access the underlying Lambda client:
+
+```typescript
+import { getLambdaClient } from '@leanstacks/lambda-utils';
+import { ListFunctionsCommand } from '@aws-sdk/client-lambda';
+
+export const handler = async (event: any) => {
+  const client = getLambdaClient();
+
+  const response = await client.send(new ListFunctionsCommand({}));
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify(response.Functions),
+  };
+};
+```
+
+### Custom Configuration
+
+Initialize the Lambda client with custom configuration at the start of your Lambda handler:
+
+```typescript
+import { initializeLambdaClient, invokeLambdaSync } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  // Initialize with custom configuration (only needs to be done once)
+  initializeLambdaClient({
+    region: 'us-west-2',
+    maxAttempts: 3,
+  });
+
+  const response = await invokeLambdaSync('my-function', { key: 'value' });
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify(response),
+  };
+};
+```
+
+## API Reference
+
+### initializeLambdaClient(config?)
+
+Initializes the Lambda client with the provided configuration. If the client is already initialized, this will replace it with a new instance.
+
+**Parameters:**
+
+- `config` (optional): `LambdaClientConfig` - AWS SDK Lambda client configuration
+
+**Returns:** `LambdaClient` - The Lambda client instance
+
+### getLambdaClient()
+
+Returns the singleton Lambda client instance. If the client has not been initialized, creates one with default configuration.
+
+**Returns:** `LambdaClient` - The Lambda client instance
+
+### invokeLambdaSync<T>(functionName, payload)
+
+Invokes a Lambda function synchronously (RequestResponse). The function waits for the response and returns the payload.
+
+**Parameters:**
+
+- `functionName`: `string` - The name or ARN of the Lambda function to invoke
+- `payload`: `unknown` - The JSON payload to pass to the Lambda function
+
+**Returns:** `Promise<T>` - Promise that resolves to the response payload from the Lambda function
+
+**Throws:** `Error` - If the Lambda invocation fails or returns a function error
+
+### invokeLambdaAsync(functionName, payload)
+
+Invokes a Lambda function asynchronously (Event). The function returns immediately without waiting for the Lambda execution to complete.
+
+**Parameters:**
+
+- `functionName`: `string` - The name or ARN of the Lambda function to invoke
+- `payload`: `unknown` - The JSON payload to pass to the Lambda function
+
+**Returns:** `Promise<void>` - Promise that resolves when the invocation request is accepted
+
+**Throws:** `Error` - If the Lambda invocation request fails
+
+### resetLambdaClient()
+
+Resets the Lambda client instance. Useful for testing or when you need to reinitialize the client with a different configuration.
+
+**Returns:** `void`
+
+## Error Handling
+
+Both `invokeLambdaSync` and `invokeLambdaAsync` throw errors in the following cases:
+
+1. **Function Errors**: When the invoked Lambda function returns an error (e.g., unhandled exceptions)
+2. **AWS SDK Errors**: When the AWS SDK encounters an error (e.g., network issues, permission errors)
+
+```typescript
+import { invokeLambdaSync } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  try {
+    const response = await invokeLambdaSync('my-function', { key: 'value' });
+    return {
+      statusCode: 200,
+      body: JSON.stringify(response),
+    };
+  } catch (error) {
+    console.error('Lambda invocation failed:', error);
+    return {
+      statusCode: 500,
+      body: JSON.stringify({ error: 'Failed to invoke Lambda function' }),
+    };
+  }
+};
+```
+
+## Testing
+
+The utility provides a `resetLambdaClient()` function for testing purposes:
+
+```typescript
+import { resetLambdaClient, initializeLambdaClient } from '@leanstacks/lambda-utils';
+import { mockClient } from 'aws-sdk-client-mock';
+import { LambdaClient, InvokeCommand } from '@aws-sdk/client-lambda';
+
+describe('My Lambda Tests', () => {
+  const lambdaClientMock = mockClient(LambdaClient);
+
+  beforeEach(() => {
+    resetLambdaClient();
+    lambdaClientMock.reset();
+  });
+
+  it('should invoke Lambda function successfully', async () => {
+    // Mock the Lambda client response
+    const responsePayload = { result: 'success' };
+    const encoder = new TextEncoder();
+    const responseBytes = encoder.encode(JSON.stringify(responsePayload));
+
+    lambdaClientMock.on(InvokeCommand).resolves({
+      StatusCode: 200,
+      Payload: responseBytes,
+    });
+
+    // Test your code that uses invokeLambdaSync or invokeLambdaAsync
+    // ...
+  });
+});
+```
+
+## Best Practices
+
+1. **Singleton Pattern**: The Lambda client is created once and reused across invocations, improving performance by reducing initialization overhead.
+
+2. **Error Handling**: Always wrap Lambda invocations in try-catch blocks to handle potential errors gracefully.
+
+3. **Type Safety**: Use TypeScript generics to specify the expected response type for synchronous invocations:
+
+   ```typescript
+   const response = await invokeLambdaSync<MyResponseType>('my-function', payload);
+   ```
+
+4. **Async vs Sync**: Choose the appropriate invocation type:
+   - Use `invokeLambdaSync` when you need to wait for and process the response
+   - Use `invokeLambdaAsync` for fire-and-forget scenarios to improve performance
+
+5. **IAM Permissions**: Ensure your Lambda function has the necessary IAM permissions to invoke other Lambda functions:
+   ```json
+   {
+     "Effect": "Allow",
+     "Action": ["lambda:InvokeFunction"],
+     "Resource": "arn:aws:lambda:region:account-id:function:function-name"
+   }
+   ```
+
+## See Also
+
+- [AWS SDK for JavaScript - Lambda Client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-lambda/)
+- [AWS Lambda Developer Guide - Invoking Functions](https://docs.aws.amazon.com/lambda/latest/dg/lambda-invocation.html)
+- [DynamoDB Client Documentation](./DYNAMODB_CLIENT.md)
+- [SNS Client Documentation](./SNS_CLIENT.md)

package/docs/README.md

@@ -8,18 +8,20 @@ Lambda Utilities is a collection of pre-configured tools and helpers designed to
 
 ## Documentation
 
+- **[Configuration Guide](./CONFIGURATION.md)** – Validate environment variables with Zod schemas and type-safe configuration management
 - **[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
 - **[DynamoDB Client](./DYNAMODB_CLIENT.md)** – Reusable singleton DynamoDB client instances with custom configuration
-- **[Configuration](./CONFIGURATION.md)** – Validate environment variables and configuration with Zod type safety
-- **[Getting Started](./GETTING_STARTED.md)** – Quick setup and installation instructions
+- **[Lambda Client](./LAMBDA_CLIENT.md)** – Reusable singleton Lambda client for invoking other Lambda functions
+- **[SNS Client](./SNS_CLIENT.md)** – Reusable singleton SNS client for publishing messages to topics with message attributes
+- **[SQS Client](./SQS_CLIENT.md)** – Reusable singleton SQS client for sending messages to queues with message attributes
 
 ## Features
 
 - 📝 **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
+- 🔌 **AWS Clients** – Pre-configured AWS SDK v3 clients for DynamoDB, SNS, SQS, and Lambda
 - 🔒 **Type Safe** – Full TypeScript support with comprehensive type definitions
 
 ## Support