@resistdesign/voltra 3.0.0-alpha.2 → 3.0.0-alpha.21

package/common/index.js

@@ -0,0 +1,413 @@
+// src/common/CommandLine/collectRequiredEnvironmentVariables.ts
+var collectRequiredEnvironmentVariables = (varNames) => {
+  const result = {};
+  const missingEnvVars = [];
+  for (const vN of varNames) {
+    const value = process.env[vN];
+    if (!value) {
+      missingEnvVars.push(vN);
+    } else {
+      result[vN] = value;
+    }
+  }
+  if (missingEnvVars.length > 0) {
+    throw new Error(
+      `
+\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510
+\u2502   \u26A0  ENVIRONMENT CHECK FAILED    \u2502
+\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
+
+Missing Required Environment Variables:
+
+${missingEnvVars.map((vN) => `- ${vN}`).join(`
+`)}
+`
+    );
+  }
+  return result;
+};
+
+// src/common/TypeParsing/TypeInfo.ts
+var TypeOperation = /* @__PURE__ */ ((TypeOperation2) => {
+  TypeOperation2["CREATE"] = "CREATE";
+  TypeOperation2["READ"] = "READ";
+  TypeOperation2["UPDATE"] = "UPDATE";
+  TypeOperation2["DELETE"] = "DELETE";
+  return TypeOperation2;
+})(TypeOperation || {});
+
+// src/common/TypeInfoORM/Types.ts
+var TypeInfoORMServiceError = /* @__PURE__ */ ((TypeInfoORMServiceError2) => {
+  TypeInfoORMServiceError2["NO_DRIVERS_SUPPLIED"] = "NO_DRIVERS_SUPPLIED";
+  TypeInfoORMServiceError2["NO_RELATIONSHIP_DRIVERS_SUPPLIED"] = "NO_RELATIONSHIP_DRIVERS_SUPPLIED";
+  TypeInfoORMServiceError2["NO_PRIMARY_FIELD_VALUE_SUPPLIED"] = "NO_PRIMARY_FIELD_VALUE_SUPPLIED";
+  TypeInfoORMServiceError2["INVALID_DRIVER"] = "INVALID_DRIVER";
+  TypeInfoORMServiceError2["INVALID_RELATIONSHIP_DRIVER"] = "INVALID_RELATIONSHIP_DRIVER";
+  TypeInfoORMServiceError2["INVALID_TYPE_INFO"] = "INVALID_TYPE_INFO";
+  TypeInfoORMServiceError2["TYPE_INFO_MISSING_PRIMARY_FIELD"] = "TYPE_INFO_MISSING_PRIMARY_FIELD";
+  TypeInfoORMServiceError2["INVALID_RELATIONSHIP"] = "INVALID_RELATIONSHIP";
+  TypeInfoORMServiceError2["INVALID_OPERATION"] = "INVALID_OPERATION";
+  TypeInfoORMServiceError2["MISSING_ACCESSING_ROLE"] = "MISSING_ACCESSING_ROLE";
+  TypeInfoORMServiceError2["INDEXING_UNSUPPORTED_CRITERIA"] = "INDEXING_UNSUPPORTED_CRITERIA";
+  TypeInfoORMServiceError2["INDEXING_UNSUPPORTED_COMBINATION"] = "INDEXING_UNSUPPORTED_COMBINATION";
+  TypeInfoORMServiceError2["INDEXING_MISSING_INDEX_FIELD"] = "INDEXING_MISSING_INDEX_FIELD";
+  TypeInfoORMServiceError2["INDEXING_MISSING_BACKEND"] = "INDEXING_MISSING_BACKEND";
+  TypeInfoORMServiceError2["INDEXING_REQUIRES_CRITERIA"] = "INDEXING_REQUIRES_CRITERIA";
+  return TypeInfoORMServiceError2;
+})(TypeInfoORMServiceError || {});
+
+// src/common/Routing.ts
+var PATH_DELIMITER = "/";
+var getPathString = (parts = [], delimiter = PATH_DELIMITER, filterEmptyInput = false, useJson = true, uriEncodeParts = false) => parts.filter(filterEmptyInput ? (p) => p ?? false : () => true).map(useJson ? (p) => JSON.stringify(p) : (x) => x).map(uriEncodeParts ? encodeURIComponent : (x) => x).join(delimiter);
+
+// src/common/TypeParsing/Validation.ts
+var RelationshipValidationType = /* @__PURE__ */ ((RelationshipValidationType2) => {
+  RelationshipValidationType2["INCLUDE"] = "INCLUDE";
+  RelationshipValidationType2["EXCLUDE"] = "EXCLUDE";
+  RelationshipValidationType2["STRICT_EXCLUDE"] = "STRICT_EXCLUDE";
+  return RelationshipValidationType2;
+})(RelationshipValidationType || {});
+var INVALID_CUSTOM_TYPE = "INVALID_CUSTOM_TYPE";
+var PRIMITIVE_ERROR_MESSAGE_CONSTANTS = {
+  string: "NOT_A_STRING",
+  number: "NOT_A_NUMBER",
+  boolean: "NOT_A_BOOLEAN"
+};
+var ERROR_MESSAGE_CONSTANTS = {
+  MISSING: "MISSING",
+  INVALID_OPTION: "INVALID_OPTION",
+  INVALID_FIELD: "INVALID_FIELD",
+  RELATIONSHIP_VALUES_ARE_STRICTLY_EXCLUDED: "RELATIONSHIP_VALUES_ARE_STRICTLY_EXCLUDED",
+  INVALID_TYPE: "INVALID_TYPE",
+  NO_UNION_TYPE_MATCHED: "NO_UNION_TYPE_MATCHED",
+  TYPE_DOES_NOT_EXIST: "TYPE_DOES_NOT_EXIST",
+  INVALID_PATTERN: "INVALID_PATTERN",
+  VALUE_DOES_NOT_MATCH_PATTERN: "VALUE_DOES_NOT_MATCH_PATTERN"
+};
+var DENIED_TYPE_OPERATIONS = {
+  CREATE: "DENIED_TYPE_OPERATION_CREATE",
+  READ: "DENIED_TYPE_OPERATION_READ",
+  UPDATE: "DENIED_TYPE_OPERATION_UPDATE",
+  DELETE: "DENIED_TYPE_OPERATION_DELETE"
+};
+var validateValueMatchesPattern = (typeName, value, pattern) => {
+  const results = {
+    typeName,
+    valid: true,
+    error: "",
+    errorMap: {}
+  };
+  const valueSupplied = typeof value !== "undefined";
+  const patternSupplied = typeof pattern === "string" && pattern.trim() !== "";
+  if (!valueSupplied || !patternSupplied) {
+    try {
+      const regex = new RegExp(pattern);
+      const testResult = typeof value === "string" && regex.test(value);
+      if (!testResult) {
+        results.valid = false;
+        results.error = ERROR_MESSAGE_CONSTANTS.VALUE_DOES_NOT_MATCH_PATTERN;
+      }
+    } catch (e) {
+      results.valid = false;
+      results.error = ERROR_MESSAGE_CONSTANTS.INVALID_PATTERN;
+    }
+  }
+  return results;
+};
+var getValidityValue = (existing, pending) => !existing ? false : pending;
+var TYPE_KEYWORD_VALIDATORS = {
+  string: (value) => typeof value === "string",
+  number: (value) => typeof value === "number",
+  boolean: (value) => typeof value === "boolean"
+};
+var hasValue = (value) => value ?? false;
+var validateKeywordType = (value, type) => {
+  const validator = TYPE_KEYWORD_VALIDATORS[type];
+  let valid = true;
+  if (validator) {
+    valid = validator(value);
+  }
+  return valid;
+};
+var validateCustomType = (value, customType, customValidators) => {
+  let valid = true;
+  if (customValidators && customType) {
+    const validator = customValidators[customType];
+    if (validator) {
+      try {
+        valid = validator(value);
+      } catch (e) {
+        valid = false;
+      }
+    }
+  }
+  return valid;
+};
+var validateTypeInfoFieldValue = (value, typeInfoField, typeInfoMap, ignoreArray = false, strict = false, customValidators, typeOperation, relationshipValidationType = "STRICT_EXCLUDE" /* STRICT_EXCLUDE */, itemIsPartial) => {
+  const {
+    type,
+    typeReference,
+    array,
+    optional,
+    possibleValues,
+    tags: { customType, constraints: { pattern = void 0 } = {} } = {}
+  } = typeInfoField;
+  const results = {
+    typeName: typeReference ?? type,
+    valid: true,
+    error: "",
+    errorMap: {}
+  };
+  const requiredValueAllowed = !typeReference || relationshipValidationType === "INCLUDE" /* INCLUDE */;
+  const valueIsUndefined = typeof value === "undefined";
+  const valueIsNull = value === null;
+  const canSkipValidation = itemIsPartial && (valueIsUndefined || valueIsNull) || optional && valueIsUndefined;
+  if (canSkipValidation) {
+    results.valid = true;
+  } else if (requiredValueAllowed && !itemIsPartial && !optional && !hasValue(value)) {
+    results.valid = false;
+    results.error = ERROR_MESSAGE_CONSTANTS.MISSING;
+  } else if (array && !ignoreArray) {
+    const {
+      valid: validArray,
+      error: arrayError,
+      errorMap: arrayErrorMap
+    } = validateArrayOfTypeInfoFieldValues(
+      value,
+      typeInfoField,
+      typeInfoMap,
+      strict,
+      customValidators,
+      typeOperation,
+      relationshipValidationType,
+      itemIsPartial
+    );
+    results.valid = getValidityValue(results.valid, validArray);
+    results.error = arrayError;
+    results.errorMap = arrayErrorMap;
+  } else {
+    if (typeReference) {
+      if (relationshipValidationType === "INCLUDE" /* INCLUDE */) {
+        const {
+          valid: validTypeInfo,
+          error: typeInfoError,
+          errorMap: typeInfoErrorMap
+        } = validateTypeInfoValue(
+          value,
+          typeReference,
+          typeInfoMap,
+          strict,
+          customValidators,
+          typeOperation,
+          relationshipValidationType,
+          itemIsPartial
+        );
+        results.valid = getValidityValue(results.valid, validTypeInfo);
+        results.error = typeInfoError;
+        results.errorMap = typeInfoErrorMap;
+      } else if (relationshipValidationType === "STRICT_EXCLUDE" /* STRICT_EXCLUDE */) {
+        const valueSupplied = typeof value !== "undefined";
+        if (valueSupplied) {
+          results.valid = false;
+          results.error = ERROR_MESSAGE_CONSTANTS.RELATIONSHIP_VALUES_ARE_STRICTLY_EXCLUDED;
+        }
+      } else if (relationshipValidationType === "EXCLUDE" /* EXCLUDE */) {
+        results.valid = getValidityValue(results.valid, true);
+      }
+    } else if (possibleValues && !possibleValues.includes(value)) {
+      results.valid = false;
+      results.error = ERROR_MESSAGE_CONSTANTS.INVALID_OPTION;
+    } else {
+      const pendingValid = validateKeywordType(value, type);
+      const customValid = validateCustomType(
+        value,
+        customType,
+        customValidators
+      );
+      results.valid = getValidityValue(results.valid, pendingValid);
+      results.valid = getValidityValue(results.valid, customValid);
+      if (type === "string" && typeof pattern === "string") {
+        const { valid: patternValid, error: patternError } = validateValueMatchesPattern(value, pattern);
+        results.valid = getValidityValue(results.valid, patternValid);
+        results.error = patternError;
+      }
+      if (!customValid) {
+        results.error = INVALID_CUSTOM_TYPE;
+      } else if (!results.valid) {
+        results.error = results.error ? results.error : PRIMITIVE_ERROR_MESSAGE_CONSTANTS[type];
+      }
+    }
+  }
+  return results;
+};
+var validateArrayOfTypeInfoFieldValues = (values = [], typeInfoField, typeInfoMap, strict = false, customValidators, typeOperation, relationshipValidationType, itemIsPartial) => {
+  const { type, typeReference } = typeInfoField;
+  const results = {
+    typeName: typeReference ?? type,
+    valid: true,
+    error: "",
+    errorMap: {}
+  };
+  for (let i = 0; i < values.length; i++) {
+    const v = values[i];
+    const {
+      valid: indexValid,
+      error: indexError = "",
+      errorMap: indexErrorMap
+    } = validateTypeInfoFieldValue(
+      v,
+      typeInfoField,
+      typeInfoMap,
+      true,
+      strict,
+      customValidators,
+      typeOperation,
+      relationshipValidationType,
+      itemIsPartial
+    );
+    results.valid = getValidityValue(results.valid, indexValid);
+    results.errorMap[getPathString([i])] = [indexError];
+    for (const er in indexErrorMap) {
+      results.errorMap[getPathString([i, er])] = indexErrorMap[er];
+    }
+  }
+  return results;
+};
+var validateTypeInfoFieldOperationAllowed = (fieldName, fieldOperation, typeInfoField) => {
+  const results = {
+    typeName: null,
+    valid: true,
+    error: "",
+    errorMap: {}
+  };
+  if (fieldOperation && typeInfoField) {
+    const {
+      type,
+      typeReference,
+      tags = {}
+    } = typeInfoField || {};
+    const { deniedOperations: { [fieldOperation]: denied = false } = {} } = tags;
+    results.typeName = typeReference ?? type;
+    results.valid = !denied;
+    if (!results.valid) {
+      results.error = DENIED_TYPE_OPERATIONS[fieldOperation];
+      results.errorMap[fieldName] = [results.error];
+    }
+  }
+  return results;
+};
+var validateTypeOperationAllowed = (typeName, valueFields, typeOperation, typeInfo) => {
+  const results = {
+    typeName,
+    valid: true,
+    error: "",
+    errorMap: {}
+  };
+  const { fields = {}, tags = {} } = typeInfo;
+  const { deniedOperations: { [typeOperation]: denied = false } = {} } = tags;
+  if (denied) {
+    results.valid = false;
+    results.error = DENIED_TYPE_OPERATIONS[typeOperation];
+  } else {
+    for (const vF of valueFields) {
+      const vFieldInfo = fields[vF];
+      const { valid: vFValid, error: vFError } = validateTypeInfoFieldOperationAllowed(vF, typeOperation, vFieldInfo);
+      results.valid = getValidityValue(results.valid, vFValid);
+      if (!vFValid) {
+        results.errorMap[vF] = [vFError];
+      }
+    }
+  }
+  return results;
+};
+var validateTypeInfoValue = (value, typeInfoFullName, typeInfoMap, strict = false, customValidators, typeOperation, relationshipValidationType, itemIsPartial) => {
+  const typeInfo = typeInfoMap[typeInfoFullName];
+  const results = {
+    typeName: typeInfoFullName,
+    valid: !!typeInfo,
+    error: !!typeInfo ? "" : ERROR_MESSAGE_CONSTANTS.TYPE_DOES_NOT_EXIST,
+    errorMap: {}
+  };
+  if (typeInfo) {
+    const { primaryField, fields, unionFieldSets } = typeInfo;
+    if (typeOperation) {
+      const valueFields = typeof value === "object" ? Object.keys(value ?? {}) : [];
+      const {
+        valid: operationValid,
+        error: operationError,
+        errorMap: operationErrorMap
+      } = validateTypeOperationAllowed(
+        typeInfoFullName,
+        valueFields,
+        typeOperation,
+        typeInfo
+      );
+      results.valid = getValidityValue(results.valid, operationValid);
+      results.error = operationError;
+      for (const oE in operationErrorMap) {
+        const existingError = results.errorMap[oE] ?? [];
+        results.errorMap[oE] = existingError ? [...existingError, ...operationErrorMap[oE]] : operationErrorMap[oE];
+      }
+      if (!operationValid && operationError) {
+        results.error = operationError;
+      }
+    }
+    if (unionFieldSets) {
+      const valueFields = Object.keys(value || {});
+      let valid = false;
+      for (const uFS of unionFieldSets) {
+        valid = valueFields.every((vF) => uFS.includes(vF));
+        if (valid) {
+          break;
+        }
+      }
+      if (!valid) {
+        results.valid = false;
+        results.error = ERROR_MESSAGE_CONSTANTS.NO_UNION_TYPE_MATCHED;
+      }
+    } else if (strict) {
+      const knownFields = Object.keys(fields || {});
+      const valueFields = Object.keys(value || {});
+      for (const vF of valueFields) {
+        if (!knownFields.includes(vF)) {
+          results.valid = false;
+          results.errorMap[vF] = [ERROR_MESSAGE_CONSTANTS.INVALID_FIELD];
+        }
+      }
+    }
+    if (fields) {
+      for (const key in fields) {
+        if (typeOperation !== "CREATE" /* CREATE */ || typeof primaryField !== "string" || key !== primaryField) {
+          const typeInfoField = fields[key];
+          const fieldValue = value[key];
+          const {
+            valid: fieldValid,
+            error: fieldError,
+            errorMap: fieldErrorMap
+          } = validateTypeInfoFieldValue(
+            fieldValue,
+            typeInfoField,
+            typeInfoMap,
+            false,
+            strict,
+            customValidators,
+            typeOperation,
+            relationshipValidationType,
+            itemIsPartial
+          );
+          results.valid = getValidityValue(results.valid, fieldValid);
+          results.errorMap[key] = [fieldError];
+          for (const fE in fieldErrorMap) {
+            results.errorMap[getPathString([key, fE])] = fieldErrorMap[fE];
+          }
+        }
+      }
+    }
+    if (!results.valid && !results.error) {
+      results.error = ERROR_MESSAGE_CONSTANTS.INVALID_TYPE;
+    }
+  }
+  return results;
+};
+
+export { DENIED_TYPE_OPERATIONS, ERROR_MESSAGE_CONSTANTS, INVALID_CUSTOM_TYPE, PRIMITIVE_ERROR_MESSAGE_CONSTANTS, RelationshipValidationType, TYPE_KEYWORD_VALIDATORS, TypeInfoORMServiceError, TypeOperation, collectRequiredEnvironmentVariables, getValidityValue, hasValue, validateArrayOfTypeInfoFieldValues, validateCustomType, validateKeywordType, validateTypeInfoFieldOperationAllowed, validateTypeInfoFieldValue, validateTypeInfoValue, validateTypeOperationAllowed, validateValueMatchesPattern };

package/{src/iac → iac}/SimpleCFT.d.ts

@@ -1,48 +1,92 @@
+/**
+ * @packageDocumentation
+ *
+ * Fluent builder for CloudFormation templates. Use {@link SimpleCFT} to apply
+ * packs, patches, and parameters, then read the resulting `template` or render
+ * it as JSON/YAML.
+ */
 import { CloudFormationTemplate } from "./types/IaCTypes";
 import { ParameterGroup, ParameterInfo, ResourcePackApplier } from "./utils";
 /**
  * A function used to apply a modification to a SimpleCFT instance.
+ *
+ * @param simpleCFT - SimpleCFT instance to modify.
  * */
 export type SimpleCFTModification = (simpleCFT: SimpleCFT) => void;
 /**
  * The basis for your stack template.
  * Apply packs, patches, parameters and parameter groups.
  * Access the `template` property for the resulting CloudFormation template.
- * */
+ *
+ * Example:
+ * ```ts
+ * import { SimpleCFT } from "./SimpleCFT";
+ *
+ * const template = new SimpleCFT()
+ *   .addParameter({
+ *     Group: "App",
+ *     ParameterId: "AppName",
+ *     Label: "App Name",
+ *     Parameter: { Type: "String", Default: "voltra" },
+ *   })
+ *   .patch({ Description: "My stack" });
+ *
+ * console.log(template.toString());
+ * ```
+ */
 export declare class SimpleCFT {
     template: CloudFormationTemplate;
+    /**
+     * Create a SimpleCFT template wrapper.
+     *
+     * @param template - Initial CloudFormation template.
+     */
     constructor(template?: CloudFormationTemplate);
     /**
      * Apply a pack with configuration to the stack template.
-     * @see {@link IaC} for an example.
+     * @see `@resistdesign/voltra/iac` and `@resistdesign/voltra/iac/packs` for examples.
      * */
     applyPack: <ParamsType>(pack: ResourcePackApplier<ParamsType>, params: ParamsType) => this;
     /**
      * Apply a patch to the stack template.
+     *
+     * @param patch - Template patch to merge.
      * */
     patch: (patch: Partial<CloudFormationTemplate>) => this;
     /**
      * Add a stack parameter including its descriptive info and an optional parameter group.
+     *
+     * @param parameter - Parameter definition and metadata.
      * */
     addParameter: (parameter: ParameterInfo) => this;
     /**
      * Add a group of stack parameters including their descriptive info and an optional parameter group.
+     *
+     * @param group - Parameter group definition.
      * */
     addParameterGroup: ({ Label: Group, Parameters }: ParameterGroup) => this;
     /**
      * Use a modification to dynamically apply various changes at once.
+     *
+     * @param modification - Modification callback to apply.
      * */
     modify: (modification: SimpleCFTModification) => this;
     /**
      * Convert the stack template to a string.
+     *
+     * @returns JSON string representation of the template.
      * */
     toString: () => string;
     /**
      * Convert the stack template to a JSON object.
+     *
+     * @returns Template JSON object.
      * */
     toJSON: () => CloudFormationTemplate;
     /**
      * Convert the stack template to a YAML string.
+     *
+     * @returns YAML string representation of the template.
      * */
     toYAML: () => string;
 }

package/iac/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @packageDocumentation
+ *
+ * Infrastructure-as-code entrypoint.
+ *
+ * Import from the IaC subpath only:
+ * ```ts
+ * import { SimpleCFT } from "@resistdesign/voltra/iac";
+ * import { addDNS } from "@resistdesign/voltra/iac/packs";
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { SimpleCFT } from "@resistdesign/voltra/iac";
+ * import { addDNS } from "@resistdesign/voltra/iac/packs";
+ *
+ * const cft = new SimpleCFT().applyPack(addDNS, {
+ *   hostedZoneIdParameterName: "<YOUR_INFO_HERE>",
+ *   domainNameParameterName: "<YOUR_INFO_HERE>",
+ *   localUIDevelopmentDomainName: "<YOUR_INFO_HERE>",
+ *   localUIDevelopmentIPAddress: "<YOUR_INFO_HERE>",
+ * });
+ *
+ * console.log(cft.template);
+ * ```
+ *
+ * Use flat exports for reusable resource packs and template helpers.
+ *
+ * See also: `@resistdesign/voltra/iac/packs` for direct pack imports.
+ */
+/**
+ * @category iac
+ * @group Core
+ */
+export * from "./SimpleCFT";
+/**
+ * @category iac
+ * @group Utilities
+ */
+export * from "./utils";