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

package/README.md

@@ -46,6 +46,33 @@ export const handler = async (event: any, context: any) => {
 };
 ```
 
+### Configuration Example
+
+```typescript
+import { z } from 'zod';
+import { createConfigManager } from '@leanstacks/lambda-utils';
+
+// Define your configuration schema
+const configSchema = z.object({
+  TABLE_NAME: z.string().min(1),
+  AWS_REGION: z.string().default('us-east-1'),
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+});
+
+type Config = z.infer<typeof configSchema>;
+
+const configManager = createConfigManager(configSchema);
+const config = configManager.get();
+
+export const handler = async (event: any) => {
+  console.log(`Using table: ${config.TABLE_NAME}`);
+
+  // Your Lambda handler logic here
+
+  return { statusCode: 200, body: 'Success' };
+};
+```
+
 ### API Response Example
 
 ```typescript
@@ -77,12 +104,35 @@ Comprehensive guides and examples are available in the `docs` directory:
 
 | Guide                                                        | Description                                                            |
 | ------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| **[Configuration Guide](./docs/CONFIGURATION.md)**           | Validate environment variables with Zod schemas and type safety        |
 | **[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           |
-| **[AWS Clients](./docs/README.md)**                          | Use pre-configured AWS SDK v3 clients in your handlers                 |
+| **[DynamoDB Client](./docs/DYNAMODB_CLIENT.md)**             | Use pre-configured AWS SDK v3 clients in your handlers                 |
 
 ## Usage
 
+### Configuration
+
+Validate and manage environment variables with type safety:
+
+```typescript
+import { z } from 'zod';
+import { createConfigManager } from '@leanstacks/lambda-utils';
+
+const configManager = createConfigManager(
+  z.object({
+    TABLE_NAME: z.string().min(1),
+    AWS_REGION: z.string().default('us-east-1'),
+  }),
+);
+
+const config = configManager.get();
+// TypeScript infers type from schema
+// Validation errors thrown immediately
+```
+
+**→ See [Configuration Guide](./docs/CONFIGURATION.md) for detailed validation patterns and best practices**
+
 ### Logging
 
 The Logger utility provides structured logging configured specifically for AWS Lambda:

package/dist/index.esm.js

@@ -1,2 +1,2 @@
-import n from"pino";import{lambdaRequestTracker as e,StructuredLogFormatter as t,CloudwatchLogFormatter as o,pinoLambdaDestination as r}from"pino-lambda";import{DynamoDBClient as i}from"@aws-sdk/client-dynamodb";import{DynamoDBDocumentClient as s}from"@aws-sdk/lib-dynamodb";import{z as l}from"zod";const a=e();class c{constructor(e){this._loggerConfig={enabled:!0,level:"info",format:"json"},this._instance=null,this._createLogger=()=>{const e="json"===this._loggerConfig.format?new t:new o,i=r({formatter:e});return n({enabled:this._loggerConfig.enabled,level:this._loggerConfig.level},i)},e&&(this._loggerConfig={enabled:e.enabled??!0,level:e.level??"info",format:e.format??"json"})}get instance(){return null===this._instance&&(this._instance=this._createLogger()),this._instance}}const m={contentType:n=>({"Content-Type":n}),json:{"Content-Type":"application/json"},cors:(n="*")=>({"Access-Control-Allow-Origin":n})},f=(n,e,t={})=>({statusCode:n,headers:{...t},body:JSON.stringify(e)}),g=(n,e={})=>f(200,n,e),d=(n,e={})=>f(201,n,e),u=(n={})=>f(204,{},n),h=(n="Bad Request",e={})=>f(400,{message:n},e),p=(n="Not Found",e={})=>f(404,{message:n},e),C=(n="Internal Server Error",e={})=>f(500,{message:n},e);let w=null,y=null;const _=(n,e,t)=>{w=new i(n||{});const o={marshallOptions:e||{},unmarshallOptions:t||{}};return y=s.from(w,o),{client:w,documentClient:y}},b=()=>{if(!w)throw new Error("DynamoDB client not initialized. Call initializeDynamoDBClients() first.");return w},D=()=>{if(!y)throw new Error("DynamoDB Document client not initialized. Call initializeDynamoDBClients() first.");return y},v=()=>{w=null,y=null},j=n=>{let e=null;const t=()=>{try{return n.parse(process.env)}catch(n){if(n instanceof l.ZodError){const e=n.issues.map(n=>`${n.path.join(".")}: ${n.message}`).join("\n");throw new Error(`Configuration validation failed:\n${e}`)}throw n}};return{get:()=>(e||(e=t()),e),refresh:()=>(e=t(),e)}};export{c as Logger,h as badRequest,j as createConfigManager,f as createResponse,d as created,b as getDynamoDBClient,D as getDynamoDBDocumentClient,m as httpHeaders,_ as initializeDynamoDBClients,C as internalServerError,u as noContent,p as notFound,g as ok,v as resetDynamoDBClients,a as withRequestTracking};
+import n from"pino";import{lambdaRequestTracker as e,StructuredLogFormatter as t,CloudwatchLogFormatter as o,pinoLambdaDestination as r}from"pino-lambda";import{DynamoDBClient as i}from"@aws-sdk/client-dynamodb";import{DynamoDBDocumentClient as s}from"@aws-sdk/lib-dynamodb";import{z as l}from"zod";const a=e();class c{constructor(e){this._loggerConfig={enabled:!0,level:"info",format:"json"},this._instance=null,this._createLogger=()=>{const e="json"===this._loggerConfig.format?new t:new o,i=r({formatter:e});return n({enabled:this._loggerConfig.enabled,level:this._loggerConfig.level},i)},e&&(this._loggerConfig={enabled:e.enabled??!0,level:e.level??"info",format:e.format??"json"})}get instance(){return null===this._instance&&(this._instance=this._createLogger()),this._instance}}const m={contentType:n=>({"Content-Type":n}),json:{"Content-Type":"application/json"},cors:(n="*")=>({"Access-Control-Allow-Origin":n})},f=(n,e,t={})=>({statusCode:n,headers:{...t},body:JSON.stringify(e)}),g=(n,e={})=>f(200,n,e),d=(n,e={})=>f(201,n,e),u=(n={})=>f(204,{},n),h=(n="Bad Request",e={})=>f(400,{message:n},e),p=(n="Not Found",e={})=>f(404,{message:n},e),C=(n="Internal Server Error",e={})=>f(500,{message:n},e);let w=null,y=null;const _=(n,e,t)=>{w=new i(n||{});const o={marshallOptions:e||{},unmarshallOptions:t||{}};return y=s.from(w,o),{client:w,documentClient:y}},b=()=>{if(!w)throw new Error("DynamoDB client not initialized. Call initializeDynamoDBClients() first.");return w},D=()=>{if(!y)throw new Error("DynamoDB Document client not initialized. Call initializeDynamoDBClients() first.");return y},v=()=>{w=null,y=null},j=n=>{let e=null;const t=()=>{try{return n.parse(process.env)}catch(n){if(n instanceof l.ZodError){const e=n.issues.map(n=>`${n.path.join(".")}: ${n.message}`).join(", ");throw new Error(`Configuration validation failed: ${e}`)}throw n}};return{get:()=>(e||(e=t()),e),refresh:()=>(e=t(),e)}};export{c as Logger,h as badRequest,j as createConfigManager,f as createResponse,d as created,b as getDynamoDBClient,D as getDynamoDBDocumentClient,m as httpHeaders,_ as initializeDynamoDBClients,C as internalServerError,u as noContent,p as notFound,g as ok,v as resetDynamoDBClients,a as withRequestTracking};
 //# sourceMappingURL=index.esm.js.map

package/dist/index.js

@@ -1,2 +1,2 @@
-"use strict";var e=require("pino"),t=require("pino-lambda"),n=require("@aws-sdk/client-dynamodb"),r=require("@aws-sdk/lib-dynamodb"),o=require("zod");const i=t.lambdaRequestTracker();const s=(e,t,n={})=>({statusCode:e,headers:{...n},body:JSON.stringify(t)});let a=null,l=null;exports.Logger=class{constructor(n){this._loggerConfig={enabled:!0,level:"info",format:"json"},this._instance=null,this._createLogger=()=>{const n="json"===this._loggerConfig.format?new t.StructuredLogFormatter:new t.CloudwatchLogFormatter,r=t.pinoLambdaDestination({formatter:n});return e({enabled:this._loggerConfig.enabled,level:this._loggerConfig.level},r)},n&&(this._loggerConfig={enabled:n.enabled??!0,level:n.level??"info",format:n.format??"json"})}get instance(){return null===this._instance&&(this._instance=this._createLogger()),this._instance}},exports.badRequest=(e="Bad Request",t={})=>s(400,{message:e},t),exports.createConfigManager=e=>{let t=null;const n=()=>{try{return e.parse(process.env)}catch(e){if(e instanceof o.z.ZodError){const t=e.issues.map(e=>`${e.path.join(".")}: ${e.message}`).join("\n");throw new Error(`Configuration validation failed:\n${t}`)}throw e}};return{get:()=>(t||(t=n()),t),refresh:()=>(t=n(),t)}},exports.createResponse=s,exports.created=(e,t={})=>s(201,e,t),exports.getDynamoDBClient=()=>{if(!a)throw new Error("DynamoDB client not initialized. Call initializeDynamoDBClients() first.");return a},exports.getDynamoDBDocumentClient=()=>{if(!l)throw new Error("DynamoDB Document client not initialized. Call initializeDynamoDBClients() first.");return l},exports.httpHeaders={contentType:e=>({"Content-Type":e}),json:{"Content-Type":"application/json"},cors:(e="*")=>({"Access-Control-Allow-Origin":e})},exports.initializeDynamoDBClients=(e,t,o)=>{a=new n.DynamoDBClient(e||{});const i={marshallOptions:t||{},unmarshallOptions:o||{}};return l=r.DynamoDBDocumentClient.from(a,i),{client:a,documentClient:l}},exports.internalServerError=(e="Internal Server Error",t={})=>s(500,{message:e},t),exports.noContent=(e={})=>s(204,{},e),exports.notFound=(e="Not Found",t={})=>s(404,{message:e},t),exports.ok=(e,t={})=>s(200,e,t),exports.resetDynamoDBClients=()=>{a=null,l=null},exports.withRequestTracking=i;
+"use strict";var e=require("pino"),t=require("pino-lambda"),n=require("@aws-sdk/client-dynamodb"),r=require("@aws-sdk/lib-dynamodb"),o=require("zod");const i=t.lambdaRequestTracker();const s=(e,t,n={})=>({statusCode:e,headers:{...n},body:JSON.stringify(t)});let a=null,l=null;exports.Logger=class{constructor(n){this._loggerConfig={enabled:!0,level:"info",format:"json"},this._instance=null,this._createLogger=()=>{const n="json"===this._loggerConfig.format?new t.StructuredLogFormatter:new t.CloudwatchLogFormatter,r=t.pinoLambdaDestination({formatter:n});return e({enabled:this._loggerConfig.enabled,level:this._loggerConfig.level},r)},n&&(this._loggerConfig={enabled:n.enabled??!0,level:n.level??"info",format:n.format??"json"})}get instance(){return null===this._instance&&(this._instance=this._createLogger()),this._instance}},exports.badRequest=(e="Bad Request",t={})=>s(400,{message:e},t),exports.createConfigManager=e=>{let t=null;const n=()=>{try{return e.parse(process.env)}catch(e){if(e instanceof o.z.ZodError){const t=e.issues.map(e=>`${e.path.join(".")}: ${e.message}`).join(", ");throw new Error(`Configuration validation failed: ${t}`)}throw e}};return{get:()=>(t||(t=n()),t),refresh:()=>(t=n(),t)}},exports.createResponse=s,exports.created=(e,t={})=>s(201,e,t),exports.getDynamoDBClient=()=>{if(!a)throw new Error("DynamoDB client not initialized. Call initializeDynamoDBClients() first.");return a},exports.getDynamoDBDocumentClient=()=>{if(!l)throw new Error("DynamoDB Document client not initialized. Call initializeDynamoDBClients() first.");return l},exports.httpHeaders={contentType:e=>({"Content-Type":e}),json:{"Content-Type":"application/json"},cors:(e="*")=>({"Access-Control-Allow-Origin":e})},exports.initializeDynamoDBClients=(e,t,o)=>{a=new n.DynamoDBClient(e||{});const i={marshallOptions:t||{},unmarshallOptions:o||{}};return l=r.DynamoDBDocumentClient.from(a,i),{client:a,documentClient:l}},exports.internalServerError=(e="Internal Server Error",t={})=>s(500,{message:e},t),exports.noContent=(e={})=>s(204,{},e),exports.notFound=(e="Not Found",t={})=>s(404,{message:e},t),exports.ok=(e,t={})=>s(200,e,t),exports.resetDynamoDBClients=()=>{a=null,l=null},exports.withRequestTracking=i;
 //# sourceMappingURL=index.js.map

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/README.md

@@ -8,11 +8,10 @@ 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
 
 ## Features
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leanstacks/lambda-utils",
-  "version": "0.3.0-alpha.4",
+  "version": "0.3.0",
   "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",
@@ -55,7 +55,7 @@
     "jest": "30.2.0",
     "prettier": "3.7.4",
     "rimraf": "6.1.2",
-    "rollup": "4.53.5",
+    "rollup": "4.54.0",
     "rollup-plugin-peer-deps-external": "2.2.4",
     "rollup-plugin-typescript2": "0.36.0",
     "ts-jest": "29.4.6",
@@ -63,8 +63,8 @@
     "typescript": "5.9.3"
   },
   "dependencies": {
-    "@aws-sdk/client-dynamodb": "3.955.0",
-    "@aws-sdk/lib-dynamodb": "3.955.0",
+    "@aws-sdk/client-dynamodb": "3.956.0",
+    "@aws-sdk/lib-dynamodb": "3.956.0",
     "pino": "10.1.0",
     "pino-lambda": "4.4.1",
     "zod": "4.2.1"