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

package/README.md

@@ -67,7 +67,7 @@ export const handler = async (event: APIGatewayProxyEvent) => {
 - **📝 Structured Logging** – Pino logger pre-configured for Lambda with automatic AWS request context enrichment
 - **📤 API Response Helpers** – Standard response formatting for API Gateway with proper HTTP status codes
 - **⚙️ Configuration Validation** – Environment variable validation with Zod schema support
-- **🔌 AWS SDK Clients** – Pre-configured AWS SDK v3 clients for DynamoDB, Lambda, and more
+- **🔌 AWS SDK Clients** – Pre-configured AWS SDK v3 clients including DynamoDB with document client support
 - **🔒 Full TypeScript Support** – Complete type definitions and IDE autocomplete
 - **⚡ Lambda Optimized** – Designed for performance in serverless environments
 
@@ -79,9 +79,7 @@ Comprehensive guides and examples are available in the `docs` directory:
 | ------------------------------------------------------------ | ---------------------------------------------------------------------- |
 | **[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           |
-| **[Configuration](./docs/CONFIGURATION.md)**                 | Validate and manage environment variables with type safety             |
-| **[AWS Clients](./docs/CLIENTS.md)**                         | Use pre-configured AWS SDK v3 clients in your handlers                 |
-| **[Getting Started](./docs/GETTING_STARTED.md)**             | Setup and first steps guide                                            |
+| **[AWS Clients](./docs/README.md)**                          | Use pre-configured AWS SDK v3 clients in your handlers                 |
 
 ## Usage
 
@@ -119,39 +117,35 @@ export const handler = async (event: APIGatewayProxyEvent) => {
 
 **→ See [API Gateway Responses](./docs/API_GATEWAY_RESPONSES.md) for all response types**
 
-### Configuration Validation
-
-Validate your Lambda environment configuration:
-
-```typescript
-import { validateConfig } from '@leanstacks/lambda-utils';
-import { z } from 'zod';
-
-const configSchema = z.object({
-  DATABASE_URL: z.string().url(),
-  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']),
-  API_KEY: z.string(),
-});
-
-const config = validateConfig(configSchema);
-```
+### AWS Clients
 
-**→ See [Configuration](./docs/CONFIGURATION.md) for validation patterns**
+Use pre-configured AWS SDK v3 clients. Currently available:
 
-### AWS Clients
+#### DynamoDB Client
 
-Use pre-configured AWS SDK v3 clients:
+Initialize the DynamoDB clients (base client and document client) once during handler initialization:
 
 ```typescript
-import { getDynamoDBClient, getLambdaClient } from '@leanstacks/lambda-utils';
+import { initializeDynamoDBClients, getDynamoDBDocumentClient } from '@leanstacks/lambda-utils';
 
-const dynamoDB = getDynamoDBClient();
-const lambda = getLambdaClient();
+export const handler = async (event: any, context: any) => {
+  // Initialize clients once
+  initializeDynamoDBClients({ region: 'us-east-1' });
+
+  // Use the document client for operations
+  const docClient = getDynamoDBDocumentClient();
+  const result = await docClient.get({
+    TableName: 'MyTable',
+    Key: { id: 'item-123' },
+  });
 
-// Use clients for API calls
+  return { statusCode: 200, body: JSON.stringify(result) };
+};
 ```
 
-**→ See [AWS Clients](./docs/CLIENTS.md) for available clients and examples**
+**→ See [DynamoDB Client Guide](./docs/DYNAMODB_CLIENT.md) for detailed configuration and examples**
+
+Additional AWS Clients are coming soon.
 
 ## Examples
 

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 export { Logger, LoggerConfig, withRequestTracking } from './logging/logger';
 export { createResponse, ok, created, noContent, badRequest, notFound, internalServerError, httpHeaders, Headers, } from './utils/apigateway-response';
 export { getDynamoDBClient, getDynamoDBDocumentClient, initializeDynamoDBClients, resetDynamoDBClients, } from './clients/dynamodb-client';
-export { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-export { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+export { createConfigManager, ConfigManager } from './validation/config';

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 i}from"pino-lambda";import{DynamoDBClient as l}from"@aws-sdk/client-dynamodb";export{DynamoDBClient}from"@aws-sdk/client-dynamodb";import{DynamoDBDocumentClient as r}from"@aws-sdk/lib-dynamodb";export{DynamoDBDocumentClient}from"@aws-sdk/lib-dynamodb";const s=e();class a{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,l=i({formatter:e});return n({enabled:this._loggerConfig.enabled,level:this._loggerConfig.level},l)},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})},c=(n,e,t={})=>({statusCode:n,headers:{...t},body:JSON.stringify(e)}),d=(n,e={})=>c(200,n,e),g=(n,e={})=>c(201,n,e),f=(n={})=>c(204,{},n),u=(n="Bad Request",e={})=>c(400,{message:n},e),h=(n="Not Found",e={})=>c(404,{message:n},e),p=(n="Internal Server Error",e={})=>c(500,{message:n},e);let C=null,y=null;const D=(n,e,t)=>{C=new l(n||{});const o={marshallOptions:e||{},unmarshallOptions:t||{}};return y=r.from(C,o),{client:C,documentClient:y}},b=()=>{if(!C)throw new Error("DynamoDB client not initialized. Call initializeDynamoDBClients() first.");return C},w=()=>{if(!y)throw new Error("DynamoDB Document client not initialized. Call initializeDynamoDBClients() first.");return y},_=()=>{C=null,y=null};export{a as Logger,u as badRequest,c as createResponse,g as created,b as getDynamoDBClient,w as getDynamoDBDocumentClient,m as httpHeaders,D as initializeDynamoDBClients,p as internalServerError,f as noContent,h as notFound,d as ok,_ as resetDynamoDBClients,s 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("\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};
 //# 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"),o=require("@aws-sdk/lib-dynamodb");const r=t.lambdaRequestTracker();const i=(e,t,n={})=>({statusCode:e,headers:{...n},body:JSON.stringify(t)});let s=null,a=null;Object.defineProperty(exports,"DynamoDBClient",{enumerable:!0,get:function(){return n.DynamoDBClient}}),Object.defineProperty(exports,"DynamoDBDocumentClient",{enumerable:!0,get:function(){return o.DynamoDBDocumentClient}}),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,o=t.pinoLambdaDestination({formatter:n});return e({enabled:this._loggerConfig.enabled,level:this._loggerConfig.level},o)},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={})=>i(400,{message:e},t),exports.createResponse=i,exports.created=(e,t={})=>i(201,e,t),exports.getDynamoDBClient=()=>{if(!s)throw new Error("DynamoDB client not initialized. Call initializeDynamoDBClients() first.");return s},exports.getDynamoDBDocumentClient=()=>{if(!a)throw new Error("DynamoDB Document client not initialized. Call initializeDynamoDBClients() first.");return a},exports.httpHeaders={contentType:e=>({"Content-Type":e}),json:{"Content-Type":"application/json"},cors:(e="*")=>({"Access-Control-Allow-Origin":e})},exports.initializeDynamoDBClients=(e,t,r)=>{s=new n.DynamoDBClient(e||{});const i={marshallOptions:t||{},unmarshallOptions:r||{}};return a=o.DynamoDBDocumentClient.from(s,i),{client:s,documentClient:a}},exports.internalServerError=(e="Internal Server Error",t={})=>i(500,{message:e},t),exports.noContent=(e={})=>i(204,{},e),exports.notFound=(e="Not Found",t={})=>i(404,{message:e},t),exports.ok=(e,t={})=>i(200,e,t),exports.resetDynamoDBClients=()=>{s=null,a=null},exports.withRequestTracking=r;
+"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;
 //# sourceMappingURL=index.js.map

package/dist/validation/config.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+/**
+ * Interface for a configuration manager instance
+ */
+export interface ConfigManager<T> {
+    /**
+     * Get the validated configuration (cached after first call)
+     * @throws {Error} if validation fails
+     * @returns The validated configuration object
+     */
+    get: () => T;
+    /**
+     * Refresh the configuration by re-validating environment variables
+     * Useful in tests when environment variables are changed
+     * @throws {Error} if validation fails
+     * @returns The newly validated configuration object
+     */
+    refresh: () => T;
+}
+/**
+ * Creates a reusable configuration manager for any Lambda function
+ *
+ * @template T - The configuration type inferred from the provided Zod schema
+ * @param schema - A Zod schema that defines the structure and validation rules for environment variables
+ * @returns A ConfigManager instance with get() and refresh() methods
+ *
+ * @example
+ * ```typescript
+ * // Define your schema
+ * const configSchema = z.object({
+ *   TABLE_NAME: z.string().min(1),
+ *   AWS_REGION: z.string().default('us-east-1'),
+ * });
+ *
+ * // Create config manager
+ * const configManager = createConfigManager(configSchema);
+ *
+ * // Access configuration (cached on first call)
+ * const config = configManager.get();
+ *
+ * // Type your config
+ * type Config = z.infer<typeof configSchema>;
+ * ```
+ */
+export declare const createConfigManager: <T extends z.ZodSchema>(schema: T) => ConfigManager<z.infer<T>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leanstacks/lambda-utils",
-  "version": "0.3.0-alpha.2",
+  "version": "0.3.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",
   "module": "dist/index.esm.js",
@@ -63,9 +63,10 @@
     "typescript": "5.9.3"
   },
   "dependencies": {
-    "@aws-sdk/client-dynamodb": "^3.955.0",
-    "@aws-sdk/lib-dynamodb": "^3.955.0",
-    "pino": "^10.1.0",
-    "pino-lambda": "^4.4.1"
+    "@aws-sdk/client-dynamodb": "3.955.0",
+    "@aws-sdk/lib-dynamodb": "3.955.0",
+    "pino": "10.1.0",
+    "pino-lambda": "4.4.1",
+    "zod": "4.2.1"
   }
 }