@composurecdk/lambda 0.10.0 → 0.10.1

package/README.md

@@ -49,6 +49,32 @@ const handler = createFunctionBuilder()
   .build(stack, "MyFunction");
 ```
 
+## Environment variables
+
+Each **value** in `.environment(...)` is independently `Resolvable`, so a variable can carry a sibling's output while the rest stay literal:
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+import { createRestApiBuilder, type RestApiBuilderResult } from "@composurecdk/apigateway";
+
+compose(
+  {
+    api: createRestApiBuilder().restApiName("Orders"),
+    worker: createFunctionBuilder()
+      .runtime(Runtime.NODEJS_22_X)
+      .handler("index.handler")
+      .code(Code.fromAsset("lambda"))
+      .environment({
+        API_URL: ref("api", (r: RestApiBuilderResult) => r.api.url),
+        LOG_LEVEL: "info",
+      }),
+  },
+  { api: [], worker: ["api"] },
+);
+```
+
+Per value rather than over the whole record, because mixing the two is the common case: wrapping the record would push every literal through the same `ref`, and through [`combine`](../core/README.md) as soon as two siblings are involved.
+
 ## Environment variable encryption
 
 Lambda encrypts environment variables at rest with an AWS-managed key. `.environmentEncryption(...)` opts into a customer-managed one, and accepts a concrete key or a `Resolvable`, so a key built by [`@composurecdk/kms`](../kms/README.md) can be a component of the same system rather than a construct created before `compose`:
@@ -402,6 +428,155 @@ today (the queue often arrives as an unresolved `ref()`); they are tracked in
 `kinesisEventSource` is still deferred — see
 [#120](https://github.com/laazyj/composureCDK/issues/120).
 
+## Deploy-time invocation: `.invokeOnDeploy()`
+
+Some work has to happen _as part of shipping the stack_, and its outcome has to
+gate the deployment: registering the release with an external service, calling
+the system you just deployed to prove it answers, seeding reference data through
+a service API. `.invokeOnDeploy()` invokes the function once during deployment
+and **fails the deployment if the function fails** — the stack rolls back and
+the handler's error message lands in the CloudFormation events.
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+import { createFunctionBuilder } from "@composurecdk/lambda";
+
+compose(
+  {
+    register: createFunctionBuilder()
+      .runtime(Runtime.NODEJS_22_X)
+      .handler("index.handler")
+      .code(Code.fromAsset("register"))
+      .timeout(Duration.seconds(30))
+      .environment({ API_URL: "https://releases.example.com/v1/register" })
+      .invokeOnDeploy({ after: [ref("api", (r: RestApiBuilderResult) => r.api)] }),
+
+    api: createRestApiBuilder().restApiName("Orders"),
+  },
+  { api: [], register: ["api"] },
+).build(stack, "Release");
+```
+
+### What it is
+
+If you already write CDK custom resources, the whole mental model is one
+sentence: **it is CDK's
+[`triggers.Trigger`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.triggers-readme.html),
+with the synchronous invocation fixed and the wait and ordering derived from the
+function.** Everything below is detail on those defaults.
+
+Worth stating plainly, because the other two tools look right and are not.
+`custom_resources.Provider` wants a handler of yours that speaks the
+CloudFormation custom-resource protocol. `AwsCustomResource` runs one fixed SDK
+call with no handler of yours — and reaching for `Lambda.invoke` there
+[reports success when your handler fails](../custom-resources/README.md).
+`Trigger` is the one that invokes a plain handler and fails the stack on an
+error, and it is the least known of the three.
+
+It is a domain action on the function builder
+([ADR-0016](../../docs/adr/0016-domain-action-custom-resource.md)): you declare
+the intent, the builder owns the invocation semantics, the wait derivation, the
+execution-role ordering and the IAM. The custom resource is exposed on the build
+result as `deploymentTrigger`, so a sibling can be ordered against the call
+itself (`deploymentTrigger.executeBefore(...)`).
+
+Three things reach the template:
+
+- **A `Custom::Trigger`**, carrying the handler ARN, the invocation type, the
+  wait, and `ExecuteOnHandlerChange`.
+- **A trigger provider Lambda and its role** — one per stack, shared by every
+  `Trigger` in it, created by CDK rather than by this builder.
+- **An `AWS::Lambda::Version` of your function.** `Trigger` addresses the handler
+  by its `currentVersion`, so calling `.invokeOnDeploy()` publishes a version —
+  unconditionally, including under `executeOnHandlerChange: false`. That is the
+  re-invocation mechanism rather than an accident: the version ARN changes when
+  the function's code or configuration does, and that property change is what
+  CloudFormation acts on.
+
+### The handler must throw
+
+**A handler that returns an error rather than throwing does not fail the
+deployment.** Lambda considers an invocation that returns successful no matter
+what the payload says, so an HTTP-shaped `{ statusCode: 500 }` — or a caught
+error folded into the response — deploys green:
+
+```ts
+export const handler = async () => {
+  const response = await fetch(process.env.API_URL, { method: "POST" });
+  if (!response.ok) {
+    // Throw. Returning `{ statusCode: response.status }` here would deploy green.
+    throw new Error(`Registration failed: ${response.status} ${await response.text()}`);
+  }
+};
+```
+
+### Ordering
+
+The function's own execution role is always waited for, so the policies attached
+_to it_ by `.grant()` and `.configureRole()` exist before the handler runs —
+CloudFormation does not otherwise sequence those ahead of a custom resource, and
+the handler would race them.
+
+That covers the **identity** half of a grant, which is not always the whole
+grant. `grantDecrypt` on a KMS key, or a cross-account bucket grant, also writes
+a **resource** policy, and that half lives in the granting resource's own tree
+where this ordering does not reach. If the handler needs it at deploy time, name
+that resource in `after`.
+
+Everything else the call depends on goes in `after` as well. It takes any
+[`DependencySource`](../core/README.md#ordering-adddependencies) — the same
+shapes as `dependsOn` in
+[`@composurecdk/custom-resources`](../custom-resources/README.md).
+
+One caveat on "always": a role supplied with `.role(Role.fromRoleArn(...))`
+contributes no resources to the template, so there is nothing to sequence and
+the wait is a no-op. Nothing is lost — an imported role's policies were never
+this stack's to create — but do not read it as a guarantee that they are in
+place.
+
+### Defaults
+
+| Option                   | Default                          | Rationale                                                                                                                                                                                |
+| ------------------------ | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| invocation type          | `RequestResponse` (not settable) | The deployment waits for the result. An asynchronous invocation returns before the work happens, reporting success whatever the handler did — the opposite of the point.                 |
+| `timeout`                | function `timeout` + 30s         | The deployment outlives the handler, so a handler that runs to its limit reports _its_ error ("Task timed out after …") instead of the deployment abandoning the call. Capped at 14m30s. |
+| `executeOnHandlerChange` | `true`                           | Re-invokes when the handler's code or configuration changes; a no-op on unrelated stack updates.                                                                                         |
+
+The derivation values are exported as `INVOKE_ON_DEPLOY_DEFAULTS`. With no
+function `timeout` set (or a token one), the wait falls back to 2 minutes,
+matching CDK's own `Trigger` default.
+
+Whenever the wait ends up at or below the function's own timeout, a suppressible
+warning fires under `INVOKE_ON_DEPLOY_TIMEOUT_WARNING_ID` — the deployment would
+stop waiting while the handler is still running, so a slow call fails the stack
+as an abandoned invocation rather than reporting the handler's error. That
+covers an explicit `timeout` set too low, and also a function timeout at or
+above the 14m30s cap, where the cap leaves no margin to add.
+
+The cap is not Lambda's 15-minute ceiling but CDK's trigger provider: that
+provider runs with a 15-minute Lambda timeout of its own and `Trigger` sets no
+`ServiceTimeout` on the custom resource, so a provider that dies mid-wait posts
+nothing back and CloudFormation is never told. The result is a **hung**
+deployment, not a failed one. `.invokeOnDeploy()` therefore **throws** on an
+explicit `timeout` above the cap rather than clamping it, and keeps 30s in hand
+on the derived path so the provider outlives the call it is waiting on.
+
+### What it does not do
+
+- **It does not invoke on every deployment.** With `executeOnHandlerChange: true`
+  the invocation re-runs when the handler changes; with `false` it runs only on
+  the stack's first deployment. CDK's `Trigger` offers no "always" mode.
+- **It does not invoke on stack deletion.** For teardown-time work, use
+  [`@composurecdk/custom-resources`](../custom-resources/README.md), which has
+  create/update/**delete** semantics.
+- **It creates no alarms.** The custom resource runs once per deployment, not
+  continuously; there is no steady-state signal to alarm on. Failures surface as
+  a failed deployment.
+- **It is not a general SDK-call escape hatch.** A call that has no
+  CloudFormation resource but needs no handler of yours belongs in
+  `createAwsCustomResourceBuilder()` — that builder invokes an AWS API directly,
+  no Lambda of yours involved.
+
 ## Examples
 
 - [DualFunctionStack](../examples/src/dual-function-app.ts) — Two Lambda functions with recommended alarms, custom alarms, and SNS alarm actions

package/dist/commonjs/function-builder.d.ts

@@ -2,6 +2,7 @@ import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
 import { type IGrantable, type IRole } from "aws-cdk-lib/aws-iam";
 import { Function as LambdaFunction, type FunctionProps, type IEventSource } from "aws-cdk-lib/aws-lambda";
 import type { LogGroup } from "aws-cdk-lib/aws-logs";
+import type { Trigger } from "aws-cdk-lib/triggers";
 import { type IConstruct } from "constructs";
 import { COPY_STATE, type Grant, type Lifecycle, type Resolvable } from "@composurecdk/core";
 import { type ITaggedBuilder } from "@composurecdk/cloudformation";
@@ -9,16 +10,18 @@ import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
 import { type IRoleBuilder } from "@composurecdk/iam";
 import type { FunctionAlarmConfig } from "./alarm-config.js";
 import { type ComposureEventSource } from "./event-sources/composure-event-source.js";
+import { type InvokeOnDeployOptions } from "./invoke-on-deploy.js";
 /**
  * Configuration properties for the Lambda function builder.
  *
  * Extends the CDK {@link FunctionProps} with builder-specific options. The
- * `role` and `environmentEncryption` props are widened to {@link Resolvable}
- * so a role or key built by a sibling component can be referenced via
- * `ref(...)` at configuration time; both read their inner type from CDK's own
- * prop so they keep tracking it (ADR-0018).
+ * `role` and `environmentEncryption` are widened to {@link Resolvable}, and
+ * `environment` to a record of `Resolvable` values, so a role, key or value
+ * built by a sibling component can be referenced via `ref(...)` at
+ * configuration time. Each reads its inner type from CDK's own prop so they
+ * keep tracking it (ADR-0018).
  */
-export interface FunctionBuilderProps extends Omit<FunctionProps, "role" | "environmentEncryption"> {
+export interface FunctionBuilderProps extends Omit<FunctionProps, "role" | "environmentEncryption" | "environment"> {
     /**
      * The IAM execution role to attach to the function. When set, the builder
      * skips creating its own role and the auto-created `LogsWriter` inline
@@ -52,6 +55,20 @@ export interface FunctionBuilderProps extends Omit<FunctionProps, "role" | "envi
      * @see https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-encryption
      */
     environmentEncryption?: Resolvable<NonNullable<FunctionProps["environmentEncryption"]>>;
+    /**
+     * Key-value pairs the function can read from `process.env` (e.g.
+     * `.environment({ API_URL: ref("api", (r) => r.api.url), LOG_LEVEL: "info" })`).
+     *
+     * Each **value** is independently {@link Resolvable}, rather than the record
+     * as a whole, because mixing a reference with literals is the common case:
+     * wrapping the record would push every literal through the same `ref`, and
+     * through {@link combine} as soon as two siblings are involved. Matches
+     * `validationZones` in `@composurecdk/acm`.
+     *
+     * The value type is read from CDK's own prop rather than written as `string`,
+     * so it tracks `aws-cdk-lib` (ADR-0018).
+     */
+    environment?: Record<string, Resolvable<NonNullable<FunctionProps["environment"]>[string]>>;
     /**
      * Configuration for AWS-recommended CloudWatch alarms.
      *
@@ -131,6 +148,18 @@ export interface FunctionBuilderResult {
      * Always present — `{}` when no event sources were added.
      */
     eventSources: Record<string, IEventSource>;
+    /**
+     * The custom resource that invokes the function during deployment, or
+     * `undefined` unless {@link IFunctionBuilder.invokeOnDeploy} was called.
+     *
+     * Exposed so a sibling can be ordered against the invocation — e.g.
+     * `deploymentTrigger.executeBefore(...)` to gate another resource on the
+     * call having succeeded.
+     *
+     * Optional, unlike the always-present `alarms` / `eventSources` beside it:
+     * there is no empty `Trigger` to stand in for the absence of one.
+     */
+    deploymentTrigger?: Trigger;
 }
 /**
  * A fluent builder for configuring and creating an AWS Lambda function.
@@ -239,6 +268,48 @@ declare class FunctionBuilder implements Lifecycle<FunctionBuilderResult> {
      * Mutually exclusive with {@link role} and {@link configureRole}.
      */
     useCdkAutoRole(): this;
+    /**
+     * Invoke this function once during deployment, and **fail the deployment if
+     * it fails** — a domain action for work that must happen as part of shipping
+     * the stack, such as registering the release with an external service,
+     * verifying the deployed system answers correctly, or seeding reference data
+     * through a service API (ADR-0016).
+     *
+     * The deployment waits for the handler's response. If the handler throws or
+     * times out, the stack fails and rolls back, and the handler's error message
+     * reaches the CloudFormation stack events.
+     *
+     * **The handler must throw to fail the deployment.** Returning an error
+     * object — an HTTP-shaped `{ statusCode: 500 }`, or a caught error swallowed
+     * into the response — is a *successful* invocation as far as Lambda is
+     * concerned, and the deployment goes green.
+     *
+     * Ordering is data: the function's own execution role is always waited for,
+     * and anything else the call needs is declared with
+     * {@link InvokeOnDeployOptions.after}.
+     *
+     * The deployment waits for this function's own `timeout` plus 30s, rather
+     * than the flat 2 minutes CDK's `Trigger` defaults to, so a handler that runs
+     * to its limit reports *its* error instead of the deployment abandoning the
+     * call first. The wait is capped at 14m30s — see
+     * {@link InvokeOnDeployOptions.timeout}, which throws above that rather than
+     * clamping.
+     *
+     * Calling this more than once replaces the previous options. The resulting
+     * custom resource is exposed on
+     * {@link FunctionBuilderResult.deploymentTrigger}.
+     *
+     * @example
+     * ```ts
+     * createFunctionBuilder()
+     *   .runtime(Runtime.NODEJS_22_X)
+     *   .handler("index.handler")
+     *   .code(Code.fromAsset("register"))
+     *   .timeout(Duration.seconds(30))
+     *   .invokeOnDeploy({ after: [ref("api", (r: RestApiBuilderResult) => r.api)] });
+     * ```
+     */
+    invokeOnDeploy(options?: InvokeOnDeployOptions): this;
     /**
      * Grant this function's execution role access to a resource built by a
      * sibling component.

package/dist/commonjs/function-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"function-builder.d.ts","sourceRoot":"","sources":["../../src/function-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"function-builder.d.ts","sourceRoot":"","sources":["../../src/function-builder.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/function-builder.js

@@ -12,6 +12,7 @@ const function_alarms_js_1 = require("./function-alarms.js");
 const defaults_js_1 = require("./defaults.js");
 const composure_event_source_js_1 = require("./event-sources/composure-event-source.js");
 const event_source_relationship_guards_js_1 = require("./event-sources/event-source-relationship-guards.js");
+const invoke_on_deploy_js_1 = require("./invoke-on-deploy.js");
 const LOGS_WRITER_POLICY_NAME = "LogsWriter";
 /**
  * The log group's ARN, wherever the installed `aws-cdk-lib` keeps it.
@@ -45,6 +46,7 @@ class FunctionBuilder {
     #grants = new core_1.GrantQueue();
     #configureRole;
     #useCdkAutoRole = false;
+    #invokeOnDeploy;
     addAlarm(key, configure) {
         this.#customAlarms.push(configure(new cloudwatch_1.AlarmDefinitionBuilder(key)));
         return this;
@@ -108,6 +110,51 @@ class FunctionBuilder {
         this.#useCdkAutoRole = true;
         return this;
     }
+    /**
+     * Invoke this function once during deployment, and **fail the deployment if
+     * it fails** — a domain action for work that must happen as part of shipping
+     * the stack, such as registering the release with an external service,
+     * verifying the deployed system answers correctly, or seeding reference data
+     * through a service API (ADR-0016).
+     *
+     * The deployment waits for the handler's response. If the handler throws or
+     * times out, the stack fails and rolls back, and the handler's error message
+     * reaches the CloudFormation stack events.
+     *
+     * **The handler must throw to fail the deployment.** Returning an error
+     * object — an HTTP-shaped `{ statusCode: 500 }`, or a caught error swallowed
+     * into the response — is a *successful* invocation as far as Lambda is
+     * concerned, and the deployment goes green.
+     *
+     * Ordering is data: the function's own execution role is always waited for,
+     * and anything else the call needs is declared with
+     * {@link InvokeOnDeployOptions.after}.
+     *
+     * The deployment waits for this function's own `timeout` plus 30s, rather
+     * than the flat 2 minutes CDK's `Trigger` defaults to, so a handler that runs
+     * to its limit reports *its* error instead of the deployment abandoning the
+     * call first. The wait is capped at 14m30s — see
+     * {@link InvokeOnDeployOptions.timeout}, which throws above that rather than
+     * clamping.
+     *
+     * Calling this more than once replaces the previous options. The resulting
+     * custom resource is exposed on
+     * {@link FunctionBuilderResult.deploymentTrigger}.
+     *
+     * @example
+     * ```ts
+     * createFunctionBuilder()
+     *   .runtime(Runtime.NODEJS_22_X)
+     *   .handler("index.handler")
+     *   .code(Code.fromAsset("register"))
+     *   .timeout(Duration.seconds(30))
+     *   .invokeOnDeploy({ after: [ref("api", (r: RestApiBuilderResult) => r.api)] });
+     * ```
+     */
+    invokeOnDeploy(options = {}) {
+        this.#invokeOnDeploy = options;
+        return this;
+    }
     /**
      * Grant this function's execution role access to a resource built by a
      * sibling component.
@@ -138,9 +185,10 @@ class FunctionBuilder {
         this.#grants.copyInto(target.#grants);
         target.#configureRole = this.#configureRole;
         target.#useCdkAutoRole = this.#useCdkAutoRole;
+        target.#invokeOnDeploy = this.#invokeOnDeploy;
     }
     build(scope, id, context = {}) {
-        const { role: roleResolvable, environmentEncryption, recommendedAlarms: alarmConfig, ...functionProps } = this.props;
+        const { role: roleResolvable, environmentEncryption, environment, recommendedAlarms: alarmConfig, ...functionProps } = this.props;
         const seamCount = (roleResolvable !== undefined ? 1 : 0) +
             (this.#configureRole !== undefined ? 1 : 0) +
             (this.#useCdkAutoRole ? 1 : 0);
@@ -168,6 +216,7 @@ class FunctionBuilder {
             ...(environmentEncryption !== undefined
                 ? { environmentEncryption: (0, core_1.resolve)(environmentEncryption, context) }
                 : {}),
+            ...(environment !== undefined ? { environment: (0, core_1.resolve)((0, core_1.combine)(environment), context) } : {}),
         };
         const fn = new aws_lambda_1.Function(scope, id, mergedProps);
         this.#grants.applyTo(fn, context);
@@ -207,7 +256,12 @@ class FunctionBuilder {
         if (!resolvedRole) {
             throw new Error(`FunctionBuilder "${id}": Lambda function has no execution role.`);
         }
-        return { function: fn, role: resolvedRole, logGroup, alarms, eventSources };
+        // Built last so the invocation is ordered after everything the builder
+        // attached to the function — grants included.
+        const deploymentTrigger = this.#invokeOnDeploy
+            ? (0, invoke_on_deploy_js_1.createDeploymentTrigger)(scope, id, fn, resolvedRole, this.#invokeOnDeploy, context)
+            : undefined;
+        return { function: fn, role: resolvedRole, logGroup, alarms, eventSources, deploymentTrigger };
     }
     #buildDefaultRole(scope, id, context, logGroup) {
         if (!logGroup) {

package/dist/commonjs/function-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"function-builder.js","sourceRoot":"","sources":["../../src/function-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"function-builder.js","sourceRoot":"","sources":["../../src/function-builder.ts"],"names":[],"mappings":"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"}

package/dist/commonjs/index.d.ts

@@ -1,6 +1,7 @@
 export { createFunctionBuilder, type FunctionBuilderProps, type FunctionBuilderResult, type IFunctionBuilder, } from "./function-builder.js";
 export { functionGrants } from "./grants.js";
 export { FUNCTION_DEFAULTS } from "./defaults.js";
+export { INVOKE_ON_DEPLOY_TIMEOUT_WARNING_ID, INVOKE_ON_DEPLOY_DEFAULTS, type InvokeOnDeployOptions, } from "./invoke-on-deploy.js";
 export { type FunctionAlarmConfig, type PercentageAlarmConfig } from "./alarm-config.js";
 export { FUNCTION_ALARM_DEFAULTS } from "./alarm-defaults.js";
 export { type ComposureEventSource, type EventSourceKind, } from "./event-sources/composure-event-source.js";

package/dist/commonjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,KAAK,mBAAmB,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACzF,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACL,cAAc,EACd,8BAA8B,GAC/B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EACL,iCAAiC,EACjC,qBAAqB,GACtB,MAAM,qDAAqD,CAAC;AAC7D,OAAO,EAAE,iCAAiC,EAAE,MAAM,iDAAiD,CAAC;AACpG,OAAO,EACL,iBAAiB,EACjB,iCAAiC,EACjC,KAAK,4BAA4B,GAClC,MAAM,0CAA0C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,mCAAmC,EACnC,yBAAyB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,mBAAmB,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACzF,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACL,cAAc,EACd,8BAA8B,GAC/B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EACL,iCAAiC,EACjC,qBAAqB,GACtB,MAAM,qDAAqD,CAAC;AAC7D,OAAO,EAAE,iCAAiC,EAAE,MAAM,iDAAiD,CAAC;AACpG,OAAO,EACL,iBAAiB,EACjB,iCAAiC,EACjC,KAAK,4BAA4B,GAClC,MAAM,0CAA0C,CAAC"}

package/dist/commonjs/index.js

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_DYNAMO_EVENT_SOURCE_PROPS = exports.dynamoEventSource = exports.DEFAULT_STREAM_EVENT_SOURCE_PROPS = exports.STREAM_DLQ_WARNING_ID = exports.SQS_VISIBILITY_TIMEOUT_WARNING_ID = exports.DEFAULT_SQS_EVENT_SOURCE_PROPS = exports.sqsEventSource = exports.FUNCTION_ALARM_DEFAULTS = exports.FUNCTION_DEFAULTS = exports.functionGrants = exports.createFunctionBuilder = void 0;
+exports.DEFAULT_DYNAMO_EVENT_SOURCE_PROPS = exports.dynamoEventSource = exports.DEFAULT_STREAM_EVENT_SOURCE_PROPS = exports.STREAM_DLQ_WARNING_ID = exports.SQS_VISIBILITY_TIMEOUT_WARNING_ID = exports.DEFAULT_SQS_EVENT_SOURCE_PROPS = exports.sqsEventSource = exports.FUNCTION_ALARM_DEFAULTS = exports.INVOKE_ON_DEPLOY_DEFAULTS = exports.INVOKE_ON_DEPLOY_TIMEOUT_WARNING_ID = exports.FUNCTION_DEFAULTS = exports.functionGrants = exports.createFunctionBuilder = void 0;
 var function_builder_js_1 = require("./function-builder.js");
 Object.defineProperty(exports, "createFunctionBuilder", { enumerable: true, get: function () { return function_builder_js_1.createFunctionBuilder; } });
 var grants_js_1 = require("./grants.js");
 Object.defineProperty(exports, "functionGrants", { enumerable: true, get: function () { return grants_js_1.functionGrants; } });
 var defaults_js_1 = require("./defaults.js");
 Object.defineProperty(exports, "FUNCTION_DEFAULTS", { enumerable: true, get: function () { return defaults_js_1.FUNCTION_DEFAULTS; } });
+var invoke_on_deploy_js_1 = require("./invoke-on-deploy.js");
+Object.defineProperty(exports, "INVOKE_ON_DEPLOY_TIMEOUT_WARNING_ID", { enumerable: true, get: function () { return invoke_on_deploy_js_1.INVOKE_ON_DEPLOY_TIMEOUT_WARNING_ID; } });
+Object.defineProperty(exports, "INVOKE_ON_DEPLOY_DEFAULTS", { enumerable: true, get: function () { return invoke_on_deploy_js_1.INVOKE_ON_DEPLOY_DEFAULTS; } });
 var alarm_defaults_js_1 = require("./alarm-defaults.js");
 Object.defineProperty(exports, "FUNCTION_ALARM_DEFAULTS", { enumerable: true, get: function () { return alarm_defaults_js_1.FUNCTION_ALARM_DEFAULTS; } });
 var sqs_event_source_js_1 = require("./event-sources/sqs-event-source.js");

package/dist/commonjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,6DAK+B;AAJ7B,4HAAA,qBAAqB,OAAA;AAKvB,yCAA6C;AAApC,2GAAA,cAAc,OAAA;AACvB,6CAAkD;AAAzC,gHAAA,iBAAiB,OAAA;AAE1B,yDAA8D;AAArD,4HAAA,uBAAuB,OAAA;AAKhC,2EAG6C;AAF3C,qHAAA,cAAc,OAAA;AACd,qIAAA,8BAA8B,OAAA;AAEhC,2GAG6D;AAF3D,wJAAA,iCAAiC,OAAA;AACjC,4IAAA,qBAAqB,OAAA;AAEvB,mGAAoG;AAA3F,oJAAA,iCAAiC,OAAA;AAC1C,qFAIkD;AAHhD,6HAAA,iBAAiB,OAAA;AACjB,6IAAA,iCAAiC,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,6DAK+B;AAJ7B,4HAAA,qBAAqB,OAAA;AAKvB,yCAA6C;AAApC,2GAAA,cAAc,OAAA;AACvB,6CAAkD;AAAzC,gHAAA,iBAAiB,OAAA;AAC1B,6DAI+B;AAH7B,0IAAA,mCAAmC,OAAA;AACnC,gIAAA,yBAAyB,OAAA;AAI3B,yDAA8D;AAArD,4HAAA,uBAAuB,OAAA;AAKhC,2EAG6C;AAF3C,qHAAA,cAAc,OAAA;AACd,qIAAA,8BAA8B,OAAA;AAEhC,2GAG6D;AAF3D,wJAAA,iCAAiC,OAAA;AACjC,4IAAA,qBAAqB,OAAA;AAEvB,mGAAoG;AAA3F,oJAAA,iCAAiC,OAAA;AAC1C,qFAIkD;AAHhD,6HAAA,iBAAiB,OAAA;AACjB,6IAAA,iCAAiC,OAAA"}

package/dist/commonjs/invoke-on-deploy.d.ts

@@ -0,0 +1,83 @@
+import { Duration } from "aws-cdk-lib";
+import type { Function as LambdaFunction } from "aws-cdk-lib/aws-lambda";
+import { Trigger } from "aws-cdk-lib/triggers";
+import type { IConstruct } from "constructs";
+import { type DependencySource } from "@composurecdk/core";
+/**
+ * Suppression id for the deploy-time invocation timeout guard. Stable and part
+ * of the public surface — silence the warning with
+ * `Annotations.of(scope).acknowledgeWarning(INVOKE_ON_DEPLOY_TIMEOUT_WARNING_ID)`,
+ * so it must not be renamed casually.
+ */
+export declare const INVOKE_ON_DEPLOY_TIMEOUT_WARNING_ID = "@composurecdk/lambda:invoke-on-deploy-timeout";
+/**
+ * How {@link IFunctionBuilder.invokeOnDeploy | `.invokeOnDeploy()`} derives the
+ * wait when the caller sets no {@link InvokeOnDeployOptions.timeout}. A public
+ * mirror of this module's constants, exported for visibility and testing — the
+ * rationale for each value is on the constant it mirrors.
+ */
+export declare const INVOKE_ON_DEPLOY_DEFAULTS: {
+    /** @see {@link TIMEOUT_MARGIN} */
+    readonly timeoutMargin: Duration;
+    /** @see {@link FALLBACK_TIMEOUT} */
+    readonly fallbackTimeout: Duration;
+    /** @see {@link MAX_TIMEOUT} */
+    readonly maxTimeout: Duration;
+};
+/**
+ * Options for {@link IFunctionBuilder.invokeOnDeploy | `.invokeOnDeploy()`}.
+ */
+export interface InvokeOnDeployOptions {
+    /**
+     * What must be fully provisioned before the handler runs — see
+     * {@link DependencySource} for the shapes it takes and what each one reaches.
+     *
+     * The function's own execution role, and therefore every policy attached to
+     * it by `.grant()` or `.configureRole()`, is already waited for. This is for
+     * everything else the call depends on: the API it will call, the table it
+     * will seed — and the resource behind any grant that writes a *resource*
+     * policy rather than an identity one, such as a KMS key, since that half is
+     * not attached to the role and so is not covered.
+     */
+    readonly after?: DependencySource[];
+    /**
+     * How long the deployment waits for the handler before failing the stack.
+     *
+     * Defaults to the function's own `timeout` plus
+     * {@link INVOKE_ON_DEPLOY_DEFAULTS.timeoutMargin}, capped at
+     * {@link INVOKE_ON_DEPLOY_DEFAULTS.maxTimeout}. Setting it at or below the
+     * function's timeout warns under {@link INVOKE_ON_DEPLOY_TIMEOUT_WARNING_ID};
+     * setting it above `maxTimeout` throws, because the provider would not
+     * survive the wait to report anything.
+     */
+    readonly timeout?: Duration;
+    /**
+     * Re-invoke the handler whenever its code or configuration changes.
+     *
+     * `true` (the default) binds the invocation to the function's current
+     * version, so it re-runs on a handler change and is a no-op on unrelated
+     * stack updates — right for an idempotent registration. `false` invokes only
+     * on the stack's *first* deployment. Neither setting invokes on every
+     * deployment; that is not something CDK's `Trigger` offers.
+     */
+    readonly executeOnHandlerChange?: boolean;
+}
+/**
+ * Creates the custom resource that invokes `handler` during deployment and
+ * fails the stack if it errors.
+ *
+ * The invocation is ordered after the function's execution role, so the policies
+ * attached *to it* by `.grant()` / `.configureRole()` — which CloudFormation
+ * does not otherwise sequence ahead of a custom resource — exist by the time the
+ * handler runs.
+ *
+ * That reaches the identity half of a grant only: one that also writes a
+ * resource policy (a KMS key policy, a cross-account bucket policy) leaves that
+ * half in the granting resource's tree, and an imported role contributes no
+ * resources to sequence at all. Both are the consumer's to declare through
+ * {@link InvokeOnDeployOptions.after}, as is anything else the call needs.
+ *
+ * @internal
+ */
+export declare function createDeploymentTrigger(scope: IConstruct, id: string, handler: LambdaFunction, executionRole: IConstruct, options: InvokeOnDeployOptions, context: Record<string, object>): Trigger;
+//# sourceMappingURL=invoke-on-deploy.d.ts.map

package/dist/commonjs/invoke-on-deploy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke-on-deploy.d.ts","sourceRoot":"","sources":["../../src/invoke-on-deploy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,QAAQ,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,IAAI,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAkB,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE5E;;;;;GAKG;AACH,eAAO,MAAM,mCAAmC,kDAAkD,CAAC;AA6CnG;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;IACpC,kCAAkC;;IAGlC,oCAAoC;;IAGpC,+BAA+B;;CAEvB,CAAC;AAEX;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAEpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC;IAE5B;;;;;;;;OAQG;IACH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,cAAc,EACvB,aAAa,EAAE,UAAU,EACzB,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,OAAO,CAaT"}