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

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/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/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",
+  "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"
   }
 }