add support for transforms, add TS type generation from CF JSON schema

Author: matuscongrady

.knip.json

@@ -1,5 +1,5 @@
 import { PrismaPg } from '@prisma/adapter-pg';
-import { PrismaClient } from './generated/client';
+import { PrismaClient } from './generated/prisma/client';
 
 const adapter = new PrismaPg({
   ssl: { rejectUnauthorized: false },

@generated/cloudform/AwsLambdaFunction.ts

@@ -11,7 +11,15 @@ export default defineConfig(() => {
         enabled: true
       }
     },
-    overrides: {}
+    transforms: {
+      lambda: (props) => {
+        return {
+          ...props,
+          MemorySize: (props.MemorySize ?? 128) * 2,
+          Description: 'This is a test lambda',
+        }
+      }
+    }
   });
 
   return {

_test-stacks/monorepo-ts/packages/prisma/prisma.ts

@@ -15,7 +15,7 @@ import {
   generateStacktapeConfigType
 } from './code-generation/generate-augmented-props';
 import { generatePropertiesInterfaces } from './code-generation/generate-cf-properties';
-import { generateOverrideTypes } from './code-generation/generate-overrides';
+import { generateOverrideTypes, generateTransformsTypes } from './code-generation/generate-overrides';
 import { generateResourceClassDeclarations } from './code-generation/generate-resource-classes';
 import {
   generateTypePropertiesClassDeclarations,
@@ -281,6 +281,7 @@ export async function generateTypeDeclarations(): Promise<void> {
   logInfo('Extracting Properties interfaces from CloudFormation files...');
   const propertiesInterfaces = generatePropertiesInterfaces(CHILD_RESOURCES);
   const overridesTypes = generateOverrideTypes(CHILD_RESOURCES);
+  const transformsTypes = generateTransformsTypes(CHILD_RESOURCES);
 
   // Compile source files
   logInfo('Compiling TypeScript source files...');
@@ -354,6 +355,12 @@ ${augmentedPropsTypes}
 
 ${overridesTypes}
 
+// ==========================================
+// CLOUDFORMATION TRANSFORMS
+// ==========================================
+
+${transformsTypes}
+
 // ==========================================
 // RESOURCE CLASS DECLARATIONS
 // ==========================================

_test-stacks/simple-lambda/stacktape.ts

@@ -67,6 +67,16 @@ Allows fine-grained control over the generated infrastructure.`,
   tags: []
 };
 
+/**
+ * Default JSDoc for transforms property
+ */
+const DEFAULT_TRANSFORMS_JSDOC = {
+  description: `Transform functions for underlying CloudFormation resources.
+Each function receives the current properties and returns modified properties.
+Unlike overrides, transforms allow dynamic modification based on existing values.`,
+  tags: []
+};
+
 /**
  * Generates a property declaration with JSDoc
  */
@@ -123,6 +133,18 @@ function getOverridesPropertyInfo(overridesTypeName: string): PropertyInfo {
   };
 }
 
+/**
+ * Gets transforms property info with JSDoc
+ */
+function getTransformsPropertyInfo(transformsTypeName: string): PropertyInfo {
+  return {
+    name: 'transforms',
+    type: transformsTypeName,
+    optional: true,
+    jsdoc: DEFAULT_TRANSFORMS_JSDOC
+  };
+}
+
 /**
  * Generates a ConnectTo type alias for a resource
  */
@@ -143,7 +165,7 @@ function generateAugmentedPropsType(
   originalPropsType: string,
   resourceType: string,
   connectToType: string,
-  includeOverrides: boolean
+  includeOverridesAndTransforms: boolean
 ): string {
   const lines: string[] = [];
 
@@ -158,10 +180,13 @@ function generateAugmentedPropsType(
   const environmentProperty = getEnvironmentPropertyInfo(originalPropsType);
   lines.push(generatePropertyWithJSDoc(environmentProperty));
 
-  // Add overrides if needed
-  if (includeOverrides) {
+  // Add overrides and transforms if needed
+  if (includeOverridesAndTransforms) {
     const overridesProperty = getOverridesPropertyInfo(`${resourceType}Overrides`);
     lines.push(generatePropertyWithJSDoc(overridesProperty));
+
+    const transformsProperty = getTransformsPropertyInfo(`${resourceType}Transforms`);
+    lines.push(generatePropertyWithJSDoc(transformsProperty));
   }
 
   lines.push('};');
@@ -171,15 +196,19 @@ function generateAugmentedPropsType(
 
 /**
  * Generates a WithOverrides type for resources without augmented props
+ * Also includes transforms
  */
-function generateWithOverridesType(propsType: string, className: string): string {
+function generateWithOverridesAndTransformsType(propsType: string, className: string): string {
   const lines: string[] = [];
 
   lines.push(`export type ${propsType}WithOverrides = ${propsType} & {`);
 
   const overridesProperty = getOverridesPropertyInfo(`${className}Overrides`);
   lines.push(generatePropertyWithJSDoc(overridesProperty));
 
+  const transformsProperty = getTransformsPropertyInfo(`${className}Transforms`);
+  lines.push(generatePropertyWithJSDoc(transformsProperty));
+
   lines.push('};');
 
   return lines.join('\n');
@@ -219,7 +248,7 @@ export function generateAugmentedPropsTypes(): string {
   }
 
   result.push('');
-  result.push('// Augmented props types with connectTo, environment, and overrides');
+  result.push('// Augmented props types with connectTo, environment, overrides, and transforms');
   result.push('');
 
   // Generate augmented props for resources
@@ -229,7 +258,7 @@ export function generateAugmentedPropsTypes(): string {
       `Sdk${resource.propsType}`,
       resource.className,
       `${resource.className}ConnectTo`,
-      true // includeOverrides
+      true // includeOverridesAndTransforms
     );
     result.push(augmentedType);
     result.push('');
@@ -242,7 +271,7 @@ export function generateAugmentedPropsTypes(): string {
       `Sdk${scriptPropsType}`,
       'Script',
       'ScriptConnectTo',
-      false // Scripts don't have overrides
+      false // Scripts don't have overrides or transforms
     );
     result.push(augmentedType);
     result.push('');
@@ -257,7 +286,7 @@ export function generateAugmentedPropsTypes(): string {
   const resourcesWithOverrides = getResourcesWithOverrides();
   for (const resource of resourcesWithOverrides) {
     if (!augmentedPropsNames.includes(resource.propsType)) {
-      const withOverridesType = generateWithOverridesType(resource.propsType, resource.className);
+      const withOverridesType = generateWithOverridesAndTransformsType(resource.propsType, resource.className);
       result.push(withOverridesType);
       result.push('');
     }

scripts/build-npm-main-export.ts

@@ -32,6 +32,35 @@ function generateOverrideProperties(childResources: ChildResourceMetadata[]): st
   return properties;
 }
 
+/**
+ * Generates transform property declarations for a resource's child resources
+ * Transforms are functions that receive props and return modified props
+ */
+function generateTransformProperties(childResources: ChildResourceMetadata[]): string[] {
+  const properties: string[] = [];
+
+  for (const childResource of childResources) {
+    // Skip unresolvable resources
+    if (childResource.unresolvable) {
+      continue;
+    }
+
+    const mapping = cfTypeToInterface(childResource.resourceType);
+    if (!mapping) {
+      continue;
+    }
+
+    const propertyName = getPropertyNameFromLogicalName(childResource.logicalName);
+    if (!propertyName) {
+      continue;
+    }
+
+    properties.push(`  ${propertyName}?: (props: Partial<${mapping.interface}>) => Partial<${mapping.interface}>;`);
+  }
+
+  return properties;
+}
+
 /**
  * Generates a single override type declaration
  */
@@ -52,6 +81,26 @@ function generateOverrideType(typeName: string, properties: string[]): string {
   return lines.join('\n');
 }
 
+/**
+ * Generates a single transforms type declaration
+ */
+function generateTransformsType(typeName: string, properties: string[]): string {
+  if (properties.length === 0) {
+    return '';
+  }
+
+  const lines = [
+    `export type ${typeName} = {`,
+    ...properties,
+    '  // Allow any additional transform functions',
+    '  [key: string]: ((props: any) => any) | undefined;',
+    '};',
+    ''
+  ];
+
+  return lines.join('\n');
+}
+
 /**
  * Generate override types for all child resources
  */
@@ -78,3 +127,29 @@ export function generateOverrideTypes(CHILD_RESOURCES: ChildResourcesMap): strin
 
   return results.join('\n');
 }
+
+/**
+ * Generate transforms types for all child resources
+ */
+export function generateTransformsTypes(CHILD_RESOURCES: ChildResourcesMap): string {
+  const results: string[] = [];
+  const resourcesWithOverrides = getResourcesWithOverrides();
+
+  for (const resource of resourcesWithOverrides) {
+    const childResourcesArray = CHILD_RESOURCES[resource.resourceType];
+
+    if (!childResourcesArray || childResourcesArray.length === 0) {
+      continue;
+    }
+
+    const transformsTypeName = `${resource.className}Transforms`;
+    const properties = generateTransformProperties(childResourcesArray);
+    const transformsType = generateTransformsType(transformsTypeName, properties);
+
+    if (transformsType) {
+      results.push(transformsType);
+    }
+  }
+
+  return results.join('\n');
+}

scripts/code-generation/generate-augmented-props.ts

@@ -1,12 +1,49 @@
+import type { JSDocComment } from './types';
 import { TYPE_PROPERTIES } from '../../src/api/npm/ts/resource-metadata';
+import { getTypePropertiesDescription } from './jsdoc-extractor';
+
+/**
+ * Formats a JSDoc comment for a constructor (with indentation)
+ */
+function formatConstructorJSDoc(description: JSDocComment | undefined, className: string): string {
+  const lines: string[] = ['  /**'];
+
+  if (description?.description) {
+    // Split description into lines and add proper indentation
+    const descriptionLines = description.description.split('\n');
+    for (const line of descriptionLines) {
+      lines.push(`   * ${line}`);
+    }
+  } else {
+    lines.push(`   * Create a ${className}`);
+  }
+
+  // Add tags if any
+  if (description?.tags) {
+    for (const tag of description.tags) {
+      if (tag.value) {
+        lines.push(`   * @${tag.tag} ${tag.value}`);
+      } else {
+        lines.push(`   * @${tag.tag}`);
+      }
+    }
+  }
+
+  lines.push('   */');
+  return lines.join('\n');
+}
 
 /**
  * Generate type/properties class declarations
  */
 export function generateTypePropertiesClassDeclarations(): string {
   return TYPE_PROPERTIES.map(({ className, typeValue, propsType }) => {
+    const description = getTypePropertiesDescription(className);
+    const constructorJsDoc = formatConstructorJSDoc(description, className);
+
     return `
 export declare class ${className} extends BaseTypeProperties {
+${constructorJsDoc}
   constructor(properties: ${propsType});
   readonly type: '${typeValue}';
 }`;