@aws-blocks/bb-distributed-table 0.1.5 → 0.1.6

package/src/types.ts

@@ -57,6 +57,80 @@ export interface DistributedTableOptions<
 	 * ```
 	 */
 	ttl?: keyof T & string;
+	/**
+	 * DynamoDB Point-in-Time Recovery (continuous backups) — restore the table
+	 * to any second within a retention window, protecting against accidental
+	 * writes/deletes and logical corruption.
+	 *
+	 * A single knob, since the recovery window only means anything when PITR is
+	 * on:
+	 * - `true` — enable PITR with the default 35-day window.
+	 * - `false` — disable PITR.
+	 * - `{ retentionDays: n }` — enable PITR and keep `n` days of continuous
+	 *   backups (**1–35**). A shorter window reduces backup-storage cost at the
+	 *   expense of how far back you can restore.
+	 *
+	 * When omitted, the stack-wide default applies (`defaults.pointInTimeRecovery`
+	 * from `BlocksPresets` — on under `production`, off under `sandbox`). A
+	 * per-block value always wins.
+	 *
+	 * Note: PITR bills for continuous-backup storage (per GB-month of table
+	 * size), so it is not free on large tables.
+	 */
+	pointInTimeRecovery?: boolean | { retentionDays: number };
+	/**
+	 * How hard the table is to destroy — a single knob spanning DynamoDB
+	 * deletion protection and the CloudFormation removal policy, which together
+	 * answer one question: "can this table be destroyed?"
+	 *
+	 * - `'disposable'`: `RemovalPolicy.DESTROY`, deletion protection **off**.
+	 *   Deleting the stack deletes the table. The **sandbox default** — keeps
+	 *   `sandbox:destroy` a one-command teardown.
+	 * - `'retained'`: `RemovalPolicy.RETAIN`, deletion protection **off**.
+	 *   Deleting the stack orphans (keeps) the table, but a direct
+	 *   `DeleteTable`/console delete still works. Use when you want the data to
+	 *   survive stack teardown without blocking intentional deletes.
+	 * - `'locked'`: `RemovalPolicy.RETAIN` **and** deletion protection **on**.
+	 *   The table survives stack deletion and DynamoDB refuses a direct delete
+	 *   until protection is turned off. The **production default**.
+	 *
+	 * When omitted, removal policy and deletion protection follow the stack-wide
+	 * `defaults` (`BlocksPresets.production` ≈ `'locked'`, `BlocksPresets.sandbox`
+	 * ≈ `'disposable'`). A per-block value always wins.
+	 *
+	 * Replaces the separate `deletionProtection` + `removalPolicy` booleans:
+	 * those two knobs could encode the contradictory `deletionProtection: true`
+	 * + `removalPolicy: 'destroy'` state, which wedges stack deletion (CFN
+	 * issues `DeleteTable`, DynamoDB refuses it, the stack lands in
+	 * `DELETE_FAILED`). A single enum makes that state unrepresentable.
+	 */
+	protection?: 'disposable' | 'retained' | 'locked';
+	/**
+	 * Server-side encryption at rest.
+	 *
+	 * - `'aws-managed'` (default): SSE with the AWS-managed `aws/dynamodb` KMS
+	 *   key. Auditable via CloudTrail with no per-key monthly charge.
+	 * - `'customer-managed'`: provisions a **dedicated** customer-managed KMS
+	 *   key (CMK) for this table, giving you full control over rotation and key
+	 *   policy. Incurs standard KMS key + request charges — and note this mints
+	 *   a **separate key per table**, so a dozen tables means a dozen keys.
+	 * - a {@link ExternalKmsKeyRef} from {@link DistributedTable.fromKmsKey}:
+	 *   uses an **existing** CMK you already own, so several tables can share one
+	 *   key (and one monthly charge) instead of each provisioning its own.
+	 *
+	 * DynamoDB is always encrypted at rest; this only selects the key.
+	 *
+	 * @example
+	 * ```ts
+	 * // Share one key across several tables
+	 * const key = DistributedTable.fromKmsKey(
+	 *   'arn:aws:kms:us-east-1:111122223333:key/abcd-1234',
+	 * );
+	 * new DistributedTable(scope, 'orders', { schema, key: { partitionKey: 'id' }, encryption: key });
+	 * new DistributedTable(scope, 'events', { schema, key: { partitionKey: 'id' }, encryption: key });
+	 * ```
+	 */
+	encryption?: 'aws-managed' | 'customer-managed' | ExternalKmsKeyRef;
 	/**
 	 * How reads (`get`, `getBatch`, `query`, `scan`) reconcile a stored item with
 	 * the configured `schema`. Writes (`put`/`putBatch`) always validate; this
@@ -109,6 +183,17 @@ export interface ExternalTableRef {
 	readonly tableName: string;
 }
 
+/**
+ * A reference to an existing customer-managed KMS key, produced by
+ * {@link DistributedTable.fromKmsKey}. Pass it as the `encryption` option to
+ * encrypt the table with a CMK you already own — letting several tables share
+ * one key instead of each provisioning its own dedicated key.
+ */
+export interface ExternalKmsKeyRef {
+	readonly __brand: 'ExternalKmsKeyRef';
+	readonly keyArn: string;
+}
+
 // ── Key type for get/delete ─────────────────────────────────────────────────
 
 /**

package/src/version.ts

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
 export const BB_NAME = 'DistributedTable';
-export const BB_VERSION = '0.1.5';
+export const BB_VERSION = '0.1.6';