lambda-reactor 1.0.0

package/examples/health.ts

@@ -0,0 +1,7 @@
+import {createHandler} from "#src/handler"
+import {method} from "#src/method"
+import {Response} from "#src/response"
+
+export const handler = createHandler({
+    GET: method().handle(() => Response.text(200, "OK")),
+})

package/examples/items.ts

@@ -0,0 +1,25 @@
+import {createHandler} from "#src/handler"
+import {method} from "#src/method"
+import {Response} from "#src/response"
+import {z} from "zod"
+
+const ItemSchema = z.object({id: z.string(), label: z.string(), qty: z.number().int()})
+const CreateItemSchema = ItemSchema.omit({id: true})
+const ListSchema = z.array(ItemSchema)
+
+const store: z.infer<typeof ItemSchema>[] = []
+
+export const handler = createHandler({
+    GET: method()
+        .output(ListSchema)
+        .handle(() => store),
+
+    POST: method()
+        .input(CreateItemSchema)
+        .output(ItemSchema)
+        .handle(({body}) => {
+            const item = {id: crypto.randomUUID(), ...body}
+            store.push(item)
+            return Response.json(201, item)
+        }),
+})

package/examples/users-get.ts

@@ -0,0 +1,20 @@
+import {createHandler} from "#src/handler"
+import {method} from "#src/method"
+import {Response} from "#src/response"
+import {z} from "zod"
+
+const UserSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.email(),
+})
+
+export const handler = createHandler({
+    GET: method()
+        .output(UserSchema)
+        .handle(({event}) => {
+            const id = event.pathParameters?.["id"]
+            if (!id) return Response.text(400, "Missing id")
+            return {id, name: "Alice", email: "alice@example.com"}
+        }),
+})

package/examples/users-post.ts

@@ -0,0 +1,26 @@
+import {createHandler} from "#src/handler"
+import {method} from "#src/method"
+import {cors} from "#src/middleware"
+import {Response} from "#src/response"
+import {z} from "zod"
+
+const CreateUserSchema = z.object({
+    name: z.string().min(1),
+    email: z.email(),
+})
+
+const CreatedUserSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.email(),
+})
+
+export const handler = createHandler({
+    POST: method()
+        .use(cors())
+        .input(CreateUserSchema)
+        .output(CreatedUserSchema)
+        .handle(({body}) => {
+            return Response.json(201, {id: crypto.randomUUID(), ...body})
+        }),
+})

package/lefthook.yml

@@ -0,0 +1,16 @@
+pre-commit:
+    parallel: true
+    jobs:
+        - name: format
+          glob: "*.{ts,tsx,js,json,yml,yaml,md}"
+          run: bunx prettier -w {staged_files} && git add {staged_files}
+        - name: lint
+          glob: "*.{ts,tsx}"
+          run: bunx eslint --fix {staged_files} && git add {staged_files}
+
+pre-push:
+    jobs:
+        - name: check
+          run: bun run check
+        - name: test
+          run: bun test

package/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "lambda-reactor",
+    "version": "1.0.0",
+    "scripts": {
+        "prepare": "lefthook install",
+        "check": "tsgo",
+        "lint": "eslint --fix",
+        "format": "prettier -uwu .",
+        "test": "vitest",
+        "build": "rm -rf dist && tsgo -p tsconfig.build.json && bun build --target=node --external='*' --splitting --sourcemap=external --keep-names --root=src --outdir=dist src/*.ts"
+    },
+    "type": "module",
+    "imports": {
+        "#src/*": "./src/*.ts"
+    },
+    "devDependencies": {
+        "@eslint/js": "^10.0.1",
+        "@types/aws-lambda": "^8.10.161",
+        "@types/node": "^25.6.0",
+        "@types/source-map-support": "^0.5.10",
+        "@typescript/native-preview": "^7.0.0-dev.20260410.1",
+        "eslint": "^10.2.0",
+        "eslint-plugin-perfectionist": "^5.8.0",
+        "jiti": "^2.6.1",
+        "lefthook": "^2.1.5",
+        "prettier": "^3.8.2",
+        "typescript-eslint": "^8.46.1",
+        "vitest": "^4.1.4"
+    },
+    "dependencies": {
+        "aws-cdk-lib": "^2.248.0",
+        "source-map-support": "^0.5.21",
+        "zod": "^4.3.6"
+    }
+}

package/src/build-handlers.ts

@@ -0,0 +1,30 @@
+import {join} from "path"
+
+import type {IFunction} from "aws-cdk-lib/aws-lambda"
+/**
+ * A factory function that constructs an AWS Lambda {@link IFunction} from a
+ * source-file entry path and a logical identifier string.
+ */
+export type FunctionFactory = (entry: string, id: string) => IFunction
+
+/**
+ * Builds a map of route paths to Lambda functions by invoking `factory` for
+ * each path.
+ *
+ * The `entry` passed to `factory` is the absolute path
+ * `<cwd>/src/<path>.ts`, and the `id` is the route path string itself.
+ *
+ * @param paths   - Array of route path strings (e.g. `["/users", "/items"]`).
+ * @param factory - {@link FunctionFactory} used to construct each Lambda function.
+ */
+export function buildHandlers<TPaths extends string>(
+    paths: TPaths[],
+    factory: FunctionFactory,
+): Record<TPaths, IFunction> {
+    return Object.fromEntries(
+        paths.map((path) => [
+            path,
+            factory(join(process.cwd(), "src", `${path}.ts`), path),
+        ]),
+    ) as Record<TPaths, IFunction>
+}

package/src/dispatch.ts

@@ -0,0 +1,91 @@
+import {logError} from "#src/logger"
+import {RouteHandler} from "#src/method"
+import {Response} from "#src/response"
+import type {APIGatewayProxyEvent, Context} from "aws-lambda"
+import {z} from "zod"
+
+import {applyMiddlewares} from "./middleware"
+
+/**
+ * Executes a single {@link RouteHandler} for an incoming Lambda proxy event.
+ *
+ * Processing order:
+ * 1. Parse `event.body` as JSON when possible.
+ * 2. Validate the body against `route.bodySchema` (Zod); return `400` on
+ *    failure.
+ * 3. Invoke `route.callback` with the validated body, event, and context.
+ * 4. If the callback returns a {@link Response}, optionally validate its body
+ *    against `route.outputSchema`; return `500` on failure.
+ * 5. If the callback returns a plain value, wrap it in a `200 JSON` response,
+ *    optionally validating against `route.outputSchema`.
+ * 6. Apply all middlewares left-to-right before returning.
+ *
+ * @param route   - The route handler to execute.
+ * @param event   - Raw API Gateway proxy event.
+ * @param context - Lambda execution context.
+ */
+export async function dispatch(
+    route: RouteHandler,
+    event: APIGatewayProxyEvent,
+    context: Context,
+) {
+    let body
+    try {
+        body = event.body ? JSON.parse(event.body) : undefined
+    } catch (error) {
+        if (error instanceof Error) {
+            return Response.text(400, error.message).toAPIGatewayProxyResult()
+        }
+        throw error
+    }
+    if (route.bodySchema) {
+        const parsed = route.bodySchema.safeParse(body)
+        if (!parsed.success) {
+            return Response.text(
+                400,
+                z.treeifyError(parsed.error).errors.join("\n"),
+            ).toAPIGatewayProxyResult()
+        }
+        body = parsed.data
+    }
+    if (!route.callback) {
+        const err = new Error("Route has no handler defined")
+        logError(err)
+        return Response.text(500, err.message).toAPIGatewayProxyResult()
+    }
+    const cb = route.callback as (props: {
+        body: unknown
+        event: APIGatewayProxyEvent
+        context: Context
+    }) => Promise<unknown>
+    const result = await cb({body, event, context})
+    if (result instanceof Response) {
+        if (route.outputSchema) {
+            const parsed = route.outputSchema.safeParse(result.body)
+            if (!parsed.success) {
+                logError(parsed.error)
+                return Response.text(
+                    500,
+                    z.treeifyError(parsed.error).errors.join("\n"),
+                ).toAPIGatewayProxyResult()
+            }
+            result.body = parsed.data
+        }
+        return applyMiddlewares(result.toAPIGatewayProxyResult(), route)
+    }
+    if (route.outputSchema) {
+        const parsed = route.outputSchema.safeParse(result)
+        if (!parsed.success) {
+            logError(parsed.error)
+            return Response.text(
+                500,
+                z.treeifyError(parsed.error).errors.join("\n"),
+            ).toAPIGatewayProxyResult()
+        }
+        return applyMiddlewares(
+            Response.json(200, parsed.data).toAPIGatewayProxyResult(),
+            route,
+        )
+    }
+    return applyMiddlewares(Response.json(200, result).toAPIGatewayProxyResult(), route)
+}

package/src/env.ts

@@ -0,0 +1,23 @@
+const PROD_VALUES = new Set(["production", "prod"])
+
+/**
+ * Returns `true` if the given environment variable value represents a
+ * production environment (`"production"` or `"prod"`, case-insensitive).
+ */
+function isProductionValue(value: string | undefined): boolean {
+    return value !== undefined && PROD_VALUES.has(value.toLowerCase())
+}
+
+/**
+ * Returns `true` when any of the conventional environment variables
+ * (`NODE_ENV`, `STAGE`, `ENV`, `ENVIRONMENT`) indicate a production
+ * deployment.
+ */
+export function isProduction(): boolean {
+    return (
+        isProductionValue(process.env["NODE_ENV"]) ||
+        isProductionValue(process.env["STAGE"]) ||
+        isProductionValue(process.env["ENV"]) ||
+        isProductionValue(process.env["ENVIRONMENT"])
+    )
+}

package/src/handler.ts

@@ -0,0 +1,58 @@
+import {dispatch} from "#src/dispatch"
+import {isProduction} from "#src/env"
+import {formatError, logError} from "#src/logger"
+import {RouteHandler} from "#src/method"
+import {Response} from "#src/response"
+import type {APIGatewayProxyEvent, APIGatewayProxyResult, Context} from "aws-lambda"
+import {install} from "source-map-support"
+
+install()
+
+/**
+ * Creates an AWS Lambda handler function from a map of HTTP-method names to
+ * {@link RouteHandler} instances.
+ *
+ * The returned handler:
+ * - Returns `405 Method Not Allowed` (with an `Allow` header) for any HTTP
+ *   method not present in `routes`.
+ * - Delegates matching requests to {@link dispatch}.
+ * - Catches any `Error` thrown by `dispatch`, logs it, and returns
+ *   `500 Internal Server Error`.  In non-production environments the error
+ *   message and stack trace are included in the response body.
+ * - Re-throws non-`Error` throwables so they propagate to the Lambda runtime.
+ *
+ * @param routes - Map of upper-case HTTP method names (e.g. `"GET"`, `"POST"`)
+ *   to their corresponding {@link RouteHandler}.
+ *
+ * @example
+ * ```ts
+ * export const handler = createHandler({
+ *   GET: method().handle(async () => Response.json(200, {ok: true})),
+ * })
+ * ```
+ */
+export function createHandler<T extends Record<string, RouteHandler>>(routes: T) {
+    return async (
+        event: APIGatewayProxyEvent,
+        context: Context,
+    ): Promise<APIGatewayProxyResult> => {
+        const route = routes[event.httpMethod as keyof T]
+        if (!route) {
+            return Response.text(405, "Method Not Allowed")
+                .header("Allow", Object.keys(routes).join(", "))
+                .toAPIGatewayProxyResult()
+        }
+        try {
+            return await dispatch(route, event, context)
+        } catch (error) {
+            if (error instanceof Error) {
+                logError(error)
+                return Response.text(
+                    500,
+                    isProduction() ? "Internal Server Error" : formatError(error),
+                ).toAPIGatewayProxyResult()
+            }
+            throw error
+        }
+    }
+}

package/src/logger.ts

@@ -0,0 +1,19 @@
+import * as z from "zod"
+
+/**
+ * Formats an `Error` into a human-readable string that includes the error
+ * name, message, an optional Zod validation detail block, and the stack
+ * trace when available.
+ */
+export function formatError(error: Error): string {
+    let detail
+    if (error instanceof z.ZodError) {
+        detail = z.treeifyError(error).errors.join("\n")
+    }
+    return `${error.name}: ${error.message}${detail ? `\n${detail}` : ""}${error.stack ? `\n${error.stack}` : ""}`
+}
+
+/** Writes a formatted error to `stderr` via `console.error`. */
+export function logError(error: Error): void {
+    console.error(formatError(error))
+}

package/src/method.ts

@@ -0,0 +1,92 @@
+import {type Middleware} from "#src/middleware"
+import {EndpointCallback, RouteHandler} from "#src/route-handler"
+import type {ZodType} from "zod"
+
+export type {EndpointCallback, RouteHandler}
+
+/**
+ * Fluent, immutable builder for a single HTTP-method handler.
+ *
+ * Every method returns a new `Method` instance, leaving the original
+ * unchanged.  Build a method with the following chain:
+ *
+ * ```ts
+ * method().use(cors()).input(schema).output(schema).handle(async ({body}) => …)
+ * ```
+ *
+ * @typeParam TInput  - Shape of the validated request body.
+ * @typeParam TOutput - Return type of the handler callback.
+ */
+export class Method<TInput = unknown, TOutput = unknown> {
+    middlewares: Middleware[] = []
+    bodySchema?: ZodType<TInput>
+    outputSchema?: ZodType<TOutput>
+    callback?: EndpointCallback<TInput, TOutput>
+
+    /**
+     * Appends a middleware to the chain.  Middlewares are applied
+     * left-to-right after the callback resolves.
+     *
+     * @param middleware - The {@link Middleware} to append.
+     */
+    use(middleware: Middleware): Method<TInput, TOutput> {
+        const r = new Method<TInput, TOutput>()
+        r.middlewares = [...this.middlewares, middleware]
+        if (this.bodySchema) r.bodySchema = this.bodySchema
+        if (this.outputSchema) r.outputSchema = this.outputSchema
+        if (this.callback) r.callback = this.callback
+        return r
+    }
+
+    /**
+     * Attaches a Zod schema used to validate (and narrow) the request body.
+     * When validation fails, `dispatch` returns a `400` response automatically.
+     *
+     * @param bodySchema - Zod schema for the request body.
+     */
+    input<U>(bodySchema: ZodType<U>): Method<U, TOutput> {
+        const r = new Method<U, TOutput>()
+        r.middlewares = this.middlewares
+        r.bodySchema = bodySchema
+        if (this.outputSchema) r.outputSchema = this.outputSchema as ZodType<TOutput>
+        if (this.callback)
+            r.callback = this.callback as unknown as EndpointCallback<U, TOutput>
+        return r
+    }
+
+    /**
+     * Attaches a Zod schema that describes the expected response shape.
+     * Currently stored for documentation / code-generation purposes.
+     *
+     * @param schema - Zod schema for the response body.
+     */
+    output<U>(schema: ZodType<U>): Method<TInput, U> {
+        const r = new Method<TInput, U>()
+        r.middlewares = this.middlewares
+        if (this.bodySchema) r.bodySchema = this.bodySchema
+        r.outputSchema = schema
+        if (this.callback)
+            r.callback = this.callback as unknown as EndpointCallback<TInput, U>
+        return r
+    }
+
+    /**
+     * Registers the async handler callback for this method.
+     *
+     * @param callback - Function that receives the validated body, the raw
+     *   Lambda event, and the Lambda context, and returns the response.
+     */
+    handle(callback: EndpointCallback<TInput, TOutput>): Method<TInput, TOutput> {
+        const r = new Method<TInput, TOutput>()
+        r.middlewares = this.middlewares
+        if (this.bodySchema) r.bodySchema = this.bodySchema
+        if (this.outputSchema) r.outputSchema = this.outputSchema
+        r.callback = callback
+        return r
+    }
+}
+
+/** Creates a new, empty {@link Method} builder. */
+export function method(): Method {
+    return new Method()
+}

package/src/middleware.ts

@@ -0,0 +1,41 @@
+import type {APIGatewayProxyResult} from "aws-lambda"
+
+import {RouteHandler} from "./route-handler"
+
+/**
+ * A pure function that receives an {@link APIGatewayProxyResult} and returns
+ * a (possibly modified) copy of it.  Middlewares are composed left-to-right
+ * by {@link dispatch}.
+ */
+export type Middleware = (result: APIGatewayProxyResult) => APIGatewayProxyResult
+
+/**
+ * Creates a middleware that injects CORS response headers.
+ *
+ * Each key in `headers` is prefixed with `"Access-Control-"` before being
+ * merged into the response, so passing `{"Allow-Origin": "*"}` produces the
+ * `Access-Control-Allow-Origin: *` header.
+ *
+ * @param headers - Map of unprefixed CORS header names to their values.
+ *   Defaults to an empty object (no CORS headers added).
+ */
+export function cors(headers: Record<string, string> = {}): Middleware {
+    return (result) => {
+        const corsHeaders: Record<string, string> = {}
+        for (const [key, value] of Object.entries(headers)) {
+            corsHeaders[`Access-Control-${key}`] = value
+        }
+        return {...result, headers: {...result.headers, ...corsHeaders}}
+    }
+}
+
+/**
+ * Folds all middlewares registered on `route` over `result`, applying them
+ * left-to-right, and returns the final {@link APIGatewayProxyResult}.
+ */
+export function applyMiddlewares(
+    result: APIGatewayProxyResult,
+    route: RouteHandler,
+): APIGatewayProxyResult {
+    return route.middlewares.reduce((r, middleware) => middleware(r), result)
+}

package/src/response.ts

@@ -0,0 +1,86 @@
+import type {APIGatewayProxyResult} from "aws-lambda"
+
+/**
+ * Immutable builder for AWS Lambda proxy responses.
+ *
+ * All mutation methods return a new `Response` instance so that existing
+ * instances are never modified.  Construct instances through the static
+ * factory methods {@link Response.text} and {@link Response.json}.
+ */
+export class Response {
+    status?: number
+    body?: unknown
+    text?: string
+    headers?: Record<string, string>
+
+    private constructor() {}
+
+    /**
+     * Creates a plain-text response.
+     *
+     * @param status - HTTP status code.
+     * @param text - Response body as a plain string.
+     */
+    static text(status: number, text: string) {
+        const r = new Response()
+        r.status = status
+        r.text = text
+        return r
+    }
+
+    /**
+     * Creates a JSON response.
+     *
+     * @param status - HTTP status code.
+     * @param body - Value to be serialised with `JSON.stringify`.
+     */
+    static json(status: number, body: unknown) {
+        const r = new Response()
+        r.status = status
+        r.body = body
+        return r
+    }
+
+    /**
+     * Returns a new `Response` with an additional HTTP response header.
+     *
+     * @param name - Header name (e.g. `"Allow"`).
+     * @param value - Header value.
+     */
+    header(name: string, value: string): Response {
+        const r = new Response()
+        if (this.status !== undefined) r.status = this.status
+        if (this.body !== undefined) r.body = this.body
+        if (this.text !== undefined) r.text = this.text
+        r.headers = {...this.headers, [name]: value}
+        return r
+    }
+
+    /**
+     * Serialises this `Response` into the shape expected by the AWS Lambda
+     * proxy integration.
+     *
+     * - When constructed via {@link Response.json} the body is JSON-encoded
+     *   and `Content-Type` is set to `application/json; charset=utf-8`.
+     * - When constructed via {@link Response.text} the body is returned as-is
+     *   and `Content-Type` is set to `text/plain; charset=utf-8`.
+     * - Additional headers set via {@link Response.header} are merged last and
+     *   therefore take precedence over the defaults above.
+     */
+    toAPIGatewayProxyResult(): APIGatewayProxyResult {
+        return {
+            statusCode: this.status ?? 200,
+            body:
+                this.text === undefined ?
+                    (JSON.stringify(this.body) ?? "null")
+                :   this.text,
+            headers: {
+                "Content-Type":
+                    this.text === undefined ?
+                        "application/json; charset=utf-8"
+                    :   "text/plain; charset=utf-8",
+                ...this.headers,
+            },
+        }
+    }
+}

package/src/route-handler.ts

@@ -0,0 +1,28 @@
+import {type Middleware} from "#src/middleware"
+import {Response} from "#src/response"
+import type {APIGatewayProxyEvent, Context} from "aws-lambda"
+import type {ZodType} from "zod"
+
+/**
+ * The user-supplied handler function for a single HTTP method on a route.
+ *
+ * @typeParam TInput  - Shape of the validated request body (after Zod parsing).
+ * @typeParam TOutput - Shape of the value returned by the callback.
+ */
+export type EndpointCallback<TInput, TOutput> = (props: {
+    body: TInput
+    event: APIGatewayProxyEvent
+    context: Context
+}) => Promise<TOutput | Response> | TOutput | Response
+
+/**
+ * Internal read-only view of a {@link Method} used by {@link dispatch} and
+ * {@link createHandler}.  The type parameters are erased so that handlers for
+ * different routes can be stored in the same map.
+ */
+export interface RouteHandler {
+    readonly middlewares: Middleware[]
+    readonly bodySchema?: ZodType<unknown>
+    readonly outputSchema?: ZodType<unknown>
+    readonly callback?: (props: never) => unknown
+}