@rexeus/typeweaver-aws-cdk 0.0.1

package/README.md

@@ -0,0 +1,264 @@
+# @rexeus/typeweaver-aws-cdk
+
+AWS CDK constructs and deployment utilities for TypeWeaver APIs.
+
+## Overview
+
+This plugin generates AWS CDK constructs and HTTP API Gateway routers from your TypeWeaver API
+definitions, making it easy to deploy type-safe APIs to AWS.
+
+## Installation
+
+```bash
+npm install @rexeus/typeweaver-aws-cdk
+```
+
+**Peer Dependencies:**
+
+```bash
+npm install @rexeus/typeweaver-core @rexeus/typeweaver-gen
+```
+
+## Usage
+
+### CLI
+
+```bash
+npx typeweaver generate --input ./api/definitions --output ./api/generated --plugins aws-cdk
+```
+
+### Configuration File
+
+```javascript
+// typeweaver.config.js
+export default {
+  input: "./api/definitions",
+  output: "./api/generated",
+  plugins: ["aws-cdk"],
+};
+```
+
+## Generated Output
+
+This plugin generates HTTP API Gateway routers for each entity in your API definitions.
+
+### Example Generated Router
+
+For an API definition with a `users` entity, the plugin generates:
+
+```typescript
+// UsersHttpApiRouter.ts
+import { HttpMethod } from "@rexeus/typeweaver-core";
+
+export const UsersHttpApiRouter = {
+  "/users": [HttpMethod.POST],
+  "/users/{userId}": [HttpMethod.GET, HttpMethod.PUT, HttpMethod.DELETE],
+};
+```
+
+### Router Structure
+
+The generated routers provide:
+
+- **Route Definitions** - Express-style paths converted to API Gateway format
+- **HTTP Methods** - Supported methods for each route
+- **Parameter Mapping** - Path parameters (`:param` → `{param}`)
+
+### Path Conversion
+
+The plugin automatically converts Express-style paths to API Gateway format:
+
+- `/users/:userId` → `/users/{userId}`
+- `/users/:userId/posts/:postId` → `/users/{userId}/posts/{postId}`
+
+## AWS CDK Integration
+
+Use the generated routers in your CDK stacks:
+
+```typescript
+import { HttpApi, HttpMethod } from "@aws-cdk/aws-apigatewayv2-alpha";
+import { UsersHttpApiRouter, PostsHttpApiRouter } from "./api/generated";
+
+export class ApiStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const api = new HttpApi(this, "TypeWeaverApi");
+
+    // Add routes from generated routers
+    Object.entries(UsersHttpApiRouter).forEach(([path, methods]) => {
+      methods.forEach(method => {
+        api.addRoutes({
+          path,
+          methods: [method],
+          integration: new HttpLambdaIntegration("UsersIntegration", usersHandler),
+        });
+      });
+    });
+
+    Object.entries(PostsHttpApiRouter).forEach(([path, methods]) => {
+      methods.forEach(method => {
+        api.addRoutes({
+          path,
+          methods: [method],
+          integration: new HttpLambdaIntegration("PostsIntegration", postsHandler),
+        });
+      });
+    });
+  }
+}
+```
+
+## Complete AWS Deployment Example
+
+### 1. Define Your API
+
+```typescript
+// api/definitions/users/GetUserDefinition.ts
+import { HttpOperationDefinition, HttpMethod, HttpStatusCode } from "@rexeus/typeweaver-core";
+import { z } from "zod/v4";
+
+export default new HttpOperationDefinition({
+  operationId: "GetUser",
+  method: HttpMethod.GET,
+  path: "/users/:userId",
+  request: {
+    param: z.object({
+      userId: z.string(),
+    }),
+  },
+  responses: [
+    {
+      statusCode: HttpStatusCode.OK,
+      body: z.object({
+        id: z.string(),
+        name: z.string(),
+        email: z.email(),
+      }),
+    },
+  ],
+});
+```
+
+### 2. Generate Code
+
+```bash
+npx typeweaver generate --input ./api/definitions --output ./api/generated --plugins aws-cdk,types,clients
+```
+
+### 3. Create CDK Stack
+
+```typescript
+// lib/api-stack.ts
+import { Stack, StackProps } from "aws-cdk-lib";
+import { Construct } from "constructs";
+import { HttpApi } from "@aws-cdk/aws-apigatewayv2-alpha";
+import { HttpLambdaIntegration } from "@aws-cdk/aws-apigatewayv2-integrations-alpha";
+import { UsersHttpApiRouter } from "../api/generated/users/UsersHttpApiRouter";
+
+export class ApiStack extends Stack {
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const api = new HttpApi(this, "TypeWeaverApi");
+
+    // Create Lambda handler (your implementation)
+    const usersHandler = new Function(this, "UsersHandler", {
+      // Lambda configuration
+    });
+
+    // Add routes using generated router
+    Object.entries(UsersHttpApiRouter).forEach(([path, methods]) => {
+      methods.forEach(method => {
+        api.addRoutes({
+          path,
+          methods: [method],
+          integration: new HttpLambdaIntegration("UsersIntegration", usersHandler),
+        });
+      });
+    });
+  }
+}
+```
+
+### 4. Deploy
+
+```bash
+cdk deploy
+```
+
+## Features
+
+### Route Organization
+
+- **Entity-based routing** - Each entity gets its own router file
+- **Method grouping** - Routes grouped by HTTP method support
+- **Parameter extraction** - Path parameters automatically identified
+
+### Type Safety
+
+- **Generated types** - Work seamlessly with other TypeWeaver plugins
+- **CDK integration** - Type-safe AWS CDK constructs
+- **Validation** - Runtime validation via TypeWeaver Core
+
+### Development Workflow
+
+- **Hot reload** - Regenerate routes when API definitions change
+- **Version control** - Generated files can be committed for review
+- **Testing** - Generated routes can be unit tested
+
+## Plugin Architecture
+
+This plugin extends the TypeWeaver plugin system:
+
+```typescript
+import { BasePlugin, type GeneratorContext } from "@rexeus/typeweaver-gen";
+
+export default class AwsCdkPlugin extends BasePlugin {
+  public name = "aws-cdk";
+
+  public override generate(context: GeneratorContext): void {
+    // Generates HTTP API routers for each entity
+  }
+}
+```
+
+## Best Practices
+
+### CDK Integration
+
+- Use the generated routers as single source of truth for API routes
+- Combine with other TypeWeaver plugins for complete type safety
+- Version generated files in source control
+
+### Deployment
+
+- Generate code before CDK synthesis
+- Use CDK context for environment-specific configuration
+- Implement proper error handling in Lambda functions
+
+### Monitoring
+
+- Add CloudWatch metrics for generated routes
+- Implement distributed tracing
+- Monitor API Gateway throttling and errors
+
+## Troubleshooting
+
+### Common Issues
+
+**Route conflicts**: Ensure API definitions don't have conflicting paths **Method mismatches**:
+Verify HTTP methods in definitions match usage **Parameter mapping**: Check path parameter names are
+consistent
+
+### Debug Mode
+
+Enable verbose logging during generation:
+
+```bash
+DEBUG=typeweaver:* npx typeweaver generate --plugins aws-cdk
+```
+
+## License
+
+ISC © Dennis Wentzien 2025

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { BasePlugin, GeneratorContext } from '@rexeus/typeweaver-gen';
+
+declare class AwsCdkPlugin extends BasePlugin {
+    name: string;
+    generate(context: GeneratorContext): Promise<void> | void;
+}
+
+export { AwsCdkPlugin as default };

package/dist/index.js

@@ -0,0 +1,238 @@
+import { BasePlugin } from '@rexeus/typeweaver-gen';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+function getDefaultExportFromCjs (x) {
+	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
+}
+
+var Case$2 = {exports: {}};
+
+var Case$1 = Case$2.exports;
+
+var hasRequiredCase;
+
+function requireCase () {
+	if (hasRequiredCase) return Case$2.exports;
+	hasRequiredCase = 1;
+	(function (module) {
+		/*! Case - v1.6.2 - 2020-03-24
+		* Copyright (c) 2020 Nathan Bubna; Licensed MIT, GPL */
+		(function() {
+		  var unicodes = function(s, prefix) {
+		    prefix = prefix || "";
+		    return s.replace(/(^|-)/g, "$1\\u" + prefix).replace(/,/g, "\\u" + prefix);
+		  }, basicSymbols = unicodes("20-26,28-2F,3A-40,5B-60,7B-7E,A0-BF,D7,F7", "00"), baseLowerCase = "a-z" + unicodes("DF-F6,F8-FF", "00"), baseUpperCase = "A-Z" + unicodes("C0-D6,D8-DE", "00"), improperInTitle = "A|An|And|As|At|But|By|En|For|If|In|Of|On|Or|The|To|Vs?\\.?|Via", regexps = function(symbols, lowers, uppers, impropers) {
+		    symbols = symbols || basicSymbols;
+		    lowers = lowers || baseLowerCase;
+		    uppers = uppers || baseUpperCase;
+		    impropers = impropers || improperInTitle;
+		    return {
+		      capitalize: new RegExp("(^|[" + symbols + "])([" + lowers + "])", "g"),
+		      pascal: new RegExp("(^|[" + symbols + "])+([" + lowers + uppers + "])", "g"),
+		      fill: new RegExp("[" + symbols + "]+(.|$)", "g"),
+		      sentence: new RegExp('(^\\s*|[\\?\\!\\.]+"?\\s+"?|,\\s+")([' + lowers + "])", "g"),
+		      improper: new RegExp("\\b(" + impropers + ")\\b", "g"),
+		      relax: new RegExp("([^" + uppers + "])([" + uppers + "]*)([" + uppers + "])(?=[^" + uppers + "]|$)", "g"),
+		      upper: new RegExp("^[^" + lowers + "]+$"),
+		      hole: /[^\s]\s[^\s]/,
+		      apostrophe: /'/g,
+		      room: new RegExp("[" + symbols + "]")
+		    };
+		  }, re = regexps(), _ = {
+		    re,
+		    unicodes,
+		    regexps,
+		    types: [],
+		    up: String.prototype.toUpperCase,
+		    low: String.prototype.toLowerCase,
+		    cap: function(s) {
+		      return _.up.call(s.charAt(0)) + s.slice(1);
+		    },
+		    decap: function(s) {
+		      return _.low.call(s.charAt(0)) + s.slice(1);
+		    },
+		    deapostrophe: function(s) {
+		      return s.replace(re.apostrophe, "");
+		    },
+		    fill: function(s, fill, deapostrophe) {
+		      if (fill != null) {
+		        s = s.replace(re.fill, function(m, next) {
+		          return next ? fill + next : "";
+		        });
+		      }
+		      if (deapostrophe) {
+		        s = _.deapostrophe(s);
+		      }
+		      return s;
+		    },
+		    prep: function(s, fill, pascal, upper) {
+		      s = s == null ? "" : s + "";
+		      if (!upper && re.upper.test(s)) {
+		        s = _.low.call(s);
+		      }
+		      if (!fill && !re.hole.test(s)) {
+		        var holey = _.fill(s, " ");
+		        if (re.hole.test(holey)) {
+		          s = holey;
+		        }
+		      }
+		      if (!pascal && !re.room.test(s)) {
+		        s = s.replace(re.relax, _.relax);
+		      }
+		      return s;
+		    },
+		    relax: function(m, before, acronym, caps) {
+		      return before + " " + (acronym ? acronym + " " : "") + caps;
+		    }
+		  }, Case = {
+		    _,
+		    of: function(s) {
+		      for (var i = 0, m = _.types.length; i < m; i++) {
+		        if (Case[_.types[i]].apply(Case, arguments) === s) {
+		          return _.types[i];
+		        }
+		      }
+		    },
+		    flip: function(s) {
+		      return s.replace(/\w/g, function(l) {
+		        return (l == _.up.call(l) ? _.low : _.up).call(l);
+		      });
+		    },
+		    random: function(s) {
+		      return s.replace(/\w/g, function(l) {
+		        return (Math.round(Math.random()) ? _.up : _.low).call(l);
+		      });
+		    },
+		    type: function(type2, fn) {
+		      Case[type2] = fn;
+		      _.types.push(type2);
+		    }
+		  }, types = {
+		    lower: function(s, fill, deapostrophe) {
+		      return _.fill(_.low.call(_.prep(s, fill)), fill, deapostrophe);
+		    },
+		    snake: function(s) {
+		      return Case.lower(s, "_", true);
+		    },
+		    constant: function(s) {
+		      return Case.upper(s, "_", true);
+		    },
+		    camel: function(s) {
+		      return _.decap(Case.pascal(s));
+		    },
+		    kebab: function(s) {
+		      return Case.lower(s, "-", true);
+		    },
+		    upper: function(s, fill, deapostrophe) {
+		      return _.fill(_.up.call(_.prep(s, fill, false, true)), fill, deapostrophe);
+		    },
+		    capital: function(s, fill, deapostrophe) {
+		      return _.fill(_.prep(s).replace(re.capitalize, function(m, border, letter) {
+		        return border + _.up.call(letter);
+		      }), fill, deapostrophe);
+		    },
+		    header: function(s) {
+		      return Case.capital(s, "-", true);
+		    },
+		    pascal: function(s) {
+		      return _.fill(_.prep(s, false, true).replace(re.pascal, function(m, border, letter) {
+		        return _.up.call(letter);
+		      }), "", true);
+		    },
+		    title: function(s) {
+		      return Case.capital(s).replace(re.improper, function(small, p, i, s2) {
+		        return i > 0 && i < s2.lastIndexOf(" ") ? _.low.call(small) : small;
+		      });
+		    },
+		    sentence: function(s, names, abbreviations) {
+		      s = Case.lower(s).replace(re.sentence, function(m, prelude, letter) {
+		        return prelude + _.up.call(letter);
+		      });
+		      if (names) {
+		        names.forEach(function(name) {
+		          s = s.replace(new RegExp("\\b" + Case.lower(name) + "\\b", "g"), _.cap);
+		        });
+		      }
+		      if (abbreviations) {
+		        abbreviations.forEach(function(abbr) {
+		          s = s.replace(new RegExp("(\\b" + Case.lower(abbr) + "\\. +)(\\w)"), function(m, abbrAndSpace, letter) {
+		            return abbrAndSpace + _.low.call(letter);
+		          });
+		        });
+		      }
+		      return s;
+		    }
+		  };
+		  types.squish = types.pascal;
+		  Case.default = Case;
+		  for (var type in types) {
+		    Case.type(type, types[type]);
+		  }
+		  var define = typeof define === "function" ? define : function() {
+		  };
+		  define(module.exports ? module.exports = Case : this.Case = Case);
+		}).call(Case$1); 
+	} (Case$2));
+	return Case$2.exports;
+}
+
+var CaseExports = requireCase();
+var Case = /*@__PURE__*/getDefaultExportFromCjs(CaseExports);
+
+const __dirname$1 = path.dirname(fileURLToPath(import.meta.url));
+class HttpApiRouterGenerator {
+  static generate(context) {
+    const templateFile = path.join(__dirname$1, "templates", "HttpApiRouter.ejs");
+    for (const [entityName, operationResources] of Object.entries(
+      context.resources.entityResources
+    )) {
+      this.writeHttpApiRoutes(entityName, templateFile, operationResources, context);
+    }
+  }
+  static writeHttpApiRoutes(entityName, templateFile, operationResources, context) {
+    const routes = {};
+    const pascalCaseEntityName = Case.pascal(entityName);
+    const outputDir = operationResources[0].outputDir;
+    const outputFile = path.join(
+      outputDir,
+      `${pascalCaseEntityName}HttpApiRouter.ts`
+    );
+    for (const operation of operationResources) {
+      const path2 = this.createRoutePath(operation.definition.path);
+      if (!routes[path2]) {
+        routes[path2] = [];
+      }
+      routes[path2].push(operation.definition.method);
+    }
+    const content = context.renderTemplate(templateFile, {
+      entityName,
+      pascalCaseEntityName,
+      routes,
+      coreDir: context.coreDir
+    });
+    const relativePath = path.relative(context.outputDir, outputFile);
+    context.writeFile(relativePath, content);
+  }
+  static createRoutePath(path2) {
+    const parts = path2.split("/").map((part) => {
+      if (part.startsWith(":")) {
+        return `{${part.slice(1)}}`;
+      }
+      return part;
+    });
+    return parts.join("/");
+  }
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+class AwsCdkPlugin extends BasePlugin {
+  name = "aws-cdk";
+  generate(context) {
+    const libDir = path.join(__dirname, "lib");
+    this.copyLibFiles(context, libDir, "aws-cdk");
+    HttpApiRouterGenerator.generate(context);
+  }
+}
+
+export { AwsCdkPlugin as default };

package/dist/lib/AwsHttpApiGatewayRouter.ts

@@ -0,0 +1,10 @@
+import { HttpMethod } from "@rexeus/typeweaver-core";
+
+export type AwsHttpApiGatewayRoute = {
+  path: string;
+  methods: HttpMethod[];
+};
+
+export abstract class AwsHttpApiGatewayRouter {
+  public abstract getRoutes(): AwsHttpApiGatewayRoute[];
+}

package/dist/lib/index.ts

@@ -0,0 +1 @@
+export * from "./AwsHttpApiGatewayRouter";

package/dist/templates/HttpApiRouter.ejs

@@ -0,0 +1,24 @@
+import { HttpMethod } from "<%= coreDir %>";
+import {
+  type AwsHttpApiGatewayRoute,
+  AwsHttpApiGatewayRouter,
+} from "../lib/aws-cdk";
+
+export class <%= pascalCaseEntityName %>HttpApiRouter extends AwsHttpApiGatewayRouter {
+  private routes: AwsHttpApiGatewayRoute[] = [
+<% for(const [path, methods] of Object.entries(routes)) { %>
+    {
+      path: "<%= path %>",
+      methods: [<% for(const method of methods) { %>HttpMethod.<%= method %>,<% } %>],
+    },
+<% } %>
+  ];
+
+  public constructor() {
+    super();
+  }
+
+  public getRoutes(): AwsHttpApiGatewayRoute[] {
+    return this.routes;
+  }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@rexeus/typeweaver-aws-cdk",
+  "version": "0.0.1",
+  "description": "AWS CDK constructs and deployment utilities for TypeWeaver APIs",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "package.json",
+    "README.md"
+  ],
+  "keywords": [
+    "api",
+    "spec",
+    "definition",
+    "typescript",
+    "zod",
+    "generator",
+    "typeweaver"
+  ],
+  "author": "Dennis Wentzien <dw@rexeus.com>",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rexeus/typeweaver.git",
+    "directory": "packages/aws-cdk"
+  },
+  "bugs": {
+    "url": "https://github.com/rexeus/typeweaver/issues"
+  },
+  "homepage": "https://github.com/rexeus/typeweaver#readme",
+  "peerDependencies": {
+    "@rexeus/typeweaver-core": "*",
+    "@rexeus/typeweaver-gen": "*"
+  },
+  "devDependencies": {
+    "@rexeus/typeweaver-core": "0.0.1",
+    "@rexeus/typeweaver-gen": "0.0.1"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "build": "pkgroll --clean-dist && cp -r ./src/templates ./dist/templates && cp -r ./src/lib ./dist/lib",
+    "preversion": "npm run build"
+  }
+}