feat(mixins-preview): developer preview of CDK Mixins

Author: mrgrain

packages/@aws-cdk/mixins-preview/README.md

@@ -55,11 +55,11 @@ The `.with()` method is available after importing `@aws-cdk/mixins-preview/with`
 
 ## Creating Custom Mixins
 
-Mixins are simple classes that implement the `IMixin` interface:
+Mixins are simple classes that implement the `IMixin` interface (usually by extending the abstract `Mixin` class:
 
 ```typescript
 // Simple mixin that enables versioning
-class CustomVersioningMixin implements IMixin {
+class CustomVersioningMixin extends Mixin implements IMixin {
   supports(construct: any): boolean {
     return construct instanceof s3.CfnBucket;
   }
@@ -131,7 +131,7 @@ For every CloudFormation resource, CDK Mixins automatically generates type-safe
 
 ```typescript
 import '@aws-cdk/mixins-preview/with';
-import { CfnBucketPropsMixin } from '@aws-cdk/mixins-preview/aws-s3/mixins';
+
 
 const bucket = new s3.Bucket(scope, "Bucket")
   .with(new CfnBucketPropsMixin({
@@ -146,6 +146,8 @@ const bucket = new s3.Bucket(scope, "Bucket")
 Property mixins support two merge strategies:
 
 ```typescript
+declare const bucket: s3.CfnBucket;
+
 // MERGE (default): Deep merges properties with existing values
 Mixins.of(bucket).apply(new CfnBucketPropsMixin(
   { versioningConfiguration: { status: "Enabled" } },
@@ -155,16 +157,16 @@ Mixins.of(bucket).apply(new CfnBucketPropsMixin(
 // OVERWRITE: Replaces existing property values
 Mixins.of(bucket).apply(new CfnBucketPropsMixin(
   { versioningConfiguration: { status: "Enabled" } },
-  { strategy: PropertyMergeStrategy.OVERWRITE }
+  { strategy: PropertyMergeStrategy.OVERRIDE }
 ));
 ```
 
 Property mixins are available for all AWS services:
 
 ```typescript
-import { CfnLogGroupMixin } from '@aws-cdk/mixins-preview/aws-logs/mixins';
-import { CfnFunctionMixin } from '@aws-cdk/mixins-preview/aws-lambda/mixins';
-import { CfnTableMixin } from '@aws-cdk/mixins-preview/aws-dynamodb/mixins';
+import { CfnLogGroupPropsMixin } from '@aws-cdk/mixins-preview/aws_logs/mixins';
+import { CfnFunctionPropsMixin } from '@aws-cdk/mixins-preview/aws_lambda/mixins';
+import { CfnTablePropsMixin } from '@aws-cdk/mixins-preview/aws_dynamodb/mixins';
 ```
 
 ## Error Handling

packages/@aws-cdk/mixins-preview/jest.config.js

@@ -3,7 +3,9 @@ const baseConfig = require('@aws-cdk/cdk-build-tools/config/jest.config');
 /** @type {import('ts-jest').JestConfigWithTsJest} */
 module.exports = {
   ...baseConfig,
-  transform: {
-    '^.+\\.tsx?$': ['ts-jest'],
-  },
+  coveragePathIgnorePatterns: [
+    'scripts',
+    '\\.generated\\.[jt]s$',
+    '.warnings.jsii.js$'
+  ],
 };

packages/@aws-cdk/mixins-preview/lib/core/applicator.ts

@@ -21,39 +21,31 @@ export class MixinApplicator {
   /**
    * Applies a mixin to selected constructs.
    */
-  apply(mixin: IMixin): this {
+  apply(...mixins: IMixin[]): this {
     const constructs = this.selector.select(this.scope);
     for (const construct of constructs) {
-      if (mixin.supports(construct)) {
-        const errors = mixin.validate?.(construct) ?? [];
-        if (errors.length > 0) {
-          throw new ValidationError(`Mixin validation failed: ${errors.join(', ')}`, this.scope);
+      for (const mixin of mixins) {
+        if (mixin.supports(construct)) {
+          mixin.applyTo(construct);
         }
-        mixin.applyTo(construct);
       }
     }
     return this;
   }
 
   /**
-   * Applies a mixin and requires that it be applied to at least one construct.
+   * Applies a mixin and requires that it be applied to all constructs.
    */
-  mustApply(mixin: IMixin): this {
+  mustApply(...mixins: IMixin[]): this {
     const constructs = this.selector.select(this.scope);
-    let applied = false;
     for (const construct of constructs) {
-      if (mixin.supports(construct)) {
-        const errors = mixin.validate?.(construct) ?? [];
-        if (errors.length > 0) {
-          throw new ValidationError(`Mixin validation failed: ${errors.join(', ')}`, construct);
+      for (const mixin of mixins) {
+        if (!mixin.supports(construct)) {
+          throw new ValidationError(`Mixin ${mixin.constructor.name} could not be applied to ${construct.constructor.name} but was requested to.`, this.scope);
         }
         mixin.applyTo(construct);
-        applied = true;
       }
     }
-    if (!applied) {
-      throw new ValidationError(`Mixin ${mixin.constructor.name} could not be applied to any constructs`, this.scope);
-    }
     return this;
   }
 }

packages/@aws-cdk/mixins-preview/lib/core/mixins.ts

@@ -27,11 +27,6 @@ export interface IMixin {
    */
   supports(construct: IConstruct): boolean;
 
-  /**
-   * Validates the construct before applying the mixin.
-   */
-  validate?(construct: IConstruct): string[];
-
   /**
    * Applies the mixin functionality to the target construct.
    */
@@ -60,9 +55,5 @@ export abstract class Mixin implements IMixin {
     return true;
   }
 
-  public validate(_construct: IConstruct): string[] {
-    return [];
-  }
-
   abstract applyTo(construct: IConstruct): IConstruct;
 }

packages/@aws-cdk/mixins-preview/lib/with.ts

@@ -5,16 +5,16 @@ import { Mixins, ConstructSelector } from './core';
 
 declare module 'constructs' {
   interface IConstruct {
-    with(mixin: IMixin): this;
+    with(...mixin: IMixin[]): this;
   }
 
   interface Construct {
-    with(mixin: IMixin): this;
+    with(...mixin: IMixin[]): this;
   }
 }
 
 // Hack the prototype to add .with() method
-(Construct.prototype as any).with = function(this: IConstruct, mixin: IMixin): IConstruct {
-  Mixins.of(this, ConstructSelector.cfnResource()).mustApply(mixin);
+(Construct.prototype as any).with = function(this: IConstruct, ...mixin: IMixin[]): IConstruct {
+  Mixins.of(this, ConstructSelector.cfnResource()).mustApply(...mixin);
   return this;
 };