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

package/src/index.mock.ts

@@ -15,6 +15,7 @@ export type {
 	DistributedTableOptions,
 	ReadValidationMode,
 	ExternalTableRef,
+	ExternalKmsKeyRef,
 	TableKey,
 	PartitionKeyCondition,
 	SortKeyCondition,
@@ -29,6 +30,7 @@ import type {
 	TableKeyConfig,
 	DistributedTableOptions,
 	ExternalTableRef,
+	ExternalKmsKeyRef,
 	SortKeyCondition,
 	ScanOptions,
 	PutOptions,
@@ -264,7 +266,14 @@ export class DistributedTable<
 			const dir = options.order === 'desc' ? -1 : 1;
 			items.sort((a, b) => {
 				const av = (a as any)[skField], bv = (b as any)[skField];
-				return (av < bv ? -1 : av > bv ? 1 : 0) * dir;
+				const primary = av < bv ? -1 : av > bv ? 1 : 0;
+				// Tie-break on the base-table primary key. On a GSI the sort key need
+				// not be unique, so equal sort-key values must NOT fall back to Map
+				// insertion order (which varies by write order / disk reload) — that's
+				// the mock-vs-DynamoDB divergence. DynamoDB orders index ties by the
+				// base-table key, and the whole index (ties included) reverses under
+				// `order: 'desc'`.
+				return (primary !== 0 ? primary : this.compareByBaseKey(a, b)) * dir;
 			});
 		}
 
@@ -334,6 +343,10 @@ export class DistributedTable<
 		return { __brand: 'ExternalTableRef' as const, tableName };
 	}
 
+	static fromKmsKey(keyArn: string): ExternalKmsKeyRef {
+		return { __brand: 'ExternalKmsKeyRef' as const, keyArn };
+	}
+
 	// ── Internal ────────────────────────────────────────────────────────────
 
 	private checkFieldEquals(keyStr: string, fields: Partial<T>): void {
@@ -353,6 +366,27 @@ export class DistributedTable<
 		}
 	}
 
+	/**
+	 * Deterministic tie-break for `query` ordering: compare two items by the
+	 * base-table primary key (partition key, then sort key). Used when an index
+	 * sort-key value is shared by multiple items, so results don't depend on Map
+	 * insertion order. Returns a stable -1/0/1.
+	 */
+	private compareByBaseKey(a: T, b: T): number {
+		const pk = this.keyConfig.partitionKey;
+		const ap = (a as any)[pk], bp = (b as any)[pk];
+		if (ap !== bp) return ap < bp ? -1 : 1;
+		const sk = this.keyConfig.sortKey;
+		if (sk) {
+			const as = (a as any)[sk], bs = (b as any)[sk];
+			if (as !== bs) return as < bs ? -1 : 1;
+		}
+		// Unreachable for distinct rows: every item is keyed by its serialized base
+		// primary key, so two different entries always differ in base PK or SK.
+		// (String comparisons above use JS UTF-16 order — see DESIGN.md D-DT-6.)
+		return 0;
+	}
+
 	private serializeKey(key: TableKey<T, K>): string {
 		const parts = [(key as any)[this.keyConfig.partitionKey]];
 		if (this.keyConfig.sortKey) parts.push((key as any)[this.keyConfig.sortKey]);

package/src/index.test.ts

@@ -859,4 +859,49 @@ describe('DistributedTable', () => {
 			);
 		});
 	});
+
+	// ── Query: index sort-key ties are ordered deterministically ────────────
+	describe('query (index sort-key ties)', () => {
+		const cardSchema = z.object({ boardId: z.string(), cardId: z.string(), position: z.number() });
+		// Base key is (boardId, cardId); the GSI sorts by `position`, which is NOT
+		// unique — several cards can share a position. DynamoDB tie-breaks such
+		// index rows by the base-table key, so the mock must too (not by Map
+		// insertion order, which varies by write order / disk reload).
+		function cardTable() {
+			return new DistributedTable(testScope(), 'cards', {
+				schema: cardSchema,
+				key: { partitionKey: 'boardId', sortKey: 'cardId' },
+				indexes: { byPosition: { partitionKey: 'boardId', sortKey: 'position' } },
+			});
+		}
+		const q = (t: ReturnType<typeof cardTable>, order?: 'asc' | 'desc') =>
+			collect(t.query({ index: 'byPosition', where: { boardId: { equals: 'b1' } }, ...(order ? { order } : {}) }));
+
+		test('ties on the index sort key order by the base-table key, regardless of write order', async () => {
+			const t1 = cardTable();
+			// All position=1; insert cardIds out of order.
+			for (const cardId of ['c3', 'c1', 'c2']) await t1.put({ boardId: 'b1', cardId, position: 1 });
+			assert.deepEqual((await q(t1)).map((c) => c.cardId), ['c1', 'c2', 'c3']);
+
+			// A different write order must yield the SAME result (deterministic).
+			const t2 = cardTable();
+			for (const cardId of ['c2', 'c3', 'c1']) await t2.put({ boardId: 'b1', cardId, position: 1 });
+			assert.deepEqual((await q(t2)).map((c) => c.cardId), ['c1', 'c2', 'c3']);
+		});
+
+		test('desc reverses ties too (whole index order flips)', async () => {
+			const t = cardTable();
+			for (const cardId of ['c1', 'c3', 'c2']) await t.put({ boardId: 'b1', cardId, position: 1 });
+			assert.deepEqual((await q(t, 'desc')).map((c) => c.cardId), ['c3', 'c2', 'c1']);
+		});
+
+		test('primary order stays by index sort key; base key only breaks ties', async () => {
+			const t = cardTable();
+			await t.put({ boardId: 'b1', cardId: 'zzz', position: 1 });
+			await t.put({ boardId: 'b1', cardId: 'aaa', position: 2 });
+			await t.put({ boardId: 'b1', cardId: 'mmm', position: 1 });
+			// position asc first (1,1,2); within position=1, base key (cardId) breaks the tie.
+			assert.deepEqual((await q(t)).map((c) => [c.position, c.cardId]), [[1, 'mmm'], [1, 'zzz'], [2, 'aaa']]);
+		});
+	});
 });

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.7';