@ttoss/cloudformation 0.12.0 → 0.12.1

package/README.md

@@ -0,0 +1,79 @@
+# @ttoss/cloudformation
+
+Utilities and TypeScript types for working with AWS CloudFormation templates.
+
+## Installation
+
+```bash
+pnpm add @ttoss/cloudformation
+```
+
+## Intrinsic Function Types
+
+The package exports TypeScript types for all commonly used CloudFormation intrinsic functions:
+
+| Type                        | CloudFormation equivalent                            |
+| --------------------------- | ---------------------------------------------------- |
+| `CloudFormationRef`         | `{ Ref: string }`                                    |
+| `CloudFormationGetAtt`      | `{ 'Fn::GetAtt': [string, string] }`                 |
+| `CloudFormationJoin`        | `{ 'Fn::Join': [string, ...] }`                      |
+| `CloudFormationSub`         | `{ 'Fn::Sub': string }`                              |
+| `CloudFormationSelect`      | `{ 'Fn::Select': [number, string[]] }`               |
+| `CloudFormationSplit`       | `{ 'Fn::Split': [string, string] }`                  |
+| `CloudFormationImportValue` | `{ 'Fn::ImportValue': string \| CloudFormationSub }` |
+| `CloudFormationIntrinsic`   | Union of all the above                               |
+| `CloudFormationValue<T>`    | `T \| CloudFormationIntrinsic`                       |
+
+## Helpers
+
+### `importValueFromParameter`
+
+Generates an `Fn::ImportValue` + `Fn::Sub` intrinsic that reads the export name
+from a CloudFormation parameter. This is the standard pattern for consuming
+cross-stack exports whose names are not known at author time.
+
+```typescript
+import { importValueFromParameter } from '@ttoss/cloudformation';
+
+importValueFromParameter('AppSyncLambdaRoleArn');
+// => { 'Fn::ImportValue': { 'Fn::Sub': '${AppSyncLambdaRoleArn}' } }
+```
+
+Typical use in a CloudFormation template:
+
+```typescript
+import { importValueFromParameter } from '@ttoss/cloudformation';
+import { createApiTemplate } from '@ttoss/appsync-api';
+
+const template = createApiTemplate({
+  schemaComposer,
+  dataSource: {
+    roleArn: importValueFromParameter('AppSyncLambdaDataSourceIAMRoleArn'),
+  },
+  lambdaFunction: {
+    roleArn: importValueFromParameter('AppSyncLambdaFunctionIAMRoleArn'),
+    environment: {
+      variables: {
+        TABLE_NAME: { Ref: 'DynamoTableName' },
+        EXTERNAL_ARN: importValueFromParameter('SomeOtherStackExportedName'),
+      },
+    },
+  },
+});
+```
+
+## Reading Templates
+
+### `findAndReadCloudFormationTemplate`
+
+Reads a CloudFormation template file from disk. Supports both TypeScript and
+YAML files.
+
+```typescript
+import { findAndReadCloudFormationTemplate } from '@ttoss/cloudformation';
+
+const template = await findAndReadCloudFormationTemplate({
+  templatePath: './cloudformation.ts',
+  options: { environment: 'Production' },
+});
+```

package/dist/esm/index.js

@@ -196,4 +196,13 @@ var findAndReadCloudFormationTemplate = /* @__PURE__ */__name(async ({
     options
   });
 }, "findAndReadCloudFormationTemplate");
-export { findAndReadCloudFormationTemplate };
+
+// src/CloudFormationTemplate.ts
+var importValueFromParameter = /* @__PURE__ */__name(parameterName => {
+  return {
+    "Fn::ImportValue": {
+      "Fn::Sub": `\${${parameterName}}`
+    }
+  };
+}, "importValueFromParameter");
+export { findAndReadCloudFormationTemplate, importValueFromParameter };

package/dist/index.d.cts

@@ -16,7 +16,19 @@ type CloudFormationSelect = {
 type CloudFormationSplit = {
     'Fn::Split': [string, string];
 };
-type CloudFormationIntrinsic = CloudFormationRef | CloudFormationGetAtt | CloudFormationJoin | CloudFormationSub | CloudFormationSelect | CloudFormationSplit;
+type CloudFormationImportValue = {
+    'Fn::ImportValue': string | CloudFormationSub;
+};
+/**
+ * Returns an `Fn::ImportValue` intrinsic that resolves the export name from
+ * a CloudFormation parameter via `Fn::Sub`.
+ *
+ * @example
+ * importValueFromParameter('MyStackExportName')
+ * // => { 'Fn::ImportValue': { 'Fn::Sub': '${MyStackExportName}' } }
+ */
+declare const importValueFromParameter: (parameterName: string) => CloudFormationImportValue;
+type CloudFormationIntrinsic = CloudFormationRef | CloudFormationGetAtt | CloudFormationJoin | CloudFormationSub | CloudFormationSelect | CloudFormationSplit | CloudFormationImportValue;
 type CloudFormationValue<T = any> = T | CloudFormationIntrinsic;
 type Parameter = {
     AllowedValues?: string[];
@@ -112,4 +124,4 @@ declare const findAndReadCloudFormationTemplate: ({ templatePath: defaultTemplat
     options?: unknown;
 }) => Promise<CloudFormationTemplate>;
 
-export { type BaseResource, type CloudFormationGetAtt, type CloudFormationIntrinsic, type CloudFormationJoin, type CloudFormationRef, type CloudFormationSelect, type CloudFormationSplit, type CloudFormationSub, type CloudFormationTemplate, type CloudFormationValue, type Condition, type Conditions, type IAMRoleResource, type Output, type Outputs, type Parameter, type Parameters, type Policy, type PolicyDocument, type PolicyStatement, type Resource, type Resources, findAndReadCloudFormationTemplate };
+export { type BaseResource, type CloudFormationGetAtt, type CloudFormationImportValue, type CloudFormationIntrinsic, type CloudFormationJoin, type CloudFormationRef, type CloudFormationSelect, type CloudFormationSplit, type CloudFormationSub, type CloudFormationTemplate, type CloudFormationValue, type Condition, type Conditions, type IAMRoleResource, type Output, type Outputs, type Parameter, type Parameters, type Policy, type PolicyDocument, type PolicyStatement, type Resource, type Resources, findAndReadCloudFormationTemplate, importValueFromParameter };

package/dist/index.d.ts

@@ -16,7 +16,19 @@ type CloudFormationSelect = {
 type CloudFormationSplit = {
     'Fn::Split': [string, string];
 };
-type CloudFormationIntrinsic = CloudFormationRef | CloudFormationGetAtt | CloudFormationJoin | CloudFormationSub | CloudFormationSelect | CloudFormationSplit;
+type CloudFormationImportValue = {
+    'Fn::ImportValue': string | CloudFormationSub;
+};
+/**
+ * Returns an `Fn::ImportValue` intrinsic that resolves the export name from
+ * a CloudFormation parameter via `Fn::Sub`.
+ *
+ * @example
+ * importValueFromParameter('MyStackExportName')
+ * // => { 'Fn::ImportValue': { 'Fn::Sub': '${MyStackExportName}' } }
+ */
+declare const importValueFromParameter: (parameterName: string) => CloudFormationImportValue;
+type CloudFormationIntrinsic = CloudFormationRef | CloudFormationGetAtt | CloudFormationJoin | CloudFormationSub | CloudFormationSelect | CloudFormationSplit | CloudFormationImportValue;
 type CloudFormationValue<T = any> = T | CloudFormationIntrinsic;
 type Parameter = {
     AllowedValues?: string[];
@@ -112,4 +124,4 @@ declare const findAndReadCloudFormationTemplate: ({ templatePath: defaultTemplat
     options?: unknown;
 }) => Promise<CloudFormationTemplate>;
 
-export { type BaseResource, type CloudFormationGetAtt, type CloudFormationIntrinsic, type CloudFormationJoin, type CloudFormationRef, type CloudFormationSelect, type CloudFormationSplit, type CloudFormationSub, type CloudFormationTemplate, type CloudFormationValue, type Condition, type Conditions, type IAMRoleResource, type Output, type Outputs, type Parameter, type Parameters, type Policy, type PolicyDocument, type PolicyStatement, type Resource, type Resources, findAndReadCloudFormationTemplate };
+export { type BaseResource, type CloudFormationGetAtt, type CloudFormationImportValue, type CloudFormationIntrinsic, type CloudFormationJoin, type CloudFormationRef, type CloudFormationSelect, type CloudFormationSplit, type CloudFormationSub, type CloudFormationTemplate, type CloudFormationValue, type Condition, type Conditions, type IAMRoleResource, type Output, type Outputs, type Parameter, type Parameters, type Policy, type PolicyDocument, type PolicyStatement, type Resource, type Resources, findAndReadCloudFormationTemplate, importValueFromParameter };

package/dist/index.js

@@ -42,7 +42,8 @@ var __toCommonJS = mod => __copyProps(__defProp({}, "__esModule", {
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  findAndReadCloudFormationTemplate: () => findAndReadCloudFormationTemplate
+  findAndReadCloudFormationTemplate: () => findAndReadCloudFormationTemplate,
+  importValueFromParameter: () => importValueFromParameter
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -237,7 +238,17 @@ var findAndReadCloudFormationTemplate = /* @__PURE__ */__name(async ({
     options
   });
 }, "findAndReadCloudFormationTemplate");
+
+// src/CloudFormationTemplate.ts
+var importValueFromParameter = /* @__PURE__ */__name(parameterName => {
+  return {
+    "Fn::ImportValue": {
+      "Fn::Sub": `\${${parameterName}}`
+    }
+  };
+}, "importValueFromParameter");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  findAndReadCloudFormationTemplate
+  findAndReadCloudFormationTemplate,
+  importValueFromParameter
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/cloudformation",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "CloudFormation utils.",
   "license": "MIT",
   "author": "ttoss",