@actuallyjamez/elysian 0.2.1

package/README.md

@@ -0,0 +1,225 @@
+# elysian
+
+Automatic Lambda bundler for [Elysia](https://elysiajs.com/) with AWS API Gateway and Terraform integration.
+
+## Features
+
+- **Zero-config Lambda handlers** - Just export your Elysia routes as default, handlers are auto-generated
+- **Automatic OpenAPI aggregation** - All routes are aggregated into a single OpenAPI spec endpoint
+- **Terraform integration** - Generates `tfvars` files for seamless infrastructure deployment
+- **Type-safe configuration** - Full TypeScript support with `defineConfig()`
+- **Watch mode** - Fast rebuilds during development
+
+## Installation
+
+```bash
+# Configure GitHub registry for @actuallyjamez scope
+echo "@actuallyjamez:registry=https://npm.pkg.github.com" >> .npmrc
+
+# Install
+bun add elysia @actuallyjamez/elysian
+```
+
+## Quick Start
+
+### 1. Initialize your project
+
+```bash
+bunx @actuallyjamez/elysian init --name my-api
+```
+
+This creates:
+- `elysian.config.ts` - Configuration file
+- `src/lambdas/hello.ts` - Example lambda
+- `terraform/main.tf` - Terraform infrastructure
+
+### 2. Write your lambdas
+
+```typescript
+// src/lambdas/users.ts
+import { createLambda, t } from "@actuallyjamez/elysian";
+
+export default createLambda()
+  .get("/users", () => db.getUsers(), {
+    response: t.Array(t.Object({ id: t.String(), name: t.String() })),
+    detail: { summary: "List all users", tags: ["Users"] },
+  })
+  .get("/users/:id", ({ params }) => db.getUser(params.id), {
+    params: t.Object({ id: t.String() }),
+    detail: { summary: "Get user by ID", tags: ["Users"] },
+  })
+  .post("/users", ({ body }) => db.createUser(body), {
+    body: t.Object({ name: t.String(), email: t.String() }),
+    detail: { summary: "Create user", tags: ["Users"] },
+  });
+```
+
+**That's it!** No need to export a handler - the bundler wraps your default export automatically.
+
+### 3. Build
+
+```bash
+# Development build
+bunx elysian build
+
+# Production build (minified)
+bunx elysian build --prod
+```
+
+### 4. Deploy
+
+```bash
+cd terraform
+terraform init
+terraform apply
+```
+
+## Configuration
+
+Create `elysian.config.ts` in your project root:
+
+```typescript
+import { defineConfig } from "@actuallyjamez/elysian";
+
+export default defineConfig({
+  // Required
+  apiName: "my-api",
+
+  // Optional (showing defaults)
+  lambdasDir: "src/lambdas",
+  outputDir: "dist",
+
+  // OpenAPI configuration
+  openapi: {
+    enabled: true,
+    title: "My API",
+    version: "1.0.0",
+    description: "API description",
+  },
+
+  // Terraform output configuration
+  terraform: {
+    outputDir: "terraform",
+    tfvarsFilename: "api-routes.auto.tfvars", // Won't overwrite your existing tfvars
+  },
+
+  // Lambda defaults (used in generated tfvars)
+  lambda: {
+    runtime: "nodejs20.x",
+    memorySize: 256,
+    timeout: 30,
+  },
+});
+```
+
+## CLI Commands
+
+### `elysian build`
+
+Build all lambdas for deployment.
+
+```bash
+bunx elysian build          # Development build
+bunx elysian build --prod   # Production build (minified)
+```
+
+**Output:**
+- `dist/*.js` - Bundled lambda code
+- `dist/*.zip` - Lambda deployment packages
+- `dist/manifest.json` - Route manifest (for debugging)
+- `terraform/api-routes.auto.tfvars` - Terraform variables
+
+### `elysian dev`
+
+Watch mode for development - rebuilds on file changes.
+
+```bash
+bunx elysian dev              # Watch with packaging
+bunx elysian dev --no-package # Skip zip creation (faster)
+```
+
+### `elysian init`
+
+Initialize a new project with example files.
+
+```bash
+bunx elysian init --name my-api
+bunx elysian init --force  # Overwrite existing files
+```
+
+### `elysian generate-iac`
+
+Regenerate Terraform files without rebuilding lambdas.
+
+```bash
+bunx elysian generate-iac
+```
+
+## How It Works
+
+### 1. Route Discovery
+
+The bundler scans your `lambdasDir` for `.ts` files. Each file becomes a separate Lambda function.
+
+### 2. Handler Injection
+
+When you export an Elysia app as default:
+
+```typescript
+export default createLambda().get("/hello", () => "Hello!");
+```
+
+The bundler automatically wraps it with a Lambda handler:
+
+```typescript
+import { Hono } from "hono/tiny";
+import { handle } from "hono/aws-lambda";
+
+const app = /* your exported app */;
+export const handler = handle(new Hono().mount("/", app.fetch));
+```
+
+### 3. OpenAPI Aggregation
+
+An `__openapi__` lambda is automatically generated that imports all your routes and exposes:
+- `GET /openapi` - Swagger UI
+- `GET /openapi/json` - OpenAPI JSON spec
+
+### 4. Terraform Integration
+
+The generated `tfvars` file contains:
+- List of Lambda names
+- Route-to-Lambda mappings (with API Gateway path format)
+- Lambda configuration defaults
+
+## Project Structure
+
+```
+my-api/
+├── elysian.config.ts         # Configuration
+├── src/
+│   └── lambdas/
+│       ├── users.ts          # → users.zip Lambda
+│       ├── posts.ts          # → posts.zip Lambda
+│       └── auth.ts           # → auth.zip Lambda
+├── dist/                     # Build output
+│   ├── users.js
+│   ├── users.zip
+│   ├── posts.js
+│   ├── posts.zip
+│   ├── __openapi__.js        # Auto-generated
+│   ├── __openapi__.zip
+│   └── manifest.json
+└── terraform/
+    ├── main.tf
+    └── api-routes.auto.tfvars  # Auto-generated
+```
+
+## Requirements
+
+- [Bun](https://bun.sh/) runtime
+- [Elysia](https://elysiajs.com/) v1.0+
+
+## License
+
+MIT

package/dist/cli/commands/build.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Build command - Production build of all lambdas
+ */
+export declare const buildCommand: import("citty").CommandDef<{
+    prod: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+}>;

package/dist/cli/commands/build.js

@@ -0,0 +1,199 @@
+/**
+ * Build command - Production build of all lambdas
+ */
+import { defineCommand } from "citty";
+import { readdirSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import pc from "picocolors";
+import { loadConfig } from "../../core/config";
+import { bundleLambda } from "../../core/bundler";
+import { packageLambda } from "../../core/packager";
+import { generateManifest, writeManifest } from "../../core/manifest";
+import { writeTerraformVars } from "../../core/terraform";
+import { shouldGenerateOpenApi, writeOpenApiLambda, cleanupOpenApiLambda, } from "../../core/openapi";
+import { createWrapperEntry } from "../../core/handler-wrapper";
+import { getLambdaBundleName } from "../../core/naming";
+import { version } from "../../core/version";
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    return `${(ms / 1000).toFixed(2)}s`;
+}
+function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+export const buildCommand = defineCommand({
+    meta: {
+        name: "build",
+        description: "Build all lambdas for production deployment",
+    },
+    args: {
+        prod: {
+            type: "boolean",
+            description: "Production build (minify, no sourcemaps)",
+            default: false,
+        },
+    },
+    async run({ args }) {
+        const startTime = Date.now();
+        // Set production mode if flag is set
+        if (args.prod) {
+            process.env.NODE_ENV = "production";
+        }
+        // Header
+        console.log();
+        console.log(`  ${pc.bold(pc.cyan("elysian"))} ${pc.dim(`v${version}`)} ${args.prod ? pc.yellow("production") : pc.dim("development")}`);
+        console.log();
+        // Load config
+        let config;
+        try {
+            config = await loadConfig();
+        }
+        catch (error) {
+            console.log(`  ${pc.red("✗")} ${error instanceof Error ? error.message : error}`);
+            process.exit(1);
+        }
+        const apiName = config.apiName;
+        const lambdasDir = join(process.cwd(), config.lambdasDir);
+        const outputDir = join(process.cwd(), config.outputDir);
+        const terraformDir = join(process.cwd(), config.terraform.outputDir);
+        // Ensure directories exist
+        if (!existsSync(lambdasDir)) {
+            console.log(`  ${pc.red("✗")} Lambdas directory not found: ${lambdasDir}`);
+            process.exit(1);
+        }
+        mkdirSync(outputDir, { recursive: true });
+        mkdirSync(terraformDir, { recursive: true });
+        // Get lambda files
+        let lambdaFiles = readdirSync(lambdasDir).filter((f) => f.endsWith(".ts") && !f.startsWith("__"));
+        if (lambdaFiles.length === 0) {
+            console.log(`  ${pc.yellow("!")} No lambda files found in ${config.lambdasDir}`);
+            return;
+        }
+        // Generate OpenAPI aggregator if enabled
+        if (shouldGenerateOpenApi(config)) {
+            await writeOpenApiLambda(lambdaFiles, lambdasDir, config);
+            lambdaFiles.push("__openapi__.ts");
+        }
+        // Build phase
+        console.log(`  ${pc.green("✓")} Compiling ${lambdaFiles.length} lambdas...`);
+        const tempDir = join(outputDir, "__temp__");
+        mkdirSync(tempDir, { recursive: true });
+        const buildResults = [];
+        for (const file of lambdaFiles) {
+            const name = file.replace(/\.ts$/, "");
+            const bundleName = getLambdaBundleName(apiName, name);
+            const inputPath = join(lambdasDir, file);
+            // Create wrapper entry that imports the original and exports handler
+            const wrapperPath = join(tempDir, `${name}-wrapper.ts`);
+            const wrapperContent = createWrapperEntry(inputPath);
+            await Bun.write(wrapperPath, wrapperContent);
+            // Bundle the wrapper with prefixed name
+            const result = await bundleLambda(bundleName, wrapperPath, outputDir, config);
+            buildResults.push({ ...result, name, bundleName });
+            if (!result.success) {
+                console.log(`  ${pc.red("✗")} Failed to build ${name}: ${result.error}`);
+                process.exit(1);
+            }
+        }
+        // Clean up temp directory
+        const { rmSync } = await import("fs");
+        rmSync(tempDir, { recursive: true, force: true });
+        // Clean up generated OpenAPI file
+        if (shouldGenerateOpenApi(config)) {
+            await cleanupOpenApiLambda(lambdasDir);
+        }
+        // Package phase
+        console.log(`  ${pc.green("✓")} Packaging lambdas...`);
+        const packageSizes = new Map();
+        for (const file of lambdaFiles) {
+            const name = file.replace(/\.ts$/, "");
+            const bundleName = getLambdaBundleName(apiName, name);
+            const jsPath = join(outputDir, `${bundleName}.js`);
+            const result = await packageLambda(bundleName, jsPath, outputDir);
+            if (!result.success) {
+                console.log(`  ${pc.red("✗")} Failed to package ${name}: ${result.error}`);
+                process.exit(1);
+            }
+            // Get zip size (store by original name for display)
+            const zipPath = join(outputDir, `${bundleName}.zip`);
+            const stat = await Bun.file(zipPath).stat();
+            if (stat) {
+                packageSizes.set(name, stat.size);
+            }
+        }
+        // Generate manifest
+        console.log(`  ${pc.green("✓")} Generating manifest...`);
+        try {
+            const manifest = await generateManifest(lambdaFiles, outputDir, config.openapi.enabled, apiName);
+            // Write JSON manifest
+            const manifestPath = join(outputDir, "manifest.json");
+            await writeManifest(manifest, manifestPath);
+            // Write Terraform variables
+            await writeTerraformVars(manifest, config);
+            // Duration
+            const duration = Date.now() - startTime;
+            // Route table header
+            console.log();
+            console.log(`  ${pc.bold("Routes")}`);
+            console.log();
+            // Group routes by lambda (use original name for display)
+            const routesByLambda = new Map();
+            for (const route of manifest.routes) {
+                // Extract display name (original name) from bundle name
+                const displayName = route.lambda.startsWith(`${apiName}-`)
+                    ? route.lambda.slice(apiName.length + 1)
+                    : route.lambda;
+                const existing = routesByLambda.get(displayName) || [];
+                existing.push(route);
+                routesByLambda.set(displayName, existing);
+            }
+            // Method colors
+            const methodColor = (method) => {
+                switch (method) {
+                    case "GET":
+                        return pc.green;
+                    case "POST":
+                        return pc.blue;
+                    case "PUT":
+                        return pc.yellow;
+                    case "DELETE":
+                        return pc.red;
+                    case "PATCH":
+                        return pc.magenta;
+                    default:
+                        return pc.white;
+                }
+            };
+            // Find longest path for alignment
+            const maxPathLen = Math.max(...manifest.routes.map((r) => r.path.length));
+            for (const [displayName, routes] of routesByLambda) {
+                const size = packageSizes.get(displayName);
+                const sizeStr = size ? pc.dim(` (${formatSize(size)})`) : "";
+                console.log(`  ${pc.dim("λ")} ${pc.bold(displayName)}${sizeStr}`);
+                for (const route of routes) {
+                    const method = methodColor(route.method)(route.method.padEnd(6));
+                    const path = route.path.padEnd(maxPathLen + 2);
+                    const params = route.pathParameters.length > 0
+                        ? pc.dim(` [${route.pathParameters.join(", ")}]`)
+                        : "";
+                    console.log(`    ${method} ${path}${params}`);
+                }
+                console.log();
+            }
+            // Summary footer
+            console.log(pc.dim("  " + "─".repeat(40)));
+            console.log();
+            console.log(`  ${pc.green("✓")} Compiled ${pc.bold(String(manifest.lambdas.length))} lambdas (${manifest.routes.length} routes) in ${pc.bold(formatDuration(duration))}`);
+            console.log();
+        }
+        catch (error) {
+            console.log(`  ${pc.red("✗")} ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(1);
+        }
+    },
+});

package/dist/cli/commands/dev.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Dev command - Watch mode for development
+ */
+export declare const devCommand: import("citty").CommandDef<{
+    "no-package": {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+}>;

package/dist/cli/commands/dev.js

@@ -0,0 +1,120 @@
+/**
+ * Dev command - Watch mode for development
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import { watch, readdirSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { loadConfig } from "../../core/config";
+import { bundleLambda } from "../../core/bundler";
+import { packageLambda } from "../../core/packager";
+import { createWrapperEntry } from "../../core/handler-wrapper";
+import { getLambdaBundleName } from "../../core/naming";
+export const devCommand = defineCommand({
+    meta: {
+        name: "dev",
+        description: "Watch mode - rebuild lambdas on file changes",
+    },
+    args: {
+        "no-package": {
+            type: "boolean",
+            description: "Skip creating zip files (faster rebuilds)",
+            default: false,
+        },
+    },
+    async run({ args }) {
+        consola.start("Loading configuration...");
+        let config;
+        try {
+            config = await loadConfig();
+        }
+        catch (error) {
+            consola.error(error instanceof Error ? error.message : error);
+            process.exit(1);
+        }
+        const apiName = config.apiName;
+        const lambdasDir = join(process.cwd(), config.lambdasDir);
+        const outputDir = join(process.cwd(), config.outputDir);
+        const tempDir = join(outputDir, "__temp__");
+        // Ensure directories exist
+        if (!existsSync(lambdasDir)) {
+            consola.error(`Lambdas directory not found: ${lambdasDir}`);
+            process.exit(1);
+        }
+        mkdirSync(outputDir, { recursive: true });
+        mkdirSync(tempDir, { recursive: true });
+        // Get initial lambda files
+        const lambdaFiles = readdirSync(lambdasDir).filter((f) => f.endsWith(".ts") && !f.startsWith("__"));
+        if (lambdaFiles.length === 0) {
+            consola.warn("No lambda files found in", config.lambdasDir);
+        }
+        // Build function for a single lambda
+        async function buildSingleLambda(filename) {
+            const name = filename.replace(/\.ts$/, "");
+            const bundleName = getLambdaBundleName(apiName, name);
+            const inputPath = join(lambdasDir, filename);
+            // Create wrapper entry
+            const wrapperPath = join(tempDir, `${name}-wrapper.ts`);
+            const wrapperContent = createWrapperEntry(inputPath);
+            await Bun.write(wrapperPath, wrapperContent);
+            // Bundle with prefixed name
+            const buildResult = await bundleLambda(bundleName, wrapperPath, outputDir, config);
+            if (!buildResult.success) {
+                consola.error(`Failed to build ${name}: ${buildResult.error}`);
+                return false;
+            }
+            consola.success(`Built ${bundleName}.js`);
+            // Package if not disabled
+            if (!args["no-package"]) {
+                const jsPath = join(outputDir, `${bundleName}.js`);
+                const packageResult = await packageLambda(bundleName, jsPath, outputDir);
+                if (!packageResult.success) {
+                    consola.error(`Failed to package ${name}: ${packageResult.error}`);
+                    return false;
+                }
+                consola.success(`Packaged ${bundleName}.zip`);
+            }
+            return true;
+        }
+        // Initial build of all lambdas
+        consola.start("Initial build...");
+        for (const file of lambdaFiles) {
+            await buildSingleLambda(file);
+        }
+        consola.info("Initial build complete");
+        console.log("");
+        consola.box("Watch mode active\n\n" +
+            `Watching: ${config.lambdasDir}/\n` +
+            `Output:   ${config.outputDir}/\n\n` +
+            "Press Ctrl+C to stop");
+        // Set up file watcher
+        const watcher = watch(lambdasDir, { recursive: false }, async (event, filename) => {
+            if (!filename || !filename.endsWith(".ts") || filename.startsWith("__")) {
+                return;
+            }
+            console.log("");
+            consola.info(`Change detected: ${filename}`);
+            const success = await buildSingleLambda(filename);
+            if (success) {
+                consola.ready("Rebuild complete");
+            }
+        });
+        // Handle graceful shutdown
+        process.on("SIGINT", () => {
+            console.log("");
+            consola.info("Stopping watcher...");
+            watcher.close();
+            // Clean up temp directory
+            const { rmSync } = require("fs");
+            try {
+                rmSync(tempDir, { recursive: true, force: true });
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+            process.exit(0);
+        });
+        // Keep process alive
+        await new Promise(() => { });
+    },
+});

package/dist/cli/commands/generate-iac.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Generate IAC command - Regenerate Terraform files without rebuilding
+ */
+export declare const generateIacCommand: import("citty").CommandDef<{}>;

package/dist/cli/commands/generate-iac.js

@@ -0,0 +1,83 @@
+/**
+ * Generate IAC command - Regenerate Terraform files without rebuilding
+ */
+import { defineCommand } from "citty";
+import consola from "consola";
+import { readdirSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { loadConfig } from "../../core/config";
+import { generateManifest, writeManifest } from "../../core/manifest";
+import { writeTerraformVars } from "../../core/terraform";
+import { getOriginalLambdaName } from "../../core/naming";
+export const generateIacCommand = defineCommand({
+    meta: {
+        name: "generate-iac",
+        description: "Regenerate Terraform files from existing build artifacts",
+    },
+    args: {},
+    async run() {
+        consola.start("Loading configuration...");
+        let config;
+        try {
+            config = await loadConfig();
+        }
+        catch (error) {
+            consola.error(error instanceof Error ? error.message : error);
+            process.exit(1);
+        }
+        const apiName = config.apiName;
+        const outputDir = join(process.cwd(), config.outputDir);
+        const terraformDir = join(process.cwd(), config.terraform.outputDir);
+        // Check that build output exists
+        if (!existsSync(outputDir)) {
+            consola.error(`Build output directory not found: ${outputDir}\nRun 'elysian build' first.`);
+            process.exit(1);
+        }
+        // Ensure terraform directory exists
+        mkdirSync(terraformDir, { recursive: true });
+        // Get built lambda files (they have the apiName prefix)
+        const jsFiles = readdirSync(outputDir).filter((f) => f.endsWith(".js") && !f.startsWith("__temp__"));
+        if (jsFiles.length === 0) {
+            consola.error(`No built lambda files found in ${outputDir}\nRun 'elysian build' first.`);
+            process.exit(1);
+        }
+        // Convert bundle names back to .ts names for manifest generation
+        // The manifest generator will re-add the prefix
+        const lambdaFiles = jsFiles.map((f) => {
+            const bundleName = f.replace(/\.js$/, "");
+            const originalName = getOriginalLambdaName(apiName, bundleName);
+            return `${originalName}.ts`;
+        });
+        consola.info(`Found ${lambdaFiles.length} built lambda(s)`);
+        // Generate manifest
+        consola.start("Generating route manifest...");
+        try {
+            const manifest = await generateManifest(lambdaFiles, outputDir, config.openapi.enabled, apiName);
+            // Write JSON manifest
+            const manifestPath = join(outputDir, "manifest.json");
+            await writeManifest(manifest, manifestPath);
+            consola.success("Generated manifest.json");
+            // Write Terraform variables
+            const tfvarsPath = await writeTerraformVars(manifest, config);
+            consola.success(`Generated ${config.terraform.tfvarsFilename}`);
+            // Print summary
+            console.log("");
+            consola.box(`Infrastructure files generated\n\n` +
+                `Lambdas: ${manifest.lambdas.length}\n` +
+                `Routes:  ${manifest.routes.length}\n\n` +
+                `Output: ${config.terraform.outputDir}/${config.terraform.tfvarsFilename}`);
+            // Print route summary
+            console.log("\nRoute Summary:");
+            for (const route of manifest.routes) {
+                const params = route.pathParameters.length > 0
+                    ? ` [${route.pathParameters.join(", ")}]`
+                    : "";
+                console.log(`  ${route.method.padEnd(6)} ${route.path.padEnd(30)} → ${route.lambda}${params}`);
+            }
+        }
+        catch (error) {
+            consola.error(error instanceof Error ? error.message : error);
+            process.exit(1);
+        }
+    },
+});

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Init command - Initialize a new elysian project
+ */
+export declare const initCommand: import("citty").CommandDef<{
+    name: {
+        type: "string";
+        description: string;
+        default: string;
+    };
+    force: {
+        type: "boolean";
+        description: string;
+        default: false;
+    };
+}>;