docs: expand documentation across codebase

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) {

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' },

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<Array<{check: Function, handler: Function}>>} 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();

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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<any>;
 
+/** Entrypoint exported by this package. */
 export declare function handler(event: any, context: Context): Promise<any>;
 export default handler;

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', () => {

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';
 

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';

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', () => {

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', () => {