feat: Introduce mixins for migratable constructs

[akash1810]

What does this change?

Currently, to define a migratable construct you need to:

• ensure the props implement the correct interfaces
• call GuMigratingResource.setLogicalId in the constructor

This is quite a lot and if there are no tests against the latter, we're just hoping to spot mistakes at review time.

Enter mixins!

Along with traditional OO hierarchies, another popular way of building up classes from reusable components is to build them by combining simpler partial classes. You may be familiar with the idea of mixins or traits for languages like Scala, and the pattern has also reached some popularity in the JavaScript community.

In this change, we create two mixins:

1. GuMigratableConstruct
2. GuStatefulMigratableConstruct

These mixins greatly simplify the process of defining a migratable construct.

For example, for a stateful construct, we go from:

class GuMyConstruct extends AwsConstruct implements GuStatefulConstruct {
  isStatefulConstruct: true;

  constructor(scope: GuStack, id: string, props: GuMyConstructProps) {
    super(scope, id, props);

    this.isStatefulConstruct = true;

    GuMigratingResource.setLogicalId(
      this,
      {
        migratedFromCloudFormation: scope.migratedFromCloudFormation
      },
      {
        existingLogicalId: props.existingLogicalId
      }
    );
  }
}

To:

class GuMyConstruct extends GuStatefulMigratableConstruct(AwsConstruct) { }

There is a reduction of boilerplate and less need to explicitly test the migration logic at each individual construct level. Thus less reliance on code review catching mistakes.

This should also make the adoption (#400) of the revised logicalId logic (#364) much simpler.

Lastly, to demonstrate the mixin, the only construct using the new logic (GuCertificate) has been refactored. This is in its own commit, happy to make it it's own PR for true separation of concerns.

Does this change require changes to existing projects or CDK CLI?

No.

How to test

New tests added. Look at CI to see them and existing tests pass.

How can we measure success?

• A simpler API to follow
• Less need to explicitly test the migration logic at each individual construct level

Have we considered potential risks?

Mixins can definitely become complicated. They can also be quite simple and useful and bring a sprinkling of Scala to a TypeScript codebase!

The risk is the codebase is more complicated to understand.

The movement of the GuStatefulConstruct interface from constructs/core/migrating to utils/mixin might make cause a bit of rebasing pain for open PRs.

Having a specific types directory might help here? Something like this:

src
├── constructs
│   └── core
│       └── stack.ts
└── types
    └── constructs
        └── core
            └── stack.ts

[jacobwinch]

Lastly, to demonstrate the mixin, the only construct using the new logic (GuCertificate) has been refactored. This is in its own commit, happy to make it it's own PR for true separation of concerns.

It's useful to have one example in this PR; it helped me to understand the change properly!

[jacobwinch]

Looks great 💯

Although the code is a little more complex, I think it's definitely worthwhile as this approach:

just hoping to spot mistakes at review time.

would definitely have tripped us up at some point!

[github-actions]

🎉 This PR is included in version 8.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀