lambda-reactor 1.0.0

package/src/router-class.ts

@@ -0,0 +1,98 @@
+import {readFileSync} from "fs"
+import {join} from "path"
+
+import {buildHandlers, type FunctionFactory} from "#src/build-handlers"
+import {getMethods} from "#src/router"
+import {type CorsOptions, IRestApi, LambdaIntegration} from "aws-cdk-lib/aws-apigateway"
+import {IFunction} from "aws-cdk-lib/aws-lambda"
+
+/**
+ * Immutable CDK router that maps route paths to Lambda-backed API Gateway
+ * resources.
+ *
+ * ```ts
+ * const api = router()
+ *   .cors({allowOrigins: ["*"]})
+ *   .route("/users")
+ *   .route("/items")
+ *   .defineRestApi(restApi, factory)
+ * ```
+ *
+ * @typeParam TPaths - Union of all route path strings registered so far.
+ */
+export class Router<TPaths extends string = never> {
+    srcDir: string
+    corsOptions?: CorsOptions
+    paths: TPaths[] = []
+
+    constructor(srcDir: string) {
+        this.srcDir = srcDir
+    }
+
+    /**
+     * Returns a new `Router` with CORS preflight options applied to every
+     * resource added via {@link Router.route}.
+     *
+     * @param options - CDK `CorsOptions` passed to `addCorsPreflight`.
+     */
+    cors(options: CorsOptions): Router<TPaths> {
+        const r = new Router<TPaths>(this.srcDir)
+        r.corsOptions = options
+        r.paths = this.paths
+        return r
+    }
+
+    /**
+     * Registers a new route path and returns a new `Router` with the path
+     * added to its path union.
+     *
+     * @param path - Route path string (e.g. `"/users"`).  Must correspond to a
+     *   handler file at `<srcDir>/<path>.ts`.
+     */
+    route<TPath extends string>(path: TPath): Router<TPaths | TPath> {
+        const r = new Router<TPaths | TPath>(this.srcDir)
+        if (this.corsOptions) r.corsOptions = this.corsOptions
+        r.paths = [...this.paths, path as unknown as TPaths | TPath]
+        return r
+    }
+
+    /**
+     * Wires all registered routes into the given API Gateway REST API.
+     *
+     * For each route path the method:
+     * 1. Creates (or reuses) nested API Gateway resources for each path segment.
+     * 2. Optionally calls `addCorsPreflight` when CORS options are configured.
+     * 3. Reads the handler source file and extracts HTTP method names via
+     *    {@link getMethods}.
+     * 4. Adds an `addMethod` entry backed by a `LambdaIntegration` for each
+     *    discovered method.
+     *
+     * @param api     - The CDK `IRestApi` to attach resources and methods to.
+     * @param factory - {@link FunctionFactory} used to build Lambda functions.
+     * @returns A record mapping each route path to its {@link IFunction}.
+     */
+    defineRestApi<TApi extends IRestApi>(
+        api: TApi,
+        factory: FunctionFactory,
+    ): Record<TPaths, IFunction> {
+        const handlers = buildHandlers(this.paths, factory)
+        for (const path of this.paths) {
+            const resource = path
+                .split("/")
+                .filter(Boolean)
+                .reduce(
+                    (r, part) => r.getResource(part) ?? r.addResource(part),
+                    api.root,
+                )
+            if (this.corsOptions) resource.addCorsPreflight(this.corsOptions)
+            const src = readFileSync(
+                join(process.cwd(), this.srcDir, `${path}.ts`),
+                "utf-8",
+            )
+            for (const method of getMethods(src)) {
+                resource.addMethod(method, new LambdaIntegration(handlers[path]!))
+            }
+        }
+        return handlers
+    }
+}

package/src/router.ts

@@ -0,0 +1,30 @@
+import {Router} from "#src/router-class"
+
+export {Router}
+
+/**
+ * Extracts the HTTP method names declared inside a `createHandler({…})` call
+ * by statically scanning the source text of a handler file.
+ *
+ * @param src - Raw TypeScript source of a handler module.
+ * @returns Array of upper-case HTTP method names (e.g. `["GET", "POST"]`),
+ *   or an empty array when no `createHandler` call is found.
+ */
+export function getMethods(src: string): string[] {
+    const match = src.match(/createHandler\(\{([^}]*)\}\)/)
+    if (!match || !match[1]) return []
+    return match[1]
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+}
+
+/**
+ * Creates a new, empty {@link Router} builder.
+ *
+ * @param srcDir - Directory (relative to `cwd`) where handler `.ts` files
+ *   live.  Defaults to `"src"`.
+ */
+export function router(srcDir: string = "src"): Router {
+    return new Router(srcDir)
+}

package/tests/api-get-methods.test.ts

@@ -0,0 +1,14 @@
+import {getMethods} from "#src/router"
+import {describe, expect, it} from "vitest"
+
+describe("getMethods", () => {
+    it("extracts HTTP method names from a lambda handler file", () => {
+        expect(
+            getMethods(`export const handler = createHandler({GET, POST, DELETE})`),
+        ).toEqual(["GET", "POST", "DELETE"])
+    })
+
+    it("returns empty array when no createHandler call is found", () => {
+        expect(getMethods(`export const handler = () => {}`)).toEqual([])
+    })
+})

package/tests/api-router-factory.test.ts

@@ -0,0 +1,46 @@
+import {join} from "path"
+
+import type {IRestApi} from "aws-cdk-lib/aws-apigateway"
+import type {IFunction} from "aws-cdk-lib/aws-lambda"
+import {beforeEach, describe, expect, it, vi} from "vitest"
+
+vi.mock("fs", () => ({readFileSync: vi.fn()}))
+vi.mock("aws-cdk-lib/aws-apigateway", () => ({
+    LambdaIntegration: vi.fn(),
+}))
+
+describe("router defineRestApi factory overload", () => {
+    beforeEach(async () => {
+        const {readFileSync} = await import("fs")
+        ;(readFileSync as ReturnType<typeof vi.fn>).mockReturnValue(
+            `export const handler = createHandler({GET})`,
+        )
+    })
+
+    it("accepts a factory and returns a record keyed by path", async () => {
+        const {router} = await import("#src/router")
+        const fakeResource = {
+            getResource: () => undefined,
+            addResource: () => fakeResource,
+            addMethod: vi.fn(),
+        }
+        const api = {root: fakeResource} as unknown as IRestApi
+        const factory = vi.fn(
+            (entry: string, id: string) => ({entry, id}) as unknown as IFunction,
+        )
+        const result = router()
+            .route("/user/{user_id}")
+            .route("/posts")
+            .defineRestApi(api, factory)
+        expect(factory).toHaveBeenCalledWith(
+            join(process.cwd(), "src", "/user/{user_id}.ts"),
+            "/user/{user_id}",
+        )
+        expect(factory).toHaveBeenCalledWith(
+            join(process.cwd(), "src", "/posts.ts"),
+            "/posts",
+        )
+        expect(Object.keys(result)).toEqual(["/user/{user_id}", "/posts"])
+        expect(result).not.toBe(api)
+    })
+})

package/tests/api-router.test.ts

@@ -0,0 +1,72 @@
+import {join} from "path"
+
+import type {IRestApi} from "aws-cdk-lib/aws-apigateway"
+import type {IFunction} from "aws-cdk-lib/aws-lambda"
+import {beforeEach, describe, expect, it, vi} from "vitest"
+
+vi.mock("fs", () => ({readFileSync: vi.fn()}))
+
+vi.mock("aws-cdk-lib/aws-apigateway", () => ({
+    LambdaIntegration: vi.fn((handler: unknown) => ({handler})),
+}))
+
+class FakeResource {
+    children = new Map<string, FakeResource>()
+    methods: {method: string; integration: unknown}[] = []
+    getResource(part: string) {
+        return this.children.get(part)
+    }
+    addResource(part: string) {
+        const child = new FakeResource()
+        this.children.set(part, child)
+        return child
+    }
+    addMethod(method: string, value: unknown) {
+        this.methods.push({method, integration: value})
+        return this
+    }
+}
+
+describe("router defineRestApi", () => {
+    beforeEach(async () => {
+        const {LambdaIntegration} = await import("aws-cdk-lib/aws-apigateway")
+        ;(LambdaIntegration as ReturnType<typeof vi.fn>).mockClear()
+        const {readFileSync} = await import("fs")
+        ;(readFileSync as ReturnType<typeof vi.fn>).mockReturnValue(
+            `export const handler = createHandler({GET, POST})`,
+        )
+    })
+
+    it("defines nested rest resources on an existing api instance", async () => {
+        const {router} = await import("#src/router")
+        const root = new FakeResource()
+        const api = {root} as unknown as IRestApi
+        const getUser = {name: "getUser"} as unknown as IFunction
+        const createPost = {name: "createPost"} as unknown as IFunction
+        const factory = vi.fn((_entry: string, id: string) => {
+            if (id === "/user/{user_id}") return getUser
+            return createPost
+        })
+        router().route("/user/{user_id}").route("/posts").defineRestApi(api, factory)
+        expect(factory).toHaveBeenCalledWith(
+            join(process.cwd(), "src", "/user/{user_id}.ts"),
+            "/user/{user_id}",
+        )
+        expect(factory).toHaveBeenCalledWith(
+            join(process.cwd(), "src", "/posts.ts"),
+            "/posts",
+        )
+        const {LambdaIntegration} = await import("aws-cdk-lib/aws-apigateway")
+        expect(LambdaIntegration).toHaveBeenCalledWith(getUser)
+        expect(LambdaIntegration).toHaveBeenCalledWith(createPost)
+        const user = root.getResource("user")
+        expect(user?.getResource("{user_id}")?.methods).toEqual([
+            {method: "GET", integration: {handler: getUser}},
+            {method: "POST", integration: {handler: getUser}},
+        ])
+        expect(root.getResource("posts")?.methods).toEqual([
+            {method: "GET", integration: {handler: createPost}},
+            {method: "POST", integration: {handler: createPost}},
+        ])
+    })
+})

package/tests/config-cors.test.ts

@@ -0,0 +1,50 @@
+import {dispatch} from "#src/dispatch"
+import {method} from "#src/method"
+import {cors} from "#src/middleware"
+import type {APIGatewayProxyEvent, Context} from "aws-lambda"
+import {describe, expect, it} from "vitest"
+
+const context = {} as Context
+
+const event = {
+    body: null,
+    headers: {},
+    multiValueHeaders: {},
+    httpMethod: "GET",
+    isBase64Encoded: false,
+    path: "/",
+    pathParameters: null,
+    queryStringParameters: null,
+    multiValueQueryStringParameters: null,
+    stageVariables: null,
+    resource: "/",
+    requestContext: {} as APIGatewayProxyEvent["requestContext"],
+} satisfies APIGatewayProxyEvent
+
+describe("cors middleware", () => {
+    it("adds Access-Control headers to response", async () => {
+        const route = method()
+            .use(cors({"Allow-Origin": "*", "Allow-Methods": "GET,POST"}))
+            .handle(async () => "ok")
+        const result = await dispatch(route, event, context)
+        expect(result.headers?.["Access-Control-Allow-Origin"]).toBe("*")
+        expect(result.headers?.["Access-Control-Allow-Methods"]).toBe("GET,POST")
+    })
+
+    it("does not add cors headers when no middleware used", async () => {
+        const route = method().handle(async () => "ok")
+        const result = await dispatch(route, event, context)
+        const keys = Object.keys(result.headers ?? {})
+        expect(keys.some((k) => k.startsWith("Access-Control"))).toBe(false)
+    })
+
+    it("applies multiple cors middlewares in order", async () => {
+        const route = method()
+            .use(cors({"Allow-Origin": "*"}))
+            .use(cors({"Allow-Methods": "GET"}))
+            .handle(async () => "ok")
+        const result = await dispatch(route, event, context)
+        expect(result.headers?.["Access-Control-Allow-Origin"]).toBe("*")
+        expect(result.headers?.["Access-Control-Allow-Methods"]).toBe("GET")
+    })
+})

package/tests/config.test.ts

@@ -0,0 +1,79 @@
+import {method} from "#src/method"
+import {cors} from "#src/middleware"
+import {router} from "#src/router"
+import {describe, expect, it} from "vitest"
+import {z} from "zod"
+
+describe("method middlewares", () => {
+    it("has empty middlewares by default", () => {
+        expect(method().middlewares).toEqual([])
+    })
+
+    it("adds middleware via .use()", () => {
+        const m = cors({"Allow-Origin": "*"})
+        expect(method().use(m).middlewares).toHaveLength(1)
+    })
+
+    it("accumulates multiple middlewares", () => {
+        const m1 = cors({"Allow-Origin": "*"})
+        const m2 = cors({"Allow-Methods": "GET"})
+        expect(method().use(m1).use(m2).middlewares).toHaveLength(2)
+    })
+
+    it("propagates middlewares through input chain", () => {
+        const m = cors({"Allow-Origin": "*"})
+        expect(
+            method()
+                .use(m)
+                .input(z.object({x: z.string()})).middlewares,
+        ).toHaveLength(1)
+    })
+
+    it("propagates middlewares through output chain", () => {
+        const m = cors({"Allow-Origin": "*"})
+        expect(
+            method()
+                .use(m)
+                .output(z.object({x: z.string()})).middlewares,
+        ).toHaveLength(1)
+    })
+
+    it("propagates middlewares through handle chain", () => {
+        const m = cors({"Allow-Origin": "*"})
+        expect(
+            method()
+                .use(m)
+                .handle(async () => "ok").middlewares,
+        ).toHaveLength(1)
+    })
+})
+
+describe("router srcDir", () => {
+    it("defaults srcDir to src", () => {
+        expect(router().srcDir).toBe("src")
+    })
+
+    it("accepts custom srcDir", () => {
+        expect(router("src/api").srcDir).toBe("src/api")
+    })
+
+    it("propagates srcDir through route chain", () => {
+        expect(router("src/api").route("/health").srcDir).toBe("src/api")
+    })
+})
+
+describe("router cors", () => {
+    it("stores corsOptions via .cors()", () => {
+        const options = {allowOrigins: ["*"], allowMethods: ["GET"]}
+        expect(router().cors(options).corsOptions).toEqual(options)
+    })
+
+    it("propagates corsOptions through route chain", () => {
+        const options = {allowOrigins: ["*"], allowMethods: ["GET"]}
+        expect(router().cors(options).route("/health").corsOptions).toEqual(options)
+    })
+
+    it("has no corsOptions by default", () => {
+        expect(router().corsOptions).toBeUndefined()
+    })
+})

package/tests/dispatch-error-logging.test.ts

@@ -0,0 +1,61 @@
+import {dispatch} from "#src/dispatch"
+import * as logger from "#src/logger"
+import {method} from "#src/method"
+import type {APIGatewayProxyEvent, Context} from "aws-lambda"
+import {describe, expect, it, vi} from "vitest"
+import {z} from "zod"
+
+const context = {} as Context
+
+const event = {
+    body: null,
+    headers: {},
+    multiValueHeaders: {},
+    httpMethod: "GET",
+    isBase64Encoded: false,
+    path: "/",
+    pathParameters: null,
+    queryStringParameters: null,
+    multiValueQueryStringParameters: null,
+    stageVariables: null,
+    resource: "/",
+    requestContext: {} as APIGatewayProxyEvent["requestContext"],
+} satisfies APIGatewayProxyEvent
+
+describe("dispatch error logging", () => {
+    it("logs error when route has no callback", async () => {
+        const logError = vi.spyOn(logger, "logError").mockImplementation(() => "")
+        const route = method()
+        await expect(dispatch(route, event, context)).resolves.toMatchObject({
+            statusCode: 500,
+        })
+        expect(logError).toHaveBeenCalledWith(expect.any(Error))
+        logError.mockRestore()
+    })
+
+    it("logs error when output schema validation fails on Response body", async () => {
+        const logError = vi.spyOn(logger, "logError").mockImplementation(() => "")
+        const route = method()
+            .output(z.object({n: z.number()}))
+            .handle(() => ({n: "not-a-number"}) as unknown as {n: number})
+        await expect(dispatch(route, event, context)).resolves.toMatchObject({
+            statusCode: 500,
+        })
+        expect(logError).toHaveBeenCalled()
+        logError.mockRestore()
+    })
+
+    it("logs error when output schema validation fails on plain result", async () => {
+        const logError = vi.spyOn(logger, "logError").mockImplementation(() => "")
+        const route = method()
+            .output(z.object({n: z.number()}))
+            .handle(() =>
+                Promise.resolve({n: "not-a-number"} as unknown as {n: number}),
+            )
+        await expect(dispatch(route, event, context)).resolves.toMatchObject({
+            statusCode: 500,
+        })
+        expect(logError).toHaveBeenCalled()
+        logError.mockRestore()
+    })
+})

package/tests/env.test.ts

@@ -0,0 +1,38 @@
+import {isProduction} from "#src/env"
+import {afterEach, describe, expect, it} from "vitest"
+
+const ENV_KEYS = ["NODE_ENV", "STAGE", "ENV", "ENVIRONMENT"] as const
+
+describe("isProduction", () => {
+    afterEach(() => {
+        for (const key of ENV_KEYS) {
+            delete process.env[key]
+        }
+    })
+
+    it("returns false when no env vars are set", () => {
+        expect(isProduction()).toBe(false)
+    })
+
+    for (const key of ENV_KEYS) {
+        it(`returns true when ${key}=production`, () => {
+            process.env[key] = "production"
+            expect(isProduction()).toBe(true)
+        })
+
+        it(`returns true when ${key}=prod`, () => {
+            process.env[key] = "prod"
+            expect(isProduction()).toBe(true)
+        })
+
+        it(`returns true when ${key}=PRODUCTION (case-insensitive)`, () => {
+            process.env[key] = "PRODUCTION"
+            expect(isProduction()).toBe(true)
+        })
+
+        it(`returns false when ${key}=development`, () => {
+            process.env[key] = "development"
+            expect(isProduction()).toBe(false)
+        })
+    }
+})

package/tests/handler-error-logging.test.ts

@@ -0,0 +1,61 @@
+import {createHandler} from "#src/handler"
+import {method} from "#src/method"
+import type {APIGatewayProxyEvent, Context} from "aws-lambda"
+import {afterEach, describe, expect, it, vi} from "vitest"
+
+vi.mock("source-map-support", () => ({install: vi.fn()}))
+
+const context = {} as Context
+
+function event(httpMethod: string): APIGatewayProxyEvent {
+    return {
+        body: null,
+        headers: {},
+        multiValueHeaders: {},
+        httpMethod,
+        isBase64Encoded: false,
+        path: "/",
+        pathParameters: null,
+        queryStringParameters: null,
+        multiValueQueryStringParameters: null,
+        stageVariables: null,
+        resource: "/",
+        requestContext: {} as APIGatewayProxyEvent["requestContext"],
+    }
+}
+
+describe("createHandler error logging", () => {
+    afterEach(() => {
+        delete process.env["NODE_ENV"]
+    })
+
+    it("logs the error message and returns it in the body outside production", async () => {
+        const consoleError = vi.spyOn(console, "error").mockImplementation(() => {})
+        const boom = new Error("boom")
+        const handler = createHandler({
+            GET: method().handle(() => {
+                throw boom
+            }),
+        })
+        const result = await handler(event("GET"), context)
+        expect(result.statusCode).toBe(500)
+        expect(result.body).toContain("boom")
+        expect(consoleError).toHaveBeenCalledWith(expect.stringContaining("boom"))
+        consoleError.mockRestore()
+    })
+
+    it("returns generic message in production", async () => {
+        process.env["NODE_ENV"] = "production"
+        const consoleError = vi.spyOn(console, "error").mockImplementation(() => {})
+        const handler = createHandler({
+            GET: method().handle(() => {
+                throw new Error("secret details")
+            }),
+        })
+        const result = await handler(event("GET"), context)
+        expect(result.statusCode).toBe(500)
+        expect(result.body).toBe("Internal Server Error")
+        expect(result.body).not.toContain("secret details")
+        consoleError.mockRestore()
+    })
+})

package/tests/handler-routing-validation.test.ts

@@ -0,0 +1,86 @@
+import {createHandler} from "#src/handler"
+import {method} from "#src/method"
+import {Response} from "#src/response"
+import type {APIGatewayProxyEvent, Context} from "aws-lambda"
+import {describe, expect, it} from "vitest"
+import {z} from "zod"
+
+function event(httpMethod: string, body: unknown = undefined): APIGatewayProxyEvent {
+    return {
+        body:
+            body === undefined ? null
+            : typeof body === "string" ? body
+            : JSON.stringify(body),
+        headers: {},
+        multiValueHeaders: {},
+        httpMethod,
+        isBase64Encoded: false,
+        path: "/",
+        pathParameters: null,
+        queryStringParameters: null,
+        multiValueQueryStringParameters: null,
+        stageVariables: null,
+        resource: "/",
+        requestContext: {} as APIGatewayProxyEvent["requestContext"],
+    }
+}
+
+const context = {} as Context
+
+describe("createHandler validation", () => {
+    it("validates input and returns 400 on bad input", async () => {
+        const handler = createHandler({
+            POST: method()
+                .input(z.object({username: z.string()}))
+                .handle(({body}) => ({username: body.username})),
+        })
+        const invalid = await handler(event("POST", {username: 7}), context)
+        expect(invalid).toMatchObject({
+            statusCode: 400,
+            headers: {"Content-Type": "text/plain; charset=utf-8"},
+        })
+    })
+
+    it("validates output schema and returns json on success", async () => {
+        const handler = createHandler({
+            POST: method()
+                .input(z.object({username: z.string()}))
+                .output(z.object({username: z.string()}))
+                .handle(({body}) => ({username: body.username})),
+        })
+        await expect(
+            handler(event("POST", {username: "neo"}), context),
+        ).resolves.toEqual({
+            statusCode: 200,
+            body: JSON.stringify({username: "neo"}),
+            headers: {"Content-Type": "application/json; charset=utf-8"},
+        })
+    })
+
+    it("validates output schema against raw Response body and returns 500 on mismatch", async () => {
+        const handler = createHandler({
+            POST: method()
+                .output(z.object({username: z.string()}))
+                .handle(() => Response.json(200, {username: 42})),
+        })
+        const result = await handler(event("POST"), context)
+        expect(result).toMatchObject({
+            statusCode: 500,
+            headers: {"Content-Type": "text/plain; charset=utf-8"},
+        })
+    })
+
+    it("validates output schema against raw Response body and passes on match", async () => {
+        const handler = createHandler({
+            POST: method()
+                .output(z.object({username: z.string()}))
+                .handle(() => Response.json(201, {username: "neo"})),
+        })
+        const result = await handler(event("POST"), context)
+        expect(result).toEqual({
+            statusCode: 201,
+            body: JSON.stringify({username: "neo"}),
+            headers: {"Content-Type": "application/json; charset=utf-8"},
+        })
+    })
+})

package/tests/handler-routing.test.ts

@@ -0,0 +1,37 @@
+import {createHandler} from "#src/handler"
+import {method} from "#src/method"
+import type {APIGatewayProxyEvent, Context} from "aws-lambda"
+import {describe, expect, it} from "vitest"
+
+function event(httpMethod: string, body: unknown = undefined): APIGatewayProxyEvent {
+    return {
+        body:
+            body === undefined ? null
+            : typeof body === "string" ? body
+            : JSON.stringify(body),
+        headers: {},
+        multiValueHeaders: {},
+        httpMethod,
+        isBase64Encoded: false,
+        path: "/",
+        pathParameters: null,
+        queryStringParameters: null,
+        multiValueQueryStringParameters: null,
+        stageVariables: null,
+        resource: "/",
+        requestContext: {} as APIGatewayProxyEvent["requestContext"],
+    }
+}
+
+const context = {} as Context
+
+describe("createHandler routing", () => {
+    it("returns 405 with allow header for unsupported methods", async () => {
+        const handler = createHandler({GET: method().handle(() => ({ok: true}))})
+        await expect(handler(event("POST"), context)).resolves.toEqual({
+            statusCode: 405,
+            body: "Method Not Allowed",
+            headers: {"Content-Type": "text/plain; charset=utf-8", Allow: "GET"},
+        })
+    })
+})