lambda-reactor 1.0.0 → 1.0.1

package/examples/items.ts

@@ -1,25 +0,0 @@
-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

@@ -1,20 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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/src/dispatch.ts

@@ -1,91 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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

@@ -1,58 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,92 +0,0 @@
-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/response.ts

@@ -1,86 +0,0 @@
-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/router-class.ts

@@ -1,98 +0,0 @@
-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/tests/api-get-methods.test.ts

@@ -1,14 +0,0 @@
-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

@@ -1,46 +0,0 @@
-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)
-    })
-})