@incloodsolutions/devkit 0.0.4 → 0.0.5

package/dist/aws-cdk/stacks/lambda-sqs.js

@@ -0,0 +1,218 @@
+import { Duration, CfnOutput, RemovalPolicy, Stack } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { Function, Architecture, Runtime, Code, LayerVersion, EventSourceMapping } from 'aws-cdk-lib/aws-lambda';
+import { detectDuplicateProperties, AppEnvironmentEnum, CustomException } from '@incloodsolutions/toolkit';
+import { Queue } from 'aws-cdk-lib/aws-sqs';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var BaseLambdaConstruct = class extends Construct {
+  static {
+    __name(this, "BaseLambdaConstruct");
+  }
+  /** The created Lambda function instance */
+  function;
+  /**
+   * @param scope Parent construct
+   * @param id Unique construct identifier
+   * @param props Configuration for Lambda function
+   */
+  constructor(scope, id, props) {
+    super(scope, id);
+    const environment = {
+      ...props.options?.lambdaOptions?.environment,
+      NODE_ENV: props.stage,
+      NODE_OPTIONS: "--enable-source-maps",
+      AWS_NODEJS_CONNECTION_REUSE_ENABLED: "1"
+    };
+    detectDuplicateProperties({ data: environment });
+    this.function = new Function(this, id, {
+      ...props?.options?.lambdaOptions,
+      /**
+       * Lambda function name
+       * Defaults to "<stackName>" if not provided
+       */
+      functionName: `${props?.options?.lambdaOptions?.functionName || props?.stackName}`,
+      /**
+       * Function description
+       */
+      description: props?.options?.lambdaOptions?.description || "A lambda function",
+      /**
+       * Entry handler for the Lambda function
+       */
+      handler: props?.options?.lambdaOptions?.handler || "lambda.handler",
+      /**
+       * Runtime environment
+       */
+      runtime: props?.options?.lambdaOptions?.runtime || Runtime.NODEJS_24_X,
+      /**
+       * Execution timeout
+       * - 30 seconds in production
+       * - 15 seconds otherwise
+       */
+      timeout: props?.options?.lambdaOptions?.timeout || Duration.seconds(
+        props.stage === AppEnvironmentEnum.PRODUCTION ? 30 : 15
+      ),
+      /**
+       * Memory allocation (in MB)
+       */
+      memorySize: props?.options?.lambdaOptions?.memorySize || 1024,
+      /**
+       * CPU architecture
+       */
+      architecture: props?.options?.lambdaOptions?.architecture || Architecture.ARM_64,
+      /**
+       * Lambda deployment package source
+       */
+      code: props?.options?.lambdaOptions?.code || Code.fromAsset("dist"),
+      /**
+       * Final merged environment variables
+       */
+      environment
+    });
+    new CfnOutput(this, "LambdaFunctionArn", {
+      value: this.function.functionArn
+    });
+  }
+};
+var BaseLambdaLayerConstruct = class extends Construct {
+  static {
+    __name(this, "BaseLambdaLayerConstruct");
+  }
+  /** Newly created Lambda Layer (null if importing existing layer) */
+  layer;
+  /** Imported Lambda Layer reference (null if creating new layer) */
+  existingLayer;
+  /**
+   * @param scope Parent construct
+   * @param id Unique construct identifier
+   * @param props Configuration for layer creation or import
+   */
+  constructor(scope, id, props) {
+    super(scope, id);
+    if (props?.options?.fromExistingLayerArn) {
+      this.existingLayer = LayerVersion.fromLayerVersionArn(
+        this,
+        `${id}-Arn`,
+        props?.options?.fromExistingLayerArn
+      );
+    } else if (props?.options?.fromExistingLayerAttribute) {
+      this.existingLayer = LayerVersion.fromLayerVersionAttributes(
+        this,
+        `${id}-Attribute`,
+        props?.options?.fromExistingLayerAttribute
+      );
+    } else {
+      this.layer = new LayerVersion(this, id, {
+        ...props.options?.layerOptions,
+        /**
+         * Default layer code asset
+         */
+        code: props?.options?.layerOptions?.code || Code.fromAsset("./dist-layer"),
+        /**
+         * Layer description
+         */
+        description: props?.options?.layerOptions?.description || "Lambda Layer written in NodeJS, NestJS, NodeJS-express, serverless-express",
+        /**
+         * Supported CPU architectures
+         */
+        compatibleArchitectures: [Architecture.ARM_64, Architecture.X86_64],
+        /**
+         * Supported runtimes
+         */
+        compatibleRuntimes: [
+          Runtime.NODEJS_22_X,
+          Runtime.NODEJS_24_X,
+          Runtime.NODEJS_LATEST
+        ]
+      });
+    }
+    new CfnOutput(this, "LambdaLayerArn", {
+      value: props.options?.fromExistingLayerArn || props.options?.fromExistingLayerAttribute ? this.existingLayer.layerVersionArn : this.layer.layerVersionArn
+    });
+  }
+};
+var BaseSqsConstruct = class extends Construct {
+  static {
+    __name(this, "BaseSqsConstruct");
+  }
+  /** The created SQS queue instance */
+  queue;
+  /**
+   * @param scope Parent construct
+   * @param id Unique construct identifier
+   * @param props Configuration for queue and Lambda consumers
+   */
+  constructor(scope, id, props) {
+    super(scope, id);
+    this.queue = new Queue(this, id, {
+      ...props?.options?.queueOptions,
+      /**
+       * Removal policy applied to the queue
+       * Defaults to DESTROY if not explicitly defined
+       */
+      removalPolicy: props?.options?.queueOptions?.removalPolicy || RemovalPolicy.DESTROY
+    });
+    if (props?.targetFunctions?.length) {
+      props.targetFunctions.forEach((targetFunction, index) => {
+        new EventSourceMapping(this, `${id}-eventSourceMap${index + 1}`, {
+          ...props?.options?.eventSourceMappingOptions,
+          /** Target Lambda function */
+          target: targetFunction,
+          /** Source SQS queue ARN */
+          eventSourceArn: this.queue.queueArn,
+          /**
+           * Retry attempts for failed batch processing
+           * Defaults to 3 if not explicitly defined
+           */
+          retryAttempts: props?.options?.eventSourceMappingOptions?.retryAttempts || 3
+        });
+      });
+    }
+    new CfnOutput(this, "SqsQueueArn", {
+      value: this.queue.queueArn
+    });
+  }
+};
+var BaseLambdaSqsStack = class extends Stack {
+  static {
+    __name(this, "BaseLambdaSqsStack");
+  }
+  constructor(scope, id, props) {
+    super(scope, id, props);
+    let layers = [];
+    if (props?.stackOptions?.layerOptions) {
+      if (!props.stackOptions?.layerOptions?.name || !props.stackOptions?.layerOptions?.version) {
+        throw new CustomException("Invalid layer options provided");
+      }
+      const { existingLayer } = new BaseLambdaLayerConstruct(
+        this,
+        "layer",
+        {
+          options: {
+            fromExistingLayerArn: `arn:aws:lambda:${props.env?.region}:${props.env?.account}:layer:${props.stackOptions?.layerOptions?.name}:${props.stackOptions?.layerOptions?.version}`
+          }
+        }
+      );
+      layers.push(existingLayer);
+    }
+    const { function: lambdaFunction } = new BaseLambdaConstruct(this, "lambda", {
+      stage: props.stackOptions?.stage,
+      stackName: props.stackName,
+      options: {
+        lambdaOptions: { layers }
+      }
+    });
+    new BaseSqsConstruct(this, "sqs", {
+      targetFunctions: [lambdaFunction],
+      options: {
+        eventSourceMappingOptions: {},
+        queueOptions: {}
+      }
+    });
+  }
+};
+
+export { BaseLambdaSqsStack };
+//# sourceMappingURL=lambda-sqs.js.map
+//# sourceMappingURL=lambda-sqs.js.map

package/dist/aws-cdk/stacks/lambda-sqs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/aws/cdk/constructs/lambda-construct.ts","../../../src/aws/cdk/constructs/lambda-layer-construct.ts","../../../src/aws/cdk/constructs/sqs-construct.ts","../../../src/aws/cdk/stacks/lambda-sqs-stack.ts"],"names":["Construct","Code","Architecture","Runtime","CfnOutput"],"mappings":"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","file":"lambda-sqs.js","sourcesContent":["import { Construct } from 'constructs';\nimport { CfnOutput, Duration } from 'aws-cdk-lib';\nimport {\n\tArchitecture,\n\tCode,\n\tFunction,\n\tFunctionProps,\n\tRuntime,\n} from 'aws-cdk-lib/aws-lambda';\n\nimport {\n\tdetectDuplicateProperties,\n\tAppEnvironmentEnum,\n} from '@incloodsolutions/toolkit';\n\nimport { IBaseCdkConstructProps } from '../../types';\n\n/**\n * Props for BaseLambdaConstruct\n *\n * Provides configuration for creating a Lambda function\n * with optional overrides for runtime, memory, timeout, and environment.\n */\ninterface ILambdaConstructProps extends Omit<\n\tIBaseCdkConstructProps<{\n\t\t/** Partial Lambda configuration options */\n\t\treadonly lambdaOptions: Partial<FunctionProps>;\n\t}>,\n\t'appName'\n> {}\n\n/**\n * CDK construct for AWS Lambda function\n *\n * Responsibilities:\n * - Creates a Lambda function with sensible defaults\n * - Merges and validates environment variables\n * - Applies stage-based configuration (e.g. timeout)\n * - Exposes the function ARN as a CloudFormation output\n */\nexport class BaseLambdaConstruct extends Construct {\n\t/** The created Lambda function instance */\n\treadonly function: Function;\n\n\t/**\n\t * @param scope Parent construct\n\t * @param id Unique construct identifier\n\t * @param props Configuration for Lambda function\n\t */\n\tconstructor(scope: Construct, id: string, props: ILambdaConstructProps) {\n\t\tsuper(scope, id);\n\n\t\t/**\n\t\t * Environment variables for the Lambda function\n\t\t *\n\t\t * Includes:\n\t\t * - User-defined variables\n\t\t * - NODE_ENV derived from stage\n\t\t * - Node.js runtime optimisations\n\t\t */\n\t\tconst environment = {\n\t\t\t...props.options?.lambdaOptions?.environment,\n\t\t\tNODE_ENV: props.stage,\n\t\t\tNODE_OPTIONS: '--enable-source-maps',\n\t\t\tAWS_NODEJS_CONNECTION_REUSE_ENABLED: '1',\n\t\t};\n\n\t\t/**\n\t\t * Validate environment variables for duplicate keys\n\t\t */\n\t\tdetectDuplicateProperties({ data: environment });\n\n\t\tthis.function = new Function(this, id, {\n\t\t\t...props?.options?.lambdaOptions,\n\n\t\t\t/**\n\t\t\t * Lambda function name\n\t\t\t * Defaults to \"<stackName>\" if not provided\n\t\t\t */\n\t\t\tfunctionName: `${props?.options?.lambdaOptions?.functionName || props?.stackName}`,\n\n\t\t\t/**\n\t\t\t * Function description\n\t\t\t */\n\t\t\tdescription:\n\t\t\t\tprops?.options?.lambdaOptions?.description || 'A lambda function',\n\n\t\t\t/**\n\t\t\t * Entry handler for the Lambda function\n\t\t\t */\n\t\t\thandler: props?.options?.lambdaOptions?.handler || 'lambda.handler',\n\n\t\t\t/**\n\t\t\t * Runtime environment\n\t\t\t */\n\t\t\truntime: props?.options?.lambdaOptions?.runtime || Runtime.NODEJS_24_X,\n\n\t\t\t/**\n\t\t\t * Execution timeout\n\t\t\t * - 30 seconds in production\n\t\t\t * - 15 seconds otherwise\n\t\t\t */\n\t\t\ttimeout:\n\t\t\t\tprops?.options?.lambdaOptions?.timeout ||\n\t\t\t\tDuration.seconds(\n\t\t\t\t\tprops.stage === AppEnvironmentEnum.PRODUCTION ? 30 : 15,\n\t\t\t\t),\n\n\t\t\t/**\n\t\t\t * Memory allocation (in MB)\n\t\t\t */\n\t\t\tmemorySize: props?.options?.lambdaOptions?.memorySize || 1024,\n\n\t\t\t/**\n\t\t\t * CPU architecture\n\t\t\t */\n\t\t\tarchitecture:\n\t\t\t\tprops?.options?.lambdaOptions?.architecture || Architecture.ARM_64,\n\n\t\t\t/**\n\t\t\t * Lambda deployment package source\n\t\t\t */\n\t\t\tcode: props?.options?.lambdaOptions?.code || Code.fromAsset('dist'),\n\n\t\t\t/**\n\t\t\t * Final merged environment variables\n\t\t\t */\n\t\t\tenvironment,\n\t\t});\n\n\t\t/**\n\t\t * CloudFormation output exposing the Lambda function ARN\n\t\t */\n\t\tnew CfnOutput(this, 'LambdaFunctionArn', {\n\t\t\tvalue: this.function.functionArn,\n\t\t});\n\t}\n}\n","import { Construct } from 'constructs';\nimport { CfnOutput } from 'aws-cdk-lib';\nimport {\n\tArchitecture,\n\tCode,\n\tILayerVersion,\n\tLayerVersion,\n\tLayerVersionProps,\n\tRuntime,\n} from 'aws-cdk-lib/aws-lambda';\n\nimport { IBaseCdkConstructProps } from '../../types';\n\n/**\n * Props for BaseLambdaLayerConstruct\n *\n * Provides configuration for:\n * - Creating a new Lambda Layer\n * - Importing an existing layer by ARN or attributes\n */\ninterface ILambdaLayerConstructProps extends Omit<\n\tIBaseCdkConstructProps<{\n\t\t/**\n\t\t * Configuration for creating a new Lambda layer\n\t\t *\n\t\t * Note:\n\t\t * - `layerVersionName` is required\n\t\t * - `compatibleArchitectures` is managed internally\n\t\t */\n\t\treadonly layerOptions?: Partial<\n\t\t\tOmit<LayerVersionProps, 'layerVersionName' | 'compatibleArchitectures'>\n\t\t> &\n\t\t\tRequired<Pick<LayerVersionProps, 'layerVersionName'>>;\n\n\t\t/** Import an existing layer by ARN */\n\t\treadonly fromExistingLayerArn?: string;\n\n\t\t/** Import an existing layer using attributes */\n\t\treadonly fromExistingLayerAttribute?: {\n\t\t\treadonly layerVersionArn: string;\n\t\t\treadonly compatibleRuntimes?: Runtime[];\n\t\t};\n\t}>,\n\t'appName' | 'stage' | 'stackName'\n> {}\n\n/**\n * CDK construct for Lambda Layer\n *\n * Responsibilities:\n * - Creates a new Lambda layer or imports an existing one\n * - Applies default runtime and architecture compatibility\n * - Exposes the layer ARN as a CloudFormation output\n */\nexport class BaseLambdaLayerConstruct extends Construct {\n\t/** Newly created Lambda Layer (null if importing existing layer) */\n\treadonly layer: LayerVersion;\n\n\t/** Imported Lambda Layer reference (null if creating new layer) */\n\treadonly existingLayer: ILayerVersion;\n\n\t/**\n\t * @param scope Parent construct\n\t * @param id Unique construct identifier\n\t * @param props Configuration for layer creation or import\n\t */\n\tconstructor(\n\t\tscope: Construct,\n\t\tid: string,\n\t\tprops?: ILambdaLayerConstructProps,\n\t) {\n\t\tsuper(scope, id);\n\n\t\t/**\n\t\t * Import layer by ARN\n\t\t */\n\t\tif (props?.options?.fromExistingLayerArn) {\n\t\t\tthis.existingLayer = LayerVersion.fromLayerVersionArn(\n\t\t\t\tthis,\n\t\t\t\t`${id}-Arn`,\n\t\t\t\tprops?.options?.fromExistingLayerArn,\n\t\t\t);\n\n\t\t\t/**\n\t\t\t * Import layer using attributes\n\t\t\t */\n\t\t} else if (props?.options?.fromExistingLayerAttribute) {\n\t\t\tthis.existingLayer = LayerVersion.fromLayerVersionAttributes(\n\t\t\t\tthis,\n\t\t\t\t`${id}-Attribute`,\n\t\t\t\tprops?.options?.fromExistingLayerAttribute,\n\t\t\t);\n\n\t\t\t/**\n\t\t\t * Create new Lambda layer\n\t\t\t */\n\t\t} else {\n\t\t\tthis.layer = new LayerVersion(this, id, {\n\t\t\t\t...props.options?.layerOptions,\n\n\t\t\t\t/**\n\t\t\t\t * Default layer code asset\n\t\t\t\t */\n\t\t\t\tcode:\n\t\t\t\t\tprops?.options?.layerOptions?.code || Code.fromAsset('./dist-layer'),\n\n\t\t\t\t/**\n\t\t\t\t * Layer description\n\t\t\t\t */\n\t\t\t\tdescription:\n\t\t\t\t\tprops?.options?.layerOptions?.description ||\n\t\t\t\t\t'Lambda Layer written in NodeJS, NestJS, NodeJS-express, serverless-express',\n\n\t\t\t\t/**\n\t\t\t\t * Supported CPU architectures\n\t\t\t\t */\n\t\t\t\tcompatibleArchitectures: [Architecture.ARM_64, Architecture.X86_64],\n\n\t\t\t\t/**\n\t\t\t\t * Supported runtimes\n\t\t\t\t */\n\t\t\t\tcompatibleRuntimes: [\n\t\t\t\t\tRuntime.NODEJS_22_X,\n\t\t\t\t\tRuntime.NODEJS_24_X,\n\t\t\t\t\tRuntime.NODEJS_LATEST,\n\t\t\t\t],\n\t\t\t} as LayerVersionProps);\n\t\t}\n\n\t\t/**\n\t\t * CloudFormation output exposing the layer ARN\n\t\t * Resolves to either created or imported layer\n\t\t */\n\t\tnew CfnOutput(this, 'LambdaLayerArn', {\n\t\t\tvalue:\n\t\t\t\tprops.options?.fromExistingLayerArn ||\n\t\t\t\tprops.options?.fromExistingLayerAttribute\n\t\t\t\t\t? this.existingLayer.layerVersionArn\n\t\t\t\t\t: this.layer.layerVersionArn,\n\t\t});\n\t}\n}\n","import { Construct } from 'constructs';\nimport { CfnOutput, RemovalPolicy } from 'aws-cdk-lib';\nimport { Queue, QueueProps } from 'aws-cdk-lib/aws-sqs';\nimport {\n\tEventSourceMapping,\n\tEventSourceMappingProps,\n\tFunction,\n} from 'aws-cdk-lib/aws-lambda';\n\nimport { IBaseCdkConstructProps } from '../../types';\n\n/**\n * Props for BaseSqsConstruct\n *\n * Provides configuration for:\n * - SQS queue creation\n * - Lambda event source mappings\n */\ninterface ISqsConstructProps extends Omit<\n\tIBaseCdkConstructProps<{\n\t\t/** Configuration options for the SQS queue */\n\t\treadonly queueOptions?: QueueProps;\n\n\t\t/**\n\t\t * Configuration for Lambda event source mapping\n\t\t *\n\t\t * Note:\n\t\t * `eventSourceArn` and `target` are managed internally\n\t\t */\n\t\treadonly eventSourceMappingOptions?: Omit<\n\t\t\tEventSourceMappingProps,\n\t\t\t'eventSourceArn' | 'target'\n\t\t>;\n\t}>,\n\t'appName' | 'stage' | 'stackName'\n> {\n\t/**\n\t * Lambda functions to be triggered by SQS messages\n\t *\n\t * Each function will be connected via an event source mapping\n\t */\n\treadonly targetFunctions?: Function[];\n}\n\n/**\n * CDK construct for SQS queue with Lambda integration\n *\n * Responsibilities:\n * - Creates an SQS queue with configurable options\n * - Attaches one or more Lambda consumers via event source mappings\n * - Applies default retry behaviour\n * - Exposes the queue ARN as a CloudFormation output\n */\nexport class BaseSqsConstruct extends Construct {\n\t/** The created SQS queue instance */\n\treadonly queue: Queue;\n\n\t/**\n\t * @param scope Parent construct\n\t * @param id Unique construct identifier\n\t * @param props Configuration for queue and Lambda consumers\n\t */\n\tconstructor(scope: Construct, id: string, props: ISqsConstructProps) {\n\t\tsuper(scope, id);\n\n\t\tthis.queue = new Queue(this, id, {\n\t\t\t...props?.options?.queueOptions,\n\n\t\t\t/**\n\t\t\t * Removal policy applied to the queue\n\t\t\t * Defaults to DESTROY if not explicitly defined\n\t\t\t */\n\t\t\tremovalPolicy:\n\t\t\t\tprops?.options?.queueOptions?.removalPolicy || RemovalPolicy.DESTROY,\n\t\t});\n\n\t\t/**\n\t\t * Attach Lambda event source mappings for queue consumption\n\t\t */\n\t\tif (props?.targetFunctions?.length) {\n\t\t\tprops.targetFunctions.forEach((targetFunction, index) => {\n\t\t\t\tnew EventSourceMapping(this, `${id}-eventSourceMap${index + 1}`, {\n\t\t\t\t\t...props?.options?.eventSourceMappingOptions,\n\n\t\t\t\t\t/** Target Lambda function */\n\t\t\t\t\ttarget: targetFunction,\n\n\t\t\t\t\t/** Source SQS queue ARN */\n\t\t\t\t\teventSourceArn: this.queue.queueArn,\n\n\t\t\t\t\t/**\n\t\t\t\t\t * Retry attempts for failed batch processing\n\t\t\t\t\t * Defaults to 3 if not explicitly defined\n\t\t\t\t\t */\n\t\t\t\t\tretryAttempts:\n\t\t\t\t\t\tprops?.options?.eventSourceMappingOptions?.retryAttempts || 3,\n\t\t\t\t});\n\t\t\t});\n\t\t}\n\n\t\t/**\n\t\t * CloudFormation output exposing the SQS queue ARN\n\t\t */\n\t\tnew CfnOutput(this, 'SqsQueueArn', {\n\t\t\tvalue: this.queue.queueArn,\n\t\t});\n\t}\n}\n","import { App, Stack } from \"aws-cdk-lib\";\n\nimport { IBaseStackProps } from \"../../types\";\nimport { BaseLambdaConstruct, BaseLambdaLayerConstruct, BaseSqsConstruct } from \"../constructs\";\nimport { CustomException } from \"@incloodsolutions/toolkit\";\nimport { ILayerVersion } from \"aws-cdk-lib/aws-lambda\";\n\nexport class BaseLambdaSqsStack extends Stack {\n\tconstructor(scope: App, id: string, props: IBaseStackProps<{\n\t\tlayerOptions?: {\n\t\t\tname: string;\n\t\t\tversion: number;\n\t\t};\n\t\tlambdaOptions?: {};\n\t\tapiGatewayOptions?: {\n\t\t\tversion?: 'v1' | 'v2';\n\t\t};\n\t}>) {\n\t\tsuper(scope, id, props);\n\t\tlet layers: ILayerVersion[] = [];\n\n\t\tif (props?.stackOptions?.layerOptions) {\n\t\t\tif (!props.stackOptions?.layerOptions?.name || !props.stackOptions?.layerOptions?.version) {\n\t\t\t\tthrow new CustomException(\"Invalid layer options provided\");\n\t\t\t}\n\t\t\tconst { existingLayer } = new BaseLambdaLayerConstruct(\n\t\t\t\tthis,\n\t\t\t\t'layer',\n\t\t\t\t{\n\t\t\t\t\toptions: {\n\t\t\t\t\t\tfromExistingLayerArn: `arn:aws:lambda:${props.env?.region}:${props.env?.account}:layer:${props.stackOptions?.layerOptions?.name}:${props.stackOptions?.layerOptions?.version}`,\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t);\n\t\t\tlayers.push(existingLayer);\n\t\t}\n\n\t\tconst { function: lambdaFunction } = new BaseLambdaConstruct(this, 'lambda', {\n\t\t\tstage: props.stackOptions?.stage,\n\t\t\tstackName: props.stackName,\n\t\t\toptions: {\n\t\t\t\tlambdaOptions: { layers },\n\t\t\t},\n\t\t});\n\n\t\tnew BaseSqsConstruct(this, 'sqs', {\n\t\t\ttargetFunctions: [lambdaFunction],\n\t\t\toptions: {\n\t\t\t\teventSourceMappingOptions: {},\n\t\t\t\tqueueOptions: {}\n\t\t\t}\n\t\t});\n\n\t}\n}"]}

package/dist/aws-types.d.cts

@@ -1,4 +1,5 @@
 import { IBaseEnableDebug, ObjectType, AppEnvironmentType } from '@incloodsolutions/toolkit';
+import { StackProps } from 'aws-cdk-lib';
 
 /**
  * @packageDocumentation
@@ -38,5 +39,17 @@ interface IBaseCdkConstructProps<TOptions extends ObjectType = any> extends Read
     /** Application name, used by some constructs to derive resource names. */
     readonly appName?: string;
 }
+/**
+ * The common configuration shape accepted by every `Base*` CDK stack in this package.
+ */
+interface IBaseStackProps<TStackOptions extends ObjectType = any> extends StackProps {
+    readonly stackOptions: {
+        /**
+         * Deployment stage/environment. Some constructs use it to pick defaults
+         * (e.g. a longer Lambda timeout in `'production'`) and to set `NODE_ENV`.
+         */
+        readonly stage?: AppEnvironmentType;
+    } & TStackOptions & Readonly<Partial<IBaseEnableDebug>>;
+}
 
-export type { IBaseCdkConstructProps, IBaseConstruct };
+export type { IBaseCdkConstructProps, IBaseConstruct, IBaseStackProps };

package/dist/aws-types.d.ts

@@ -1,4 +1,5 @@
 import { IBaseEnableDebug, ObjectType, AppEnvironmentType } from '@incloodsolutions/toolkit';
+import { StackProps } from 'aws-cdk-lib';
 
 /**
  * @packageDocumentation
@@ -38,5 +39,17 @@ interface IBaseCdkConstructProps<TOptions extends ObjectType = any> extends Read
     /** Application name, used by some constructs to derive resource names. */
     readonly appName?: string;
 }
+/**
+ * The common configuration shape accepted by every `Base*` CDK stack in this package.
+ */
+interface IBaseStackProps<TStackOptions extends ObjectType = any> extends StackProps {
+    readonly stackOptions: {
+        /**
+         * Deployment stage/environment. Some constructs use it to pick defaults
+         * (e.g. a longer Lambda timeout in `'production'`) and to set `NODE_ENV`.
+         */
+        readonly stage?: AppEnvironmentType;
+    } & TStackOptions & Readonly<Partial<IBaseEnableDebug>>;
+}
 
-export type { IBaseCdkConstructProps, IBaseConstruct };
+export type { IBaseCdkConstructProps, IBaseConstruct, IBaseStackProps };

package/dist/aws.cjs

@@ -14,6 +14,7 @@ var awsEventsTargets = require('aws-cdk-lib/aws-events-targets');
 var awsApigatewayv2Authorizers = require('aws-cdk-lib/aws-apigatewayv2-authorizers');
 var awsLambda = require('aws-cdk-lib/aws-lambda');
 var awsIam = require('aws-cdk-lib/aws-iam');
+var awsRoute53 = require('aws-cdk-lib/aws-route53');
 var awsS3 = require('aws-cdk-lib/aws-s3');
 var awsCloudfrontOrigins = require('aws-cdk-lib/aws-cloudfront-origins');
 var awsS3Deployment = require('aws-cdk-lib/aws-s3-deployment');
@@ -544,9 +545,9 @@ var BaseLambdaConstruct = class extends constructs.Construct {
       ...props?.options?.lambdaOptions,
       /**
        * Lambda function name
-       * Defaults to "<stackName>-handler" if not provided
+       * Defaults to "<stackName>" if not provided
        */
-      functionName: `${props?.options?.lambdaOptions?.functionName || props?.stackName}-handler`,
+      functionName: `${props?.options?.lambdaOptions?.functionName || props?.stackName}`,
       /**
        * Function description
        */
@@ -687,6 +688,72 @@ var BaseRolePolicyConstruct = class extends constructs.Construct {
     });
   }
 };
+var BaseRoute53Construct = class extends constructs.Construct {
+  static {
+    __name(this, "BaseRoute53Construct");
+  }
+  /** The hosted zone this construct created, imported, or looked up */
+  hostedZone;
+  /**
+   * @param scope Parent construct
+   * @param id Unique construct identifier
+   * @param props Configuration for the hosted zone and its records
+   */
+  constructor(scope, id, props) {
+    super(scope, id);
+    const options = props?.options ?? {};
+    if (options.hostedZoneOptions) {
+      this.hostedZone = new awsRoute53.HostedZone(
+        this,
+        `${id}-HostedZone`,
+        options.hostedZoneOptions
+      );
+    } else if (options.fromExistingHostedZoneAttributes) {
+      this.hostedZone = awsRoute53.HostedZone.fromHostedZoneAttributes(
+        this,
+        `${id}-HostedZone`,
+        options.fromExistingHostedZoneAttributes
+      );
+    } else if (options.fromLookupOptions) {
+      this.hostedZone = awsRoute53.HostedZone.fromLookup(
+        this,
+        `${id}-HostedZone`,
+        options.fromLookupOptions
+      );
+    } else {
+      throw new toolkit.CustomException(
+        "BaseRoute53Construct requires one of hostedZoneOptions, fromExistingHostedZoneAttributes, or fromLookupOptions"
+      );
+    }
+    options.aRecords?.forEach((record, index) => {
+      new awsRoute53.ARecord(this, `${id}-ARecord-${index}`, {
+        ...record,
+        zone: this.hostedZone
+      });
+    });
+    options.aaaaRecords?.forEach((record, index) => {
+      new awsRoute53.AaaaRecord(this, `${id}-AaaaRecord-${index}`, {
+        ...record,
+        zone: this.hostedZone
+      });
+    });
+    options.cnameRecords?.forEach((record, index) => {
+      new awsRoute53.CnameRecord(this, `${id}-CnameRecord-${index}`, {
+        ...record,
+        zone: this.hostedZone
+      });
+    });
+    options.txtRecords?.forEach((record, index) => {
+      new awsRoute53.TxtRecord(this, `${id}-TxtRecord-${index}`, {
+        ...record,
+        zone: this.hostedZone
+      });
+    });
+    new awsCdkLib.CfnOutput(this, "Route53HostedZoneId", {
+      value: this.hostedZone.hostedZoneId
+    });
+  }
+};
 var BaseS3Construct = class extends constructs.Construct {
   static {
     __name(this, "BaseS3Construct");
@@ -883,6 +950,132 @@ var BaseVpcConstruct = class extends constructs.Construct {
     });
   }
 };
+var BaseLambdaApiStack = class extends awsCdkLib.Stack {
+  static {
+    __name(this, "BaseLambdaApiStack");
+  }
+  constructor(scope, id, props) {
+    super(scope, id, props);
+    let layers = [];
+    if (props?.stackOptions?.layerOptions) {
+      if (!props.stackOptions?.layerOptions?.name || !props.stackOptions?.layerOptions?.version) {
+        throw new toolkit.CustomException("Invalid layer options provided! Both layer 'name' and 'version' are required.");
+      }
+      const { existingLayer } = new BaseLambdaLayerConstruct(
+        this,
+        "layer",
+        {
+          options: {
+            fromExistingLayerArn: `arn:aws:lambda:${props.env?.region}:${props.env?.account}:layer:${props.stackOptions?.layerOptions?.name}:${props.stackOptions?.layerOptions?.version}`
+          }
+        }
+      );
+      layers.push(existingLayer);
+    }
+    const { function: lambdaFunction } = new BaseLambdaConstruct(this, "lambda", {
+      stage: props.stackOptions?.stage,
+      stackName: props.stackName,
+      options: {
+        lambdaOptions: { layers }
+      }
+    });
+    new BaseApiGatewayV2Construct(this, "apiGateway", {
+      handlerFunctions: [lambdaFunction],
+      options: {
+        gatewayOptions: {
+          apiName: props.stackName,
+          corsPreflight: {
+            allowOrigins: ["*"]
+          }
+        },
+        routeOptions: [
+          {
+            path: "/{proxy+}",
+            methods: [awsApigatewayv2.HttpMethod.ANY]
+          }
+        ]
+      }
+    });
+  }
+};
+var BaseLambdaSqsStack = class extends awsCdkLib.Stack {
+  static {
+    __name(this, "BaseLambdaSqsStack");
+  }
+  constructor(scope, id, props) {
+    super(scope, id, props);
+    let layers = [];
+    if (props?.stackOptions?.layerOptions) {
+      if (!props.stackOptions?.layerOptions?.name || !props.stackOptions?.layerOptions?.version) {
+        throw new toolkit.CustomException("Invalid layer options provided");
+      }
+      const { existingLayer } = new BaseLambdaLayerConstruct(
+        this,
+        "layer",
+        {
+          options: {
+            fromExistingLayerArn: `arn:aws:lambda:${props.env?.region}:${props.env?.account}:layer:${props.stackOptions?.layerOptions?.name}:${props.stackOptions?.layerOptions?.version}`
+          }
+        }
+      );
+      layers.push(existingLayer);
+    }
+    const { function: lambdaFunction } = new BaseLambdaConstruct(this, "lambda", {
+      stage: props.stackOptions?.stage,
+      stackName: props.stackName,
+      options: {
+        lambdaOptions: { layers }
+      }
+    });
+    new BaseSqsConstruct(this, "sqs", {
+      targetFunctions: [lambdaFunction],
+      options: {
+        eventSourceMappingOptions: {},
+        queueOptions: {}
+      }
+    });
+  }
+};
+var BaseLambdaSnsStack = class extends awsCdkLib.Stack {
+  static {
+    __name(this, "BaseLambdaSnsStack");
+  }
+  constructor(scope, id, props) {
+    super(scope, id, props);
+    let layers = [];
+    if (props?.stackOptions?.layerOptions) {
+      if (!props.stackOptions?.layerOptions?.name || !props.stackOptions?.layerOptions?.version) {
+        throw new toolkit.CustomException("Invalid layer options provided");
+      }
+      const { existingLayer } = new BaseLambdaLayerConstruct(
+        this,
+        "layer",
+        {
+          options: {
+            fromExistingLayerArn: `arn:aws:lambda:${props.env?.region}:${props.env?.account}:layer:${props.stackOptions?.layerOptions?.name}:${props.stackOptions?.layerOptions?.version}`
+          }
+        }
+      );
+      layers.push(existingLayer);
+    }
+    const { function: lambdaFunction } = new BaseLambdaConstruct(this, "lambda", {
+      stage: props.stackOptions?.stage,
+      stackName: props.stackName,
+      options: {
+        lambdaOptions: { layers }
+      }
+    });
+    new BaseSnsConstruct(this, "sns", {
+      options: {
+        targetFunctions: [lambdaFunction],
+        topicOptions: {
+          ...props?.stackOptions?.topicOptions,
+          topicName: props?.stackOptions?.topicOptions?.topicName || props.stackName
+        }
+      }
+    });
+  }
+};
 
 exports.BaseApiGatewayConstruct = BaseApiGatewayConstruct;
 exports.BaseApiGatewayV2Construct = BaseApiGatewayV2Construct;
@@ -891,11 +1084,15 @@ exports.BaseCloudfrontConstruct = BaseCloudfrontConstruct;
 exports.BaseCloudwatchLogGroupConstruct = BaseCloudwatchLogGroupConstruct;
 exports.BaseDynamoDBConstruct = BaseDynamoDBConstruct;
 exports.BaseEventBridgeConstruct = BaseEventBridgeConstruct;
+exports.BaseLambdaApiStack = BaseLambdaApiStack;
 exports.BaseLambdaAuthoriserConstruct = BaseLambdaAuthoriserConstruct;
 exports.BaseLambdaAuthoriserV2Construct = BaseLambdaAuthoriserV2Construct;
 exports.BaseLambdaConstruct = BaseLambdaConstruct;
 exports.BaseLambdaLayerConstruct = BaseLambdaLayerConstruct;
+exports.BaseLambdaSnsStack = BaseLambdaSnsStack;
+exports.BaseLambdaSqsStack = BaseLambdaSqsStack;
 exports.BaseRolePolicyConstruct = BaseRolePolicyConstruct;
+exports.BaseRoute53Construct = BaseRoute53Construct;
 exports.BaseS3Construct = BaseS3Construct;
 exports.BaseS3DeploymentConstruct = BaseS3DeploymentConstruct;
 exports.BaseSnsConstruct = BaseSnsConstruct;