# ArrayMergeStrategy

Strategies for merging arrays in L1 property mixins.

Array elements are never deep-merged.

- Source: [`core/lib/mixins/property-merge-strategy.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/core/lib/mixins/property-merge-strategy.ts#L52)
- Type last changed: v2.254.0 · 13 May 2026

## Methods

- `append(): IArrayMergeStrategy` (static) — Append source elements after the existing target elements.

  ```ts
  // target: [1, 2], source: [3, 4] → [1, 2, 3, 4]
  ```

- `prepend(): IArrayMergeStrategy` (static) — Prepend source elements before the existing target elements.

  ```ts
  // target: [1, 2], source: [3, 4] → [3, 4, 1, 2]
  ```

- `replace(): IArrayMergeStrategy` (static) — Replace the target array entirely with the source array.

  ```ts
  // target: [1, 2, 3], source: [4, 5] → [4, 5]
  ```

- `replaceByIndex(): IArrayMergeStrategy` (static) — Overwrite target elements positionally with source elements.

  Target elements beyond the source length are preserved.

  ```ts
  // target: ['a', 'b', 'c', 'd'], source: ['x', 'y'] → ['x', 'y', 'c', 'd']
  ```

- `replaceByKey(key: string): IArrayMergeStrategy` (static) — Match source and target elements by a shared key property.

  Matching target elements are replaced (not deep-merged).
  Unmatched source elements are appended.

  Supports Box-backed elements: when target array elements are Boxes, the
  match is deferred until the Boxes resolve.

  **Parameters**

  - `key` — - The property name to match elements on.

  ```ts
  // key: 'id'
  // target: [{id: 1, v: 'old'}, {id: 2, v: 'keep'}]
  // source: [{id: 1, v: 'new'}, {id: 3, v: 'added'}]
  // result: [{id: 1, v: 'new'}, {id: 2, v: 'keep'}, {id: 3, v: 'added'}]
  ```