@leanstacks/lambda-utils 0.2.0-alpha.3 → 0.3.0-alpha.1

package/README.md

@@ -49,16 +49,16 @@ export const handler = async (event: any, context: any) => {
 ### API Response Example
 
 ```typescript
-import { success, badRequest } from '@leanstacks/lambda-utils';
+import { ok, badRequest } from '@leanstacks/lambda-utils';
 
-export const handler = async (event: any) => {
+export const handler = async (event: APIGatewayProxyEvent) => {
   if (!event.body) {
-    return badRequest({ message: 'Body is required' });
+    return badRequest('Body is required');
   }
 
   // Process request
 
-  return success({ message: 'Request processed successfully' });
+  return ok({ message: 'Request processed successfully' });
 };
 ```
 
@@ -108,10 +108,10 @@ logger.error({ message: 'Operation failed', error: err.message });
 Generate properly formatted responses for API Gateway:
 
 ```typescript
-import { success, error, created, badRequest } from '@leanstacks/lambda-utils';
+import { ok, created, badRequest } from '@leanstacks/lambda-utils';
 
-export const handler = async (event: any) => {
-  return success({
+export const handler = async (event: APIGatewayProxyEvent) => {
+  return ok({
     data: { id: '123', name: 'Example' },
   });
 };

package/dist/clients/dynamodb-client.d.ts

@@ -0,0 +1,59 @@
+import { DynamoDBClient, DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient, marshallOptions as MarshallOptions, unmarshallOptions as UnmarshallOptions } from '@aws-sdk/lib-dynamodb';
+/**
+ * Initializes both the DynamoDB client and DynamoDB Document client with the provided configuration.
+ * If the clients are already initialized, this will replace them with new instances.
+ *
+ * @param config - DynamoDB client configuration
+ * @param marshallOptions - Options for marshalling JavaScript objects to DynamoDB AttributeValues
+ * @param unmarshallOptions - Options for unmarshalling DynamoDB AttributeValues to JavaScript objects
+ * @returns An object containing both the base client and document client
+ *
+ * @example
+ * ```typescript
+ * // Initialize with default configuration
+ * initializeDynamoDBClients();
+ *
+ * // Initialize with custom configuration
+ * initializeDynamoDBClients(
+ *   { region: 'us-east-1' },
+ *   { removeUndefinedValues: true },
+ *   { wrapNumbers: false }
+ * );
+ * ```
+ */
+export declare const initializeDynamoDBClients: (config?: DynamoDBClientConfig, marshallOptions?: MarshallOptions, unmarshallOptions?: UnmarshallOptions) => {
+    client: DynamoDBClient;
+    documentClient: DynamoDBDocumentClient;
+};
+/**
+ * Returns the singleton DynamoDB client instance.
+ * Throws an error if the client has not been initialized.
+ *
+ * @returns The DynamoDB client instance
+ * @throws Error if the client has not been initialized
+ *
+ * @example
+ * ```typescript
+ * const client = getDynamoDBClient();
+ * ```
+ */
+export declare const getDynamoDBClient: () => DynamoDBClient;
+/**
+ * Returns the singleton DynamoDB Document client instance.
+ * Throws an error if the client has not been initialized.
+ *
+ * @returns The DynamoDB Document client instance
+ * @throws Error if the client has not been initialized
+ *
+ * @example
+ * ```typescript
+ * const docClient = getDynamoDBDocumentClient();
+ * ```
+ */
+export declare const getDynamoDBDocumentClient: () => DynamoDBDocumentClient;
+/**
+ * Resets both DynamoDB client instances.
+ * Useful for testing or when you need to reinitialize the clients with different configurations.
+ */
+export declare const resetDynamoDBClients: () => void;

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 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';

package/dist/index.esm.js

@@ -1,2 +1,2 @@
-import e from"pino";import{lambdaRequestTracker as n,StructuredLogFormatter as o,CloudwatchLogFormatter as t,pinoLambdaDestination as s}from"pino-lambda";const r=n();class i{constructor(n){this._loggerConfig={enabled:!0,level:"info",format:"json"},this._instance=null,this._createLogger=()=>{const n="json"===this._loggerConfig.format?new o:new t,r=s({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}}const l={contentType:e=>({"Content-Type":e}),json:{"Content-Type":"application/json"},cors:(e="*")=>({"Access-Control-Allow-Origin":e})},a=(e,n,o={})=>({statusCode:e,headers:{...o},body:JSON.stringify(n)}),g=(e,n={})=>a(200,e,n),c=(e,n={})=>a(201,e,n),f=(e={})=>a(204,{},e),m=(e="Bad Request",n={})=>a(400,{message:e},n),h=(e="Not Found",n={})=>a(404,{message:e},n),d=(e="Internal Server Error",n={})=>a(500,{message:e},n);export{i as Logger,m as badRequest,a as createResponse,c as created,l as httpHeaders,d as internalServerError,f as noContent,h as notFound,g as ok,r as withRequestTracking};
+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";import{DynamoDBDocumentClient as r}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)}),g=(n,e={})=>c(200,n,e),f=(n,e={})=>c(201,n,e),d=(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 _=(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},D=()=>{C=null,y=null};export{a as Logger,u as badRequest,c as createResponse,f as created,b as getDynamoDBClient,w as getDynamoDBDocumentClient,m as httpHeaders,_ as initializeDynamoDBClients,p as internalServerError,d as noContent,h as notFound,g as ok,D as resetDynamoDBClients,s 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");const o=t.lambdaRequestTracker();const r=(e,t,o={})=>({statusCode:e,headers:{...o},body:JSON.stringify(t)});exports.Logger=class{constructor(o){this._loggerConfig={enabled:!0,level:"info",format:"json"},this._instance=null,this._createLogger=()=>{const o="json"===this._loggerConfig.format?new t.StructuredLogFormatter:new t.CloudwatchLogFormatter,r=t.pinoLambdaDestination({formatter:o});return e({enabled:this._loggerConfig.enabled,level:this._loggerConfig.level},r)},o&&(this._loggerConfig={enabled:o.enabled??!0,level:o.level??"info",format:o.format??"json"})}get instance(){return null===this._instance&&(this._instance=this._createLogger()),this._instance}},exports.badRequest=(e="Bad Request",t={})=>r(400,{message:e},t),exports.createResponse=r,exports.created=(e,t={})=>r(201,e,t),exports.httpHeaders={contentType:e=>({"Content-Type":e}),json:{"Content-Type":"application/json"},cors:(e="*")=>({"Access-Control-Allow-Origin":e})},exports.internalServerError=(e="Internal Server Error",t={})=>r(500,{message:e},t),exports.noContent=(e={})=>r(204,{},e),exports.notFound=(e="Not Found",t={})=>r(404,{message:e},t),exports.ok=(e,t={})=>r(200,e,t),exports.withRequestTracking=o;
+"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;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;
 //# sourceMappingURL=index.js.map

package/docs/API_GATEWAY_RESPONSES.md

@@ -0,0 +1,451 @@
+# API Gateway Responses Guide
+
+The Lambda Utilities library provides a set of helper functions for creating properly formatted API Gateway responses. These utilities abstract away the boilerplate of response construction and ensure consistent response formatting across your Lambda functions.
+
+## Overview
+
+API Gateway responses require a specific structure with a status code, headers, and a JSON-stringified body. The response helpers provided by Lambda Utilities simplify this by:
+
+- Providing typed functions for common HTTP status codes
+- Managing automatic JSON serialization
+- Supporting custom headers
+- Ensuring consistency with AWS Lambda proxy integration specifications
+
+## Installation
+
+```bash
+npm install @leanstacks/lambda-utils
+```
+
+## Basic Usage
+
+### Creating Responses
+
+Import the response helpers from Lambda Utilities:
+
+```typescript
+import { ok, created, badRequest, notFound, internalServerError } from '@leanstacks/lambda-utils';
+```
+
+### Response Functions
+
+#### `ok(body, headers?)`
+
+Creates a **200 OK** response.
+
+```typescript
+export const handler = async (event: any) => {
+  const data = { id: '123', name: 'Example' };
+  return ok(data);
+};
+
+// Response:
+// {
+//   statusCode: 200,
+//   body: '{"id":"123","name":"Example"}',
+//   headers: {}
+// }
+```
+
+#### `created(body, headers?)`
+
+Creates a **201 Created** response, typically used when a resource is successfully created.
+
+```typescript
+export const handler = async (event: any) => {
+  const newResource = { id: '456', name: 'New Resource' };
+  return created(newResource);
+};
+
+// Response:
+// {
+//   statusCode: 201,
+//   body: '{"id":"456","name":"New Resource"}',
+//   headers: {}
+// }
+```
+
+#### `noContent(headers?)`
+
+Creates a **204 No Content** response, used when the request is successful but there's no content to return.
+
+```typescript
+export const handler = async (event: any) => {
+  // Delete operation
+  return noContent();
+};
+
+// Response:
+// {
+//   statusCode: 204,
+//   body: '{}',
+//   headers: {}
+// }
+```
+
+#### `badRequest(message?, headers?)`
+
+Creates a **400 Bad Request** error response.
+
+```typescript
+export const handler = async (event: any) => {
+  if (!event.body) {
+    return badRequest('Request body is required');
+  }
+};
+
+// Response:
+// {
+//   statusCode: 400,
+//   body: '{"message":"Request body is required"}',
+//   headers: {}
+// }
+```
+
+#### `notFound(message?, headers?)`
+
+Creates a **404 Not Found** error response.
+
+```typescript
+export const handler = async (event: any) => {
+  const resource = await getResource(event.pathParameters.id);
+
+  if (!resource) {
+    return notFound(`Resource with id ${event.pathParameters.id} not found`);
+  }
+
+  return ok(resource);
+};
+
+// Response:
+// {
+//   statusCode: 404,
+//   body: '{"message":"Resource with id 123 not found"}',
+//   headers: {}
+// }
+```
+
+#### `internalServerError(message?, headers?)`
+
+Creates a **500 Internal Server Error** response.
+
+```typescript
+export const handler = async (event: any) => {
+  try {
+    // Process request
+  } catch (error) {
+    return internalServerError('An unexpected error occurred');
+  }
+};
+
+// Response:
+// {
+//   statusCode: 500,
+//   body: '{"message":"An unexpected error occurred"}',
+//   headers: {}
+// }
+```
+
+#### `createResponse(statusCode, body, headers?)`
+
+Creates a custom response with any status code. Use this for status codes not covered by the helper functions.
+
+```typescript
+import { createResponse } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  return createResponse(202, { status: 'Accepted' });
+};
+
+// Response:
+// {
+//   statusCode: 202,
+//   body: '{"status":"Accepted"}',
+//   headers: {}
+// }
+```
+
+## Headers
+
+### HTTP Headers Helpers
+
+Lambda Utilities provides a `httpHeaders` object with common header builders:
+
+#### `httpHeaders.json`
+
+Sets the `Content-Type` header to `application/json`.
+
+```typescript
+import { ok, httpHeaders } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  return ok({ message: 'Success' }, httpHeaders.json);
+};
+
+// Response:
+// {
+//   statusCode: 200,
+//   body: '{"message":"Success"}',
+//   headers: { 'Content-Type': 'application/json' }
+// }
+```
+
+#### `httpHeaders.contentType(type)`
+
+Sets the `Content-Type` header to a custom MIME type.
+
+```typescript
+import { ok, httpHeaders } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  return ok(csvData, httpHeaders.contentType('text/csv'));
+};
+
+// Response:
+// {
+//   statusCode: 200,
+//   body: '...',
+//   headers: { 'Content-Type': 'text/csv' }
+// }
+```
+
+#### `httpHeaders.cors(origin?)`
+
+Sets the `Access-Control-Allow-Origin` header for CORS support. Default is `*`.
+
+```typescript
+import { ok, httpHeaders } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  return ok({ data: '...' }, httpHeaders.cors('https://example.com'));
+};
+
+// Response:
+// {
+//   statusCode: 200,
+//   body: '{"data":"..."}',
+//   headers: { 'Access-Control-Allow-Origin': 'https://example.com' }
+// }
+```
+
+### Custom Headers
+
+Combine multiple headers or add custom ones by passing a headers object:
+
+```typescript
+import { ok, httpHeaders } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  const headers = {
+    ...httpHeaders.json,
+    ...httpHeaders.cors(),
+    'X-Custom-Header': 'value',
+  };
+
+  return ok({ message: 'Success' }, headers);
+};
+
+// Response:
+// {
+//   statusCode: 200,
+//   body: '{"message":"Success"}',
+//   headers: {
+//     'Content-Type': 'application/json',
+//     'Access-Control-Allow-Origin': '*',
+//     'X-Custom-Header': 'value'
+//   }
+// }
+```
+
+## Complete Examples
+
+### Validation and Error Handling
+
+```typescript
+import { ok, badRequest, internalServerError, httpHeaders } from '@leanstacks/lambda-utils';
+
+interface RequestBody {
+  email: string;
+  name: string;
+}
+
+export const handler = async (event: any) => {
+  try {
+    // Validate request
+    if (!event.body) {
+      return badRequest('Request body is required', httpHeaders.json);
+    }
+
+    const body: RequestBody = JSON.parse(event.body);
+
+    if (!body.email || !body.name) {
+      return badRequest('Missing required fields: email, name', httpHeaders.json);
+    }
+
+    // Process request
+    const result = { id: '123', ...body };
+
+    return ok(result, httpHeaders.json);
+  } catch (error) {
+    console.error('Handler error:', error);
+    return internalServerError('Failed to process request', httpHeaders.json);
+  }
+};
+```
+
+### CRUD Operations
+
+```typescript
+import {
+  ok,
+  created,
+  noContent,
+  badRequest,
+  notFound,
+  internalServerError,
+  httpHeaders,
+} from '@leanstacks/lambda-utils';
+
+const headers = httpHeaders.json;
+
+export const handlers = {
+  // GET /items/{id}
+  getItem: async (event: any) => {
+    try {
+      const item = await findItem(event.pathParameters.id);
+      return item ? ok(item, headers) : notFound('Item not found', headers);
+    } catch (error) {
+      return internalServerError('Failed to retrieve item', headers);
+    }
+  },
+
+  // POST /items
+  createItem: async (event: any) => {
+    try {
+      if (!event.body) {
+        return badRequest('Request body is required', headers);
+      }
+
+      const newItem = await saveItem(JSON.parse(event.body));
+      return created(newItem, headers);
+    } catch (error) {
+      return internalServerError('Failed to create item', headers);
+    }
+  },
+
+  // DELETE /items/{id}
+  deleteItem: async (event: any) => {
+    try {
+      await removeItem(event.pathParameters.id);
+      return noContent(headers);
+    } catch (error) {
+      return internalServerError('Failed to delete item', headers);
+    }
+  },
+};
+```
+
+### CORS-Enabled Handler
+
+```typescript
+import { ok, badRequest, httpHeaders } from '@leanstacks/lambda-utils';
+
+const corsHeaders = {
+  ...httpHeaders.json,
+  ...httpHeaders.cors('https://app.example.com'),
+  'X-API-Version': '1.0',
+};
+
+export const handler = async (event: any) => {
+  // Handle preflight requests
+  if (event.requestContext.http.method === 'OPTIONS') {
+    return ok({}, corsHeaders);
+  }
+
+  if (!event.body) {
+    return badRequest('Body is required', corsHeaders);
+  }
+
+  return ok({ processed: true }, corsHeaders);
+};
+```
+
+## Best Practices
+
+1. **Use Consistent Headers** – Define headers once and reuse them across handlers to maintain consistency.
+
+   ```typescript
+   const defaultHeaders = httpHeaders.json;
+   ```
+
+2. **Provide Meaningful Error Messages** – Include specific error details to help clients understand what went wrong.
+
+   ```typescript
+   return badRequest(`Missing required field: ${fieldName}`, headers);
+   ```
+
+3. **Handle Errors Gracefully** – Use try-catch blocks and return appropriate error responses.
+
+   ```typescript
+   try {
+     // Process
+   } catch (error) {
+     return internalServerError('Operation failed', headers);
+   }
+   ```
+
+4. **Use Appropriate Status Codes** – Choose the correct HTTP status code for each scenario:
+   - `200 OK` – Request successful
+   - `201 Created` – Resource created
+   - `204 No Content` – Request successful, no content
+   - `400 Bad Request` – Invalid input
+   - `404 Not Found` – Resource not found
+   - `500 Internal Server Error` – Unexpected error
+
+5. **Log Errors** – Log error details for debugging while returning user-friendly messages.
+
+   ```typescript
+   catch (error) {
+     logger.error({ message: 'Processing failed', error: error.message });
+     return internalServerError('Failed to process request', headers);
+   }
+   ```
+
+6. **Combine with Logging** – Use response helpers with structured logging for complete observability.
+
+   ```typescript
+   import { Logger } from '@leanstacks/lambda-utils';
+   const logger = new Logger().instance;
+
+   export const handler = async (event: any) => {
+     logger.info('Request received', { path: event.path });
+     return ok({ message: 'Success' }, httpHeaders.json);
+   };
+   ```
+
+## Type Safety
+
+All response functions are fully typed with TypeScript. The `body` parameter accepts `unknown`, allowing you to pass any serializable value:
+
+```typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+const user: User = { id: '1', name: 'John', email: 'john@example.com' };
+return ok(user); // ✓ Type-safe
+```
+
+Error functions accept string or number messages:
+
+```typescript
+return badRequest('Invalid input'); // ✓ String message
+return notFound(404); // ✓ Number message
+```
+
+## Further reading
+
+- **[Logging Guide](./LOGGING.md)** – Structured logging for Lambda functions
+- **[Back to the project documentation](README.md)**

package/docs/DYNAMODB_CLIENT.md

@@ -0,0 +1,214 @@
+# DynamoDB Client Utilities
+
+The DynamoDB client utilities provide reusable singleton instances of `DynamoDBClient` and `DynamoDBDocumentClient` for use in AWS Lambda functions. These utilities enable you to configure clients once and reuse them across invocations, following AWS best practices for Lambda performance optimization.
+
+## Overview
+
+The utility exports the following functions:
+
+- `initializeDynamoDBClients()` - Initialize both DynamoDB clients with optional configuration
+- `getDynamoDBClient()` - Get the singleton DynamoDB client instance
+- `getDynamoDBDocumentClient()` - Get the singleton DynamoDB Document client instance
+- `resetDynamoDBClients()` - Reset both client instances (useful for testing)
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { initializeDynamoDBClients, getDynamoDBDocumentClient } from '@leanstacks/lambda-utils';
+import { PutCommand } from '@aws-sdk/lib-dynamodb';
+
+// Initialize both clients (typically done once outside the handler)
+initializeDynamoDBClients({ region: 'us-east-1' });
+
+export const handler = async (event: any) => {
+  // Get the document client (most common use case)
+  const docClient = getDynamoDBDocumentClient();
+
+  // Use the document client
+  await docClient.send(
+    new PutCommand({
+      TableName: 'MyTable',
+      Item: { id: '123', name: 'Example' },
+    }),
+  );
+};
+```
+
+### Using the Base DynamoDB Client
+
+````typescript
+import { initializeDynamoDBClients, getDynamoDBClient } from '@leanstacks/lambda-utils';
+import { PutItemCommand } from '@aws-sdk/client-dynamodb';
+
+// Initialize both clients
+initializeDynamoDBClients({ region: 'us-east-1' });
+
+export const handler = async (event: any) => {
+  // Get the base client for advanced use cases
+  const client = getDynamoDBClient();
+
+  // Use the base client
+  await client.send(new PutItemCommand({
+    TableName: 'MyTable',
+    Item: { id: { S: '123' }, name: { S: 'Example' } }
+  }));
+
+### Advanced Configuration
+
+#### Custom DynamoDB Client Configuration
+
+```typescript
+import { initializeDynamoDBClients } from '@leanstacks/lambda-utils';
+
+initializeDynamoDBClients({
+  region: 'us-west-2',
+  endpoint: 'http://localhost:8000', // For local development
+  credentials: {
+    accessKeyId: 'local',
+    secretAccessKey: 'local',
+  },
+});
+````
+
+#### Custom Marshall/Unmarshall Options
+
+```typescript
+import { initializeDynamoDBClients } from '@leanstacks/lambda-utils';
+
+initializeDynamoDBClients(
+  { region: 'us-east-1' },
+  {
+    // Marshall options
+    removeUndefinedValues: true,
+    convertEmptyValues: false,
+    convertClassInstanceToMap: true,
+  },
+  {
+    // Unmarshall options
+    wrapNumbers: false,
+  },
+);
+```
+
+### Lambda Handler Pattern
+
+```typescript
+import { initializeDynamoDBClients, getDynamoDBDocumentClient } from '@leanstacks/lambda-utils';
+import { GetCommand } from '@aws-sdk/lib-dynamodb';
+
+// Initialize clients outside the handler (runs once per cold start)
+initializeDynamoDBClients({ region: process.env.AWS_REGION }, { removeUndefinedValues: true });
+
+// Handler function
+export const handler = async (event: any) => {
+  const docClient = getDynamoDBDocumentClient();
+
+  const result = await docClient.send(
+    new GetCommand({
+      TableName: process.env.TABLE_NAME,
+      Key: { id: event.id },
+    }),
+  );
+
+  return result.Item;
+};
+```
+
+## API Reference
+
+### `initializeDynamoDBClients(config?, marshallOptions?, unmarshallOptions?): { client: DynamoDBClient; documentClient: DynamoDBDocumentClient }`
+
+Initializes both the DynamoDB client and DynamoDB Document client with the provided configuration.
+
+**Parameters:**
+
+- `config` (optional) - DynamoDB client configuration object
+- `marshallOptions` (optional) - Options for marshalling JavaScript objects to DynamoDB AttributeValues
+- `unmarshallOptions` (optional) - Options for unmarshalling DynamoDB AttributeValues to JavaScript objects
+
+**Returns:**
+
+- An object containing both `client` (DynamoDBClient) and `documentClient` (DynamoDBDocumentClient)
+
+**Notes:**
+
+- Creates both clients in a single call
+- If called multiple times, it will replace the existing client instances
+- If no config is provided, uses default AWS SDK configuration
+- Most users will only need the `documentClient` from the return value or via `getDynamoDBDocumentClient()`
+
+### `getDynamoDBClient(): DynamoDBClient`
+
+Returns the singleton DynamoDB client instance.
+
+**Returns:**
+
+- The `DynamoDBClient` instance
+
+**Throws:**
+
+- Error if the client has not been initialized
+
+### `getDynamoDBDocumentClient(): DynamoDBDocumentClient`
+
+Returns the singleton DynamoDB Document client instance.
+
+**Returns:**
+
+- The `DynamoDBDocumentClient` instance
+
+**Throws:**
+
+- Error if the document client has not been initialized
+
+### `resetDynamoDBClients(): void`
+
+Resets both DynamoDB client instances to null.
+
+**Notes:**
+
+- Primarily useful for testing scenarios where you need to reinitialize clients with different configurations
+- After calling this, you must reinitialize the clients before using the getter functions
+
+## Best Practices
+
+1. **Initialize Outside the Handler**: Always initialize clients outside your Lambda handler function to reuse the instance across invocations.
+
+2. **Use Environment Variables**: Configure clients using environment variables for flexibility across environments.
+
+3. **Error Handling**: Always wrap client operations in try-catch blocks to handle errors gracefully.
+
+4. **Testing**: Use `resetDynamoDBClients()` in test setup/teardown to ensure clean test isolation.
+
+## Testing Example
+
+```typescript
+import { initializeDynamoDBClients, getDynamoDBDocumentClient, resetDynamoDBClients } from '@leanstacks/lambda-utils';
+
+describe('MyLambdaHandler', () => {
+  beforeEach(() => {
+    resetDynamoDBClients();
+    initializeDynamoDBClients(
+      { region: 'us-east-1', endpoint: 'http://localhost:8000' },
+      { removeUndefinedValues: true },
+    );
+  });
+
+  afterEach(() => {
+    resetDynamoDBClients();
+  });
+
+  it('should retrieve item from DynamoDB', async () => {
+    // Your test code here
+  });
+});
+```
+
+## Related Resources
+
+- **[AWS SDK for JavaScript v3 - DynamoDB Client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-dynamodb/)**
+- **[AWS SDK for JavaScript v3 - DynamoDB Document Client](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-lib-dynamodb/Class/DynamoDBDocumentClient/)**
+- **[AWS Lambda Best Practices](https://docs.aws.amazon.com/lambda/latest/dg/best-practices.html)**
+- **[Back to the project documentation](README.md)**

package/docs/LOGGING.md

@@ -327,7 +327,8 @@ describe('MyHandler', () => {
 
 ## Further reading
 
-- [Pino Documentation](https://getpino.io/)
-- [AWS Lambda Environment and Context](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-handler.html)
-- [CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)
-- [Back to the project documentation](README.md)
+- **[Pino Documentation](https://getpino.io/)**
+- **[Pino Lambda Documentation](https://github.com/FormidableLabs/pino-lambda#readme)**
+- **[AWS Lambda Environment and Context](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-handler.html)**
+- **[CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)**
+- **[Back to the project documentation](README.md)**

package/docs/README.md

@@ -10,8 +10,8 @@ Lambda Utilities is a collection of pre-configured tools and helpers designed to
 
 - **[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
-- **[AWS Clients](./CLIENTS.md)** – Pre-configured AWS SDK v3 clients optimized for Lambda
 - **[Getting Started](./GETTING_STARTED.md)** – Quick setup and installation instructions
 
 ## Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leanstacks/lambda-utils",
-  "version": "0.2.0-alpha.3",
+  "version": "0.3.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",
   "module": "dist/index.esm.js",
@@ -63,7 +63,9 @@
     "typescript": "5.9.3"
   },
   "dependencies": {
-    "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"
   }
 }