lambda-warmer-util

Lightweight utility to detect and handle AWS Lambda warmer events — returns early with a configurable delay to keep functions warm and reduce cold starts.

Installation

npm install lambda-warmer-util

Quick Start

import { checkWarmer } from 'lambda-warmer-util';

export const handler = async (event: unknown) => {
  const result = await checkWarmer(event);
  if (result.isWarmer) return 'warmed';

  // Your normal handler logic here...
  return { statusCode: 200, body: 'Hello World' };
};

How It Works

When the provisioner (common-rp-service) invokes a Lambda to keep it warm, it sends a warmer event. This utility detects that event, applies a configurable delay (to hold the execution environment active), and returns a result so the handler can exit early without running business logic.

Supported Event Shapes

Nested body (from ProvisionerServiceImpl):

{ "body": { "warmer": true, "delayInMilliSeconds": 75 } }

Flat (direct invocation / AWS Console testing):

{ "warmer": true, "delayInMilliSeconds": 75 }

JSON string body (API Gateway style):

{ "body": "{\"warmer\": true, \"delayInMilliSeconds\": 75}" }

API Reference

checkWarmer(event, config?)

| Parameter | Type | Description | |-----------|------|-------------| | event | unknown | The Lambda invocation event | | config | WarmerConfig | Optional configuration (see below) |

Returns: Promise<WarmerResult>

WarmerResult

| Field | Type | Description | |-------|------|-------------| | isWarmer | boolean | true if a warmer event was detected and delay applied | | delayApplied | number | Delay in milliseconds that was applied (0 if not a warmer) |

WarmerConfig

| Field | Type | Default | Description | |-------|------|---------|-------------| | defaultDelay | number | 75 | Default delay (ms) when event doesn't specify one. Clamped to [1, 10000]. | | log | boolean | true | Whether to log when a warmer event is detected | | logFn | (message: string) => void | console.log | Custom log function for structured logging |

Examples

With Custom Logger

import { checkWarmer } from 'lambda-warmer-util';
import { logger } from './my-logger.js';

export const handler = async (event: unknown) => {
  const result = await checkWarmer(event, {
    logFn: (msg) => logger.info(msg),
  });
  if (result.isWarmer) return 'warmed';

  // Business logic...
};

With Custom Default Delay

const result = await checkWarmer(event, { defaultDelay: 100 });

Silent Mode (No Logging)

const result = await checkWarmer(event, { log: false });

Development

npm install          # Install dependencies
npm run build        # Compile TypeScript to dist/
npm run test         # Run unit tests
npm run test:coverage # Run tests with coverage report
npm run lint         # Run ESLint
npm run format       # Format code with Prettier