chore(mixins-preview): implement Mixins RFC (#36013)

### Reason for this change

This PR implements the foundational infrastructure for the CDK Mixins framework, introducing a composable abstraction system for applying functionality to CDK constructs. It is based on the _current_ state of the [RFC](aws/aws-cdk-rfcs#824).

While the RFC is not yet approved and finalized, this PR aims to implement it including all its flaws so we can move forward with other implementing depending on this. We will update the package as the RFC evolves.

### Description of changes

**Core Framework:**
- Implemented `IMixin` interface and `Mixin` base class for creating composable abstractions
- Added `Mixins.of()` API for applying mixins to constructs with `apply()` and `mustApply()` methods
- Created `ConstructSelector` for filtering constructs by type, ID pattern, or CloudFormation resource type
- Added comprehensive error handling and validation support
- Added `.with()` augmentation to constructs for fluent mixin application

**Testing:**
- Comprehensive unit tests for core framework, selectors, and all built-in mixins
- Integration tests demonstrating real-world usage patterns
- Property manipulation utility tests including edge cases

**Documentation:**
- Updated README with usage examples, API reference, and best practices
- Added Rosetta fixture for documentation code examples

### Description of how you validated changes

- All new code is covered by unit tests
- Integration tests validate end-to-end functionality
- Rosetta fixture ensures documentation examples are valid

### 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

@@ -37,6 +37,22 @@ Mixins.of(bucket)
   .apply(new AutoDeleteObjects());
 ```
 
+### Fluent Syntax with `.with()`
+
+For convenience, you can use the `.with()` method for a more fluent syntax:
+
+```typescript
+import '@aws-cdk/mixins-preview/with';
+
+const bucket = new s3.CfnBucket(scope, "MyBucket")
+  .with(new EnableVersioning())
+  .with(new AutoDeleteObjects());
+```
+
+The `.with()` method is available after importing `@aws-cdk/mixins-preview/with`, which augments all constructs with this method. It provides the same functionality as `Mixins.of().apply()` but with a more chainable API.
+
+> **Note**: The `.with()` fluent syntax is only available in JavaScript and TypeScript. Other jsii languages (Python, Java, C#, and Go) should use the `Mixins.of(...).mustApply()` syntax instead. The import requirement is temporary during the preview phase. Once the API is stable, the `.with()` method will be available by default on all constructs and in all languages.
+
 ## Creating Custom Mixins
 
 Mixins are simple classes that implement the `IMixin` interface:

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

@@ -0,0 +1,59 @@
+import type { IConstruct } from 'constructs';
+import { ValidationError } from 'aws-cdk-lib/core';
+import type { IMixin } from './mixins';
+import { ConstructSelector } from './selectors';
+
+/**
+ * Applies mixins to constructs.
+ */
+export class MixinApplicator {
+  private readonly scope: IConstruct;
+  private readonly selector: ConstructSelector;
+
+  constructor(
+    scope: IConstruct,
+    selector: ConstructSelector = ConstructSelector.all(),
+  ) {
+    this.scope = scope;
+    this.selector = selector;
+  }
+
+  /**
+   * Applies a mixin to selected constructs.
+   */
+  apply(mixin: 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);
+        }
+        mixin.applyTo(construct);
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Applies a mixin and requires that it be applied to at least one construct.
+   */
+  mustApply(mixin: 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);
+        }
+        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/index.ts

@@ -0,0 +1,4 @@
+// Re-export all core functionality from separate modules
+export * from './mixins';
+export * from './selectors';
+export * from './applicator';

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

@@ -0,0 +1,68 @@
+import type { IConstruct } from 'constructs';
+import type { ConstructSelector } from './selectors';
+import { MixinApplicator } from './applicator';
+
+// this will change when we update the interface to deliberately break compatibility checks
+const MIXIN_SYMBOL = Symbol.for('@aws-cdk/mixins-preview.Mixin.pre1');
+
+/**
+ * Main entry point for applying mixins.
+ */
+export class Mixins {
+  /**
+   * Creates a MixinApplicator for the given scope.
+   */
+  static of(scope: IConstruct, selector?: ConstructSelector): MixinApplicator {
+    return new MixinApplicator(scope, selector);
+  }
+}
+
+/**
+ * A mixin is a reusable piece of functionality that can be applied to constructs
+ * to add behavior, properties, or modify existing functionality without inheritance.
+ */
+export interface IMixin {
+  /**
+   * Determines whether this mixin can be applied to the given construct.
+   */
+  supports(construct: IConstruct): boolean;
+
+  /**
+   * Validates the construct before applying the mixin.
+   */
+  validate?(construct: IConstruct): string[];
+
+  /**
+   * Applies the mixin functionality to the target construct.
+   */
+  applyTo(construct: IConstruct): IConstruct;
+}
+
+/**
+ * Abstract base class for mixins that provides default implementations.
+ */
+export abstract class Mixin implements IMixin {
+  /**
+   * Checks if `x` is a Mixin.
+   *
+   * @param x Any object
+   * @returns true if `x` is an object created from a class which extends `Mixin`.
+   */
+  static isMixin(x: any): x is Mixin {
+    return x != null && typeof x === 'object' && MIXIN_SYMBOL in x;
+  }
+
+  constructor() {
+    Object.defineProperty(this, MIXIN_SYMBOL, { value: true });
+  }
+
+  public supports(_construct: IConstruct): boolean {
+    return true;
+  }
+
+  public validate(_construct: IConstruct): string[] {
+    return [];
+  }
+
+  abstract applyTo(construct: IConstruct): IConstruct;
+}

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

@@ -0,0 +1,109 @@
+import type { IConstruct } from 'constructs';
+import { CfnResource } from 'aws-cdk-lib/core';
+
+/**
+ * Selects constructs from a construct tree based on various criteria.
+ */
+export abstract class ConstructSelector {
+  /**
+   * Selects all constructs in the tree.
+   */
+  static all(): ConstructSelector {
+    return new AllConstructsSelector();
+  }
+
+  /**
+   * Selects CfnResource constructs or the default CfnResource child.
+   */
+  static cfnResource(): ConstructSelector {
+    return new CfnResourceSelector();
+  }
+
+  /**
+   * Selects constructs of a specific type.
+   */
+  static resourcesOfType(type: string | any): ConstructSelector {
+    return new ResourceTypeSelector(type);
+  }
+
+  /**
+   * Selects constructs whose IDs match a pattern.
+   */
+  static byId(pattern: any): ConstructSelector {
+    return new IdPatternSelector(pattern);
+  }
+
+  /**
+   * Selects constructs from the given scope based on the selector's criteria.
+   */
+  abstract select(scope: IConstruct): IConstruct[];
+}
+
+class AllConstructsSelector extends ConstructSelector {
+  select(scope: IConstruct): IConstruct[] {
+    return scope.node.findAll();
+  }
+}
+
+class CfnResourceSelector extends ConstructSelector {
+  select(scope: IConstruct): IConstruct[] {
+    if (CfnResource.isCfnResource(scope)) {
+      return [scope];
+    }
+    const defaultChild = scope.node.defaultChild;
+    if (CfnResource.isCfnResource(defaultChild)) {
+      return [defaultChild];
+    }
+    return [];
+  }
+}
+
+class ResourceTypeSelector extends ConstructSelector {
+  constructor(private readonly type: string | any) {
+    super();
+  }
+
+  select(scope: IConstruct): IConstruct[] {
+    const result: IConstruct[] = [];
+    const visit = (node: IConstruct) => {
+      if (typeof this.type === 'string') {
+        if (CfnResource.isCfnResource(node) && node.cfnResourceType === this.type) {
+          result.push(node);
+        }
+      } else if ('isCfnResource' in this.type && 'CFN_RESOURCE_TYPE_NAME' in this.type) {
+        if (CfnResource.isCfnResource(node) && node.cfnResourceType === this.type.CFN_RESOURCE_TYPE_NAME) {
+          result.push(node);
+        }
+      } else {
+        if (node instanceof this.type) {
+          result.push(node);
+        }
+      }
+      for (const child of node.node.children) {
+        visit(child);
+      }
+    };
+    visit(scope);
+    return result;
+  }
+}
+
+class IdPatternSelector extends ConstructSelector {
+  constructor(private readonly pattern: any) {
+    super();
+  }
+
+  select(scope: IConstruct): IConstruct[] {
+    const result: IConstruct[] = [];
+    const visit = (node: IConstruct) => {
+      if (this.pattern && typeof this.pattern.test === 'function' && this.pattern.test(node.node.id)) {
+        result.push(node);
+      }
+      for (const child of node.node.children) {
+        visit(child);
+      }
+    };
+    visit(scope);
+    return result;
+  }
+}

packages/@aws-cdk/mixins-preview/lib/custom-resource-handlers/aws-s3/auto-delete-objects-provider.ts

@@ -0,0 +1,26 @@
+import * as path from 'path';
+import type { Construct } from 'constructs';
+import type { CustomResourceProviderOptions } from 'aws-cdk-lib/core';
+import { Stack, CustomResourceProviderBase, determineLatestNodeRuntimeName } from 'aws-cdk-lib/core';
+
+export class AutoDeleteObjectsProvider extends CustomResourceProviderBase {
+  public static getOrCreate(scope: Construct, uniqueid: string, props?: CustomResourceProviderOptions): string {
+    return this.getOrCreateProvider(scope, uniqueid, props).serviceToken;
+  }
+
+  public static getOrCreateProvider(scope: Construct, uniqueid: string, props?: CustomResourceProviderOptions): AutoDeleteObjectsProvider {
+    const id = `${uniqueid}CustomResourceProvider`;
+    const stack = Stack.of(scope);
+    const existing = stack.node.tryFindChild(id) as AutoDeleteObjectsProvider;
+    return existing ?? new AutoDeleteObjectsProvider(stack, id, props);
+  }
+
+  private constructor(scope: Construct, id: string, props?: CustomResourceProviderOptions) {
+    super(scope, id, {
+      ...props,
+      codeDirectory: path.join(__dirname, '..', 'dist', 'aws-s3', 'auto-delete-objects-handler'),
+      runtimeName: determineLatestNodeRuntimeName(scope),
+    });
+    this.node.addMetadata('aws:cdk:is-custom-resource-handler-customResourceProvider', true);
+  }
+}

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

@@ -1 +1,2 @@
-export * from './mixins';
+export * as core from './core';
+export * as mixins from './mixins';

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

@@ -1,73 +1 @@
-import type { IConstruct } from 'constructs';
-
-/**
- * A mixin is a reusable piece of functionality that can be applied to constructs
- * to add behavior, properties, or modify existing functionality without inheritance.
- *
- * Mixins follow a three-phase pattern:
- * 1. Check if the mixin supports the target construct (supports)
- * 2. Optionally validate the construct before applying (validate)
- * 3. Apply the mixin functionality to the construct (applyTo)
- */
-export interface IMixin {
-  /**
-   * Determines whether this mixin can be applied to the given construct.
-   *
-   * This method should perform type checking and compatibility validation
-   * to ensure the mixin can safely operate on the construct.
-   *
-   * @param construct - The construct to check for compatibility
-   * @returns true if the mixin supports this construct type, false otherwise
-   */
-  supports(construct: IConstruct): boolean;
-
-  /**
-   * Validates the construct before applying the mixin.
-   *
-   * This optional method allows the mixin to perform additional validation
-   * beyond basic type compatibility. It can check for required properties,
-   * configuration constraints, or other preconditions.
-   *
-   * @param construct - The construct to validate
-   * @returns An array of validation error messages, or empty array if valid
-   */
-  validate?(construct: IConstruct): string[];
-
-  /**
-   * Applies the mixin functionality to the target construct.
-   *
-   * This method performs the actual work of the mixin, such as:
-   * - Adding new properties or methods
-   * - Modifying existing behavior
-   * - Setting up additional resources or configurations
-   * - Establishing relationships with other constructs
-   *
-   * @param construct - The construct to apply the mixin to
-   * @returns The modified construct (may be the same instance or a wrapper)
-   */
-  applyTo(construct: IConstruct): IConstruct;
-}
-
-/**
- * Abstract base class for mixins that provides default implementations
- * and simplifies mixin creation.
- */
-export abstract class Mixin implements IMixin {
-  /**
-   * Default implementation that supports any construct.
-   * Override this method to add type-specific support logic.
-   */
-  public supports(_construct: IConstruct): boolean {
-    return true;
-  }
-
-  /**
-   * Default validation implementation that returns no errors.
-   * Override this method to add custom validation logic.
-   */
-  public validate(_construct: IConstruct): string[] {
-    return [];
-  }
-
-  abstract applyTo(construct: IConstruct): IConstruct;
-}
+export * from './property-mixins';

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

@@ -0,0 +1,25 @@
+/**
+ * Strategy for handling nested properties in L1 property mixins
+ */
+export enum PropertyMergeStrategy {
+  /**
+   * Override all properties
+   */
+  OVERRIDE = 'override',
+  /**
+   * Deep merge nested objects, override primitives and arrays
+   */
+  MERGE = 'merge',
+}
+
+/**
+ * Options for applying CfnProperty mixins
+ */
+export interface CfnPropertyMixinOptions {
+  /**
+   * Strategy for merging nested properties
+   *
+   * @default - PropertyMergeStrategy.MERGE
+   */
+  readonly strategy?: PropertyMergeStrategy;
+}