@cdktn/provider-generator 0.24.0-pre.5 → 0.24.0-pre.50

package/src/get/generator/emitter/struct-emitter.ts

@@ -0,0 +1,683 @@
+// Copyright (c) HashiCorp, Inc
+// SPDX-License-Identifier: MPL-2.0
+import { CodeMaker } from "codemaker";
+import { ResourceModel, Struct, ConfigStruct } from "../models";
+import { AttributesEmitter } from "./attributes-emitter";
+import { downcaseFirst } from "../../../util";
+import * as path from "path";
+import { STRUCT_SHARDING_THRESHOLD } from "../models/resource-model";
+import { AttributeModel } from "../models/attribute-model";
+import { sanitizedComment } from "../sanitized-comments";
+
+export class StructEmitter {
+  attributesEmitter: AttributesEmitter;
+  private readonly importExtension: string;
+
+  constructor(
+    private readonly code: CodeMaker,
+    importExtension: string,
+  ) {
+    this.attributesEmitter = new AttributesEmitter(this.code);
+    this.importExtension = importExtension;
+  }
+
+  public emit(resource: ResourceModel) {
+    if (resource.structsRequireSharding) {
+      this.emitNamespacedStructs(resource);
+    } else {
+      this.emitStructs(resource);
+    }
+  }
+
+  // Due to https://github.com/hashicorp/terraform-plugin-sdk/commit/2387eb85e32c064b4a62718c9f5c80bf00dc7fb9 all
+  // resources from providers using the old SDK have the id field by default
+  // We have no way to distinguish them through the provider schema, so a word of warning for our users
+  private warnAboutIdField(att: AttributeModel) {
+    if (att.name === "id") {
+      this.code.line(`*`);
+      this.code.line(
+        `* Please be aware that the id field is automatically added to all resources in Terraform providers using a Terraform provider SDK version below 2.`,
+      );
+      this.code.line(
+        `* If you experience problems setting this value it might not be settable. Please take a look at the provider documentation to ensure it should be settable.`,
+      );
+    }
+  }
+
+  public emitInterface(
+    resource: ResourceModel,
+    struct: Struct,
+    name = struct.name,
+  ) {
+    if (resource.isProvider) {
+      this.code.openBlock(`export interface ${name}`);
+    } else {
+      this.code.openBlock(`export interface ${name}${struct.extends}`);
+    }
+
+    for (const att of struct.assignableAttributes) {
+      const comment = sanitizedComment(this.code);
+      if (att.description) {
+        comment.line(att.description);
+        comment.line(``);
+        comment.line(
+          `Docs at Terraform Registry: {@link ${resource.linkToDocs}#${att.terraformName} ${resource.className}#${att.terraformName}}`,
+        );
+        this.warnAboutIdField(att);
+        comment.end();
+      } else {
+        comment.line(
+          `Docs at Terraform Registry: {@link ${resource.linkToDocs}#${att.terraformName} ${resource.className}#${att.terraformName}}`,
+        );
+        this.warnAboutIdField(att);
+        comment.end();
+      }
+
+      this.code.line(`readonly ${att.typeDefinition};`);
+    }
+    this.code.closeBlock();
+
+    if (!(struct instanceof ConfigStruct)) {
+      this.emitToTerraformFunction(struct);
+      this.emitToHclTerraformFunction(struct);
+    }
+  }
+
+  private emitStructs(resource: ResourceModel) {
+    resource.structs.forEach((struct) => {
+      if (struct instanceof ConfigStruct) {
+        this.emitInterface(resource, struct);
+      } else {
+        // We use the interface here for the configuration / inputs of a resource / nested block
+        this.emitInterface(resource, struct);
+        // And we use the class for the attributes / outputs of a resource / nested block
+        if (!struct.isProvider) {
+          this.emitClass(struct);
+        }
+      }
+    });
+  }
+
+  private emitNamespacedStructs(resource: ResourceModel) {
+    // iterate over all structs in batches of 400 to avoid too many exports (> 1200)
+    const structImports: Record<string, string> = {};
+
+    // drop configStruct from resource.structs to avoid double import
+    const structsWithoutConfigStruct = resource.structs.slice(1);
+
+    const structSplits: Struct[][] = [[]];
+    const splitCounts: number[] = [0];
+    structsWithoutConfigStruct.forEach((struct) => {
+      if (
+        splitCounts[splitCounts.length - 1] + struct.exportCount <=
+        STRUCT_SHARDING_THRESHOLD
+      ) {
+        structSplits[structSplits.length - 1].push(struct);
+        splitCounts[splitCounts.length - 1] += struct.exportCount;
+      } else {
+        structSplits.push([struct]);
+        splitCounts.push(struct.exportCount);
+      }
+    });
+
+    // fill the struct imports mapping before code generation so that imports can
+    // point to not yet generated struct files
+    for (let i = 0; i < structSplits.length; i++) {
+      const structFilename = `structs${i * STRUCT_SHARDING_THRESHOLD}.ts`;
+      const structs = structSplits[i];
+
+      // associate current structs batch with the file it will be written to
+      // to find it in subsequent files for importing
+      structs.forEach(
+        (struct) => (structImports[struct.name] = structFilename),
+      );
+    }
+
+    const structPaths = [];
+    for (let i = 0; i < structSplits.length; i++) {
+      const structsToImport: Record<string, string[]> = {};
+      const structs = structSplits[i];
+      const structFilename = `structs${i * STRUCT_SHARDING_THRESHOLD}.ts`;
+      structPaths.push(structFilename);
+
+      // find all structs that need to be imported in this file
+      structs.forEach((struct) => {
+        struct.attributes.forEach((att) => {
+          const structTypeName = att.type.struct?.name;
+          const fileToImport = structImports[structTypeName ?? ""];
+
+          if (fileToImport && fileToImport !== structFilename) {
+            const attTypeStruct = att.type.struct;
+            if (!attTypeStruct)
+              throw new Error(`${structTypeName} is not a struct`);
+
+            structsToImport[fileToImport] ??= [];
+
+            const attReferences = att.getReferencedTypes(
+              struct instanceof ConfigStruct,
+            );
+            if (attReferences) {
+              structsToImport[fileToImport].push(...attReferences);
+            }
+          }
+        });
+      });
+
+      const namespacedFilePath = path.join(
+        resource.structsFolderPath,
+        structFilename,
+      );
+
+      this.code.openFile(namespacedFilePath);
+      // the structs only makes use of cdktn not constructs
+      this.code.line(`import * as cdktn from 'cdktn';`);
+      Object.entries(structsToImport).forEach(([fileToImport, structs]) => {
+        const target = path.basename(fileToImport, ".ts");
+        this.code.line(
+          `import { ${[...new Set(structs)].join(",\n")} } from './${target}${this.importExtension}';`,
+        );
+      });
+
+      structs.forEach((struct) => {
+        if (struct instanceof ConfigStruct) {
+          this.emitInterface(resource, struct);
+        } else {
+          // We use the interface here for the configuration / inputs of a resource / nested block
+          this.emitInterface(resource, struct);
+          // And we use the class for the attributes / outputs of a resource / nested block
+          if (!struct.isProvider) {
+            this.emitClass(struct);
+          }
+        }
+      });
+      this.code.closeFile(namespacedFilePath);
+    }
+
+    // emit the index file that exports all the struct files we've just generated
+    const indexFilePath = path.join(resource.structsFolderPath, "index.ts");
+
+    this.code.openFile(indexFilePath);
+    structPaths.forEach((structPath) => {
+      const target = path.basename(structPath, ".ts");
+      this.code.line(`export * from './${target}${this.importExtension}';`);
+    });
+    this.code.closeFile(indexFilePath);
+  }
+
+  private emitClass(struct: Struct) {
+    this.code.openBlock(
+      `export class ${struct.outputReferenceName} extends cdktn.ComplexObject`,
+    );
+
+    this.code.line("private isEmptyObject = false;");
+    if (!struct.isClass) {
+      this.code.line("private resolvableValue?: cdktn.IResolvable;");
+    }
+    this.code.line();
+
+    const comment = sanitizedComment(this.code);
+    comment.line(`@param terraformResource The parent resource`);
+    comment.line(
+      `@param terraformAttribute The attribute on the parent resource this class is referencing`,
+    );
+    if (struct.isSingleItem) {
+      comment.end();
+      this.code.openBlock(
+        `public constructor(terraformResource: cdktn.IInterpolatingParent, terraformAttribute: string)`,
+      );
+      this.code.line(`super(terraformResource, terraformAttribute, false, 0);`);
+      this.code.closeBlock();
+    } else if (
+      struct.nestingMode === "single" ||
+      struct.nestingMode === "object"
+    ) {
+      comment.end();
+      this.code.openBlock(
+        `public constructor(terraformResource: cdktn.IInterpolatingParent, terraformAttribute: string)`,
+      );
+      this.code.line(`super(terraformResource, terraformAttribute, false);`);
+      this.code.closeBlock();
+    } else if (struct.nestingMode.startsWith("map")) {
+      this.code.line(
+        `* @param complexObjectKey the key of this item in the map`,
+      );
+      comment.end();
+      this.code.openBlock(
+        `public constructor(terraformResource: cdktn.IInterpolatingParent, terraformAttribute: string, complexObjectKey: string)`,
+      );
+      this.code.line(
+        `super(terraformResource, terraformAttribute, false, complexObjectKey);`,
+      );
+      this.code.closeBlock();
+    } else {
+      comment.line(
+        `@param complexObjectIndex the index of this item in the list`,
+      );
+      comment.line(
+        `@param complexObjectIsFromSet whether the list is wrapping a set (will add tolist() to be able to access an item via an index)`,
+      );
+      comment.end();
+      this.code.openBlock(
+        `public constructor(terraformResource: cdktn.IInterpolatingParent, terraformAttribute: string, complexObjectIndex: number, complexObjectIsFromSet: boolean)`,
+      );
+      this.code.line(
+        `super(terraformResource, terraformAttribute, complexObjectIsFromSet, complexObjectIndex);`,
+      );
+      this.code.closeBlock();
+    }
+
+    this.code.line();
+    this.emitInternalValueGetter(struct);
+    this.code.line();
+    this.emitInternalValueSetter(struct);
+
+    for (const att of struct.attributes) {
+      this.attributesEmitter.emit(
+        att,
+        this.attributesEmitter.needsResetEscape(att, struct.attributes),
+        this.attributesEmitter.needsInputEscape(att, struct.attributes),
+      );
+    }
+
+    this.code.closeBlock();
+
+    if (
+      !struct.isSingleItem &&
+      (struct.nestingMode === "list" || struct.nestingMode === "set")
+    ) {
+      this.emitComplexListClass(struct);
+    } else if (struct.nestingMode === "map") {
+      this.emitComplexMapClass(struct);
+    } else if (struct.nestingMode === "maplist") {
+      this.emitComplexMapListClasses(struct);
+    } else if (struct.nestingMode === "mapset") {
+      this.emitComplexMapListClasses(struct);
+    } else if (struct.nestingMode === "listmap") {
+      this.emitComplexListMapClasses(struct, false);
+    } else if (struct.nestingMode === "setmap") {
+      this.emitComplexListMapClasses(struct, true);
+    } else if (
+      struct.nestingMode === "listlist" ||
+      struct.nestingMode === "listset" ||
+      struct.nestingMode === "setlist" ||
+      struct.nestingMode === "setset"
+    ) {
+      this.emitComplexListListClasses(struct);
+    }
+    // other types of nested collections aren't supported
+  }
+
+  private emitComplexListClass(struct: Struct) {
+    this.code.line();
+    this.code.openBlock(
+      `export class ${struct.listName} extends cdktn.ComplexList`,
+    );
+
+    if (struct.assignable) {
+      this.code.line(
+        `public internalValue? : ${struct.name}[] | cdktn.IResolvable`,
+      );
+    }
+
+    this.code.line();
+    const constructorComment = sanitizedComment(this.code);
+    constructorComment.line(`@param terraformResource The parent resource`);
+    constructorComment.line(
+      `@param terraformAttribute The attribute on the parent resource this class is referencing`,
+    );
+    constructorComment.line(
+      `@param wrapsSet whether the list is wrapping a set (will add tolist() to be able to access an item via an index)`,
+    );
+    constructorComment.end();
+    this.code.openBlock(
+      `constructor(terraformResource: cdktn.IInterpolatingParent, terraformAttribute: string, wrapsSet: boolean)`,
+    );
+    this.code.line(`super(terraformResource, terraformAttribute, wrapsSet);`);
+    this.code.closeBlock();
+
+    this.code.line();
+    const getterComment = sanitizedComment(this.code);
+    getterComment.line(`@param index the index of the item to return`);
+    getterComment.end();
+    this.code.openBlock(
+      `public get(index: number): ${struct.outputReferenceName}`,
+    );
+    this.code.line(
+      `return new ${struct.outputReferenceName}(this.terraformResource, this.terraformAttribute, index, this.wrapsSet);`,
+    );
+    this.code.closeBlock();
+
+    this.code.closeBlock();
+  }
+
+  private emitComplexMapClass(struct: Struct) {
+    this.code.line();
+    this.code.openBlock(
+      `export class ${struct.mapName} extends cdktn.ComplexMap`,
+    );
+
+    if (struct.assignable) {
+      this.code.line(
+        `public internalValue? : { [key: string]: ${struct.name} } | cdktn.IResolvable`,
+      );
+    }
+
+    this.code.line();
+    const constructorComment = sanitizedComment(this.code);
+    constructorComment.line(`@param terraformResource The parent resource`);
+    constructorComment.line(
+      `@param terraformAttribute The attribute on the parent resource this class is referencing`,
+    );
+    constructorComment.end();
+    this.code.openBlock(
+      `constructor(terraformResource: cdktn.IInterpolatingParent, terraformAttribute: string)`,
+    );
+    this.code.line(`super(terraformResource, terraformAttribute);`);
+    this.code.closeBlock();
+
+    this.code.line();
+    const getterComment = sanitizedComment(this.code);
+    getterComment.line(`@param key the key of the item to return`);
+    getterComment.end();
+    this.code.openBlock(
+      `public get(key: string): ${struct.outputReferenceName}`,
+    );
+    this.code.line(
+      `return new ${struct.outputReferenceName}(this.terraformResource, this.terraformAttribute, key);`,
+    );
+    this.code.closeBlock();
+
+    this.code.closeBlock();
+  }
+
+  private emitComplexMapListClasses(struct: Struct) {
+    this.emitComplexMapListClass(struct);
+    this.emitComplexMapClass(struct);
+  }
+
+  private emitComplexMapListClass(struct: Struct) {
+    this.code.line();
+    this.code.openBlock(
+      `export class ${struct.mapListName} extends cdktn.MapList`,
+    );
+
+    if (struct.assignable) {
+      this.code.line(
+        `public internalValue? : ${struct.mapName}[] | cdktn.IResolvable`,
+      );
+    }
+
+    this.code.line();
+    const constructorComment = sanitizedComment(this.code);
+    constructorComment.line(`@param terraformResource The parent resource`);
+    constructorComment.line(
+      `@param terraformAttribute The attribute on the parent resource this class is referencing`,
+    );
+    constructorComment.line(
+      `@param wrapsSet whether the list is wrapping a set (will add tolist() to be able to access an item via an index)`,
+    );
+    constructorComment.end();
+    this.code.openBlock(
+      `constructor(terraformResource: cdktn.IInterpolatingParent, terraformAttribute: string, wrapsSet: boolean)`,
+    );
+    this.code.line(`super(terraformResource, terraformAttribute, wrapsSet);`);
+    this.code.closeBlock();
+
+    this.code.line();
+    const getterComment = sanitizedComment(this.code);
+    getterComment.line(`@param index the index of the item to return`);
+    getterComment.end();
+    this.code.openBlock(`public get(index: number): ${struct.mapName}`);
+    this.code.line(`return new ${struct.mapName}(this, \`[\${index}]\`);`);
+    this.code.closeBlock();
+
+    this.code.closeBlock();
+  }
+
+  private emitComplexListMapClasses(struct: Struct, isSet: boolean) {
+    this.emitComplexListMapClass(struct, isSet);
+    this.emitComplexListClass(struct);
+  }
+
+  private emitComplexListMapClass(struct: Struct, isSet: boolean) {
+    this.code.line();
+    this.code.openBlock(
+      `export class ${struct.listMapName} extends cdktn.ComplexMap`,
+    );
+
+    if (struct.assignable) {
+      this.code.line(
+        `public internalValue? : { [key: string]: ${struct.name}[] } | cdktn.IResolvable`,
+      );
+    }
+
+    this.code.line();
+    const constructorComment = sanitizedComment(this.code);
+    constructorComment.line(`@param terraformResource The parent resource`);
+    constructorComment.line(
+      `@param terraformAttribute The attribute on the parent resource this class is referencing`,
+    );
+    constructorComment.end();
+    this.code.openBlock(
+      `constructor(terraformResource: cdktn.IInterpolatingParent, terraformAttribute: string)`,
+    );
+    this.code.line(`super(terraformResource, terraformAttribute);`);
+    this.code.closeBlock();
+
+    this.code.line();
+    const getterComment = sanitizedComment(this.code);
+    getterComment.line(`@param key the key of the item to return`);
+    getterComment.end();
+    this.code.openBlock(`public get(key: string): ${struct.listName}`);
+    this.code.line(
+      `return new ${struct.listName}(this, \`[\${key}]\`, ${isSet});`,
+    );
+    this.code.closeBlock();
+
+    this.code.closeBlock();
+  }
+
+  private emitComplexListListClasses(struct: Struct) {
+    this.emitComplexListListClass(struct);
+    this.emitComplexListClass(struct);
+  }
+
+  private emitComplexListListClass(struct: Struct) {
+    this.code.line();
+    this.code.openBlock(
+      `export class ${struct.listListName} extends cdktn.MapList`, // despite name, need the same behavior
+    );
+
+    if (struct.assignable) {
+      this.code.line(
+        `public internalValue? : ${struct.name}[][] | cdktn.IResolvable`,
+      );
+    }
+
+    this.code.line();
+    const constructorComment = sanitizedComment(this.code);
+    constructorComment.line(`@param terraformResource The parent resource`);
+    constructorComment.line(
+      `@param terraformAttribute The attribute on the parent resource this class is referencing`,
+    );
+    constructorComment.line(
+      `@param wrapsSet whether the list is wrapping a set (will add tolist() to be able to access an item via an index)`,
+    );
+    constructorComment.end();
+    this.code.openBlock(
+      `constructor(terraformResource: cdktn.IInterpolatingParent, terraformAttribute: string, wrapsSet: boolean)`,
+    );
+    this.code.line(`super(terraformResource, terraformAttribute, wrapsSet);`);
+    this.code.closeBlock();
+
+    this.code.line();
+    const getterComment = sanitizedComment(this.code);
+    getterComment.line(`@param index the index of the item to return`);
+    getterComment.end();
+    this.code.openBlock(`public get(index: number): ${struct.listName}`);
+    this.code.line(
+      `return new ${struct.listName}(this, \`[\${index}]\`, ${
+        struct.nestingMode === "setlist" || struct.nestingMode === "setset"
+      });`,
+    );
+    this.code.closeBlock();
+
+    this.code.closeBlock();
+  }
+
+  private emitInternalValueGetter(struct: Struct) {
+    this.code.openBlock(
+      `public get internalValue(): ${struct.name}${
+        !struct.isClass ? " | cdktn.IResolvable" : ""
+      } | undefined`,
+    );
+
+    if (!struct.isClass) {
+      this.code.openBlock("if (this.resolvableValue)");
+      this.code.line("return this.resolvableValue;");
+      this.code.closeBlock();
+    }
+
+    this.code.line("let hasAnyValues = this.isEmptyObject;");
+    this.code.line("const internalValueResult: any = {};");
+    for (const att of struct.attributes) {
+      if (att.isStored) {
+        if (att.getterType._type === "stored_class") {
+          this.code.openBlock(
+            `if (this.${att.storageName}?.internalValue !== undefined)`,
+          );
+        } else {
+          this.code.openBlock(`if (this.${att.storageName} !== undefined)`);
+        }
+        this.code.line("hasAnyValues = true;");
+        if (att.getterType._type === "stored_class") {
+          this.code.line(
+            `internalValueResult.${att.name} = this.${att.storageName}?.internalValue;`,
+          );
+        } else {
+          this.code.line(
+            `internalValueResult.${att.name} = this.${att.storageName};`,
+          );
+        }
+        this.code.closeBlock();
+      }
+    }
+    this.code.line("return hasAnyValues ? internalValueResult : undefined;");
+    this.code.closeBlock();
+  }
+
+  private emitInternalValueSetter(struct: Struct) {
+    this.code.openBlock(
+      `public set internalValue(value: ${struct.name}${
+        !struct.isClass ? " | cdktn.IResolvable" : ""
+      } | undefined)`,
+    );
+
+    this.code.openBlock("if (value === undefined)");
+    this.code.line("this.isEmptyObject = false;");
+    if (!struct.isClass) {
+      this.code.line("this.resolvableValue = undefined;");
+    }
+    for (const att of struct.attributes) {
+      if (att.isStored) {
+        if (att.setterType._type === "stored_class") {
+          this.code.line(`this.${att.storageName}.internalValue = undefined;`);
+        } else if (att.setterType._type !== "none") {
+          this.code.line(`this.${att.storageName} = undefined;`);
+        }
+      }
+    }
+    this.code.closeBlock();
+    if (!struct.isClass) {
+      this.code.openBlock("else if (cdktn.Tokenization.isResolvable(value))");
+      this.code.line("this.isEmptyObject = false;");
+      this.code.line("this.resolvableValue = value;");
+      this.code.closeBlock();
+    }
+    this.code.openBlock("else");
+    this.code.line("this.isEmptyObject = Object.keys(value).length === 0;");
+    if (!struct.isClass) {
+      this.code.line("this.resolvableValue = undefined;");
+    }
+    for (const att of struct.attributes) {
+      if (att.isStored) {
+        if (att.setterType._type === "stored_class") {
+          this.code.line(
+            `this.${att.storageName}.internalValue = value.${att.name};`,
+          );
+        } else if (att.setterType._type !== "none") {
+          this.code.line(`this.${att.storageName} = value.${att.name};`);
+        }
+      }
+    }
+    this.code.closeBlock();
+    this.code.closeBlock();
+  }
+
+  private emitToHclTerraformFunction(struct: Struct) {
+    this.code.line();
+    this.code.openBlock(
+      `export function ${downcaseFirst(struct.name)}ToHclTerraform(struct?: ${
+        struct.isSingleItem && !struct.isProvider
+          ? `${struct.name}OutputReference | `
+          : ""
+      }${struct.name}${!struct.isClass ? " | cdktn.IResolvable" : ""}): any`,
+    );
+    this.code.line(
+      `if (!cdktn.canInspect(struct) || cdktn.Tokenization.isResolvable(struct)) { return struct; }`,
+    );
+    this.code.openBlock(`if (cdktn.isComplexElement(struct))`);
+    this.code.line(
+      `throw new Error("A complex element was used as configuration, this is not supported: https://cdktn.io/docs/concepts/resources#references");`,
+    );
+    this.code.closeBlock();
+
+    this.code.open(`const attrs = {`);
+
+    for (const att of struct.assignableAttributes) {
+      this.attributesEmitter.emitToHclTerraform(att, true);
+    }
+
+    this.code.close(`};`);
+
+    if (struct.assignableAttributes.length > 0) {
+      this.code.line();
+      this.code.line(`// remove undefined attributes`);
+      this.code.line(
+        `return Object.fromEntries(Object.entries(attrs).filter(([_, value]) => value !== undefined && value.value !== undefined));`,
+      );
+    } else {
+      this.code.line(`return attrs;`);
+    }
+
+    this.code.closeBlock();
+    this.code.line();
+  }
+
+  private emitToTerraformFunction(struct: Struct) {
+    this.code.line();
+    this.code.openBlock(
+      `export function ${downcaseFirst(struct.name)}ToTerraform(struct?: ${
+        struct.isSingleItem && !struct.isProvider
+          ? `${struct.name}OutputReference | `
+          : ""
+      }${struct.name}${!struct.isClass ? " | cdktn.IResolvable" : ""}): any`,
+    );
+    this.code.line(
+      `if (!cdktn.canInspect(struct) || cdktn.Tokenization.isResolvable(struct)) { return struct; }`,
+    );
+    this.code.openBlock(`if (cdktn.isComplexElement(struct))`);
+    this.code.line(
+      `throw new Error("A complex element was used as configuration, this is not supported: https://cdktn.io/docs/concepts/resources#references");`,
+    );
+    this.code.closeBlock();
+
+    this.code.openBlock("return");
+    for (const att of struct.assignableAttributes) {
+      this.attributesEmitter.emitToTerraform(att, true);
+    }
+    this.code.closeBlock(";");
+    this.code.closeBlock();
+    this.code.line();
+  }
+}