feat(core): PropertyMergeStrategy now supports array merge strategies

[mrgrain]

Issue # (if applicable)

N/A

Reason for this change

The combine merge strategy always replaced arrays wholesale. There was no way to append, prepend, or selectively update array elements when applying property mixins — a common need for tags, rules, and other list-typed CloudFormation properties.

Description of changes

PropertyMergeStrategy.combine() now accepts an optional arrays option powered by a new ArrayMergeStrategy class. Available strategies are:

• replace — replace the target array entirely (default, preserves existing behavior)
• append — add source elements after target elements
• prepend — add source elements before target elements
• replaceByIndex — overwrite target elements positionally from the front
• replaceByKey(key) — match object elements by a shared key field, replacing matches and appending new ones

Array elements are never deep-merged regardless of strategy.

Additionally, CfnPropsMixin gains a static of<T>() factory to avoid circular imports when referencing L1 classes across module boundaries.

Describe any new or updated permissions being added

N/A

Description of how you validated changes

Unit tests for all array merge strategies and the CfnPropsMixin.of() factory. All existing tests continue to pass.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

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

[github-actions]

👋 It looks like your PR description follows the template but is missing a valid issue number in the first section.

PRs without a linked issue will receive lower priority for review and merging. Please update the description to include a reference like Closes #123. If no existing issue matches your change, create one first.

[aws-cdk-automation]

(This review is outdated)

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-05-12 14:42 UTC · Rule: default-squash
• ✅ Checks passed · in-place
• ✅ Merged — 2026-05-12 15:17 UTC · at 4907b2bb973dfa86927a763347b00b82aaf21f15 · squash

This pull request spent 35 minutes 37 seconds in the queue, including 1 hour 6 minutes 42 seconds running CI.

Required conditions to merge

• #approved-reviews-by >= 1 [🛡 GitHub branch protection]
  • feat(core): PropertyMergeStrategy now supports array merge strategies #37841
• #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
  • feat(core): PropertyMergeStrategy now supports array merge strategies #37841
• any of [🛡 GitHub branch protection]:
  • check-success = validate-pr
  • check-neutral = validate-pr
  • check-skipped = validate-pr
• any of [🛡 GitHub branch protection]:
  • check-success = build
  • check-neutral = build
  • check-skipped = build

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.