@composurecdk/dynamodb 0.8.4

package/README.md

@@ -0,0 +1,186 @@
+# @composurecdk/dynamodb
+
+DynamoDB table builders for [ComposureCDK](../../README.md).
+
+This package provides fluent builders for DynamoDB tables with secure, AWS-recommended defaults and built-in CloudWatch alarms. It ships **two builders**, one per CDK construct:
+
+| Factory                  | CDK construct                                                                                  | CloudFormation resource      | Use for                                                         |
+| ------------------------ | ---------------------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------- |
+| `createTableV2Builder()` | [`TableV2`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_dynamodb.TableV2.html) | `AWS::DynamoDB::GlobalTable` | **New tables (recommended).**                                   |
+| `createTableBuilder()`   | [`Table`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_dynamodb.Table.html)     | `AWS::DynamoDB::Table`       | `importSource` (S3 bulk import) and parity with classic tables. |
+
+Both share the same well-architected defaults intent, the same recommended alarms, and the same `ref()`-able result shape — they differ only in the underlying CDK prop surface.
+
+### Which builder should I use?
+
+For **new tables, prefer `createTableV2Builder()`**. A single-region `TableV2` bills the same as a classic table, but it future-proofs the one irreversible part of the decision: you can add cross-region replicas later without replacing the table. `ITableV2 extends ITable`, so a built `TableV2` works everywhere an `ITable` is expected (IAM grants, `DynamoEventSource`) — composition wiring is identical for both builders.
+
+Reach for the classic `createTableBuilder()` when you need an `importSource` (S3 bulk import is V1-only, with no `TableV2` equivalent) or parity with existing classic tables.
+
+> ⚠️ **`Table` and `TableV2` are different CloudFormation resources** (`AWS::DynamoDB::Table` vs. `AWS::DynamoDB::GlobalTable`). CloudFormation **cannot migrate between them in place** — swapping the construct on an existing table is a resource replacement, which deletes and recreates the table. Choose deliberately up front.
+
+## TableV2 builder (recommended)
+
+```ts
+import { AttributeType, StreamViewType } from "aws-cdk-lib/aws-dynamodb";
+import { createTableV2Builder } from "@composurecdk/dynamodb";
+
+const orders = createTableV2Builder()
+  .partitionKey({ name: "orderId", type: AttributeType.STRING })
+  .sortKey({ name: "createdAt", type: AttributeType.NUMBER })
+  .dynamoStream(StreamViewType.NEW_AND_OLD_IMAGES)
+  .build(stack, "Orders");
+```
+
+Every [`TablePropsV2`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_dynamodb.TablePropsV2.html) property is available as a fluent setter. Note the V2 prop shape differs from the classic one — billing is a single `.billing(Billing.onDemand())` helper, encryption is `.encryption(TableEncryptionV2.awsManagedKey())`, and the stream is `.dynamoStream(StreamViewType…)`. `partitionKey` is the one property the builder does not default — the key schema is workload-specific, so it must be set before `build()`.
+
+## Classic Table builder
+
+```ts
+import { AttributeType, StreamViewType } from "aws-cdk-lib/aws-dynamodb";
+import { createTableBuilder } from "@composurecdk/dynamodb";
+
+const orders = createTableBuilder()
+  .partitionKey({ name: "orderId", type: AttributeType.STRING })
+  .sortKey({ name: "createdAt", type: AttributeType.NUMBER })
+  .stream(StreamViewType.NEW_AND_OLD_IMAGES)
+  .build(stack, "Orders");
+```
+
+Every [`TableProps`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_dynamodb.TableProps.html) property is available as a fluent setter, including `importSource` for [S3 bulk import](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/S3DataImport.HowItWorks.html) — the main reason to choose the classic builder.
+
+## Secure Defaults
+
+Both builders apply the same well-architected intent, encoded against each construct's prop shape. Each default can be overridden via the builder's fluent API.
+
+| Intent                 | TableV2 (`TABLE_V2_DEFAULTS`)                   | Classic (`TABLE_DEFAULTS`)                 | Rationale                                                                                                                                                                                                                                                                                         |
+| ---------------------- | ----------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| On-demand billing      | `billing: Billing.onDemand()`                   | `billingMode: BillingMode.PAY_PER_REQUEST` | No forecasting, scales with traffic, avoids throttling from under-provisioning. Switch to provisioned for steady, predictable workloads.                                                                                                                                                          |
+| Encryption at rest     | `encryption: TableEncryptionV2.awsManagedKey()` | `encryption: TableEncryption.AWS_MANAGED`  | Encrypts with the AWS-managed `aws/dynamodb` KMS key — visible in the account and logged in CloudTrail, unlike the free AWS-owned default key. Bring-your-own KMS is opt-in. ([Security Pillar](https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/protecting-data-at-rest.html)) |
+| Point-in-time recovery | `pointInTimeRecoverySpecification: { … }`       | `pointInTimeRecoverySpecification: { … }`  | Continuous backups — restore to any second in the preceding 35 days. ([PITR](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/PointInTimeRecovery.html))                                                                                                                          |
+| Deletion protection    | `deletionProtection: true`                      | `deletionProtection: true`                 | Blocks table deletion (API, console, or `cdk destroy`) until explicitly disabled. Override with `.deletionProtection(false)` for ephemeral tables.                                                                                                                                                |
+
+The defaults are exported for visibility and testing:
+
+```ts
+import { TABLE_DEFAULTS, TABLE_V2_DEFAULTS } from "@composurecdk/dynamodb";
+```
+
+## DynamoDB Streams
+
+Enable a stream with `.dynamoStream(StreamViewType…)` (TableV2) or `.stream(StreamViewType…)` (classic). The build result surfaces the stream ARN so a downstream component can wire a consumer:
+
+```ts
+const result = createTableV2Builder()
+  .partitionKey({ name: "pk", type: AttributeType.STRING })
+  .dynamoStream(StreamViewType.NEW_AND_OLD_IMAGES)
+  .build(stack, "Events");
+
+result.tableStreamArn; // string — feed into a Lambda DynamoEventSource, etc.
+result.table; // the table itself, which a DynamoEventSource consumes
+```
+
+Neither construct exposes a distinct stream construct — the stream is an attribute of the table — so the result exposes `tableStreamArn` directly. It is `undefined` when no stream is configured, on both builders, so a `ref()` consumer can branch on its presence.
+
+## Recommended Alarms
+
+Both builders create the same [AWS-recommended CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#DynamoDB) by default. No alarm actions are configured — access alarms from the build result to add SNS topics or other actions.
+
+| Alarm                 | Metric                                      | Default threshold | Rationale                                                        |
+| --------------------- | ------------------------------------------- | ----------------- | ---------------------------------------------------------------- |
+| `systemErrors`        | `SystemErrors` (Sum across core ops, 1 min) | > 0               | Server-side (HTTP 500) faults — a table availability signal.     |
+| `readThrottleEvents`  | `ReadThrottleEvents` (Sum, 1 min)           | > 0               | Read throttling — hot partition or insufficient read capacity.   |
+| `writeThrottleEvents` | `WriteThrottleEvents` (Sum, 1 min)          | > 0               | Write throttling — hot partition or insufficient write capacity. |
+
+The thresholds are deliberately strict — a healthy table should sit at zero. Tune them up for workloads where brief, self-correcting throttling under burst is acceptable.
+
+`SystemErrors` is emitted per-operation, and a CloudWatch alarm on a metric-math expression can reference at most 10 metrics, so the `systemErrors` alarm sums the ten core data-plane operations (`GetItem`, `BatchGetItem`, `Query`, `Scan`, `PutItem`, `UpdateItem`, `DeleteItem`, `BatchWriteItem`, `TransactGetItems`, `TransactWriteItems`). The PartiQL statement operations and the stream `GetRecords` operation are excluded; add a custom alarm if your errors live there.
+
+The defaults are exported as `TABLE_ALARM_DEFAULTS` for visibility and testing:
+
+```ts
+import { TABLE_ALARM_DEFAULTS } from "@composurecdk/dynamodb";
+```
+
+### What is not alarmed by default
+
+- **Account-level utilization alarms** (`AccountProvisionedReadCapacityUtilization`, `AccountProvisionedWriteCapacityUtilization`) from the AWS recommended-alarms list are account-scoped, not table-scoped, so they do not belong to a per-table builder.
+- **Provisioned-capacity utilization** (consumed vs. provisioned) only applies to provisioned tables; the default billing mode here is on-demand. Add it via `addAlarm` on a provisioned table.
+- **`UserErrors` / `ConditionalCheckFailedRequests`** are caller- or application-level signals (HTTP 400) and too workload-dependent for a useful generic threshold.
+
+### Customizing thresholds
+
+Override individual alarm properties via `recommendedAlarms`. Unspecified fields keep their defaults.
+
+```ts
+const table = createTableV2Builder()
+  .partitionKey({ name: "pk", type: AttributeType.STRING })
+  .recommendedAlarms({
+    readThrottleEvents: { threshold: 10, evaluationPeriods: 3 },
+  });
+```
+
+### Disabling alarms
+
+```ts
+builder.recommendedAlarms(false);
+// or
+builder.recommendedAlarms({ enabled: false });
+// or individually
+builder.recommendedAlarms({ writeThrottleEvents: false });
+```
+
+### Custom alarms
+
+Add custom alarms alongside the recommended ones via `addAlarm`. The callback receives an `AlarmDefinitionBuilder` typed to `ITable`, so the metric factory has access to the table's metric helpers.
+
+```ts
+import { Duration } from "aws-cdk-lib";
+
+const table = createTableV2Builder()
+  .partitionKey({ name: "pk", type: AttributeType.STRING })
+  .addAlarm("userErrors", (alarm) =>
+    alarm
+      .metric((table) => table.metricUserErrors({ period: Duration.minutes(5) }))
+      .threshold(5)
+      .greaterThan()
+      .description("Table is returning client-side (HTTP 400) errors."),
+  );
+```
+
+### Applying alarm actions
+
+Alarms are returned in the build result as `Record<string, Alarm>`:
+
+```ts
+const result = createTableV2Builder()
+  .partitionKey({ name: "pk", type: AttributeType.STRING })
+  .build(stack, "Orders");
+
+const alertTopic = new Topic(stack, "AlertTopic");
+for (const alarm of Object.values(result.alarms)) {
+  alarm.addAlarmAction(new SnsAction(alertTopic));
+}
+```
+
+For composing the alarm-actions wiring across multiple builders in a single `compose` system, see [`alarmActionsPolicy`](../cloudwatch/README.md) in `@composurecdk/cloudwatch`.
+
+## Composition
+
+Both builders implement `Lifecycle`, so they slot into a `compose` system and expose a `ref()`-able stream for wiring a consumer (e.g. a Lambda `DynamoEventSource`):
+
+```ts
+import { compose } from "@composurecdk/core";
+import { createTableV2Builder } from "@composurecdk/dynamodb";
+import { createFunctionBuilder } from "@composurecdk/lambda";
+
+const system = compose(
+  {
+    orders: createTableV2Builder()
+      .partitionKey({ name: "pk", type: AttributeType.STRING })
+      .dynamoStream(StreamViewType.NEW_AND_OLD_IMAGES),
+    processor: createFunctionBuilder(),
+  },
+  { orders: [], processor: ["orders"] },
+);
+```

package/dist/commonjs/defaults.d.ts

@@ -0,0 +1,25 @@
+import { type TableProps, type TablePropsV2 } 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 declare const TABLE_DEFAULTS: Partial<TableProps>;
+/**
+ * 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 declare const TABLE_V2_DEFAULTS: Partial<TablePropsV2>;
+//# sourceMappingURL=defaults.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,YAAY,EAClB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,CAAC,UAAU,CAwD9C,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAAO,CAAC,YAAY,CA4DnD,CAAC"}

package/dist/commonjs/defaults.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TABLE_V2_DEFAULTS = exports.TABLE_DEFAULTS = void 0;
+const aws_dynamodb_1 = require("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}.
+ */
+exports.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: aws_dynamodb_1.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: aws_dynamodb_1.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.
+ */
+exports.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: aws_dynamodb_1.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: aws_dynamodb_1.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/commonjs/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/defaults.ts"],"names":[],"mappings":";;;AAAA,2DAOkC;AAElC;;;;;;;;GAQG;AACU,QAAA,cAAc,GAAwB;IACjD;;;;;;;;;;OAUG;IACH,WAAW,EAAE,0BAAW,CAAC,eAAe;IAExC;;;;;;;;;;;;;;OAcG;IACH,UAAU,EAAE,8BAAe,CAAC,WAAW;IAEvC;;;;;;;;;OASG;IACH,gCAAgC,EAAE,EAAE,0BAA0B,EAAE,IAAI,EAAE;IAEtE;;;;;;;;;;;OAWG;IACH,kBAAkB,EAAE,IAAI;CACzB,CAAC;AAEF;;;;;;;;;;;GAWG;AACU,QAAA,iBAAiB,GAA0B;IACtD;;;;;;;;;;OAUG;IACH,OAAO,EAAE,sBAAO,CAAC,QAAQ,EAAE;IAE3B;;;;;;;;;;;;;;OAcG;IACH,UAAU,EAAE,gCAAiB,CAAC,aAAa,EAAE;IAE7C;;;;;;;;;;;;;OAaG;IACH,gCAAgC,EAAE,EAAE,0BAA0B,EAAE,IAAI,EAAE;IAEtE;;;;;;;;;;;OAWG;IACH,kBAAkB,EAAE,IAAI;CACzB,CAAC"}

package/dist/commonjs/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/commonjs/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/commonjs/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TABLE_ALARM_DEFAULTS = exports.TABLE_V2_DEFAULTS = exports.TABLE_DEFAULTS = exports.createTableV2Builder = exports.createTableBuilder = void 0;
+var table_builder_js_1 = require("./table-builder.js");
+Object.defineProperty(exports, "createTableBuilder", { enumerable: true, get: function () { return table_builder_js_1.createTableBuilder; } });
+var table_v2_builder_js_1 = require("./table-v2-builder.js");
+Object.defineProperty(exports, "createTableV2Builder", { enumerable: true, get: function () { return table_v2_builder_js_1.createTableV2Builder; } });
+var defaults_js_1 = require("./defaults.js");
+Object.defineProperty(exports, "TABLE_DEFAULTS", { enumerable: true, get: function () { return defaults_js_1.TABLE_DEFAULTS; } });
+Object.defineProperty(exports, "TABLE_V2_DEFAULTS", { enumerable: true, get: function () { return defaults_js_1.TABLE_V2_DEFAULTS; } });
+var table_alarm_defaults_js_1 = require("./table-alarm-defaults.js");
+Object.defineProperty(exports, "TABLE_ALARM_DEFAULTS", { enumerable: true, get: function () { return table_alarm_defaults_js_1.TABLE_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,uDAK4B;AAJ1B,sHAAA,kBAAkB,OAAA;AAKpB,6DAK+B;AAJ7B,2HAAA,oBAAoB,OAAA;AAKtB,6CAAkE;AAAzD,6GAAA,cAAc,OAAA;AAAE,gHAAA,iBAAiB,OAAA;AAE1C,qEAAiE;AAAxD,+HAAA,oBAAoB,OAAA"}

package/dist/commonjs/package.json

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

package/dist/commonjs/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/commonjs/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/commonjs/table-alarm-config.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=table-alarm-config.js.map

package/dist/commonjs/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/commonjs/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/commonjs/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/commonjs/table-alarm-defaults.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TABLE_ALARM_DEFAULTS = void 0;
+const aws_cloudwatch_1 = require("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
+ */
+exports.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: aws_cloudwatch_1.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: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /**
+     * > 0 — surface write throttling immediately, on the same basis as read
+     * throttling.
+     */
+    writeThrottleEvents: {
+        threshold: 0,
+        evaluationPeriods: 1,
+        datapointsToAlarm: 1,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=table-alarm-defaults.js.map

package/dist/commonjs/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,+DAA8D;AAU9D;;;;;;;;;;GAUG;AACU,QAAA,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,iCAAgB,CAAC,aAAa;KACjD;IAED;;;;OAIG;IACH,kBAAkB,EAAE;QAClB,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED;;;OAGG;IACH,mBAAmB,EAAE;QACnB,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

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