@composurecdk/neptune 0.8.3

package/dist/commonjs/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/commonjs/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"}

package/dist/commonjs/cluster-builder.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClusterBuilder = createClusterBuilder;
+const aws_neptune_alpha_1 = require("@aws-cdk/aws-neptune-alpha");
+const core_1 = require("@composurecdk/core");
+const cloudformation_1 = require("@composurecdk/cloudformation");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const cluster_defaults_js_1 = require("./cluster-defaults.js");
+const cluster_parameter_group_defaults_js_1 = require("./cluster-parameter-group-defaults.js");
+const cluster_alarms_js_1 = require("./cluster-alarms.js");
+class ClusterBuilder {
+    props = {};
+    #customAlarms = [];
+    #accessors = [];
+    #vpc;
+    /**
+     * 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) {
+        this.#vpc = vpc;
+        return 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) {
+        this.#accessors.push(peer);
+        return 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, configure) {
+        this.#customAlarms.push(configure(new cloudwatch_1.AlarmDefinitionBuilder(key)));
+        return this;
+    }
+    /** @internal — see ADR-0005. */
+    [core_1.COPY_STATE](target) {
+        target.#vpc = this.#vpc;
+        target.#customAlarms.push(...this.#customAlarms);
+        target.#accessors.push(...this.#accessors);
+    }
+    build(scope, id, context) {
+        const resolvedVpc = this.#vpc ? (0, core_1.resolve)(this.#vpc, context) : undefined;
+        if (!resolvedVpc) {
+            throw new Error(`ClusterBuilder "${id}" requires a VPC. Call .vpc() with an IVpc or a Ref to one.`);
+        }
+        const { recommendedAlarms: alarmConfig, securityGroups: resolvableSgs, clusterParameters, clusterParameterGroup: userParameterGroup, ...clusterProps } = this.props;
+        if (clusterProps.instanceType === undefined) {
+            throw new Error(`ClusterBuilder "${id}" requires an instance type. Call .instanceType() with a ` +
+                `provisioned class (e.g. InstanceType.R6G_LARGE) or InstanceType.SERVERLESS ` +
+                `paired with .serverlessScalingConfiguration().`);
+        }
+        if (userParameterGroup !== undefined && clusterParameters !== undefined) {
+            throw new Error(`ClusterBuilder "${id}": .clusterParameters() cannot be combined with a ` +
+                `user-managed .clusterParameterGroup() — the supplied group is not mutated by ` +
+                `this builder. Set the parameters on your own group instead.`);
+        }
+        const clusterParameterGroup = userParameterGroup ??
+            new aws_neptune_alpha_1.ClusterParameterGroup(scope, `${id}ParameterGroup`, {
+                family: (0, cluster_parameter_group_defaults_js_1.clusterParameterGroupFamily)(clusterProps.engineVersion),
+                parameters: { ...cluster_parameter_group_defaults_js_1.CLUSTER_PARAMETER_GROUP_DEFAULTS, ...clusterParameters },
+            });
+        const securityGroups = resolvableSgs?.map((sg) => (0, core_1.resolve)(sg, context));
+        const mergedProps = {
+            ...cluster_defaults_js_1.CLUSTER_DEFAULTS,
+            ...clusterProps,
+            vpc: resolvedVpc,
+            clusterParameterGroup,
+            ...(securityGroups ? { securityGroups } : {}),
+        };
+        const cluster = new aws_neptune_alpha_1.DatabaseCluster(scope, id, mergedProps);
+        for (const resolvable of this.#accessors) {
+            const peer = (0, core_1.resolve)(resolvable, context);
+            cluster.connections.allowDefaultPortFrom(peer);
+            // The IAM `connect` grant is only meaningful when IAM authentication is
+            // enabled (the default). If a user has turned it off, opening the
+            // network path is the whole grant — a grantConnect policy would be inert.
+            if (mergedProps.iamAuthentication !== false) {
+                cluster.grantConnect(peer);
+            }
+        }
+        const alarms = (0, cluster_alarms_js_1.createClusterAlarms)(scope, id, cluster, alarmConfig, mergedProps.serverlessScalingConfiguration, this.#customAlarms);
+        return { cluster, subnetGroup: cluster.subnetGroup, clusterParameterGroup, alarms };
+    }
+}
+/**
+ * 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"] },
+ * );
+ * ```
+ */
+function createClusterBuilder() {
+    return (0, cloudformation_1.taggedBuilder)(ClusterBuilder);
+}
+//# sourceMappingURL=cluster-builder.js.map

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

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

package/dist/commonjs/cluster-defaults.d.ts

@@ -0,0 +1,19 @@
+import { type DatabaseClusterProps } from "@aws-cdk/aws-neptune-alpha";
+/**
+ * Secure, AWS-recommended defaults applied to every Neptune cluster built
+ * with {@link createClusterBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ *
+ * Every default is anchored first to the AWS Well-Architected Framework
+ * (the _why_) and then to the Neptune User Guide (the _how_), matching the
+ * citation convention used across the other builder packages.
+ *
+ * Notably absent: `instanceType`. Defaulting an instance type would create
+ * surprise cost, so the builder requires the caller to pick one explicitly
+ * (a provisioned class such as `InstanceType.R6G_LARGE`, or
+ * `InstanceType.SERVERLESS` paired with `serverlessScalingConfiguration`).
+ *
+ * @see https://docs.aws.amazon.com/prescriptive-guidance/latest/neptune-well-architected-framework/introduction.html
+ */
+export declare const CLUSTER_DEFAULTS: Partial<DatabaseClusterProps>;
+//# sourceMappingURL=cluster-defaults.d.ts.map

package/dist/commonjs/cluster-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-defaults.d.ts","sourceRoot":"","sources":["../../src/cluster-defaults.ts"],"names":[],"mappings":"AAEA,OAAO,EAAW,KAAK,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAEhF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,CAAC,oBAAoB,CAuE1D,CAAC"}

package/dist/commonjs/cluster-defaults.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLUSTER_DEFAULTS = void 0;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_logs_1 = require("aws-cdk-lib/aws-logs");
+const aws_neptune_alpha_1 = require("@aws-cdk/aws-neptune-alpha");
+/**
+ * Secure, AWS-recommended defaults applied to every Neptune cluster built
+ * with {@link createClusterBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ *
+ * Every default is anchored first to the AWS Well-Architected Framework
+ * (the _why_) and then to the Neptune User Guide (the _how_), matching the
+ * citation convention used across the other builder packages.
+ *
+ * Notably absent: `instanceType`. Defaulting an instance type would create
+ * surprise cost, so the builder requires the caller to pick one explicitly
+ * (a provisioned class such as `InstanceType.R6G_LARGE`, or
+ * `InstanceType.SERVERLESS` paired with `serverlessScalingConfiguration`).
+ *
+ * @see https://docs.aws.amazon.com/prescriptive-guidance/latest/neptune-well-architected-framework/introduction.html
+ */
+exports.CLUSTER_DEFAULTS = {
+    /**
+     * Encrypt the cluster volume at rest. Uses the AWS-managed Neptune key
+     * unless a customer-managed key is supplied via `.kmsKey()`.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_protect_data_rest_encrypt.html
+     * @see https://docs.aws.amazon.com/neptune/latest/userguide/encrypt.html
+     */
+    storageEncrypted: true,
+    /**
+     * Require IAM authentication for data-plane connections, removing the
+     * need for long-lived static credentials. Pair with `.allowAccessFrom()`
+     * (or `cluster.grantConnect()`) to authorise principals.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/framework/sec-03.html
+     * @see https://docs.aws.amazon.com/neptune/latest/userguide/iam-auth.html
+     */
+    iamAuthentication: true,
+    /**
+     * Retain the cluster on stack deletion/replacement so graph data is not
+     * destroyed by an errant `cdk destroy`. Ephemeral/dev stacks override to
+     * `RemovalPolicy.DESTROY`.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_backing_up_data_identified_backups_data.html
+     */
+    removalPolicy: aws_cdk_lib_1.RemovalPolicy.RETAIN,
+    /**
+     * Block accidental deletion of the cluster itself. The CDK L2 would infer
+     * this from `RemovalPolicy.RETAIN`; setting it explicitly keeps the
+     * security posture auditable rather than implicit.
+     * @see https://docs.aws.amazon.com/securityhub/latest/userguide/neptune-controls.html
+     */
+    deletionProtection: true,
+    /**
+     * Retain automated backups for 7 days. The CDK default is 1 day; AWS
+     * Well-Architected recommends a longer window for production data.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_backing_up_data_automated_backups_data.html
+     */
+    backupRetention: aws_cdk_lib_1.Duration.days(7),
+    /**
+     * Export audit logs to CloudWatch Logs. Audit logging is the only log
+     * type Neptune exports to CloudWatch, and it only emits once
+     * `neptune_enable_audit_log` is set on the cluster parameter group — which
+     * the builder's auto-created parameter group does by default.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_detect_investigate_events_app_service_logging.html
+     * @see https://docs.aws.amazon.com/neptune/latest/userguide/auditing.html
+     */
+    cloudwatchLogsExports: [aws_neptune_alpha_1.LogType.AUDIT],
+    /**
+     * Expire exported audit logs after one month, matching the
+     * `@composurecdk/logs` retention default rather than keeping them forever.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/framework/cost-05.html
+     */
+    cloudwatchLogsRetention: aws_logs_1.RetentionDays.ONE_MONTH,
+    /**
+     * Copy cluster tags onto automated snapshots so cost-allocation and
+     * ownership tags survive into backups.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/framework/ops-04.html
+     */
+    copyTagsToSnapshot: true,
+    /**
+     * Apply patched minor engine versions automatically during the
+     * maintenance window.
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_protect_compute_validate_software_integrity.html
+     */
+    autoMinorVersionUpgrade: true,
+};
+//# sourceMappingURL=cluster-defaults.js.map

package/dist/commonjs/cluster-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-defaults.js","sourceRoot":"","sources":["../../src/cluster-defaults.ts"],"names":[],"mappings":";;;AAAA,6CAAsD;AACtD,mDAAqD;AACrD,kEAAgF;AAEhF;;;;;;;;;;;;;;;GAeG;AACU,QAAA,gBAAgB,GAAkC;IAC7D;;;;;OAKG;IACH,gBAAgB,EAAE,IAAI;IAEtB;;;;;;OAMG;IACH,iBAAiB,EAAE,IAAI;IAEvB;;;;;OAKG;IACH,aAAa,EAAE,2BAAa,CAAC,MAAM;IAEnC;;;;;OAKG;IACH,kBAAkB,EAAE,IAAI;IAExB;;;;OAIG;IACH,eAAe,EAAE,sBAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IAEjC;;;;;;;OAOG;IACH,qBAAqB,EAAE,CAAC,2BAAO,CAAC,KAAK,CAAC;IAEtC;;;;OAIG;IACH,uBAAuB,EAAE,wBAAa,CAAC,SAAS;IAEhD;;;;OAIG;IACH,kBAAkB,EAAE,IAAI;IAExB;;;;OAIG;IACH,uBAAuB,EAAE,IAAI;CAC9B,CAAC"}

package/dist/commonjs/cluster-parameter-group-defaults.d.ts

@@ -0,0 +1,30 @@
+import { EngineVersion, ParameterGroupFamily } from "@aws-cdk/aws-neptune-alpha";
+/**
+ * Default parameters applied to the cluster parameter group the builder
+ * auto-creates when the caller does not supply their own. These change
+ * engine behaviour (not just observability), so each is documented and
+ * individually overridable via `.clusterParameters({...})`.
+ *
+ * `neptune_enable_audit_log` is what actually turns audit logging on inside
+ * the engine — without it, the `cloudwatchLogsExports: [AUDIT]` cluster
+ * default creates an empty log stream. The two defaults are deliberately
+ * paired so audit logging works end-to-end out of the box.
+ *
+ * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_detect_investigate_events_app_service_logging.html
+ * @see https://docs.aws.amazon.com/neptune/latest/userguide/auditing.html#auditing-enable
+ */
+export declare const CLUSTER_PARAMETER_GROUP_DEFAULTS: Record<string, string>;
+/**
+ * Derives the cluster parameter group family from a Neptune engine version.
+ *
+ * A cluster parameter group must declare a family compatible with the
+ * cluster's engine version, or the deploy fails. Rather than make the caller
+ * keep the two in sync by hand, the builder derives the family from the
+ * `engineVersion` (when set) so the auto-created parameter group is always
+ * compatible. When no engine version is pinned, Neptune uses a current
+ * 1.4.x engine, so the family defaults to {@link ParameterGroupFamily.NEPTUNE_1_4}.
+ *
+ * @see https://docs.aws.amazon.com/neptune/latest/userguide/parameters.html
+ */
+export declare function clusterParameterGroupFamily(engineVersion?: EngineVersion): ParameterGroupFamily;
+//# sourceMappingURL=cluster-parameter-group-defaults.d.ts.map

package/dist/commonjs/cluster-parameter-group-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-parameter-group-defaults.d.ts","sourceRoot":"","sources":["../../src/cluster-parameter-group-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAEjF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gCAAgC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGnE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,oBAAoB,CAgB/F"}

package/dist/commonjs/cluster-parameter-group-defaults.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLUSTER_PARAMETER_GROUP_DEFAULTS = void 0;
+exports.clusterParameterGroupFamily = clusterParameterGroupFamily;
+const aws_neptune_alpha_1 = require("@aws-cdk/aws-neptune-alpha");
+/**
+ * Default parameters applied to the cluster parameter group the builder
+ * auto-creates when the caller does not supply their own. These change
+ * engine behaviour (not just observability), so each is documented and
+ * individually overridable via `.clusterParameters({...})`.
+ *
+ * `neptune_enable_audit_log` is what actually turns audit logging on inside
+ * the engine — without it, the `cloudwatchLogsExports: [AUDIT]` cluster
+ * default creates an empty log stream. The two defaults are deliberately
+ * paired so audit logging works end-to-end out of the box.
+ *
+ * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/sec_detect_investigate_events_app_service_logging.html
+ * @see https://docs.aws.amazon.com/neptune/latest/userguide/auditing.html#auditing-enable
+ */
+exports.CLUSTER_PARAMETER_GROUP_DEFAULTS = {
+    /** Enable engine audit logging so the audit log export carries data. */
+    neptune_enable_audit_log: "1",
+};
+/**
+ * Derives the cluster parameter group family from a Neptune engine version.
+ *
+ * A cluster parameter group must declare a family compatible with the
+ * cluster's engine version, or the deploy fails. Rather than make the caller
+ * keep the two in sync by hand, the builder derives the family from the
+ * `engineVersion` (when set) so the auto-created parameter group is always
+ * compatible. When no engine version is pinned, Neptune uses a current
+ * 1.4.x engine, so the family defaults to {@link ParameterGroupFamily.NEPTUNE_1_4}.
+ *
+ * @see https://docs.aws.amazon.com/neptune/latest/userguide/parameters.html
+ */
+function clusterParameterGroupFamily(engineVersion) {
+    // version strings are "major.minor.patch.build", e.g. "1.4.5.1".
+    const [major, minor] = (engineVersion?.version ?? "1.4").split(".");
+    const majorMinor = `${major}.${minor}`;
+    switch (majorMinor) {
+        case "1.0":
+        case "1.1":
+            return aws_neptune_alpha_1.ParameterGroupFamily.NEPTUNE_1;
+        case "1.2":
+            return aws_neptune_alpha_1.ParameterGroupFamily.NEPTUNE_1_2;
+        case "1.3":
+            return aws_neptune_alpha_1.ParameterGroupFamily.NEPTUNE_1_3;
+        default:
+            // 1.4 and anything newer the builder has not been taught about yet.
+            return aws_neptune_alpha_1.ParameterGroupFamily.NEPTUNE_1_4;
+    }
+}
+//# sourceMappingURL=cluster-parameter-group-defaults.js.map

package/dist/commonjs/cluster-parameter-group-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-parameter-group-defaults.js","sourceRoot":"","sources":["../../src/cluster-parameter-group-defaults.ts"],"names":[],"mappings":";;;AAiCA,kEAgBC;AAjDD,kEAAiF;AAEjF;;;;;;;;;;;;;GAaG;AACU,QAAA,gCAAgC,GAA2B;IACtE,wEAAwE;IACxE,wBAAwB,EAAE,GAAG;CAC9B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,SAAgB,2BAA2B,CAAC,aAA6B;IACvE,iEAAiE;IACjE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,aAAa,EAAE,OAAO,IAAI,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpE,MAAM,UAAU,GAAG,GAAG,KAAK,IAAI,KAAK,EAAE,CAAC;IACvC,QAAQ,UAAU,EAAE,CAAC;QACnB,KAAK,KAAK,CAAC;QACX,KAAK,KAAK;YACR,OAAO,wCAAoB,CAAC,SAAS,CAAC;QACxC,KAAK,KAAK;YACR,OAAO,wCAAoB,CAAC,WAAW,CAAC;QAC1C,KAAK,KAAK;YACR,OAAO,wCAAoB,CAAC,WAAW,CAAC;QAC1C;YACE,oEAAoE;YACpE,OAAO,wCAAoB,CAAC,WAAW,CAAC;IAC5C,CAAC;AACH,CAAC"}

package/dist/commonjs/index.d.ts

@@ -0,0 +1,6 @@
+export { createClusterBuilder, type ClusterAccessor, type ClusterBuilderProps, type ClusterBuilderResult, type IClusterBuilder, } from "./cluster-builder.js";
+export { CLUSTER_DEFAULTS } from "./cluster-defaults.js";
+export { CLUSTER_PARAMETER_GROUP_DEFAULTS, clusterParameterGroupFamily, } from "./cluster-parameter-group-defaults.js";
+export { type NeptuneClusterAlarmConfig } from "./cluster-alarm-config.js";
+export { CLUSTER_ALARM_DEFAULTS } from "./cluster-alarm-defaults.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EACL,gCAAgC,EAChC,2BAA2B,GAC5B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,KAAK,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/commonjs/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLUSTER_ALARM_DEFAULTS = exports.clusterParameterGroupFamily = exports.CLUSTER_PARAMETER_GROUP_DEFAULTS = exports.CLUSTER_DEFAULTS = exports.createClusterBuilder = void 0;
+var cluster_builder_js_1 = require("./cluster-builder.js");
+Object.defineProperty(exports, "createClusterBuilder", { enumerable: true, get: function () { return cluster_builder_js_1.createClusterBuilder; } });
+var cluster_defaults_js_1 = require("./cluster-defaults.js");
+Object.defineProperty(exports, "CLUSTER_DEFAULTS", { enumerable: true, get: function () { return cluster_defaults_js_1.CLUSTER_DEFAULTS; } });
+var cluster_parameter_group_defaults_js_1 = require("./cluster-parameter-group-defaults.js");
+Object.defineProperty(exports, "CLUSTER_PARAMETER_GROUP_DEFAULTS", { enumerable: true, get: function () { return cluster_parameter_group_defaults_js_1.CLUSTER_PARAMETER_GROUP_DEFAULTS; } });
+Object.defineProperty(exports, "clusterParameterGroupFamily", { enumerable: true, get: function () { return cluster_parameter_group_defaults_js_1.clusterParameterGroupFamily; } });
+var cluster_alarm_defaults_js_1 = require("./cluster-alarm-defaults.js");
+Object.defineProperty(exports, "CLUSTER_ALARM_DEFAULTS", { enumerable: true, get: function () { return cluster_alarm_defaults_js_1.CLUSTER_ALARM_DEFAULTS; } });
+//# sourceMappingURL=index.js.map

package/dist/commonjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,2DAM8B;AAL5B,0HAAA,oBAAoB,OAAA;AAMtB,6DAAyD;AAAhD,uHAAA,gBAAgB,OAAA;AACzB,6FAG+C;AAF7C,uJAAA,gCAAgC,OAAA;AAChC,kJAAA,2BAA2B,OAAA;AAG7B,yEAAqE;AAA5D,mIAAA,sBAAsB,OAAA"}

package/dist/commonjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}