diff --git a/bin/invoke.js b/bin/invoke.js index 1442c69..38770ca 100755 --- a/bin/invoke.js +++ b/bin/invoke.js @@ -1,8 +1,16 @@ #!/usr/bin/env node +/** + * Command-line utility for invoking the universal Lambda handler with a JSON + * event payload. Useful for local testing and debugging. + */ import fs from 'fs/promises'; import path from 'path'; import { handler } from '../index.mjs'; +/** + * Read an event from disk and invoke the handler, printing the result to + * stdout. Exits the process with a non-zero code on failure. + */ async function main() { const file = process.argv[2]; if (!file) { diff --git a/dispatch-config.js b/dispatch-config.js index cbe8a50..c43eb81 100644 --- a/dispatch-config.js +++ b/dispatch-config.js @@ -13,6 +13,12 @@ function getRecordsSource(event) { return undefined; } +/** + * Ordered dispatch rules evaluated by the main handler. Each rule provides a + * `check` predicate to determine if an incoming event matches and the path to + * the handler module responsible for processing that event type. Rules are + * evaluated sequentially until a match is found. + */ export default [ { check: e => e.request && e.session && e.context?.System, handler: './handlers/handleAlexa.js' }, { check: e => e.bot && e.userId && e.inputTranscript, handler: './handlers/handleLex.js' }, diff --git a/dispatcher.js b/dispatcher.js index 30ff2e9..babe2b4 100644 --- a/dispatcher.js +++ b/dispatcher.js @@ -1,3 +1,8 @@ +/** + * Load and map all available event handlers used by the universal Lambda + * dispatcher. Handlers are imported eagerly so that their references can be + * resolved when building the dispatch table. + */ import handleAlexa from './handlers/handleAlexa.js'; import handleLex from './handlers/handleLex.js'; import handleAppSync from './handlers/handleAppSync.js'; @@ -24,6 +29,10 @@ import handleSes from './handlers/handleSes.js'; import handleEventBridge from './handlers/handleEventBridge.js'; import handleScheduled from './handlers/handleScheduled.js'; +/** + * Mapping of handler module paths to the concrete handler implementations. + * The keys correspond to the `handler` values declared in dispatch-config.js. + */ const handlerMap = { './handlers/handleAlexa.js': handleAlexa, './handlers/handleLex.js': handleLex, @@ -52,6 +61,12 @@ const handlerMap = { './handlers/handleScheduled.js': handleScheduled, }; +/** + * Resolve the dispatch configuration into executable handler functions. + * + * @returns {Promise>} The dispatch + * table, preserving the order defined in the configuration file. + */ export async function loadDispatchTable() { const { default: config } = await import('./dispatch-config.js'); return config.map(({ check, handler }) => { @@ -61,4 +76,8 @@ export async function loadDispatchTable() { }); } +/** + * Promise that resolves to the dispatch table. Loading is initiated on module + * import so the table is available by the time the Lambda handler runs. + */ export const dispatchTablePromise = loadDispatchTable(); diff --git a/handlers/handleAlb.d.ts b/handlers/handleAlb.d.ts index b68e1ce..c8da057 100644 --- a/handlers/handleAlb.d.ts +++ b/handlers/handleAlb.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleAlb handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleAlb handler. */ declare const handleAlb: LambdaHandler; export default handleAlb; diff --git a/handlers/handleAlexa.d.ts b/handlers/handleAlexa.d.ts index a064cc2..1d89a32 100644 --- a/handlers/handleAlexa.d.ts +++ b/handlers/handleAlexa.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleAlexa handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleAlexa handler. */ declare const handleAlexa: LambdaHandler; export default handleAlexa; diff --git a/handlers/handleAppSync.d.ts b/handlers/handleAppSync.d.ts index 5866803..aded001 100644 --- a/handlers/handleAppSync.d.ts +++ b/handlers/handleAppSync.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleAppSync handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleAppSync handler. */ declare const handleAppSync: LambdaHandler; export default handleAppSync; diff --git a/handlers/handleAuthorizerV1.d.ts b/handlers/handleAuthorizerV1.d.ts index 6f1dbb1..0498938 100644 --- a/handlers/handleAuthorizerV1.d.ts +++ b/handlers/handleAuthorizerV1.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleAuthorizerV1 handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleAuthorizerV1 handler. */ declare const handleAuthorizerV1: LambdaHandler; export default handleAuthorizerV1; diff --git a/handlers/handleAuthorizerV2.d.ts b/handlers/handleAuthorizerV2.d.ts index a127e43..f336bbe 100644 --- a/handlers/handleAuthorizerV2.d.ts +++ b/handlers/handleAuthorizerV2.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleAuthorizerV2 handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleAuthorizerV2 handler. */ declare const handleAuthorizerV2: LambdaHandler; export default handleAuthorizerV2; diff --git a/handlers/handleCloudWatchLogs.d.ts b/handlers/handleCloudWatchLogs.d.ts index 694665a..d38e796 100644 --- a/handlers/handleCloudWatchLogs.d.ts +++ b/handlers/handleCloudWatchLogs.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleCloudWatchLogs handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleCloudWatchLogs handler. */ declare const handleCloudWatchLogs: LambdaHandler; export default handleCloudWatchLogs; diff --git a/handlers/handleCognito.d.ts b/handlers/handleCognito.d.ts index b8b6e7b..4f8e7f2 100644 --- a/handlers/handleCognito.d.ts +++ b/handlers/handleCognito.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleCognito handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleCognito handler. */ declare const handleCognito: LambdaHandler; export default handleCognito; diff --git a/handlers/handleConfigRule.d.ts b/handlers/handleConfigRule.d.ts index 0bf9ffb..8420d26 100644 --- a/handlers/handleConfigRule.d.ts +++ b/handlers/handleConfigRule.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleConfigRule handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleConfigRule handler. */ declare const handleConfigRule: LambdaHandler; export default handleConfigRule; diff --git a/handlers/handleCustomResource.d.ts b/handlers/handleCustomResource.d.ts index d9609ba..2a0ebe9 100644 --- a/handlers/handleCustomResource.d.ts +++ b/handlers/handleCustomResource.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleCustomResource handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleCustomResource handler. */ declare const handleCustomResource: LambdaHandler; export default handleCustomResource; diff --git a/handlers/handleDefault.d.ts b/handlers/handleDefault.d.ts index 5b9a79f..093ba8c 100644 --- a/handlers/handleDefault.d.ts +++ b/handlers/handleDefault.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleDefault handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleDefault handler. */ declare const handleDefault: LambdaHandler; export default handleDefault; diff --git a/handlers/handleDynamoDB.d.ts b/handlers/handleDynamoDB.d.ts index 5b74f6f..cec59f3 100644 --- a/handlers/handleDynamoDB.d.ts +++ b/handlers/handleDynamoDB.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleDynamoDB handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleDynamoDB handler. */ declare const handleDynamoDB: LambdaHandler; export default handleDynamoDB; diff --git a/handlers/handleEdge.d.ts b/handlers/handleEdge.d.ts index 9cb24b1..b1095a5 100644 --- a/handlers/handleEdge.d.ts +++ b/handlers/handleEdge.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleEdge handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleEdge handler. */ declare const handleEdge: LambdaHandler; export default handleEdge; diff --git a/handlers/handleEventBridge.d.ts b/handlers/handleEventBridge.d.ts index c4b35c2..3f37b2a 100644 --- a/handlers/handleEventBridge.d.ts +++ b/handlers/handleEventBridge.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleEventBridge handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleEventBridge handler. */ declare const handleEventBridge: LambdaHandler; export default handleEventBridge; diff --git a/handlers/handleFirehose.d.ts b/handlers/handleFirehose.d.ts index 9fbb058..30baad4 100644 --- a/handlers/handleFirehose.d.ts +++ b/handlers/handleFirehose.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleFirehose handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleFirehose handler. */ declare const handleFirehose: LambdaHandler; export default handleFirehose; diff --git a/handlers/handleHttpV1.d.ts b/handlers/handleHttpV1.d.ts index 22fe602..52b98e7 100644 --- a/handlers/handleHttpV1.d.ts +++ b/handlers/handleHttpV1.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleHttpV1 handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleHttpV1 handler. */ declare const handleHttpV1: LambdaHandler; export default handleHttpV1; diff --git a/handlers/handleHttpV2.d.ts b/handlers/handleHttpV2.d.ts index 224f4be..4bd2492 100644 --- a/handlers/handleHttpV2.d.ts +++ b/handlers/handleHttpV2.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleHttpV2 handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleHttpV2 handler. */ declare const handleHttpV2: LambdaHandler; export default handleHttpV2; diff --git a/handlers/handleIoTRule.d.ts b/handlers/handleIoTRule.d.ts index d90a816..d8bf031 100644 --- a/handlers/handleIoTRule.d.ts +++ b/handlers/handleIoTRule.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleIoTRule handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleIoTRule handler. */ declare const handleIoTRule: LambdaHandler; export default handleIoTRule; diff --git a/handlers/handleKinesis.d.ts b/handlers/handleKinesis.d.ts index c0e2788..81131b6 100644 --- a/handlers/handleKinesis.d.ts +++ b/handlers/handleKinesis.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleKinesis handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleKinesis handler. */ declare const handleKinesis: LambdaHandler; export default handleKinesis; diff --git a/handlers/handleLex.d.ts b/handlers/handleLex.d.ts index 0f7950b..61a2019 100644 --- a/handlers/handleLex.d.ts +++ b/handlers/handleLex.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleLex handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleLex handler. */ declare const handleLex: LambdaHandler; export default handleLex; diff --git a/handlers/handleS3.d.ts b/handlers/handleS3.d.ts index c5e138e..be21ebd 100644 --- a/handlers/handleS3.d.ts +++ b/handlers/handleS3.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleS3 handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleS3 handler. */ declare const handleS3: LambdaHandler; export default handleS3; diff --git a/handlers/handleScheduled.d.ts b/handlers/handleScheduled.d.ts index 352de1a..e681ead 100644 --- a/handlers/handleScheduled.d.ts +++ b/handlers/handleScheduled.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleScheduled handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleScheduled handler. */ declare const handleScheduled: LambdaHandler; export default handleScheduled; diff --git a/handlers/handleSes.d.ts b/handlers/handleSes.d.ts index deb7824..ef9c066 100644 --- a/handlers/handleSes.d.ts +++ b/handlers/handleSes.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleSes handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleSes handler. */ declare const handleSes: LambdaHandler; export default handleSes; diff --git a/handlers/handleSns.d.ts b/handlers/handleSns.d.ts index e1a9e2c..cedefcb 100644 --- a/handlers/handleSns.d.ts +++ b/handlers/handleSns.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleSns handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleSns handler. */ declare const handleSns: LambdaHandler; export default handleSns; diff --git a/handlers/handleSqs.d.ts b/handlers/handleSqs.d.ts index f1f23a3..b736f3d 100644 --- a/handlers/handleSqs.d.ts +++ b/handlers/handleSqs.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleSqs handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleSqs handler. */ declare const handleSqs: LambdaHandler; export default handleSqs; diff --git a/handlers/handleStepFunctions.d.ts b/handlers/handleStepFunctions.d.ts index 3724f54..0bb6f20 100644 --- a/handlers/handleStepFunctions.d.ts +++ b/handlers/handleStepFunctions.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleStepFunctions handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleStepFunctions handler. */ declare const handleStepFunctions: LambdaHandler; export default handleStepFunctions; diff --git a/handlers/handleWebSocket.d.ts b/handlers/handleWebSocket.d.ts index 18151d1..7c7f8db 100644 --- a/handlers/handleWebSocket.d.ts +++ b/handlers/handleWebSocket.d.ts @@ -1,5 +1,9 @@ +/** + * Type definitions for the handleWebSocket handler. + */ import type { LambdaHandler } from '../index.d.ts'; import type { Context } from 'aws-lambda'; +/** handleWebSocket handler. */ declare const handleWebSocket: LambdaHandler; export default handleWebSocket; diff --git a/index.d.ts b/index.d.ts index eff24ff..ac31015 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1,6 +1,11 @@ +/** + * TypeScript definitions for the universal AWS Lambda handler package. + */ import type { Context } from 'aws-lambda'; +/** Generic AWS Lambda handler signature. */ export type LambdaHandler = (event: any, context: Context) => Promise; +/** Entrypoint exported by this package. */ export declare function handler(event: any, context: Context): Promise; export default handler; diff --git a/tests/collectInvocation.test.js b/tests/collectInvocation.test.js index f4bc29c..26fc4bb 100644 --- a/tests/collectInvocation.test.js +++ b/tests/collectInvocation.test.js @@ -1,3 +1,7 @@ +/** + * Unit tests for the `collectInvocation` helper, verifying that context + * functions are executed and errors handled gracefully. + */ import collectInvocation from '../collectInvocation.js'; describe('collectInvocation', () => { diff --git a/tests/dispatcher.test.js b/tests/dispatcher.test.js index 82a3371..cab85f0 100644 --- a/tests/dispatcher.test.js +++ b/tests/dispatcher.test.js @@ -1,3 +1,7 @@ +/** + * Tests for the dispatch table loader ensuring unknown handler paths trigger + * appropriate errors. + */ import config from '../dispatch-config.js'; import { loadDispatchTable } from '../dispatcher.js'; diff --git a/tests/handlers.test.js b/tests/handlers.test.js index 10bddbd..d97e3f3 100644 --- a/tests/handlers.test.js +++ b/tests/handlers.test.js @@ -1,3 +1,7 @@ +/** + * Integration tests exercising the universal handler against representative + * events for each supported AWS service. + */ import { handler } from '../index.mjs'; import zlib from 'zlib'; import { jest } from '@jest/globals'; diff --git a/tests/index.test.js b/tests/index.test.js index d0dff03..30f5c57 100644 --- a/tests/index.test.js +++ b/tests/index.test.js @@ -1,3 +1,6 @@ +/** + * Smoke tests ensuring the primary handler routes common events correctly. + */ import { handler } from '../index.mjs'; describe('handler', () => { diff --git a/tests/logger.test.js b/tests/logger.test.js index 90bd553..73bb07a 100644 --- a/tests/logger.test.js +++ b/tests/logger.test.js @@ -1,3 +1,7 @@ +/** + * Tests validating the debug logger's behavior and resilience to problematic + * payloads such as circular references. + */ import { logDebug } from '../logger.js'; describe('logDebug', () => {