@composurecdk/neptune 0.8.3

package/dist/esm/cluster-alarm-config.d.ts

@@ -0,0 +1,77 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+/**
+ * Controls which recommended alarms are created for a Neptune cluster.
+ * All applicable alarms are enabled by default with thresholds drawn from
+ * the Neptune team's own metric guidance. Set an individual alarm to `false`
+ * to disable it, or provide an {@link AlarmConfig} to tune its thresholds.
+ *
+ * Neptune is not yet covered by the CloudWatch out-of-the-box alarm
+ * recommendations table, so these thresholds are anchored to the Neptune
+ * User Guide's metrics guidance and the Neptune Well-Architected lens rather
+ * than to that table.
+ *
+ * @see https://docs.aws.amazon.com/neptune/latest/userguide/best-practices-general-metrics.html
+ * @see https://docs.aws.amazon.com/prescriptive-guidance/latest/neptune-well-architected-framework/introduction.html
+ */
+export interface NeptuneClusterAlarmConfig {
+    /**
+     * Master switch: set to `false` to disable all recommended alarms.
+     * Individual alarms can also be disabled via their own entry.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Alarm on sustained high CPU on the cluster's instances — the primary
+     * signal of a saturated writer or undersized instance.
+     *
+     * Metric: `AWS/Neptune CPUUtilization`, statistic Average, period 1 minute.
+     * Default threshold: >= 80%.
+     *
+     * @see https://docs.aws.amazon.com/neptune/latest/userguide/cloudwatch-monitoring-instances.html
+     */
+    cpuUtilization?: AlarmConfig | false;
+    /**
+     * Alarm when requests are queuing faster than the engine can execute them.
+     *
+     * Metric: `AWS/Neptune MainRequestQueuePendingRequests`, statistic Average,
+     * period 1 minute. Default threshold: > 100 pending requests.
+     *
+     * @see https://docs.aws.amazon.com/neptune/latest/userguide/best-practices-general-metrics.html
+     */
+    mainRequestQueuePendingRequests?: AlarmConfig | false;
+    /**
+     * Alarm when the buffer cache hit ratio drops, indicating the working set
+     * no longer fits in memory and query latency is dominated by I/O.
+     *
+     * Metric: `AWS/Neptune BufferCacheHitRatio`, statistic Average, period 1
+     * minute. Default threshold: < 99.9%.
+     *
+     * @see https://docs.aws.amazon.com/neptune/latest/userguide/best-practices-general-metrics.html
+     */
+    bufferCacheHitRatio?: AlarmConfig | false;
+    /**
+     * Alarm when a read replica falls too far behind the writer. Only emits
+     * data when the cluster has at least one replica, so it stays quiet on a
+     * single-instance cluster (`TreatMissingData.NOT_BREACHING`).
+     *
+     * Metric: `AWS/Neptune ClusterReplicaLag`, statistic Average, period 1
+     * minute. Default threshold: > 30000 ms.
+     *
+     * @see https://docs.aws.amazon.com/neptune/latest/userguide/cw-metrics.html
+     */
+    clusterReplicaLag?: AlarmConfig | false;
+    /**
+     * Alarm when a serverless cluster sustains capacity near its configured
+     * ceiling, indicating the max NCU setting is too low or query load is
+     * running away. Only created when the cluster is serverless (i.e.
+     * `serverlessScalingConfiguration` is set); the default threshold is
+     * derived as 90% of the configured `maxCapacity`.
+     *
+     * Metric: `AWS/Neptune ServerlessDatabaseCapacity`, statistic Average,
+     * period 1 minute.
+     *
+     * @see https://docs.aws.amazon.com/neptune/latest/userguide/neptune-serverless-capacity-scaling.html
+     */
+    serverlessDatabaseCapacity?: AlarmConfig | false;
+}
+//# sourceMappingURL=cluster-alarm-config.d.ts.map

package/dist/esm/cluster-alarm-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-alarm-config.d.ts","sourceRoot":"","sources":["../../src/cluster-alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAErC;;;;;;;OAOG;IACH,+BAA+B,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEtD;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAE1C;;;;;;;;;OASG;IACH,iBAAiB,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAExC;;;;;;;;;;;OAWG;IACH,0BAA0B,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CAClD"}

package/dist/esm/cluster-alarm-config.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cluster-alarm-config.js.map

package/dist/esm/cluster-alarm-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-alarm-config.js","sourceRoot":"","sources":["../../src/cluster-alarm-config.ts"],"names":[],"mappings":""}

package/dist/esm/cluster-alarm-defaults.d.ts

@@ -0,0 +1,20 @@
+import type { AlarmConfigDefaults } from "@composurecdk/cloudwatch";
+interface ClusterAlarmDefaults {
+    enabled: true;
+    cpuUtilization: AlarmConfigDefaults;
+    mainRequestQueuePendingRequests: AlarmConfigDefaults;
+    bufferCacheHitRatio: AlarmConfigDefaults;
+    clusterReplicaLag: AlarmConfigDefaults;
+    /** `threshold` is unused — the real value is derived from `maxCapacity` at build time. */
+    serverlessDatabaseCapacity: AlarmConfigDefaults;
+}
+/**
+ * Recommended default alarm configuration for Neptune clusters. Thresholds
+ * follow the Neptune team's metric guidance; Neptune is absent from the
+ * CloudWatch recommended-alarms table, so no anchor to that page exists.
+ *
+ * @see https://docs.aws.amazon.com/neptune/latest/userguide/best-practices-general-metrics.html
+ */
+export declare const CLUSTER_ALARM_DEFAULTS: ClusterAlarmDefaults;
+export {};
+//# sourceMappingURL=cluster-alarm-defaults.d.ts.map

package/dist/esm/cluster-alarm-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/cluster-alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,UAAU,oBAAoB;IAC5B,OAAO,EAAE,IAAI,CAAC;IACd,cAAc,EAAE,mBAAmB,CAAC;IACpC,+BAA+B,EAAE,mBAAmB,CAAC;IACrD,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,iBAAiB,EAAE,mBAAmB,CAAC;IACvC,0FAA0F;IAC1F,0BAA0B,EAAE,mBAAmB,CAAC;CACjD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,oBA4CpC,CAAC"}

package/dist/esm/cluster-alarm-defaults.js

@@ -0,0 +1,49 @@
+import { TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+/**
+ * Recommended default alarm configuration for Neptune clusters. Thresholds
+ * follow the Neptune team's metric guidance; Neptune is absent from the
+ * CloudWatch recommended-alarms table, so no anchor to that page exists.
+ *
+ * @see https://docs.aws.amazon.com/neptune/latest/userguide/best-practices-general-metrics.html
+ */
+export const CLUSTER_ALARM_DEFAULTS = {
+    enabled: true,
+    /** Sustained CPU at/above 80% over several minutes signals saturation. */
+    cpuUtilization: {
+        threshold: 80,
+        evaluationPeriods: 5,
+        datapointsToAlarm: 3,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    /** A growing request backlog means the engine cannot keep up with load. */
+    mainRequestQueuePendingRequests: {
+        threshold: 100,
+        evaluationPeriods: 5,
+        datapointsToAlarm: 3,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    /** A cache hit ratio below 99.9% indicates the working set exceeds memory. */
+    bufferCacheHitRatio: {
+        threshold: 99.9,
+        evaluationPeriods: 15,
+        datapointsToAlarm: 10,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    /** Replica lag over 30s risks stale reads; quiet on single-instance clusters. */
+    clusterReplicaLag: {
+        threshold: 30_000,
+        evaluationPeriods: 5,
+        datapointsToAlarm: 3,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    // `threshold` is a required-shape filler: the serverless capacity alarm
+    // always derives its threshold from `maxCapacity` at build time (or a user
+    // override), so this value is never read. The evaluation window is.
+    serverlessDatabaseCapacity: {
+        threshold: 0,
+        evaluationPeriods: 15,
+        datapointsToAlarm: 10,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=cluster-alarm-defaults.js.map

package/dist/esm/cluster-alarm-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-alarm-defaults.js","sourceRoot":"","sources":["../../src/cluster-alarm-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAa9D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAyB;IAC1D,OAAO,EAAE,IAAI;IAEb,0EAA0E;IAC1E,cAAc,EAAE;QACd,SAAS,EAAE,EAAE;QACb,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED,2EAA2E;IAC3E,+BAA+B,EAAE;QAC/B,SAAS,EAAE,GAAG;QACd,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED,8EAA8E;IAC9E,mBAAmB,EAAE;QACnB,SAAS,EAAE,IAAI;QACf,iBAAiB,EAAE,EAAE;QACrB,iBAAiB,EAAE,EAAE;QACrB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED,iFAAiF;IACjF,iBAAiB,EAAE;QACjB,SAAS,EAAE,MAAM;QACjB,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED,wEAAwE;IACxE,2EAA2E;IAC3E,oEAAoE;IACpE,0BAA0B,EAAE;QAC1B,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,EAAE;QACrB,iBAAiB,EAAE,EAAE;QACrB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/esm/cluster-alarms.d.ts

@@ -0,0 +1,25 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { IDatabaseCluster, ServerlessScalingConfiguration } from "@aws-cdk/aws-neptune-alpha";
+import type { IConstruct } from "constructs";
+import type { AlarmDefinition, AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { NeptuneClusterAlarmConfig } from "./cluster-alarm-config.js";
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for a Neptune cluster. The serverless capacity
+ * alarm is only emitted when `serverlessScaling` is provided.
+ */
+export declare function resolveClusterAlarmDefinitions(cluster: IDatabaseCluster, config: NeptuneClusterAlarmConfig | undefined, serverlessScaling: ServerlessScalingConfiguration | undefined): AlarmDefinition[];
+/**
+ * Creates recommended CloudWatch alarms for a Neptune cluster, merging the
+ * recommended definitions with any custom alarm builders.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param cluster - The Neptune cluster to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param serverlessScaling - The cluster's serverless scaling config, if any.
+ * @param customAlarms - Custom alarm builders added via `addAlarm()`.
+ * @returns A record mapping alarm keys to their created Alarm constructs.
+ */
+export declare function createClusterAlarms(scope: IConstruct, id: string, cluster: IDatabaseCluster, config: NeptuneClusterAlarmConfig | false | undefined, serverlessScaling: ServerlessScalingConfiguration | undefined, customAlarms?: AlarmDefinitionBuilder<IDatabaseCluster>[]): Record<string, Alarm>;
+//# sourceMappingURL=cluster-alarms.d.ts.map

package/dist/esm/cluster-alarms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-alarms.d.ts","sourceRoot":"","sources":["../../src/cluster-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAsB,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AACnG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAExF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAY3E;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,yBAAyB,GAAG,SAAS,EAC7C,iBAAiB,EAAE,8BAA8B,GAAG,SAAS,GAC5D,eAAe,EAAE,CA4GnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,yBAAyB,GAAG,KAAK,GAAG,SAAS,EACrD,iBAAiB,EAAE,8BAA8B,GAAG,SAAS,EAC7D,YAAY,GAAE,sBAAsB,CAAC,gBAAgB,CAAC,EAAO,GAC5D,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}

package/dist/esm/cluster-alarms.js

@@ -0,0 +1,129 @@
+import { Duration } from "aws-cdk-lib";
+import { ComparisonOperator } from "aws-cdk-lib/aws-cloudwatch";
+import { createAlarms, resolveAlarmConfig } from "@composurecdk/cloudwatch";
+import { CLUSTER_ALARM_DEFAULTS } from "./cluster-alarm-defaults.js";
+const METRIC_PERIOD = Duration.minutes(1);
+const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minute`;
+/**
+ * Fraction of a serverless cluster's configured `maxCapacity` at which the
+ * `serverlessDatabaseCapacity` alarm fires by default.
+ */
+const SERVERLESS_CAPACITY_ALARM_FRACTION = 0.9;
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for a Neptune cluster. The serverless capacity
+ * alarm is only emitted when `serverlessScaling` is provided.
+ */
+export function resolveClusterAlarmDefinitions(cluster, config, serverlessScaling) {
+    if (config?.enabled === false)
+        return [];
+    const definitions = [];
+    if (config?.cpuUtilization !== false) {
+        const cfg = resolveAlarmConfig(config?.cpuUtilization, CLUSTER_ALARM_DEFAULTS.cpuUtilization);
+        definitions.push({
+            key: "cpuUtilization",
+            alarmName: cfg.alarmName,
+            metric: cluster.metric("CPUUtilization", { period: METRIC_PERIOD, statistic: "Average" }),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `Neptune cluster CPU utilization is high. Threshold: >= ${String(cfg.threshold)}% over ${METRIC_PERIOD_LABEL} periods.`,
+        });
+    }
+    if (config?.mainRequestQueuePendingRequests !== false) {
+        const cfg = resolveAlarmConfig(config?.mainRequestQueuePendingRequests, CLUSTER_ALARM_DEFAULTS.mainRequestQueuePendingRequests);
+        definitions.push({
+            key: "mainRequestQueuePendingRequests",
+            alarmName: cfg.alarmName,
+            metric: cluster.metric("MainRequestQueuePendingRequests", {
+                period: METRIC_PERIOD,
+                statistic: "Average",
+            }),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `Neptune cluster request queue is backing up. Threshold: > ${String(cfg.threshold)} pending requests over ${METRIC_PERIOD_LABEL} periods.`,
+        });
+    }
+    if (config?.bufferCacheHitRatio !== false) {
+        const cfg = resolveAlarmConfig(config?.bufferCacheHitRatio, CLUSTER_ALARM_DEFAULTS.bufferCacheHitRatio);
+        definitions.push({
+            key: "bufferCacheHitRatio",
+            alarmName: cfg.alarmName,
+            metric: cluster.metric("BufferCacheHitRatio", {
+                period: METRIC_PERIOD,
+                statistic: "Average",
+            }),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.LESS_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `Neptune cluster buffer cache hit ratio is low; working set may exceed memory. Threshold: < ${String(cfg.threshold)}% over ${METRIC_PERIOD_LABEL} periods.`,
+        });
+    }
+    if (config?.clusterReplicaLag !== false) {
+        const cfg = resolveAlarmConfig(config?.clusterReplicaLag, CLUSTER_ALARM_DEFAULTS.clusterReplicaLag);
+        definitions.push({
+            key: "clusterReplicaLag",
+            alarmName: cfg.alarmName,
+            metric: cluster.metric("ClusterReplicaLag", { period: METRIC_PERIOD, statistic: "Average" }),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `Neptune read replica is lagging the writer. Threshold: > ${String(cfg.threshold)} ms over ${METRIC_PERIOD_LABEL} periods.`,
+        });
+    }
+    // Contextual: only meaningful for a serverless cluster, where capacity is
+    // measured in NCUs and a ceiling is configured. The threshold defaults to a
+    // fraction of the configured maximum.
+    if (serverlessScaling !== undefined && config?.serverlessDatabaseCapacity !== false) {
+        const cfg = resolveAlarmConfig(config?.serverlessDatabaseCapacity, CLUSTER_ALARM_DEFAULTS.serverlessDatabaseCapacity);
+        const threshold = config?.serverlessDatabaseCapacity?.threshold ??
+            serverlessScaling.maxCapacity * SERVERLESS_CAPACITY_ALARM_FRACTION;
+        definitions.push({
+            key: "serverlessDatabaseCapacity",
+            alarmName: cfg.alarmName,
+            metric: cluster.metric("ServerlessDatabaseCapacity", {
+                period: METRIC_PERIOD,
+                statistic: "Average",
+            }),
+            threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `Neptune serverless capacity is sustained near its ${String(serverlessScaling.maxCapacity)} NCU ceiling. Threshold: >= ${String(threshold)} NCU over ${METRIC_PERIOD_LABEL} periods.`,
+        });
+    }
+    return definitions;
+}
+/**
+ * Creates recommended CloudWatch alarms for a Neptune cluster, merging the
+ * recommended definitions with any custom alarm builders.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param cluster - The Neptune cluster to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param serverlessScaling - The cluster's serverless scaling config, if any.
+ * @param customAlarms - Custom alarm builders added via `addAlarm()`.
+ * @returns A record mapping alarm keys to their created Alarm constructs.
+ */
+export function createClusterAlarms(scope, id, cluster, config, serverlessScaling, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? CLUSTER_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveClusterAlarmDefinitions(cluster, config, serverlessScaling);
+    const custom = customAlarms.map((b) => b.resolve(cluster));
+    return createAlarms(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=cluster-alarms.js.map

package/dist/esm/cluster-alarms.js.map

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

package/dist/esm/cluster-builder.d.ts

@@ -0,0 +1,194 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import { type IConnectable, type ISecurityGroup, type IVpc } from "aws-cdk-lib/aws-ec2";
+import { type IGrantable } from "aws-cdk-lib/aws-iam";
+import { DatabaseCluster, type DatabaseClusterProps, type IClusterParameterGroup, type IDatabaseCluster, type ISubnetGroup } from "@aws-cdk/aws-neptune-alpha";
+import { type IConstruct } from "constructs";
+import { COPY_STATE, type Lifecycle, type Resolvable } from "@composurecdk/core";
+import { type ITaggedBuilder } from "@composurecdk/cloudformation";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { NeptuneClusterAlarmConfig } from "./cluster-alarm-config.js";
+/**
+ * A principal that can be granted access to a Neptune cluster via
+ * {@link IClusterBuilder.allowAccessFrom}. Must be both an {@link IConnectable}
+ * (so its security group can be opened to the cluster's port) and an
+ * {@link IGrantable} (so it can be granted IAM `connect`). EC2 instances,
+ * Lambda functions, and Fargate tasks all satisfy this.
+ */
+export type ClusterAccessor = IConnectable & IGrantable;
+/**
+ * Configuration properties for the Neptune cluster builder.
+ *
+ * Extends the CDK {@link DatabaseClusterProps} but lifts the
+ * cross-component-wiring props to {@link Resolvable} so they can be supplied
+ * as either concrete values or {@link Ref}s to sibling components in a
+ * {@link compose}d system:
+ *
+ * - `vpc` is supplied via the dedicated {@link IClusterBuilder.vpc | .vpc()}
+ *   method (it is required).
+ * - `securityGroups` accepts `Resolvable<ISecurityGroup>` entries.
+ *
+ * It also adds builder-specific options for the auto-created cluster
+ * parameter group and recommended alarms.
+ */
+export interface ClusterBuilderProps extends Omit<DatabaseClusterProps, "vpc" | "securityGroups"> {
+    /**
+     * Security groups to attach to the cluster. Accepts concrete
+     * {@link ISecurityGroup}s or {@link Ref}s that resolve to them at build
+     * time (e.g. a sibling `SecurityGroupBuilder`).
+     *
+     * @default - CDK creates a security group for the cluster.
+     */
+    securityGroups?: readonly Resolvable<ISecurityGroup>[];
+    /**
+     * Parameters to set on the auto-created cluster parameter group, merged
+     * onto (and overriding) {@link CLUSTER_PARAMETER_GROUP_DEFAULTS}. Use this
+     * to tune engine behaviour without managing a parameter group yourself.
+     *
+     * Mutually exclusive with `clusterParameterGroup`: a user-managed group is
+     * not built (or mutated) by this builder.
+     */
+    clusterParameters?: Record<string, string>;
+    /**
+     * Configuration for recommended CloudWatch alarms.
+     *
+     * By default the builder creates recommended alarms with sensible
+     * thresholds for every applicable metric. Individual alarms can be
+     * customized or disabled. Set to `false` to disable all alarms.
+     *
+     * No alarm actions are configured by default since notification methods
+     * are user-specific. Access alarms from the build result or use an
+     * `afterBuild` hook to apply actions.
+     */
+    recommendedAlarms?: NeptuneClusterAlarmConfig | false;
+}
+/**
+ * The build output of an {@link IClusterBuilder}. Contains the CDK
+ * constructs created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface ClusterBuilderResult {
+    /** The Neptune cluster, including the writer/reader instances it manages. */
+    cluster: DatabaseCluster;
+    /**
+     * The DB subnet group the cluster runs in. CDK auto-creates this from the
+     * VPC; it is exposed here so it can be reused or asserted against.
+     */
+    subnetGroup: ISubnetGroup;
+    /**
+     * The cluster parameter group — either the one supplied via
+     * `.clusterParameterGroup()` or the audit-log-enabled group the builder
+     * auto-creates.
+     */
+    clusterParameterGroup: IClusterParameterGroup;
+    /**
+     * CloudWatch alarms created for the cluster, keyed by alarm key (e.g.
+     * `result.alarms.cpuUtilization`). Includes recommended alarms and any
+     * added via {@link IClusterBuilder.addAlarm}. No alarm actions are
+     * configured — apply them via the result or an `afterBuild` hook.
+     */
+    alarms: Record<string, Alarm>;
+}
+/**
+ * A fluent builder for configuring and creating an Amazon Neptune cluster.
+ *
+ * Each configuration property from the CDK {@link DatabaseClusterProps} is
+ * exposed as an overloaded method: call with a value to set it (returns the
+ * builder for chaining), or call with no arguments to read the current value.
+ *
+ * The `vpc` is set via the dedicated {@link IClusterBuilder.vpc | .vpc()}
+ * method, which accepts a {@link Resolvable} for cross-component wiring (e.g.
+ * to a sibling `VpcBuilder`). `securityGroups` likewise accept
+ * {@link Resolvable} values.
+ *
+ * The builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}. When built it creates a
+ * cluster with {@link CLUSTER_DEFAULTS | well-architected defaults}, an
+ * audit-log-enabled cluster parameter group, recommended CloudWatch alarms,
+ * and returns a {@link ClusterBuilderResult}.
+ *
+ * Both provisioned and serverless clusters are supported — set a provisioned
+ * `.instanceType(InstanceType.R6G_LARGE)`, or `.instanceType(InstanceType.SERVERLESS)`
+ * with `.serverlessScalingConfiguration({ minCapacity, maxCapacity })`.
+ *
+ * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-neptune-alpha-readme.html
+ *
+ * @example
+ * ```ts
+ * const graph = createClusterBuilder()
+ *   .vpc(ref<VpcBuilderResult>("network").get("vpc"))
+ *   .instanceType(InstanceType.SERVERLESS)
+ *   .serverlessScalingConfiguration({ minCapacity: 1, maxCapacity: 8 });
+ * ```
+ */
+export type IClusterBuilder = ITaggedBuilder<ClusterBuilderProps, ClusterBuilder>;
+declare class ClusterBuilder implements Lifecycle<ClusterBuilderResult> {
+    #private;
+    props: Partial<ClusterBuilderProps>;
+    /**
+     * Sets the VPC the cluster runs in. Required. Accepts a concrete
+     * {@link IVpc} or a {@link Ref} that resolves to one at build time — the
+     * standard cross-component wiring path (e.g. to a sibling `VpcBuilder`).
+     *
+     * @param vpc - The VPC or a Ref to one.
+     * @returns This builder for chaining.
+     */
+    vpc(vpc: Resolvable<IVpc>): this;
+    /**
+     * Grants a principal both network and IAM access to the cluster in a single
+     * declaration. At build time this applies
+     * `cluster.connections.allowDefaultPortFrom(peer)` (opening the cluster's
+     * port to the peer's security group) and `cluster.grantConnect(peer)`
+     * (granting the IAM `connect` action required by the cluster's
+     * IAM-authentication default).
+     *
+     * Accepts a concrete {@link ClusterAccessor} or a {@link Ref} to one, so the
+     * grant can be declared inside `compose()` rather than wired up in an
+     * `afterBuild` hook.
+     *
+     * @param peer - The principal to grant access to, or a Ref to one.
+     * @returns This builder for chaining.
+     */
+    allowAccessFrom(peer: Resolvable<ClusterAccessor>): this;
+    /**
+     * Adds a custom CloudWatch alarm to be created alongside the recommended
+     * alarms. The callback receives an {@link AlarmDefinitionBuilder} scoped to
+     * the built cluster; configure it fluently and return it.
+     *
+     * @param key - A unique key for the alarm (used to generate the alarm id).
+     * @param configure - Callback that configures the alarm definition.
+     * @returns This builder for chaining.
+     */
+    addAlarm(key: string, configure: (alarm: AlarmDefinitionBuilder<IDatabaseCluster>) => AlarmDefinitionBuilder<IDatabaseCluster>): this;
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target: ClusterBuilder): void;
+    build(scope: IConstruct, id: string, context?: Record<string, object>): ClusterBuilderResult;
+}
+/**
+ * Creates a new {@link IClusterBuilder} for configuring an Amazon Neptune
+ * cluster.
+ *
+ * This is the entry point for defining a Neptune component. The returned
+ * builder exposes every {@link ClusterBuilderProps} property as a fluent
+ * setter/getter, plus {@link IClusterBuilder.vpc | .vpc()} and
+ * {@link IClusterBuilder.allowAccessFrom | .allowAccessFrom()} for
+ * cross-component wiring with Ref support. It implements {@link Lifecycle}
+ * for use with {@link compose}.
+ *
+ * @returns A fluent builder for an Amazon Neptune cluster.
+ *
+ * @example
+ * ```ts
+ * const system = compose(
+ *   {
+ *     network: createVpcBuilder().maxAzs(2),
+ *     graph: createClusterBuilder()
+ *       .vpc(ref<VpcBuilderResult>("network").get("vpc"))
+ *       .instanceType(InstanceType.SERVERLESS)
+ *       .serverlessScalingConfiguration({ minCapacity: 1, maxCapacity: 8 }),
+ *   },
+ *   { network: [], graph: ["network"] },
+ * );
+ * ```
+ */
+export declare function createClusterBuilder(): IClusterBuilder;
+export {};
+//# sourceMappingURL=cluster-builder.d.ts.map

package/dist/esm/cluster-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-builder.d.ts","sourceRoot":"","sources":["../../src/cluster-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,KAAK,IAAI,EAAE,MAAM,qBAAqB,CAAC;AACxF,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAEL,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAClB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,KAAK,SAAS,EAAW,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAMlE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAG3E;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,UAAU,CAAC;AAExD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAAC,oBAAoB,EAAE,KAAK,GAAG,gBAAgB,CAAC;IAC/F;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,SAAS,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;IAEvD;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE3C;;;;;;;;;;OAUG;IACH,iBAAiB,CAAC,EAAE,yBAAyB,GAAG,KAAK,CAAC;CACvD;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,OAAO,EAAE,eAAe,CAAC;IAEzB;;;OAGG;IACH,WAAW,EAAE,YAAY,CAAC;IAE1B;;;;OAIG;IACH,qBAAqB,EAAE,sBAAsB,CAAC;IAE9C;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,eAAe,GAAG,cAAc,CAAC,mBAAmB,EAAE,cAAc,CAAC,CAAC;AAElF,cAAM,cAAe,YAAW,SAAS,CAAC,oBAAoB,CAAC;;IAC7D,KAAK,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAM;IAKzC;;;;;;;OAOG;IACH,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,CAAC,GAAG,IAAI;IAKhC;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,IAAI,EAAE,UAAU,CAAC,eAAe,CAAC,GAAG,IAAI;IAKxD;;;;;;;;OAQG;IACH,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CACT,KAAK,EAAE,sBAAsB,CAAC,gBAAgB,CAAC,KAC5C,sBAAsB,CAAC,gBAAgB,CAAC,GAC5C,IAAI;IAKP,gCAAgC;IAChC,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAM1C,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,oBAAoB;CAyE7F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,CAEtD"}