@horietakehiro/aws-cdk-utul 0.35.6 → 0.40.1

package/README.md

@@ -74,12 +74,40 @@ template.hasOutput("VPCARN", {
 
 ---
 
+`ExtraMatch.{arrayWith,arrayLike,objectLike,objectEquals,not,exact}` are same method as those of `Match` class but additionally provide type hints. These are useful to type-safely use `Matcher`
+
+![](./docs/ExtraMatch-type-hints-right.png)
+
+![](./docs/ExtraMatch-type-hints-wrong.png)
+
+---
+
 ## Install
 
 ```bash
 npm install @horietakehiro/aws-cdk-utul
 ```
 
+By default, you may feel difficult to use this library because import path is too long for type hits to fit in IDE dialog box like below.
+
+![](./docs//default-tsconfig.png)
+
+So I recommend that you add module alias settings in your `tsconfig.json` file like below.
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/cfn-types": ["node_modules/@horietakehiro/aws-cdk-utul/lib/types/cfn-resource-types"],
+      "@/cfn-types/*": ["node_modules/@horietakehiro/aws-cdk-utul/lib/types/cfn-resource-types/*"]
+    }
+  }
+}
+```
+
+![](./docs/customized-tsconfig.png)
+
 ---
 
 ## Release policy

package/lib/assertions.d.ts

@@ -1,4 +1,4 @@
-import { Template, Match, Matcher } from "aws-cdk-lib/assertions";
+import { Template, Matcher } from "aws-cdk-lib/assertions";
 import { Condition, InputResource, Mapping, OutputResource, InputParamter, OutputParameter, ReturnValue, InputOutput, OutputOutput, InputResourceWithoutType, IAMPolicyDocument, AlsoMatcher, TypedMatcher } from "./typed-resource";
 /**
  * almost same class as `Template` class at "aws-cdk-lib/assertions", but you can use this with proper type definitions
@@ -141,7 +141,7 @@ export interface JoinProps {
 /**
  * provides some syntax sugars for `Match` class at `aws-cdk-lib/assertions`
  */
-export declare class ExtraMatch extends Match {
+export declare class ExtraMatch {
     /**
      * same function as `Match.objectEquals({ Ref: logicalId })`
      * @param logicalId
@@ -161,16 +161,6 @@ export declare class ExtraMatch extends Match {
      * @returns
      */
     static getAttArn(logicalId: string): Matcher;
-    static arrayWith<T extends any[]>(pattern: AlsoMatcher<T>): TypedMatcher<T>;
-    static arrayEquals<T extends any[]>(pattern: AlsoMatcher<T>): TypedMatcher<T>;
-    static objectLike<T extends {
-        [key: string]: any;
-    }>(pattern: AlsoMatcher<T>): TypedMatcher<T>;
-    static objectEquals<T extends {
-        [key: string]: any;
-    }>(pattern: AlsoMatcher<T>): TypedMatcher<T>;
-    static not<T>(pattern: AlsoMatcher<T>): TypedMatcher<T>;
-    static exact<T>(pattern: AlsoMatcher<T>): TypedMatcher<T>;
     /**
      * same function as below:
      *
@@ -183,5 +173,222 @@ export declare class ExtraMatch extends Match {
      * @returns
      */
     static joinLike(props: JoinProps): Matcher;
+    /**
+     You can define Matcher for IAM Policy Document with type hints.
+     ```js
+      template.hasResource(
+        AWS_IAM_ROLE({
+          Properties: {
+            AssumeRolePolicyDocument: ExtraMatch.iamPolicyLike({
+              Statement: [
+                {
+                  Principal: { Service: "ec2.amazonaws.com" },
+                },
+              ],
+            }),
+          },
+        })
+      );
+     ```
+     * @param doc
+     * @returns
+     */
     static iamPolicyLike(doc: AlsoMatcher<IAMPolicyDocument>): Matcher;
+    /**
+     Same method as `Match.arrayWith` but provides type hints and validate type match
+     ```js
+      // this is a right code
+      template.hasResource(
+        AWS_EC2_EIP({
+          Properties: {
+            Tags: ExtraMatch.arrayWith<Tag[]>([
+              {
+                Key: "key2",
+                Value: "val2",
+              },
+            ]),
+          },
+        })
+      );
+      // this is a wrong code(type mismatch will be detected and ts-error will be raised)
+      template.hasResource(
+        AWS_EC2_EIP({
+          Properties: {
+            Tags: ExtraMatch.arrayWith<string[]>([
+              "hoge", "fuga"
+            ]),
+          },
+        })
+      );
+     ```
+     * @param pattern
+     * @returns
+     */
+    static arrayWith<T extends any[]>(pattern: AlsoMatcher<T>): TypedMatcher<T>;
+    /**
+     * Same method as `Match.arrayEquals` but provides type hints and validate type match
+     ```js
+      // this is a right code
+      template.hasResource(
+        AWS_EC2_EIP({
+          Properties: {
+            Tags: ExtraMatch.arrayEquals<Tag[]>([
+              {
+                Key: "key1",
+                Value: "val1",
+              },
+              {
+                Key: "key2",
+                Value: "val2",
+              },
+            ]),
+          },
+        })
+      );
+      // this is a wrong code(type mismatch will be detected and ts-error will be raised)
+      template.hasResource(
+        AWS_EC2_EIP({
+          Properties: {
+            Tags: ExtraMatch.arrayEquals<Tag[]>([
+              {
+                Key: "key1",
+                Value: "val1",
+              },
+              {
+                Key: 100,
+                Value: 200,
+              },
+            ]),
+          },
+        })
+      );
+     ```
+     * @param pattern
+     * @returns
+     */
+    static arrayEquals<T extends any[]>(pattern: AlsoMatcher<T>): TypedMatcher<T>;
+    /**
+     * Same method as `Match.objectLike` but provides type hints and validate type match
+     ```js
+     // this is a right code
+      template.hasResource(
+        AWS_EC2_INSTANCE({
+          Properties: {
+            BlockDeviceMappings: [
+              {
+                DeviceName: "test",
+                Ebs: ExtraMatch.objectLike<Ebs>({
+                  VolumeSize: 10,
+                }),
+              },
+            ],
+          },
+        })
+      );
+      // this is a wrong code(type mismatch will be detected and ts-error will be raised)
+      template.hasResource(
+        AWS_EC2_INSTANCE({
+          Properties: {
+            BlockDeviceMappings: [
+              {
+                DeviceName: "test",
+                Ebs: ExtraMatch.objectLike<Ebs>({
+                  VolumeSize: "10",
+                }),
+              },
+            ],
+          },
+        })
+      );
+     * @param pattern
+     * @returns
+     */
+    static objectLike<T extends {
+        [key: string]: any;
+    }>(pattern: AlsoMatcher<T>): TypedMatcher<T>;
+    /**
+     * Same method as `Match.objectEquals` but provides type hints and validate type match
+     ```js
+     // this is a right code
+      template.hasResource(
+        AWS_EC2_EIP({
+          Properties: {
+            // You can nest TypedMatcher(use TypedMatcher inside TypedMatcher)
+            Tags: ExtraMatch.arrayWith<Tag[]>([
+              ExtraMatch.objectEquals<Tag>({
+                Key: "key1",
+                Value: "val1",
+              }),
+            ]),
+          },
+        })
+      );
+      // this is a wrong code(type mismatch will be detected and ts-error will be raised)
+      template.hasResource(
+        AWS_EC2_EIP({
+          Properties: {
+            Tags: ExtraMatch.arrayWith<Tag[]>([
+              ExtraMatch.objectEquals<Tag>({
+                Key: "key1",
+                Value: 100,
+              }),
+            ]),
+          },
+        })
+      );
+     * @param pattern
+     * @returns
+     */
+    static objectEquals<T extends {
+        [key: string]: any;
+    }>(pattern: AlsoMatcher<T>): TypedMatcher<T>;
+    /**
+     * Same method as `Match.not` but provides type hints and validate type match
+     ```js
+      // this is a right code
+      template.hasResource(
+        AWS_EC2_INSTANCE({
+          Properties: {
+            ImageId: ExtraMatch.not("ami-12345"),
+          },
+        })
+      );
+      // this is a wrong code(type mismatch will be detected and ts-error will be raised)
+      template.hasResource(
+        AWS_EC2_INSTANCE({
+          Properties: {
+            ImageId: ExtraMatch.not(100),
+          },
+        })
+      );
+     ```
+     * Same method as `Match.not` but provides type hints and validate type match
+     * @param pattern
+     * @returns
+     */
+    static not<T>(pattern: AlsoMatcher<T extends never ? never : T>): TypedMatcher<T>;
+    /**
+     * Same method as `Match.exact` but provides type hints and validate type match
+     ```js
+      // this is a right code
+      template.hasResource(
+        AWS_EC2_INSTANCE({
+          Properties: {
+            InstanceType: ExtraMatch.exact("t2.micro"),
+          },
+        })
+      );
+      // this is a wrong code(type mismatch will be detected and ts-error will be raised)
+      template.hasResource(
+        AWS_EC2_INSTANCE({
+          Properties: {
+            InstanceType: ExtraMatch.exact(false),
+          },
+        })
+      );
+     ```
+     * @param pattern
+     * @returns
+     */
+    static exact<T>(pattern: AlsoMatcher<T extends never ? never : T>): TypedMatcher<T>;
 }