chore(mixins-preview): implement Mixins RFC

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 { UnscopedValidationError, 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)) {
+        mixin.applyTo(construct);
+        const errors = mixin.validate?.(construct) ?? [];
+        if (errors.length > 0) {
+          throw new ValidationError(`Mixin validation failed: ${errors.join(', ')}`, 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)) {
+        mixin.applyTo(construct);
+        const errors = mixin.validate?.(construct) ?? [];
+        if (errors.length > 0) {
+          throw new ValidationError(`Mixin validation failed: ${errors.join(', ')}`, construct);
+        }
+        applied = true;
+      }
+    }
+    if (!applied) {
+      throw new UnscopedValidationError(`Mixin ${mixin.constructor.name} could not be applied to any constructs`);
+    }
+    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,51 @@
+import type { IConstruct } from 'constructs';
+import type { ConstructSelector } from './selectors';
+import { MixinApplicator } from './applicator';
+
+/**
+ * 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 {
+  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,117 @@
+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[] {
+    const result: IConstruct[] = [];
+    const visit = (node: IConstruct) => {
+      result.push(node);
+      for (const child of node.node.children) {
+        visit(child);
+      }
+    };
+    visit(scope);
+    return result;
+  }
+}
+
+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;
+}