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

### Reason for this change

aws/aws-cdk-rfcs#824

CDK Mixins are composable, reusable abstractions that can be applied to any construct (L1, L2 or custom).
They are breaking down the traditional barriers between construct levels,
allowing customers to mix and match sophisticated features without being locked into specific implementations.

### Description of changes

This PR makes the package public so it can be released. It also implements some small changes based on RFC feedback.
Main functional changes are:
- Removing `validate()` in favor of just throwing errors
- Making `.with()`, `.apply()` and `.mustApply()` variadic

### Describe any new or updated permissions being added

n/a

### Description of how you validated changes

Unit tests.

### Checklist
- [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

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;
 };