@gradientedge/cdk-utils-aws 2.3.0 → 2.4.1

package/dist/src/services/cloudfront/main.js

@@ -32,6 +32,12 @@ import { createCfnOutput } from '../../utils/index.js';
  * @category Service
  */
 export class CloudFrontManager {
+    /**
+     * @summary Method to create a CloudFront Origin Access Identity
+     * @param id scoped id of the resource
+     * @param scope scope in which this resource is defined
+     * @param accessBucket optional S3 bucket to grant read access to the OAI
+     */
     createOriginAccessIdentity(id, scope, accessBucket) {
         const oai = new OriginAccessIdentity(scope, `${id}`, {
             comment: `${id} - ${scope.props.stage} stage`,
@@ -228,6 +234,11 @@ export class CloudFrontManager {
         createCfnOutput(`${id}-functionName`, scope, cloudfrontFunction.functionName);
         return cloudfrontFunction;
     }
+    /**
+     * @summary Method to resolve an existing CloudFront distribution by its attributes
+     * @param scope scope in which this resource is defined
+     * @param props the distribution attributes to look up
+     */
     resolveDistribution(scope, props) {
         return Distribution.fromDistributionAttributes(scope, `${scope.node.id}-sa-distribution`, props);
     }

package/dist/src/services/cloudtrail/main.js

@@ -45,6 +45,8 @@ export class CloudTrailManager {
             ...props,
             cloudWatchLogsLogGroupArn: logGroup.attrArn,
             cloudWatchLogsRoleArn: role.attrArn,
+            /* Track only S3 data write events (not management events) to reduce
+               noise and cost — reads are excluded to focus on mutation auditing */
             eventSelectors: [
                 {
                     dataResources: [
@@ -62,6 +64,8 @@ export class CloudTrailManager {
             tags: [{ key: 'service', value: scope.props.name }],
             trailName: scope.resourceNameFormatter.format(props.trailName, scope.props.resourceNameOptions?.cloudtrail),
         });
+        /* CloudTrail requires the bucket policy (write permissions), log group,
+           and IAM role to exist before the trail can be created */
         cloudTrail.addDependency(logBucketPolicy);
         cloudTrail.addDependency(logGroup);
         cloudTrail.addDependency(role);

package/dist/src/services/cloudwatch/main.js

@@ -44,6 +44,8 @@ export class CloudWatchManager {
             throw new Error(`Could not find expression for Alarm props for id:${id}`);
         if (!props.metricProps)
             throw new Error(`Could not find metricProps for Alarm props for id:${id}`);
+        /* Build a keyed map of metrics (m0, m1, m2, ...) that aligns with the
+           metric references used in the MathExpression string (e.g. "m0 + m1") */
         const metrics = {};
         _.map(this.determineMetrics(scope, props.metricProps), (metric, index) => {
             metrics[`m${index}`] = metric;
@@ -427,6 +429,10 @@ export class CloudWatchManager {
         const metrics = [];
         if (metricProps) {
             metricProps.forEach((metricProp) => {
+                /* Start with any custom dimensions provided, then override based on
+                   which service-specific fields are set. Note: these blocks are not
+                   mutually exclusive — if multiple fields match, the last matching
+                   block wins, since each reassigns metricDimensions entirely. */
                 let metricDimensions = metricProp.dimensionsMap || {};
                 if (metricProp.functionName) {
                     metricDimensions = {
@@ -466,6 +472,7 @@ export class CloudWatchManager {
                     };
                 }
                 if (metricProp.distributionId) {
+                    /* CloudFront metrics are always reported as Region: Global */
                     metricDimensions = {
                         ...metricProp.dimensionsMap,
                         DistributionId: `${metricProp.distributionId}`,
@@ -503,6 +510,8 @@ export class CloudWatchManager {
                         RuleName: `${metricProp.ruleName}`,
                     };
                 }
+                /* When stageSuffix is enabled, append the stage to both metric name
+                   and namespace to isolate metrics per deployment stage */
                 const metric = new watch.Metric({
                     dimensionsMap: metricDimensions,
                     metricName: metricProp.stageSuffix ? `${metricProp.metricName}-${scope.props.stage}` : metricProp.metricName,

package/dist/src/services/codebuild/main.d.ts

@@ -19,19 +19,19 @@ import { CommonConstruct } from '../../common/index.js';
  */
 export declare class CodeBuildManager {
     /**
-     *
-     * @param id
-     * @param scope
-     * @param dockerfilePath
+     * @summary Method to create a Docker image used for CloudFront cache invalidation
+     * @param id scoped id of the resource
+     * @param scope scope in which this resource is defined
+     * @param dockerfilePath the path to the Dockerfile
      */
     createImageForCloudfrontInvalidation(id: string, scope: CommonConstruct, dockerfilePath: string): import("aws-cdk-lib/aws-ecr-assets").DockerImageAsset;
     /**
-     *
-     * @param id
-     * @param scope
-     * @param dockerFilepath
-     * @param distributionId
-     * @param paths
+     * @summary Method to create a CodeBuild project for invalidating a CloudFront distribution cache
+     * @param id scoped id of the resource
+     * @param scope scope in which this resource is defined
+     * @param dockerFilepath the path to the Dockerfile for the build image
+     * @param distributionId the CloudFront distribution ID to invalidate
+     * @param paths optional invalidation paths (defaults to /*)
      */
     createProjectForCloudfrontInvalidation(id: string, scope: CommonConstruct, dockerFilepath: string, distributionId: string, paths?: string): Project;
 }

package/dist/src/services/codebuild/main.js

@@ -19,21 +19,21 @@ import { BuildSpec, ComputeType, LinuxBuildImage, Project } from 'aws-cdk-lib/aw
  */
 export class CodeBuildManager {
     /**
-     *
-     * @param id
-     * @param scope
-     * @param dockerfilePath
+     * @summary Method to create a Docker image used for CloudFront cache invalidation
+     * @param id scoped id of the resource
+     * @param scope scope in which this resource is defined
+     * @param dockerfilePath the path to the Dockerfile
      */
     createImageForCloudfrontInvalidation(id, scope, dockerfilePath) {
         return scope.ecrManager.createDockerImage(`${id}-build-image`, scope, dockerfilePath);
     }
     /**
-     *
-     * @param id
-     * @param scope
-     * @param dockerFilepath
-     * @param distributionId
-     * @param paths
+     * @summary Method to create a CodeBuild project for invalidating a CloudFront distribution cache
+     * @param id scoped id of the resource
+     * @param scope scope in which this resource is defined
+     * @param dockerFilepath the path to the Dockerfile for the build image
+     * @param distributionId the CloudFront distribution ID to invalidate
+     * @param paths optional invalidation paths (defaults to /*)
      */
     createProjectForCloudfrontInvalidation(id, scope, dockerFilepath, distributionId, paths) {
         const invalidationPaths = paths ?? '/*';

package/dist/src/services/elastic-file-system/main.js

@@ -46,6 +46,8 @@ export class EfsManager {
             throw new Error(`EFS props undefined for ${id}`);
         if (!props.fileSystemName)
             throw new Error(`EFS fileSystemName undefined for ${id}`);
+        /* Appending a timestamp to the logical ID forces CDK to replace the file system
+           on each deployment — used when a fresh EFS volume is required per deploy */
         const fileSystemId = props.provisionNewOnDeployment ? `${id}-${new Date().getMilliseconds()}` : `${id}`;
         const fileSystem = new FileSystem(scope, `${fileSystemId}`, {
             ...props,
@@ -65,6 +67,7 @@ export class EfsManager {
             for (const [index, accessPointOption] of accessPointOptions.entries()) {
                 if (!accessPointOption.path)
                     throw new Error(`Undefined access point path for option: [${accessPointOption}], id: [${id}]`);
+                /* Defaults use UID/GID 1000 (standard non-root Linux user) with 755 permissions */
                 const accessPoint = fileSystem.addAccessPoint(`${id}-ap-${index}`, {
                     createAcl: accessPointOption.createAcl ?? DEFAULT_CREATE_ACL,
                     path: accessPointOption.path,

package/dist/src/services/identity-access-management/main.js

@@ -276,6 +276,9 @@ export class IamManager {
         return new PolicyStatement({
             actions: ['logs:CreateLogStream'],
             effect: Effect.ALLOW,
+            /* Note: the log stream name pattern follows CloudTrail's convention:
+               {accountId}_CloudTrail_{region}. The eu-west-1 suffix is hard-coded
+               to match the expected trail region for this deployment. */
             resources: [
                 `arn:aws:logs:${Stack.of(scope).region}:${Stack.of(scope).account}:log-group:${logGroup.logGroupName}:log-stream:${Stack.of(scope).account}_CloudTrail_eu-west-1*`,
             ],
@@ -302,6 +305,8 @@ export class IamManager {
         return new PolicyStatement({
             actions: ['logs:PutLogEvents'],
             effect: Effect.ALLOW,
+            /* Note: log stream name follows CloudTrail convention — eu-west-1 is
+               hard-coded to match the expected trail region for this deployment */
             resources: [
                 `arn:aws:logs:${Stack.of(scope).region}:${Stack.of(scope).account}:log-group:${logGroup.logGroupName}:log-stream:${Stack.of(scope).account}_CloudTrail_eu-west-1*`,
             ],

package/dist/src/services/lambda/main.d.ts

@@ -31,6 +31,11 @@ export declare class LambdaManager {
      * @param architectures
      */
     createLambdaLayer(id: string, scope: CommonConstruct, code: AssetCode, architectures?: Architecture[]): LayerVersion;
+    /**
+     * @summary Method to create Lambda Web Adapter layers for both x86_64 and ARM64 architectures
+     * @param id scoped id of the resource
+     * @param scope scope in which this resource is defined
+     */
     createWebAdapterLayer(id: string, scope: CommonConstruct): ILayerVersion[];
     /**
      * @summary Method to create a lambda function (nodejs)

package/dist/src/services/lambda/main.js

@@ -42,6 +42,11 @@ export class LambdaManager {
         createCfnOutput(`${id}-lambdaLayerArn`, scope, lambdaLayer.layerVersionArn);
         return lambdaLayer;
     }
+    /**
+     * @summary Method to create Lambda Web Adapter layers for both x86_64 and ARM64 architectures
+     * @param id scoped id of the resource
+     * @param scope scope in which this resource is defined
+     */
     createWebAdapterLayer(id, scope) {
         return [
             LayerVersion.fromLayerVersionArn(scope, `${id}-${Architecture.X86_64}`, `arn:aws:lambda:${scope.props.region}:753240598075:layer:LambdaAdapterLayerX86:17`),
@@ -77,6 +82,7 @@ export class LambdaManager {
         }
         const lambdaFunction = new Function(scope, `${id}`, {
             ...props,
+            /* When a VPC is provided, allow placement in public subnets (e.g. for NAT access) */
             allowPublicSubnet: !!vpc,
             architecture: props.architecture ?? Architecture.ARM_64,
             code,
@@ -96,7 +102,9 @@ export class LambdaManager {
                 removalPolicy: RemovalPolicy.DESTROY,
                 retention: scope.props.logRetention ?? props.logRetentionInDays,
             }),
+            /* Per-function concurrency takes precedence over the stack-wide default */
             reservedConcurrentExecutions: props.reservedConcurrentExecutions ?? scope.props.defaultReservedLambdaConcurrentExecutions,
+            /* Only L2 Role is accepted here — CfnRole (L1) is not compatible with the Function construct */
             role: role instanceof Role ? role : undefined,
             runtime: props.runtime ?? scope.props.nodejsRuntime ?? CommonStack.NODEJS_RUNTIME,
             securityGroups,
@@ -105,12 +113,16 @@ export class LambdaManager {
             vpc,
             vpcSubnets,
         });
+        /* When DLQ retries are enabled, wire the DLQ back as an SQS event source
+           so failed messages are automatically reprocessed by the same function */
         if (lambdaFunction.deadLetterQueue && props.dlq?.retriesEnabled) {
             lambdaFunction.addEventSource(new SqsEventSource(lambdaFunction.deadLetterQueue, {
                 batchSize: props.dlq.retryBatchSize ?? 1,
                 reportBatchItemFailures: true,
             }));
         }
+        /* Create aliases and optionally attach provisioned concurrency auto-scaling.
+           Provisioned concurrency requires an alias — it cannot be set on $LATEST. */
         if (props.lambdaAliases && !_.isEmpty(props.lambdaAliases)) {
             props.lambdaAliases.forEach(alias => {
                 const aliasId = alias.id ?? `${id}-${alias.aliasName}`;

package/dist/src/services/simple-queue-service/main.js

@@ -33,6 +33,7 @@ export class SqsManager {
         if (!props.queueName)
             throw new Error(`Queue queueName undefined for ${id}`);
         let queueName = scope.resourceNameFormatter.format(props.queueName, scope.props.resourceNameOptions?.sqs);
+        /* AWS SQS requires FIFO queue names to end with the .fifo suffix */
         if (props.fifo)
             queueName += '.fifo';
         const queue = new Queue(scope, id, {

package/dist/src/services/simple-storage-service/main.js

@@ -65,6 +65,10 @@ export class S3Manager {
      * @param bucketName the bucket name
      */
     static determineBucketName(scope, props, bucketName) {
+        /* Naming strategy priority (note: flags use negative naming — "exclude" means "don't use"):
+           1. Domain-based naming (default) — includes the domain name for global uniqueness
+           2. Account-based naming — falls back to account+region when domain is excluded
+           3. Formatter-only — plain prefix/suffix when both domain and account are excluded */
         if (!scope.props.excludeDomainNameForBuckets) {
             return S3Manager.determineBucketNameByDomainName(scope, bucketName);
         }

package/dist/src/services/step-function/main.js

@@ -4,6 +4,9 @@ import { CallApiGatewayRestApiEndpoint, DynamoDeleteItem, DynamoGetItem, DynamoP
 import _ from 'lodash';
 import { v4 as uuidv4 } from 'uuid';
 import { createCfnOutput } from '../../utils/index.js';
+/* Default retry configuration applied to all step function steps when no
+   explicit retries are provided: exponential backoff (2x) starting at 30s,
+   up to 6 attempts, catching all error types */
 const DEFAULT_RETRY_CONFIG = [
     {
         backoffRate: 2,
@@ -267,6 +270,8 @@ export class SfnManager {
     createSkippableLambdaStep(id, scope, props, lambdaFunction, skipExecution) {
         if (!props)
             throw new Error(`Step props undefined for ${id}`);
+        /* When skipExecution is true, substitute a no-op Pass step instead of the Lambda
+           invocation — useful for conditionally disabling steps without changing the workflow topology */
         if (skipExecution)
             return this.createPassStep(id, scope, { comment: props.comment, name: props.name });
         const step = new LambdaInvoke(scope, `${props.name}`, {

package/dist/src/services/systems-manager/main.d.ts

@@ -51,7 +51,7 @@ export declare class SsmManager {
 export declare class SSMParameterReader extends AwsCustomResource {
     constructor(scope: CommonConstruct, name: string, props: SSMParameterReaderProps);
     /**
-     *
+     * @summary Method to retrieve the SSM parameter value from the custom resource response
      */
     getParameterValue(): string;
 }

package/dist/src/services/systems-manager/main.js

@@ -91,7 +91,7 @@ export class SSMParameterReader extends AwsCustomResource {
         });
     }
     /**
-     *
+     * @summary Method to retrieve the SSM parameter value from the custom resource response
      */
     getParameterValue() {
         return this.getResponseField('Parameter.Value');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradientedge/cdk-utils-aws",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "AWS CDK utilities for @gradientedge/cdk-utils",
   "type": "module",
   "main": "dist/src/index.js",
@@ -14,17 +14,17 @@
     "dist/src/"
   ],
   "dependencies": {
-    "@aws-sdk/client-secrets-manager": "3.1034.0",
-    "@aws-sdk/credential-providers": "3.1034.0",
+    "@aws-sdk/client-secrets-manager": "3.1040.0",
+    "@aws-sdk/credential-providers": "3.1040.0",
     "@aws-sdk/types": "3.973.8",
     "@types/lodash": "4.17.24",
     "app-root-path": "3.1.0",
-    "aws-cdk-lib": "2.250.0",
+    "aws-cdk-lib": "2.252.0",
     "lodash": "4.18.1",
     "constructs": "10.6.0",
     "moment": "2.30.1",
     "uuid": "14.0.0",
-    "@gradientedge/cdk-utils-common": "2.1.0"
+    "@gradientedge/cdk-utils-common": "2.2.1"
   },
   "keywords": [
     "gradientedge",