@leanstacks/lambda-utils 0.1.0-alpha.3 → 0.1.0-alpha.5

package/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,47 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+---
+
+## Describe the bug
+
+_Provide a clear and concise description of what the bug is._
+
+## Steps to reproduce
+
+Steps to reproduce the behavior:
+
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+## Expected behavior
+
+_Provide a clear and concise description of what you expected to happen._
+
+## Screenshots
+
+_If applicable, add screenshots to help explain your problem._
+
+## Environment
+
+**Desktop (please complete the following information):**
+
+- OS: [e.g. iOS]
+- Browser [e.g. chrome, safari]
+- Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+
+- Device: [e.g. iPhone6]
+- OS: [e.g. iOS8.1]
+- Browser [e.g. stock browser, safari]
+- Version [e.g. 22]
+
+## Additional context
+
+_Add any other context about the problem here._

package/.github/ISSUE_TEMPLATE/story.md

@@ -0,0 +1,25 @@
+---
+name: Story
+about: New feature or improvement request
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+## Describe the story
+
+_Provide a clear description of the new feature or improvement to existing functionality._
+
+## Acceptance criteria
+
+_Provide clear acceptance criteria to validate the story is complete._
+
+[Gherkin syntax](https://cucumber.io/docs/gherkin/reference) example:
+
+> Given the 'PERSONA' has 'DONE SOMETHING'  
+> When the 'PERSONA' does 'ONE THING'  
+> Then the 'PERSONA' must do 'ANOTHER THING'
+
+## Additional context
+
+_Add any other context about the story here._

package/.github/ISSUE_TEMPLATE/task.md

@@ -0,0 +1,15 @@
+---
+name: Task
+about: A chore unrelated to features or problems
+title: ''
+labels: task
+assignees: ''
+---
+
+## Describe the task
+
+_Provide a clear description of the task._
+
+## Additional context
+
+_Add any other context about the task here._

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,39 @@
+:loudspeaker: **Instructions**
+
+- Begin with a **DRAFT** pull request.
+- Follow _italicized instructions_ to add detail to assist the reviewers.
+- After completing all checklist items, change the pull request to **READY**.
+
+---
+
+### :wrench: Change Summary
+
+_Describe the changes included in this pull request. Link to the associated [GitHub](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) or Jira issue(s)._
+
+- see #1234
+- Added the [...]
+- Updated the [...]
+- Fixed the [...]
+
+### :memo: Checklist
+
+_Pull request authors must complete the following tasks before marking the PR as ready to review._
+
+- [ ] Complete a self-review of changes
+- [ ] Unit tests have been created or updated
+- [ ] The code is free of [new] lint errors and warnings
+- [ ] Update project documentation as needed: README, /docs, JSDoc, etc.
+
+### :test_tube: Steps to Test
+
+_Describe the process to test the changes in this pull request._
+
+1. Go to [...]
+2. Click on [...]
+3. Verify that [...]
+
+### :link: Additional Information
+
+_Optionally, provide additional details, screenshots, or URLs that may assist the reviewer._
+
+- [...]

package/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: Continuous Integration
+
+on:
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    name: Build, Lint, and Test
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint code
+        run: npm run lint
+
+      - name: Check code formatting
+        run: npm run format:check
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests with coverage
+        run: npm run test:coverage

package/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish
+
+on:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  build:
+    name: Build and Publish
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint code
+        run: npm run lint
+
+      - name: Check code formatting
+        run: npm run format:check
+
+      - name: Run tests
+        run: npm run test
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish
+        run: npm publish

package/.husky/pre-commit

@@ -0,0 +1,3 @@
+npm test
+npm run format:check
+npm run lint

package/README.md

@@ -1,3 +1,180 @@
 # Lambda Utilities
 
-Lambda utilities
+[![npm version](https://badge.fury.io/js/@leanstacks%2Flambda-utils.svg)](https://badge.fury.io/js/@leanstacks%2Flambda-utils)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A comprehensive TypeScript utility library for AWS Lambda functions. Provides pre-configured logging, API response formatting, configuration validation, and AWS SDK clients—reducing boilerplate and promoting best practices.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
+- [Support](#support)
+
+## Installation
+
+```bash
+npm install @leanstacks/lambda-utils
+```
+
+### Requirements
+
+- Node.js 24.x or higher
+- TypeScript 5.0 or higher
+
+## Quick Start
+
+### Logging Example
+
+```typescript
+import { Logger, withRequestTracking } from '@leanstacks/lambda-utils';
+
+const logger = new Logger().instance;
+
+export const handler = async (event: any, context: any) => {
+  withRequestTracking(event, context);
+
+  logger.info('Processing request');
+
+  // Your Lambda handler logic here
+
+  return { statusCode: 200, body: 'Success' };
+};
+```
+
+### API Response Example
+
+```typescript
+import { success, badRequest } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  if (!event.body) {
+    return badRequest({ message: 'Body is required' });
+  }
+
+  // Process request
+
+  return success({ message: 'Request processed successfully' });
+};
+```
+
+## Features
+
+- **📝 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
+- **🔒 Full TypeScript Support** – Complete type definitions and IDE autocomplete
+- **⚡ Lambda Optimized** – Designed for performance in serverless environments
+
+## Documentation
+
+Comprehensive guides and examples are available in the `docs` directory:
+
+| Guide                                                        | Description                                                            |
+| ------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| **[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                                            |
+
+## Usage
+
+### Logging
+
+The Logger utility provides structured logging configured specifically for AWS Lambda:
+
+```typescript
+import { Logger } from '@leanstacks/lambda-utils';
+
+const logger = new Logger({
+  level: 'info', // debug, info, warn, error
+  format: 'json', // json or text
+}).instance;
+
+logger.info({ message: 'User authenticated', userId: '12345' });
+logger.error({ message: 'Operation failed', error: err.message });
+```
+
+**→ See [Logging Guide](./docs/LOGGING.md) for detailed configuration and best practices**
+
+### API Responses
+
+Generate properly formatted responses for API Gateway:
+
+```typescript
+import { success, error, created, badRequest } from '@leanstacks/lambda-utils';
+
+export const handler = async (event: any) => {
+  return success({
+    data: { id: '123', name: 'Example' },
+  });
+};
+```
+
+**→ 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);
+```
+
+**→ See [Configuration](./docs/CONFIGURATION.md) for validation patterns**
+
+### AWS Clients
+
+Use pre-configured AWS SDK v3 clients:
+
+```typescript
+import { getDynamoDBClient, getLambdaClient } from '@leanstacks/lambda-utils';
+
+const dynamoDB = getDynamoDBClient();
+const lambda = getLambdaClient();
+
+// Use clients for API calls
+```
+
+**→ See [AWS Clients](./docs/CLIENTS.md) for available clients and examples**
+
+## Examples
+
+Example Lambda functions using Lambda Utilities are available in the repository:
+
+- API Gateway with logging and response formatting
+- Configuration validation and DynamoDB integration
+- Error handling and structured logging
+
+## Reporting Issues
+
+If you encounter a bug or have a feature request, please report it on [GitHub Issues](https://github.com/leanstacks/lambda-utils/issues). Include as much detail as possible to help us investigate and resolve the issue quickly.
+
+## License
+
+This project is licensed under the MIT License - see [LICENSE](./LICENSE) file for details.
+
+## Support
+
+- **Issues & Questions:** [GitHub Issues](https://github.com/leanstacks/lambda-utils/issues)
+- **Documentation:** [docs](./docs/README.md)
+- **NPM Package:** [@leanstacks/lambda-utils](https://www.npmjs.com/package/@leanstacks/lambda-utils)
+
+## Changelog
+
+See the project [releases](https://github.com/leanstacks/lambda-utils/releases) for version history and updates.

package/dist/index.esm.js

@@ -0,0 +1,2 @@
+import e from"pino";import{lambdaRequestTracker as n,StructuredLogFormatter as t,CloudwatchLogFormatter as o,pinoLambdaDestination as i}from"pino-lambda";const l=n();class r{constructor(n){this._loggerConfig={enabled:!0,level:"info",format:"json"},this._instance=null,this._createLogger=()=>{const n="json"===this._loggerConfig.format?new t:new o,l=i({formatter:n});return e({enabled:this._loggerConfig.enabled,level:this._loggerConfig.level},l)},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}}export{r as Logger,l as withRequestTracking};
+//# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.esm.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/dist/index.js

@@ -1,78 +1,2 @@
-import pino from 'pino';
-import { lambdaRequestTracker, StructuredLogFormatter, CloudwatchLogFormatter, pinoLambdaDestination } from 'pino-lambda';
-
-/**
- * Logger middleware which adds AWS Lambda attributes to log messages.
- *
- * @example
- * ```typescript
- * import { withRequestTracking } from '@leanstacks/lambda-utils';
- *
- * export const handler = async (event, context) => {
- *   withRequestTracking(event, context);
- *
- *   // Your Lambda handler logic here
- * };
- * ```
- */
-const withRequestTracking = lambdaRequestTracker();
-/**
- * Logger class which provides a Pino logger instance with AWS Lambda attributes.
- *
- * @example
- * ```typescript
- * import { Logger } from '@leanstacks/lambda-utils';
- * const logger = new Logger().instance;
- *
- * logger.info('Hello, world!');
- * ```
- */
-class Logger {
-    constructor(config) {
-        this._loggerConfig = {
-            enabled: true,
-            level: 'info',
-            format: 'json',
-        };
-        this._instance = null;
-        /**
-         * Creates a new, fully configured Pino logger instance.
-         */
-        this._createLogger = () => {
-            const formatter = this._loggerConfig.format === 'json' ? new StructuredLogFormatter() : new CloudwatchLogFormatter();
-            const lambdaDestination = pinoLambdaDestination({
-                formatter,
-            });
-            return pino({
-                enabled: this._loggerConfig.enabled,
-                level: this._loggerConfig.level,
-            }, lambdaDestination);
-        };
-        if (config) {
-            this._loggerConfig = {
-                enabled: config.enabled ?? true,
-                level: config.level ?? 'info',
-                format: config.format ?? 'json',
-            };
-        }
-    }
-    /**
-     * Get the logger instance.
-     *
-     * @example
-     * ```typescript
-     * import { Logger } from '@leanstacks/lambda-utils';
-     * const logger = new Logger().instance;
-     *
-     * logger.info('Hello, world!');
-     * ```
-     */
-    get instance() {
-        if (this._instance === null) {
-            this._instance = this._createLogger();
-        }
-        return this._instance;
-    }
-}
-
-export { Logger, withRequestTracking };
+"use strict";var e=require("pino"),t=require("pino-lambda");const n=t.lambdaRequestTracker();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.withRequestTracking=n;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}