@ttoss/cloudformation 0.11.10 → 0.12.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +79 -0
  2. package/dist/esm/index.js +10 -1
  3. package/dist/index.d.cts +14 -2
  4. package/dist/index.d.ts +14 -2
  5. package/dist/index.js +13 -2
  6. package/package.json +5 -5
package/README.md ADDED
@@ -0,0 +1,79 @@
1
+ # @ttoss/cloudformation
2
+
3
+ Utilities and TypeScript types for working with AWS CloudFormation templates.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ pnpm add @ttoss/cloudformation
9
+ ```
10
+
11
+ ## Intrinsic Function Types
12
+
13
+ The package exports TypeScript types for all commonly used CloudFormation intrinsic functions:
14
+
15
+ | Type | CloudFormation equivalent |
16
+ | --------------------------- | ---------------------------------------------------- |
17
+ | `CloudFormationRef` | `{ Ref: string }` |
18
+ | `CloudFormationGetAtt` | `{ 'Fn::GetAtt': [string, string] }` |
19
+ | `CloudFormationJoin` | `{ 'Fn::Join': [string, ...] }` |
20
+ | `CloudFormationSub` | `{ 'Fn::Sub': string }` |
21
+ | `CloudFormationSelect` | `{ 'Fn::Select': [number, string[]] }` |
22
+ | `CloudFormationSplit` | `{ 'Fn::Split': [string, string] }` |
23
+ | `CloudFormationImportValue` | `{ 'Fn::ImportValue': string \| CloudFormationSub }` |
24
+ | `CloudFormationIntrinsic` | Union of all the above |
25
+ | `CloudFormationValue<T>` | `T \| CloudFormationIntrinsic` |
26
+
27
+ ## Helpers
28
+
29
+ ### `importValueFromParameter`
30
+
31
+ Generates an `Fn::ImportValue` + `Fn::Sub` intrinsic that reads the export name
32
+ from a CloudFormation parameter. This is the standard pattern for consuming
33
+ cross-stack exports whose names are not known at author time.
34
+
35
+ ```typescript
36
+ import { importValueFromParameter } from '@ttoss/cloudformation';
37
+
38
+ importValueFromParameter('AppSyncLambdaRoleArn');
39
+ // => { 'Fn::ImportValue': { 'Fn::Sub': '${AppSyncLambdaRoleArn}' } }
40
+ ```
41
+
42
+ Typical use in a CloudFormation template:
43
+
44
+ ```typescript
45
+ import { importValueFromParameter } from '@ttoss/cloudformation';
46
+ import { createApiTemplate } from '@ttoss/appsync-api';
47
+
48
+ const template = createApiTemplate({
49
+ schemaComposer,
50
+ dataSource: {
51
+ roleArn: importValueFromParameter('AppSyncLambdaDataSourceIAMRoleArn'),
52
+ },
53
+ lambdaFunction: {
54
+ roleArn: importValueFromParameter('AppSyncLambdaFunctionIAMRoleArn'),
55
+ environment: {
56
+ variables: {
57
+ TABLE_NAME: { Ref: 'DynamoTableName' },
58
+ EXTERNAL_ARN: importValueFromParameter('SomeOtherStackExportedName'),
59
+ },
60
+ },
61
+ },
62
+ });
63
+ ```
64
+
65
+ ## Reading Templates
66
+
67
+ ### `findAndReadCloudFormationTemplate`
68
+
69
+ Reads a CloudFormation template file from disk. Supports both TypeScript and
70
+ YAML files.
71
+
72
+ ```typescript
73
+ import { findAndReadCloudFormationTemplate } from '@ttoss/cloudformation';
74
+
75
+ const template = await findAndReadCloudFormationTemplate({
76
+ templatePath: './cloudformation.ts',
77
+ options: { environment: 'Production' },
78
+ });
79
+ ```
package/dist/esm/index.js CHANGED
@@ -196,4 +196,13 @@ var findAndReadCloudFormationTemplate = /* @__PURE__ */__name(async ({
196
196
  options
197
197
  });
198
198
  }, "findAndReadCloudFormationTemplate");
199
- export { findAndReadCloudFormationTemplate };
199
+
200
+ // src/CloudFormationTemplate.ts
201
+ var importValueFromParameter = /* @__PURE__ */__name(parameterName => {
202
+ return {
203
+ "Fn::ImportValue": {
204
+ "Fn::Sub": `\${${parameterName}}`
205
+ }
206
+ };
207
+ }, "importValueFromParameter");
208
+ export { findAndReadCloudFormationTemplate, importValueFromParameter };
package/dist/index.d.cts CHANGED
@@ -16,7 +16,19 @@ type CloudFormationSelect = {
16
16
  type CloudFormationSplit = {
17
17
  'Fn::Split': [string, string];
18
18
  };
19
- type CloudFormationIntrinsic = CloudFormationRef | CloudFormationGetAtt | CloudFormationJoin | CloudFormationSub | CloudFormationSelect | CloudFormationSplit;
19
+ type CloudFormationImportValue = {
20
+ 'Fn::ImportValue': string | CloudFormationSub;
21
+ };
22
+ /**
23
+ * Returns an `Fn::ImportValue` intrinsic that resolves the export name from
24
+ * a CloudFormation parameter via `Fn::Sub`.
25
+ *
26
+ * @example
27
+ * importValueFromParameter('MyStackExportName')
28
+ * // => { 'Fn::ImportValue': { 'Fn::Sub': '${MyStackExportName}' } }
29
+ */
30
+ declare const importValueFromParameter: (parameterName: string) => CloudFormationImportValue;
31
+ type CloudFormationIntrinsic = CloudFormationRef | CloudFormationGetAtt | CloudFormationJoin | CloudFormationSub | CloudFormationSelect | CloudFormationSplit | CloudFormationImportValue;
20
32
  type CloudFormationValue<T = any> = T | CloudFormationIntrinsic;
21
33
  type Parameter = {
22
34
  AllowedValues?: string[];
@@ -112,4 +124,4 @@ declare const findAndReadCloudFormationTemplate: ({ templatePath: defaultTemplat
112
124
  options?: unknown;
113
125
  }) => Promise<CloudFormationTemplate>;
114
126
 
115
- 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 };
127
+ 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 CHANGED
@@ -16,7 +16,19 @@ type CloudFormationSelect = {
16
16
  type CloudFormationSplit = {
17
17
  'Fn::Split': [string, string];
18
18
  };
19
- type CloudFormationIntrinsic = CloudFormationRef | CloudFormationGetAtt | CloudFormationJoin | CloudFormationSub | CloudFormationSelect | CloudFormationSplit;
19
+ type CloudFormationImportValue = {
20
+ 'Fn::ImportValue': string | CloudFormationSub;
21
+ };
22
+ /**
23
+ * Returns an `Fn::ImportValue` intrinsic that resolves the export name from
24
+ * a CloudFormation parameter via `Fn::Sub`.
25
+ *
26
+ * @example
27
+ * importValueFromParameter('MyStackExportName')
28
+ * // => { 'Fn::ImportValue': { 'Fn::Sub': '${MyStackExportName}' } }
29
+ */
30
+ declare const importValueFromParameter: (parameterName: string) => CloudFormationImportValue;
31
+ type CloudFormationIntrinsic = CloudFormationRef | CloudFormationGetAtt | CloudFormationJoin | CloudFormationSub | CloudFormationSelect | CloudFormationSplit | CloudFormationImportValue;
20
32
  type CloudFormationValue<T = any> = T | CloudFormationIntrinsic;
21
33
  type Parameter = {
22
34
  AllowedValues?: string[];
@@ -112,4 +124,4 @@ declare const findAndReadCloudFormationTemplate: ({ templatePath: defaultTemplat
112
124
  options?: unknown;
113
125
  }) => Promise<CloudFormationTemplate>;
114
126
 
115
- 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 };
127
+ 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 CHANGED
@@ -42,7 +42,8 @@ var __toCommonJS = mod => __copyProps(__defProp({}, "__esModule", {
42
42
  // src/index.ts
43
43
  var index_exports = {};
44
44
  __export(index_exports, {
45
- findAndReadCloudFormationTemplate: () => findAndReadCloudFormationTemplate
45
+ findAndReadCloudFormationTemplate: () => findAndReadCloudFormationTemplate,
46
+ importValueFromParameter: () => importValueFromParameter
46
47
  });
47
48
  module.exports = __toCommonJS(index_exports);
48
49
 
@@ -237,7 +238,17 @@ var findAndReadCloudFormationTemplate = /* @__PURE__ */__name(async ({
237
238
  options
238
239
  });
239
240
  }, "findAndReadCloudFormationTemplate");
241
+
242
+ // src/CloudFormationTemplate.ts
243
+ var importValueFromParameter = /* @__PURE__ */__name(parameterName => {
244
+ return {
245
+ "Fn::ImportValue": {
246
+ "Fn::Sub": `\${${parameterName}}`
247
+ }
248
+ };
249
+ }, "importValueFromParameter");
240
250
  // Annotate the CommonJS export names for ESM import in node:
241
251
  0 && (module.exports = {
242
- findAndReadCloudFormationTemplate
252
+ findAndReadCloudFormationTemplate,
253
+ importValueFromParameter
243
254
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ttoss/cloudformation",
3
- "version": "0.11.10",
3
+ "version": "0.12.1",
4
4
  "description": "CloudFormation utils.",
5
5
  "license": "MIT",
6
6
  "author": "ttoss",
@@ -24,16 +24,16 @@
24
24
  ],
25
25
  "dependencies": {
26
26
  "js-yaml": "^4.1.1",
27
- "@ttoss/read-config-file": "^2.0.20"
27
+ "@ttoss/read-config-file": "^2.1.0"
28
28
  },
29
29
  "devDependencies": {
30
30
  "@types/jest": "^30.0.0",
31
31
  "@types/js-yaml": "^4.0.9",
32
- "@types/node": "^22.19.0",
32
+ "@types/node": "^24.10.13",
33
33
  "jest": "^30.2.0",
34
34
  "tsup": "^8.5.1",
35
- "@ttoss/config": "^1.35.12",
36
- "@ttoss/test-utils": "^4.0.3"
35
+ "@ttoss/config": "^1.36.0",
36
+ "@ttoss/test-utils": "^4.1.0"
37
37
  },
38
38
  "keywords": [],
39
39
  "publishConfig": {