@leanstacks/lambda-utils 0.2.0-alpha.2 → 0.2.0

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/index.d.ts

@@ -1,2 +1,2 @@
 export { Logger, LoggerConfig, withRequestTracking } from './logging/logger';
-export { createResponse, ok, created, noContent, badRequest, notFound, internalServerError, jsonHeaders, corsHeaders, Headers, } from './utils/apigateway-response';
+export { createResponse, ok, created, noContent, badRequest, notFound, internalServerError, httpHeaders, Headers, } from './utils/apigateway-response';

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={"Content-Type":"application/json"},a=(e="*")=>({"Access-Control-Allow-Origin":e}),g=(e,n,o={})=>({statusCode:e,headers:{...o},body:JSON.stringify(n)}),c=(e,n={})=>g(200,e,n),f=(e,n={})=>g(201,e,n),m=(e={})=>g(204,{},e),h=(e="Bad Request",n={})=>g(400,{message:e},n),d=(e="Not Found",n={})=>g(404,{message:e},n),_=(e="Internal Server Error",n={})=>g(500,{message:e},n);export{i as Logger,h as badRequest,a as corsHeaders,g as createResponse,f as created,_ as internalServerError,l as jsonHeaders,m as noContent,d as notFound,c as ok,r as withRequestTracking};
+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};
 //# sourceMappingURL=index.esm.js.map

package/dist/index.js

@@ -1,2 +1,2 @@
-"use strict";var e=require("pino"),t=require("pino-lambda");const r=t.lambdaRequestTracker();const o=(e,t,r={})=>({statusCode:e,headers:{...r},body:JSON.stringify(t)});exports.Logger=class{constructor(r){this._loggerConfig={enabled:!0,level:"info",format:"json"},this._instance=null,this._createLogger=()=>{const r="json"===this._loggerConfig.format?new t.StructuredLogFormatter:new t.CloudwatchLogFormatter,o=t.pinoLambdaDestination({formatter:r});return e({enabled:this._loggerConfig.enabled,level:this._loggerConfig.level},o)},r&&(this._loggerConfig={enabled:r.enabled??!0,level:r.level??"info",format:r.format??"json"})}get instance(){return null===this._instance&&(this._instance=this._createLogger()),this._instance}},exports.badRequest=(e="Bad Request",t={})=>o(400,{message:e},t),exports.corsHeaders=(e="*")=>({"Access-Control-Allow-Origin":e}),exports.createResponse=o,exports.created=(e,t={})=>o(201,e,t),exports.internalServerError=(e="Internal Server Error",t={})=>o(500,{message:e},t),exports.jsonHeaders={"Content-Type":"application/json"},exports.noContent=(e={})=>o(204,{},e),exports.notFound=(e="Not Found",t={})=>o(404,{message:e},t),exports.ok=(e,t={})=>o(200,e,t),exports.withRequestTracking=r;
+"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;
 //# sourceMappingURL=index.js.map

package/dist/utils/apigateway-response.d.ts

@@ -4,15 +4,22 @@ import { APIGatewayProxyResult } from 'aws-lambda';
  */
 export type Headers = Record<string, string | number | boolean>;
 /**
- * Represents the headers for a JSON API Gateway response
+ * Commonly used headers for API Gateway responses
  */
-export declare const jsonHeaders: Headers;
-/**
- * Generates the headers required for CORS (Cross-Origin Resource Sharing) requests
- * @param origin The origin to allow for CORS requests
- * @returns Headers containing the CORS configuration
- */
-export declare const corsHeaders: (origin?: string) => Headers;
+export declare const httpHeaders: {
+    /** Content-Type: <type> */
+    contentType: (type: string) => {
+        'Content-Type': string;
+    };
+    /** Content-Type: application/json */
+    json: {
+        'Content-Type': string;
+    };
+    /** Access-Control-Allow-Origin: <origin> */
+    cors: (origin?: string) => {
+        'Access-Control-Allow-Origin': string;
+    };
+};
 /**
  * Creates a standardized API Gateway response.
  * @param statusCode The HTTP status code of the response
@@ -22,7 +29,7 @@ export declare const corsHeaders: (origin?: string) => Headers;
  *
  * @example
  * ```ts
- * const response = createResponse(200, { message: 'Success' }, jsonHeaders);
+ * const response = createResponse(200, { message: 'Success' }, httpHeaders.json);
  * ```
  */
 export declare const createResponse: (statusCode: number, body: unknown, headers?: Headers) => APIGatewayProxyResult;
@@ -33,7 +40,7 @@ export declare const createResponse: (statusCode: number, body: unknown, headers
  * @returns An API Gateway proxy result
  * @example
  * ```ts
- * const response = ok({ message: 'Success' }, jsonHeaders);
+ * const response = ok({ message: 'Success' }, httpHeaders.json);
  * ```
  */
 export declare const ok: (body: unknown, headers?: Headers) => APIGatewayProxyResult;
@@ -44,7 +51,7 @@ export declare const ok: (body: unknown, headers?: Headers) => APIGatewayProxyRe
  * @returns An API Gateway proxy result
  * @example
  * ```ts
- * const response = created({ message: 'Resource created' }, jsonHeaders);
+ * const response = created({ message: 'Resource created' }, httpHeaders.json);
  * ```
  */
 export declare const created: (body: unknown, headers?: Headers) => APIGatewayProxyResult;
@@ -54,7 +61,7 @@ export declare const created: (body: unknown, headers?: Headers) => APIGatewayPr
  * @returns An API Gateway proxy result
  * @example
  * ```ts
- * const response = noContent(corsHeaders());
+ * const response = noContent(httpHeaders.cors());
  * ```
  */
 export declare const noContent: (headers?: Headers) => APIGatewayProxyResult;
@@ -65,7 +72,7 @@ export declare const noContent: (headers?: Headers) => APIGatewayProxyResult;
  * @returns An API Gateway proxy result
  * @example
  * ```ts
- * const response = badRequest('Invalid input', jsonHeaders);
+ * const response = badRequest('Invalid input', httpHeaders.json);
  * ```
  */
 export declare const badRequest: (message?: string, headers?: Headers) => APIGatewayProxyResult;
@@ -76,7 +83,7 @@ export declare const badRequest: (message?: string, headers?: Headers) => APIGat
  * @returns An API Gateway proxy result
  * @example
  * ```ts
- * const response = notFound('Resource not found', jsonHeaders);
+ * const response = notFound('Resource not found', httpHeaders.json);
  * ```
  */
 export declare const notFound: (message?: string, headers?: Headers) => APIGatewayProxyResult;
@@ -87,7 +94,7 @@ export declare const notFound: (message?: string, headers?: Headers) => APIGatew
  * @returns An API Gateway proxy result
  * @example
  * ```ts
- * const response = internalServerError('Something went wrong', jsonHeaders);
+ * const response = internalServerError('Something went wrong', httpHeaders.json);
  * ```
  */
 export declare const internalServerError: (message?: string, headers?: Headers) => APIGatewayProxyResult;

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leanstacks/lambda-utils",
-  "version": "0.2.0-alpha.2",
+  "version": "0.2.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",
@@ -35,6 +35,7 @@
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
     "prepare": "husky",
+    "prepublish": "npm run clean && npm run build",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage"