chore(spec2cdk): refactor to use hand-written helpers for arrays (#36256)

### Reason for this change

The previously generated code for getting the values of the `IxxRef` in arrays was not readable, as a for loop to mutate the array in place and comma syntax were used to return the mutated array in a single line.
**Before**:
```
cdk.withResolved(props.${name}, (props.xx?.forEach((item: T | string, i: number, arr: Array<T | string>) => { arr[i] = (item as T)?.xxxRef?.xx ?? cdk.ensureStringOrUndefined(item, "xxx", "lambda.T | string"); }), props.xxx as Array<string>));
```
**After**:
```
cdk.mapArrayInPlace(props.layers, (item: IxxxRef | string) => (item as IxxxRef)?.xxxRef?.xxxArn ?? cdk.ensureStringOrUndefined(item, "xxx", "lambda.IxxxRef | string"))
```


### Description of changes
Added a handwritten function to do the in place in mapping in a generic way, preserving type safety.


### Description of how you validated changes

- This is a refactoring, unit tests for this are already in: https://github.com/aws/aws-cdk/blob/3e048c145cb801f31cf74716aacd8fa07bd004f8/packages/aws-cdk-lib/aws-lambda/test/function.test.ts#L5246

### 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: leonmk-aws

packages/aws-cdk-lib/core/lib/runtime.ts

@@ -1,5 +1,6 @@
 import { Construct } from 'constructs';
 import { ValidationError } from './errors';
+import { withResolved } from './token';
 
 // ----------------------------------------------------------------------
 // PROPERTY MAPPERS
@@ -430,3 +431,23 @@ export function ensureStringOrUndefined(value: any, propName: string, possibleTy
   }
   return value;
 }
+
+/**
+ * Map the elements of an array in place, preserving the original array reference.
+ *
+ * If `arr` is defined and resolved, each element is replaced with the result of `mapper`
+ * and the same array is returned, typed as `U[]`.
+ * If `arr` is undefined, returns undefined.
+ *
+ */
+export function mapArrayInPlace<T, U extends T>(arr: T[], mapper: (item: T) => U): U[];
+export function mapArrayInPlace<T, U extends T>(arr: T[] | undefined, mapper: (item: T) => U): U[] | undefined;
+export function mapArrayInPlace<T, U extends T>(arr: T[] | undefined, mapper: (item: T) => U): U[] | undefined {
+  if (!arr) return undefined;
+  withResolved(arr, () => {
+    for (let i = 0; i < arr.length; i++) {
+      arr[i] = mapper(arr[i]);
+    }
+  });
+  return arr as unknown as U[];
+}

tools/@aws-cdk/spec2cdk/lib/cdk/cdk.ts

@@ -34,6 +34,7 @@ export class CdkCore extends ExternalModule {
   public readonly unionMapper = makeCallableExpr(this, 'unionMapper');
   public readonly requireProperty = makeCallableExpr(this, 'requireProperty');
   public readonly isResolvableObject = makeCallableExpr(this, 'isResolvableObject');
+  public readonly mapArrayInPlace = makeCallableExpr(this, 'mapArrayInPlace');
 
   public readonly ValidationResult = $T(Type.fromName(this, 'ValidationResult'));
   public readonly VALIDATION_SUCCESS = makeCallableExpr(this, 'VALIDATION_SUCCESS');

tools/@aws-cdk/spec2cdk/lib/cdk/resolver-builder.ts

@@ -1,5 +1,5 @@
 import { DefinitionReference, Property } from '@aws-cdk/service-spec-types';
-import { expr, Expression, Module, Type } from '@cdklabs/typewriter';
+import { CallableDeclaration, expr, Expression, Lambda, Module, Parameter, Type } from '@cdklabs/typewriter';
 import { CDK_CORE } from './cdk';
 import { RelationshipDecider, Relationship, GENERATE_RELATIONSHIPS_ON_TYPES } from './relationship-decider';
 import { NON_RESOLVABLE_PROPERTY_NAMES } from './tagging';
@@ -78,13 +78,13 @@ export class ResolverBuilder {
       : Type.distinctUnionOf(resolvableType, ...newTypes);
 
     const typeDisplayNames = [
-      ...relationships.map(r => r.typeDisplayName),
+      ...[...new Set(relationships.map(r => r.typeDisplayName))],
       resolvableType.arrayOfType?.toString() ?? resolvableType.toString(),
     ].join(' | ');
 
     // Generates code like:
     // For single value T | string : (props.xx as IxxxRef)?.xxxRef?.xxxArn ?? cdk.ensureStringOrUndefined(props.xxx, "xxx", "iam.IxxxRef | string");
-    // For array <T | string>[]: (props.xx?.forEach((item: T | string, i: number, arr: Array<T | string>) => { arr[i] = (item as T)?.xxxRef?.xx ?? cdk.ensureStringOrUndefined(item, "xxx", "lambda.T | string"); }), props.xxx as Array<string>);
+    // For array <T | string>[]: cdk.mapArrayInPlace(props.layers, (item: IxxxRef | string) => (item as IxxxRef)?.xxxRef?.xxxArn ?? cdk.ensureStringOrUndefined(item, "xxx", "lambda.IxxxRef | string"))
     // Ensures that arn properties always appear first in the chain as they are more general
     const arnRels = relationships.filter(r => r.propName.toLowerCase().endsWith('arn'));
     const otherRels = relationships.filter(r => !r.propName.toLowerCase().endsWith('arn'));
@@ -94,11 +94,10 @@ export class ResolverBuilder {
         .map(r => `(${itemName} as ${r.referenceType})?.${r.referenceName}?.${r.propName}`),
       `cdk.ensureStringOrUndefined(${itemName}, "${name}", "${typeDisplayNames}")`,
     ].join(' ?? ');
-    const resolver = (_: Expression) => {
-      if (resolvableType.arrayOfType) {
-        return expr.directCode(
-          `(cdk.withResolved(props.${name}, () => props.${name}?.forEach((item: ${propType.arrayOfType!.toString()}, i: number, arr: ${propType.toString()}) => { arr[i] = ${buildChain('item')}; })), props.${name} as ${resolvableType.toString()})`,
-        );
+    const resolver = (props: Expression) => {
+      if (propType.arrayOfType) {
+        const mapper = this.createMapperLambda(propType.arrayOfType, expr.directCode(buildChain('item')));
+        return CDK_CORE.mapArrayInPlace.call(expr.get(props, name), mapper);
       } else {
         return expr.directCode(buildChain(`props.${name}`));
       }
@@ -120,20 +119,35 @@ export class ResolverBuilder {
 
     const resolver = (props: Expression) => {
       const propValue = expr.get(props, name);
-      const isArray = baseType.arrayOfType !== undefined;
+      // Prop can be of type IResolvable | Array<IResolvable | CfnProperty>
+      const arrayType = resolvableType.unionOfTypes?.find(t => t.arrayOfType)?.arrayOfType;
 
-      const flattenCall = isArray
-        ? expr.directCode(`props.${name}.forEach((item: any, i: number, arr: any[]) => { arr[i] = ${functionName}(item) }), props.${name}`)
-        : expr.ident(functionName).call(propValue);
+      let flattenCall;
+      if (arrayType) {
+        const mapper = this.createMapperLambda(arrayType, expr.ident(functionName).call(expr.ident('item')));
+        flattenCall = CDK_CORE.mapArrayInPlace.call(propValue, mapper);
+      } else {
+        flattenCall = expr.ident(functionName).call(propValue);
+      }
 
       const condition = optional
         ? expr.cond(expr.not(propValue)).then(expr.UNDEFINED).else(flattenCall)
         : flattenCall;
 
-      return isArray
+      return arrayType
         ? expr.cond(CDK_CORE.isResolvableObject(propValue)).then(propValue).else(condition)
         : condition;
     };
     return { name, propType: resolvableType, resolvableType, baseType, resolver };
   }
+
+  /**
+   * Creates an arrow function `(item: T) => body` for use with array mapping.
+   * Parameter requires a CallableDeclaration scope, but Lambda is an anonymous
+   * expression so we provide a placeholder.
+   */
+  private createMapperLambda(itemType: Type, body: Expression): Lambda {
+    const lambdaScope: CallableDeclaration = { parameters: [], returnType: Type.VOID, name: 'LambdaScope' };
+    return new Lambda([new Parameter(lambdaScope, { name: 'item', type: itemType })], body);
+  }
 }

tools/@aws-cdk/spec2cdk/test/relationships.test.ts

@@ -321,6 +321,6 @@ test('relationship have arns appear first in the constructor chain', () => {
 
   const rendered = renderer.render(module);
 
-  const chain = 'this.roleArn = (props.roleArn as IRoleRef)?.roleRef?.roleArn ?? (props.roleArn as IRoleRef)?.roleRef?.roleName ?? (props.roleArn as IRoleRef)?.roleRef?.otherPrimaryId ?? cdk.ensureStringOrUndefined(props.roleArn, "roleArn", "iam.IRoleRef | iam.IRoleRef | iam.IRoleRef | string")';
+  const chain = 'this.roleArn = (props.roleArn as IRoleRef)?.roleRef?.roleArn ?? (props.roleArn as IRoleRef)?.roleRef?.roleName ?? (props.roleArn as IRoleRef)?.roleRef?.otherPrimaryId ?? cdk.ensureStringOrUndefined(props.roleArn, "roleArn", "iam.IRoleRef | string")';
   expect(rendered).toContain(chain);
 });