@composurecdk/dynamodb 0.8.4

package/dist/esm/defaults.js

@@ -0,0 +1,135 @@
+import { Billing, BillingMode, TableEncryption, TableEncryptionV2, } from "aws-cdk-lib/aws-dynamodb";
+/**
+ * Secure, AWS-recommended defaults applied to every DynamoDB table built
+ * with {@link createTableBuilder}. Each property can be individually
+ * overridden via the builder's fluent API.
+ *
+ * `partitionKey` is intentionally not defaulted — the key schema is the
+ * single most workload-specific decision for a table and there is no safe
+ * generic value. The builder requires it to be set before {@link Lifecycle.build}.
+ */
+export const TABLE_DEFAULTS = {
+    /**
+     * On-demand (pay-per-request) capacity. Removes the need to forecast and
+     * provision read/write capacity, scales instantly with traffic, and avoids
+     * throttling caused by under-provisioning — the safe default for variable
+     * or unknown workloads. Switch to {@link BillingMode.PROVISIONED} with
+     * `.readCapacity()` / `.writeCapacity()` for steady, predictable traffic
+     * where provisioned capacity is more cost-effective.
+     *
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/capacity.html
+     * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.html
+     */
+    billingMode: BillingMode.PAY_PER_REQUEST,
+    /**
+     * Encrypt at rest with an AWS-managed KMS key (`aws/dynamodb`) rather than
+     * the default AWS-owned key. The AWS-managed key is visible in the account's
+     * KMS console and its use is logged in CloudTrail, giving an auditable record
+     * of table encryption — what the Security Pillar asks for. Bring-your-own KMS
+     * is opt-in: set `.encryptionKey(key)` and the builder infers
+     * {@link TableEncryption.CUSTOMER_MANAGED}.
+     *
+     * Note: the AWS-managed key incurs KMS API request charges that the free,
+     * AWS-owned key does not. Override with `.encryption(TableEncryption.DEFAULT)`
+     * to fall back to the AWS-owned key.
+     *
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/protecting-data-at-rest.html
+     * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/EncryptionAtRest.html
+     */
+    encryption: TableEncryption.AWS_MANAGED,
+    /**
+     * Enable point-in-time recovery (continuous backups). Lets the table be
+     * restored to any second within the preceding 35 days, protecting against
+     * accidental writes, deletes, and application-level corruption. The Reliability
+     * Pillar treats automated, restorable backups as table stakes for stateful
+     * services.
+     *
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_backing_up_data_identified_backups_data.html
+     * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/PointInTimeRecovery.html
+     */
+    pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: true },
+    /**
+     * Enable deletion protection so the table cannot be deleted by an API call,
+     * console action, or `cdk destroy` until protection is explicitly turned off.
+     * Guards production data against accidental teardown.
+     *
+     * This is intentionally heavier than CDK's default `RemovalPolicy.RETAIN`
+     * (which only orphans the table from the stack): deletion protection blocks
+     * the delete operation itself. Override with `.deletionProtection(false)` for
+     * ephemeral or test tables you expect to tear down.
+     *
+     * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.Basics.html#WorkingWithTables.Basics.DeletionProtection
+     */
+    deletionProtection: true,
+};
+/**
+ * Secure, AWS-recommended defaults applied to every DynamoDB table built with
+ * {@link createTableV2Builder}. These encode the same well-architected intent
+ * as {@link TABLE_DEFAULTS} (on-demand billing, AWS-managed-KMS encryption,
+ * point-in-time recovery, deletion protection) against the `TableV2`
+ * (`AWS::DynamoDB::GlobalTable`) prop shape, where billing and encryption are
+ * single helper objects rather than flat props.
+ *
+ * As with {@link TABLE_DEFAULTS}, `partitionKey` is intentionally not defaulted
+ * — the key schema is the single most workload-specific decision for a table
+ * and there is no safe generic value.
+ */
+export const TABLE_V2_DEFAULTS = {
+    /**
+     * On-demand (pay-per-request) capacity. Removes the need to forecast and
+     * provision read/write capacity, scales instantly with traffic, and avoids
+     * throttling caused by under-provisioning — the safe default for variable or
+     * unknown workloads. Switch to {@link Billing.provisioned} with
+     * `MaxCapacity`/`Capacity.autoscaled(...)` for steady, predictable traffic
+     * where provisioned capacity is more cost-effective.
+     *
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/serverless-applications-lens/capacity.html
+     * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.html
+     */
+    billing: Billing.onDemand(),
+    /**
+     * Encrypt at rest with an AWS-managed KMS key (`aws/dynamodb`) rather than the
+     * default AWS-owned key. The AWS-managed key is visible in the account's KMS
+     * console and its use is logged in CloudTrail, giving an auditable record of
+     * table encryption — what the Security Pillar asks for. Bring-your-own KMS is
+     * opt-in via `.encryption(TableEncryptionV2.customerManagedKey(key))`.
+     *
+     * Note: the AWS-managed key incurs KMS API request charges that the free,
+     * AWS-owned key does not. Override with
+     * `.encryption(TableEncryptionV2.dynamoOwnedKey())` to fall back to the
+     * AWS-owned key.
+     *
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/protecting-data-at-rest.html
+     * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/EncryptionAtRest.html
+     */
+    encryption: TableEncryptionV2.awsManagedKey(),
+    /**
+     * Enable point-in-time recovery (continuous backups). Lets the table be
+     * restored to any second within the preceding 35 days, protecting against
+     * accidental writes, deletes, and application-level corruption. The
+     * Reliability Pillar treats automated, restorable backups as table stakes for
+     * stateful services.
+     *
+     * Note: for `TableV2` (`AWS::DynamoDB::GlobalTable`) this setting is encoded
+     * per-replica (`Replicas[].PointInTimeRecoverySpecification`), not at the
+     * resource root — CDK applies it to each replica.
+     *
+     * @see https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/rel_backing_up_data_identified_backups_data.html
+     * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/PointInTimeRecovery.html
+     */
+    pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: true },
+    /**
+     * Enable deletion protection so the table cannot be deleted by an API call,
+     * console action, or `cdk destroy` until protection is explicitly turned off.
+     * Guards production data against accidental teardown. Override with
+     * `.deletionProtection(false)` for ephemeral or test tables.
+     *
+     * Note: for `TableV2` (`AWS::DynamoDB::GlobalTable`) this setting is encoded
+     * per-replica (`Replicas[].DeletionProtectionEnabled`), not at the resource
+     * root — CDK applies it to each replica.
+     *
+     * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.Basics.html#WorkingWithTables.Basics.DeletionProtection
+     */
+    deletionProtection: true,
+};
+//# sourceMappingURL=defaults.js.map

package/dist/esm/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,WAAW,EACX,eAAe,EACf,iBAAiB,GAGlB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAwB;IACjD;;;;;;;;;;OAUG;IACH,WAAW,EAAE,WAAW,CAAC,eAAe;IAExC;;;;;;;;;;;;;;OAcG;IACH,UAAU,EAAE,eAAe,CAAC,WAAW;IAEvC;;;;;;;;;OASG;IACH,gCAAgC,EAAE,EAAE,0BAA0B,EAAE,IAAI,EAAE;IAEtE;;;;;;;;;;;OAWG;IACH,kBAAkB,EAAE,IAAI;CACzB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA0B;IACtD;;;;;;;;;;OAUG;IACH,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE;IAE3B;;;;;;;;;;;;;;OAcG;IACH,UAAU,EAAE,iBAAiB,CAAC,aAAa,EAAE;IAE7C;;;;;;;;;;;;;OAaG;IACH,gCAAgC,EAAE,EAAE,0BAA0B,EAAE,IAAI,EAAE;IAEtE;;;;;;;;;;;OAWG;IACH,kBAAkB,EAAE,IAAI;CACzB,CAAC"}

package/dist/esm/index.d.ts

@@ -0,0 +1,6 @@
+export { createTableBuilder, type ITableBuilder, type TableBuilderProps, type TableBuilderResult, } from "./table-builder.js";
+export { createTableV2Builder, type ITableV2Builder, type TableV2BuilderProps, type TableV2BuilderResult, } from "./table-v2-builder.js";
+export { TABLE_DEFAULTS, TABLE_V2_DEFAULTS } from "./defaults.js";
+export { type TableAlarmConfig } from "./table-alarm-config.js";
+export { TABLE_ALARM_DEFAULTS } from "./table-alarm-defaults.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+export { createTableBuilder, } from "./table-builder.js";
+export { createTableV2Builder, } from "./table-v2-builder.js";
+export { TABLE_DEFAULTS, TABLE_V2_DEFAULTS } from "./defaults.js";
+export { TABLE_ALARM_DEFAULTS } from "./table-alarm-defaults.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,GAInB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,GAIrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/esm/package.json

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

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

@@ -0,0 +1,58 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+/**
+ * Controls which recommended alarms are created for a DynamoDB table.
+ * All applicable alarms are enabled by default with AWS-recommended
+ * thresholds. Set individual alarms to `false` to disable them, or provide
+ * an {@link AlarmConfig} to tune thresholds.
+ *
+ * The defaults target a table-scoped view of availability and throttling.
+ * Account-level recommended alarms (e.g. `AccountProvisionedReadCapacityUtilization`)
+ * and provisioned-capacity utilization alarms are not created here — see the
+ * package README for the rationale.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#DynamoDB
+ */
+export interface TableAlarmConfig {
+    /**
+     * 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 server-side errors (HTTP 500) returned by the table. These are
+     * faults on the DynamoDB side rather than the caller's, so any sustained
+     * occurrence is worth surfacing. Summed across all operations.
+     *
+     * Metric: `AWS/DynamoDB SystemErrors` (summed per-operation via a math
+     * expression), statistic Sum, period 1 minute.
+     * Default threshold: > 0.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#DynamoDB
+     */
+    systemErrors?: AlarmConfig | false;
+    /**
+     * Alarm when read requests are throttled. On an on-demand table sustained
+     * read throttling signals traffic ramping faster than DynamoDB's adaptive
+     * scaling can follow, or a hot partition; on a provisioned table it signals
+     * under-provisioned read capacity.
+     *
+     * Metric: `AWS/DynamoDB ReadThrottleEvents`, statistic Sum, period 1 minute.
+     * Default threshold: > 0.
+     *
+     * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/metrics-dimensions.html
+     */
+    readThrottleEvents?: AlarmConfig | false;
+    /**
+     * Alarm when write requests are throttled. As with read throttling, this
+     * indicates a hot partition or capacity that cannot keep up with the write
+     * rate.
+     *
+     * Metric: `AWS/DynamoDB WriteThrottleEvents`, statistic Sum, period 1 minute.
+     * Default threshold: > 0.
+     *
+     * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/metrics-dimensions.html
+     */
+    writeThrottleEvents?: AlarmConfig | false;
+}
+//# sourceMappingURL=table-alarm-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"table-alarm-config.d.ts","sourceRoot":"","sources":["../../src/table-alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEnC;;;;;;;;;;OAUG;IACH,kBAAkB,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEzC;;;;;;;;;OASG;IACH,mBAAmB,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CAC3C"}

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

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

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

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

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

@@ -0,0 +1,21 @@
+import type { AlarmConfigDefaults } from "@composurecdk/cloudwatch";
+interface TableAlarmDefaults {
+    enabled: true;
+    systemErrors: AlarmConfigDefaults;
+    readThrottleEvents: AlarmConfigDefaults;
+    writeThrottleEvents: AlarmConfigDefaults;
+}
+/**
+ * AWS-recommended default alarm configuration for DynamoDB tables.
+ *
+ * Thresholds are deliberately strict (> 0) because the metrics they watch —
+ * server-side errors and throttling — should be at or near zero for a healthy
+ * table. Tune them up via `recommendedAlarms` for workloads where a low rate
+ * of throttling is expected and acceptable (e.g. cost-optimised provisioned
+ * tables that lean on burst capacity).
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#DynamoDB
+ */
+export declare const TABLE_ALARM_DEFAULTS: TableAlarmDefaults;
+export {};
+//# sourceMappingURL=table-alarm-defaults.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"table-alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/table-alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,UAAU,kBAAkB;IAC1B,OAAO,EAAE,IAAI,CAAC;IACd,YAAY,EAAE,mBAAmB,CAAC;IAClC,kBAAkB,EAAE,mBAAmB,CAAC;IACxC,mBAAmB,EAAE,mBAAmB,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,EAAE,kBAqClC,CAAC"}

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

@@ -0,0 +1,48 @@
+import { TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+/**
+ * AWS-recommended default alarm configuration for DynamoDB tables.
+ *
+ * Thresholds are deliberately strict (> 0) because the metrics they watch —
+ * server-side errors and throttling — should be at or near zero for a healthy
+ * table. Tune them up via `recommendedAlarms` for workloads where a low rate
+ * of throttling is expected and acceptable (e.g. cost-optimised provisioned
+ * tables that lean on burst capacity).
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#DynamoDB
+ */
+export const TABLE_ALARM_DEFAULTS = {
+    enabled: true,
+    /**
+     * > 0 — any server-side (HTTP 500) error is an availability signal worth
+     * investigating. NOT_BREACHING for missing data: a table with no traffic
+     * emits no SystemErrors datapoints and should stay OK.
+     */
+    systemErrors: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    /**
+     * > 0 — surface read throttling immediately. Conservative starting point;
+     * raise the threshold or `evaluationPeriods` for workloads where brief,
+     * self-correcting throttling under burst is tolerable.
+     */
+    readThrottleEvents: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+    /**
+     * > 0 — surface write throttling immediately, on the same basis as read
+     * throttling.
+     */
+    writeThrottleEvents: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=table-alarm-defaults.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"table-alarm-defaults.js","sourceRoot":"","sources":["../../src/table-alarm-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAU9D;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAuB;IACtD,OAAO,EAAE,IAAI;IAEb;;;;OAIG;IACH,YAAY,EAAE;QACZ,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED;;;;OAIG;IACH,kBAAkB,EAAE;QAClB,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;IAED;;;OAGG;IACH,mBAAmB,EAAE;QACnB,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,gBAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

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

@@ -0,0 +1,26 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import { type ITable } from "aws-cdk-lib/aws-dynamodb";
+import type { IConstruct } from "constructs";
+import type { AlarmDefinition } from "@composurecdk/cloudwatch";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { TableAlarmConfig } from "./table-alarm-config.js";
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for a DynamoDB table.
+ */
+export declare function resolveTableAlarmDefinitions(table: ITable, config: TableAlarmConfig | undefined): AlarmDefinition[];
+/**
+ * Creates AWS-recommended CloudWatch alarms for a DynamoDB table, merging
+ * 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 table - The DynamoDB table to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param customAlarms - Custom alarm builders added via `addAlarm()`.
+ * @returns A record mapping alarm keys to their created Alarm constructs.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#DynamoDB
+ */
+export declare function createTableAlarms(scope: IConstruct, id: string, table: ITable, config: TableAlarmConfig | false | undefined, customAlarms?: AlarmDefinitionBuilder<ITable>[]): Record<string, Alarm>;
+//# sourceMappingURL=table-alarms.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"table-alarms.d.ts","sourceRoot":"","sources":["../../src/table-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,KAAK,EAKX,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,KAAK,MAAM,EAAa,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAoC,MAAM,0BAA0B,CAAC;AACpG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAyChE;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,gBAAgB,GAAG,SAAS,GACnC,eAAe,EAAE,CAqEnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,gBAAgB,GAAG,KAAK,GAAG,SAAS,EAC5C,YAAY,GAAE,sBAAsB,CAAC,MAAM,CAAC,EAAO,GAClD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}

package/dist/esm/table-alarms.js

@@ -0,0 +1,125 @@
+import { Duration } from "aws-cdk-lib";
+import { ComparisonOperator, Metric, Stats, } from "aws-cdk-lib/aws-cloudwatch";
+import { Operation } from "aws-cdk-lib/aws-dynamodb";
+import { createAlarms, resolveAlarmConfig } from "@composurecdk/cloudwatch";
+import { TABLE_ALARM_DEFAULTS } from "./table-alarm-defaults.js";
+const METRIC_PERIOD = Duration.minutes(1);
+const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minute`;
+/**
+ * Operations the default `systemErrors` alarm sums over. A CloudWatch alarm on
+ * a metric-math expression may reference at most 10 individual metrics, and
+ * DynamoDB defines 14 operations — so the full-table aggregate cannot be
+ * alarmed directly. These ten are the core SDK data-plane operations (single
+ * item, query/scan, batch, and transactions); the PartiQL statement operations
+ * and the stream `GetRecords` operation are omitted. Override via a custom
+ * `addAlarm` if your workload's error profile lives in the excluded set.
+ */
+const SYSTEM_ERROR_OPERATIONS = [
+    Operation.GET_ITEM,
+    Operation.BATCH_GET_ITEM,
+    Operation.QUERY,
+    Operation.SCAN,
+    Operation.PUT_ITEM,
+    Operation.UPDATE_ITEM,
+    Operation.DELETE_ITEM,
+    Operation.BATCH_WRITE_ITEM,
+    Operation.TRANSACT_GET_ITEMS,
+    Operation.TRANSACT_WRITE_ITEMS,
+];
+/**
+ * Builds a table-scoped `AWS/DynamoDB` metric with the `TableName` dimension.
+ */
+function tableMetric(table, metricName) {
+    return new Metric({
+        namespace: "AWS/DynamoDB",
+        metricName,
+        dimensionsMap: { TableName: table.tableName },
+        statistic: Stats.SUM,
+        period: METRIC_PERIOD,
+    });
+}
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for a DynamoDB table.
+ */
+export function resolveTableAlarmDefinitions(table, config) {
+    if (config?.enabled === false)
+        return [];
+    const definitions = [];
+    if (config?.systemErrors !== false) {
+        const cfg = resolveAlarmConfig(config?.systemErrors, TABLE_ALARM_DEFAULTS.systemErrors);
+        definitions.push({
+            key: "systemErrors",
+            alarmName: cfg.alarmName,
+            // metricSystemErrorsForOperations sums SystemErrors across the given
+            // operations into a single MathExpression — the per-operation dimension
+            // means there is no single plain Metric for "errors on this table".
+            metric: table.metricSystemErrorsForOperations({
+                period: METRIC_PERIOD,
+                operations: SYSTEM_ERROR_OPERATIONS,
+            }),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `DynamoDB table is returning server-side (HTTP 500) errors, summed across the core data-plane operations. ` +
+                `Threshold: > ${String(cfg.threshold)} in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.readThrottleEvents !== false) {
+        const cfg = resolveAlarmConfig(config?.readThrottleEvents, TABLE_ALARM_DEFAULTS.readThrottleEvents);
+        definitions.push({
+            key: "readThrottleEvents",
+            alarmName: cfg.alarmName,
+            metric: tableMetric(table, "ReadThrottleEvents"),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `DynamoDB table read requests are being throttled, indicating a hot partition or ` +
+                `insufficient read capacity. Threshold: > ${String(cfg.threshold)} in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    if (config?.writeThrottleEvents !== false) {
+        const cfg = resolveAlarmConfig(config?.writeThrottleEvents, TABLE_ALARM_DEFAULTS.writeThrottleEvents);
+        definitions.push({
+            key: "writeThrottleEvents",
+            alarmName: cfg.alarmName,
+            metric: tableMetric(table, "WriteThrottleEvents"),
+            threshold: cfg.threshold,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `DynamoDB table write requests are being throttled, indicating a hot partition or ` +
+                `insufficient write capacity. Threshold: > ${String(cfg.threshold)} in ${METRIC_PERIOD_LABEL}.`,
+        });
+    }
+    return definitions;
+}
+/**
+ * Creates AWS-recommended CloudWatch alarms for a DynamoDB table, merging
+ * 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 table - The DynamoDB table to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param customAlarms - Custom alarm builders added via `addAlarm()`.
+ * @returns A record mapping alarm keys to their created Alarm constructs.
+ *
+ * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#DynamoDB
+ */
+export function createTableAlarms(scope, id, table, config, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? TABLE_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveTableAlarmDefinitions(table, config);
+    const custom = customAlarms.map((b) => b.resolve(table));
+    return createAlarms(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=table-alarms.js.map

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

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

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

@@ -0,0 +1,123 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import { type ITable, Table, type TableProps } from "aws-cdk-lib/aws-dynamodb";
+import { type IConstruct } from "constructs";
+import { COPY_STATE, type Lifecycle } from "@composurecdk/core";
+import { type ITaggedBuilder } from "@composurecdk/cloudformation";
+import { AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { TableAlarmConfig } from "./table-alarm-config.js";
+/**
+ * Configuration properties for the DynamoDB table builder.
+ *
+ * Extends the CDK {@link TableProps} with additional builder-specific options.
+ */
+export interface TableBuilderProps extends TableProps {
+    /**
+     * Configuration for AWS-recommended CloudWatch alarms.
+     *
+     * By default, the builder creates recommended alarms with sensible
+     * thresholds for server-side errors and read/write throttling. 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.
+     *
+     * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#DynamoDB
+     */
+    recommendedAlarms?: TableAlarmConfig | false;
+}
+/**
+ * The build output of an {@link ITableBuilder}. Contains the CDK constructs
+ * created during {@link Lifecycle.build}, keyed by role.
+ */
+export interface TableBuilderResult {
+    /** The classic DynamoDB {@link Table} construct created by the builder. */
+    table: Table;
+    /**
+     * The table's DynamoDB Streams ARN, or `undefined` when no stream is
+     * configured. Surfaced directly so a downstream consumer (e.g. a Lambda
+     * `DynamoEventSource`) can be wired via `ref()`.
+     */
+    tableStreamArn?: string;
+    /**
+     * CloudWatch alarms created for the table, keyed by alarm name — both the
+     * AWS-recommended alarms and any added via {@link ITableBuilder.addAlarm}.
+     * No alarm actions are configured.
+     */
+    alarms: Record<string, Alarm>;
+}
+/**
+ * A fluent builder for configuring and creating an AWS DynamoDB table.
+ *
+ * Wraps the classic {@link Table} construct (`AWS::DynamoDB::Table`). For new
+ * tables, prefer {@link createTableV2Builder} ({@link TableV2}) — AWS recommends
+ * it, and it lets you add cross-region replicas later without replacing the
+ * table. Reach for this classic builder when you need an `importSource` (S3 bulk
+ * import, V1-only) or parity with existing classic tables. Note the two are
+ * different CloudFormation resources and cannot be migrated in place.
+ *
+ * Each configuration property from the CDK {@link TableProps} 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 builder implements {@link Lifecycle}, so it can be used directly as a
+ * component in a {@link compose | composed system}. When built, it creates a
+ * DynamoDB table with the configured properties — merged with secure,
+ * AWS-recommended {@link TABLE_DEFAULTS} — and returns a {@link TableBuilderResult}.
+ *
+ * The builder also creates AWS-recommended CloudWatch alarms by default. Alarms
+ * can be customized or disabled via the `recommendedAlarms` property. Custom
+ * alarms can be added via the {@link addAlarm} method.
+ *
+ * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_dynamodb.Table.html
+ *
+ * @example
+ * ```ts
+ * import { AttributeType, StreamViewType } from "aws-cdk-lib/aws-dynamodb";
+ *
+ * const orders = createTableBuilder()
+ *   .partitionKey({ name: "pk", type: AttributeType.STRING })
+ *   .sortKey({ name: "sk", type: AttributeType.STRING })
+ *   .stream(StreamViewType.NEW_AND_OLD_IMAGES);
+ * ```
+ */
+export type ITableBuilder = ITaggedBuilder<TableBuilderProps, TableBuilder>;
+declare class TableBuilder implements Lifecycle<TableBuilderResult> {
+    #private;
+    props: Partial<TableBuilderProps>;
+    addAlarm(key: string, configure: (alarm: AlarmDefinitionBuilder<ITable>) => AlarmDefinitionBuilder<ITable>): this;
+    /** @internal — see ADR-0005. */
+    [COPY_STATE](target: TableBuilder): void;
+    build(scope: IConstruct, id: string): TableBuilderResult;
+}
+/**
+ * Creates a new {@link ITableBuilder} for configuring an AWS DynamoDB table.
+ *
+ * This is the entry point for defining a DynamoDB table component. The returned
+ * builder exposes every {@link TableBuilderProps} property as a fluent
+ * setter/getter and implements {@link Lifecycle} for use with {@link compose}.
+ *
+ * @returns A fluent builder for an AWS DynamoDB table.
+ *
+ * @example
+ * ```ts
+ * import { AttributeType } from "aws-cdk-lib/aws-dynamodb";
+ *
+ * const orders = createTableBuilder().partitionKey({
+ *   name: "orderId",
+ *   type: AttributeType.STRING,
+ * });
+ *
+ * // Use standalone:
+ * const result = orders.build(stack, "Orders");
+ *
+ * // Or compose into a system, wiring the stream into a Lambda:
+ * const system = compose(
+ *   { orders, processor: createFunctionBuilder() },
+ *   { orders: [], processor: ["orders"] },
+ * );
+ * ```
+ */
+export declare function createTableBuilder(): ITableBuilder;
+export {};
+//# sourceMappingURL=table-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"table-builder.d.ts","sourceRoot":"","sources":["../../src/table-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,EAAmB,KAAK,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,KAAK,cAAc,EAAiB,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAIhE;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACnD;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,GAAG,KAAK,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,KAAK,EAAE,KAAK,CAAC;IAEb;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC,iBAAiB,EAAE,YAAY,CAAC,CAAC;AAE5E,cAAM,YAAa,YAAW,SAAS,CAAC,kBAAkB,CAAC;;IACzD,KAAK,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAM;IAGvC,QAAQ,CACN,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,MAAM,CAAC,KAAK,sBAAsB,CAAC,MAAM,CAAC,GACnF,IAAI;IAKP,gCAAgC;IAChC,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAIxC,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,kBAAkB;CAWzD;AAgCD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAElD"}