@aws-blocks/bb-distributed-table 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Shared types for DistributedTable. Imported by mock, aws, and browser entry points.
+ * This file has zero runtime dependencies — types only.
+ */
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+export interface TableKeyConfig<T> {
+    /** Attribute name used as the partition key. Must be a field in the schema. */
+    partitionKey: keyof T & string;
+    /** Attribute name used as the sort key. Must be a field in the schema. Optional. */
+    sortKey?: keyof T & string;
+}
+export interface DistributedTableOptions<T, K extends TableKeyConfig<T> = TableKeyConfig<T>, Indexes extends Record<string, TableKeyConfig<T>> = Record<string, TableKeyConfig<T>>> {
+    /** StandardSchemaV1 schema for runtime validation and type inference. Required. */
+    schema: StandardSchemaV1<T>;
+    /** Primary key configuration. */
+    key: K;
+    /** Global secondary index definitions. Optional. */
+    indexes?: Indexes;
+    /**
+     * Enable DynamoDB Time-to-Live (TTL) on the specified attribute.
+     * The attribute must be a field in the schema and should contain a Unix
+     * epoch timestamp (in seconds). DynamoDB automatically deletes items
+     * whose TTL attribute value is older than the current time.
+     *
+     * @example
+     * ```typescript
+     * const sessions = new DistributedTable(scope, 'sessions', {
+     *   schema: sessionSchema,
+     *   key: { partitionKey: 'sessionId' },
+     *   ttl: 'expiresAt',
+     * });
+     * ```
+     */
+    ttl?: keyof T & string;
+    /** Wrap an existing table instead of creating one. */
+    table?: ExternalTableRef;
+    /** Optional logger for internal operations. When omitted, a default Logger at error level is created. */
+    logger?: ChildLogger;
+}
+export interface ExternalTableRef {
+    readonly __brand: 'ExternalTableRef';
+    readonly tableName: string;
+}
+/**
+ * Picks exactly the key fields from T and makes them required.
+ * Non-key fields are excluded.
+ */
+export type TableKey<T, K extends TableKeyConfig<T> = TableKeyConfig<T>> = K extends {
+    sortKey: infer SK extends keyof T & string;
+} ? Required<Pick<T, K['partitionKey'] | SK>> : Required<Pick<T, K['partitionKey']>>;
+/** Partition key condition — DynamoDB requires exact match on PK in a Query. */
+export type PartitionKeyCondition<V> = {
+    equals: V;
+};
+/** Sort key condition — supports range queries, beginsWith (strings only). */
+export type SortKeyCondition<V> = {
+    equals?: V;
+    greaterThan?: V;
+    greaterThanOrEqual?: V;
+    lessThan?: V;
+    lessThanOrEqual?: V;
+    between?: [V, V];
+    beginsWith?: V extends string ? string : never;
+};
+/**
+ * Query input for a given index. The partition key field is required (equals only).
+ * The sort key field is optional with rich conditions. No other fields appear.
+ *
+ * @example
+ * ```typescript
+ * // Index: { partitionKey: 'userId', sortKey: 'createdAt' }
+ * // T: { userId: string; createdAt: number; name: string }
+ * // KeyCondition = { userId: { equals: string }; createdAt?: SortKeyCondition<number> }
+ * ```
+ */
+export type KeyCondition<T, K extends TableKeyConfig<T>> = K extends {
+    sortKey: infer SK extends keyof T & string;
+} ? {
+    [P in K['partitionKey']]: PartitionKeyCondition<T[P]>;
+} & {
+    [P in SK]?: SortKeyCondition<T[P]>;
+} : {
+    [P in K['partitionKey']]: PartitionKeyCondition<T[P]>;
+};
+/**
+ * Query options using named parameters. The `where` clause provides key
+ * conditions, `index` selects a GSI (omit for primary key), and `limit`
+ * and `order` control result size and sort direction.
+ *
+ * @example
+ * ```typescript
+ * // Primary key query (no index)
+ * for await (const item of table.query({ where: { userId: { equals: 'u1' } } })) { ... }
+ *
+ * // GSI query with limit and reverse order
+ * for await (const item of table.query({
+ *   index: 'byTimestamp',
+ *   where: { userId: { equals: 'u1' }, timestamp: { greaterThan: 1000 } },
+ *   limit: 10,
+ *   order: 'desc',
+ * })) { ... }
+ * ```
+ */
+export type QueryOptions<T, K extends TableKeyConfig<T>, Indexes extends Record<string, TableKeyConfig<T>>> = {
+    [Name in string & keyof Indexes]: {
+        /** GSI to query. Omit to query the primary key. */
+        index: Name;
+        /** Key conditions for the query. */
+        where: KeyCondition<T, Indexes[Name]>;
+        /** Maximum number of items to return. */
+        limit?: number;
+        /** Sort order. Defaults to 'asc'. */
+        order?: 'asc' | 'desc';
+    };
+}[string & keyof Indexes] | {
+    index?: undefined;
+    /** Key conditions for the primary key query. */
+    where: KeyCondition<T, K>;
+    /** Maximum number of items to return. */
+    limit?: number;
+    /** Sort order. Defaults to 'asc'. */
+    order?: 'asc' | 'desc';
+};
+export interface ScanOptions {
+    /** Maximum number of items to return. */
+    limit?: number;
+}
+export type PutOptions<T> = {
+    ifNotExists: true;
+    ifFieldEquals?: never;
+} | {
+    ifNotExists?: never;
+    ifFieldEquals: Partial<T>;
+} | Record<string, never>;
+export type DeleteOptions<T> = {
+    ifExists: true;
+    ifFieldEquals?: never;
+} | {
+    ifExists?: never;
+    ifFieldEquals: Partial<T>;
+} | Record<string, never>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,3 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+export {};

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+export declare const BB_NAME = "DistributedTable";
+export declare const BB_VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,OAAO,qBAAqB,CAAC;AAC1C,eAAO,MAAM,UAAU,UAAU,CAAC"}

package/dist/version.js

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

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@aws-blocks/bb-distributed-table",
+  "version": "0.1.0",
+  "author": "Amazon Web Services",
+  "license": "Apache-2.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "DESIGN.md",
+    "src",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "browser": "./dist/index.browser.js",
+      "cdk": {
+        "types": "./dist/index.cdk.d.ts",
+        "default": "./dist/index.cdk.js"
+      },
+      "aws-runtime": "./dist/index.aws.js",
+      "types": "./dist/index.mock.d.ts",
+      "default": "./dist/index.mock.js"
+    }
+  },
+  "scripts": {
+    "prebuild": "node ../../scripts/generate-version.mjs DistributedTable",
+    "build": "tsc --build && npm run build:lambda",
+    "build:lambda": "esbuild src/gsi-manager-lambda.ts --bundle --platform=node --target=node24 --outfile=dist/gsi-manager-lambda/index.js --format=cjs --external:@aws-sdk/*",
+    "test": "node --test dist/index.test.js dist/parity.test.js dist/index.cdk.test.js"
+  },
+  "dependencies": {
+    "@aws-blocks/core": "^0.1.0",
+    "@aws-blocks/bb-logger": "^0.1.0",
+    "@aws-sdk/client-dynamodb": "^3.0.0",
+    "@aws-sdk/lib-dynamodb": "^3.0.0",
+    "@standard-schema/spec": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.3.0",
+    "zod": "^4.1.12"
+  },
+  "peerDependencies": {
+    "aws-cdk-lib": "^2.257.0",
+    "constructs": "^10.6.0"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,145 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Typed error constants for DistributedTable. Use with `isBlocksError()` in catch blocks.
+ *
+ * @example
+ * ```typescript
+ * import { isBlocksError } from '@aws-blocks/core';
+ * import { DistributedTableErrors } from '@aws-blocks/bb-distributed-table';
+ *
+ * try {
+ *   await table.put(item, { ifNotExists: true });
+ * } catch (e: unknown) {
+ *   if (isBlocksError(e, DistributedTableErrors.ConditionalCheckFailed)) {
+ *     // item already exists
+ *   }
+ *   throw e;
+ * }
+ * ```
+ */
+export const DistributedTableErrors = {
+	ConditionalCheckFailed: 'ConditionalCheckFailedException',
+	ValidationFailed: 'ValidationFailedException',
+	/**
+	 * The query or condition shape is invalid and was rejected before reaching
+	 * DynamoDB: a missing `where` clause, a partition key not given as
+	 * `{ equals: value }`, an unknown index, more than one sort-key condition, or
+	 * an empty `ifFieldEquals`. These are all caller bugs — something the caller
+	 * can fix by correcting the call. Catchable via
+	 * `isBlocksError(e, DistributedTableErrors.InvalidQuery)`.
+	 *
+	 * Kept distinct from {@link ItemTooLarge} (a runtime data condition) so a
+	 * customer can tell "my query is wrong" from "this item is too big" by name
+	 * alone rather than string-matching the message.
+	 */
+	InvalidQuery: 'InvalidQueryException',
+	/**
+	 * An item exceeds DynamoDB's 400 KB per-item size limit. Unlike an invalid
+	 * query, this is not necessarily a caller bug — the size of a given item may
+	 * be outside the caller's control — so callers may want to branch on it
+	 * (skip, split, or store a reference instead). Catchable via
+	 * `isBlocksError(e, DistributedTableErrors.ItemTooLarge)`.
+	 *
+	 * The mock checks serialized byte length client-side and throws this directly.
+	 * On AWS, DynamoDB raises a generic `ValidationException` for oversized items;
+	 * the runtime detects the size-specific message and re-maps it to this name so
+	 * both layers are catchable with the same code. Other `ValidationException`
+	 * causes (malformed expressions, type mismatches) propagate as-is.
+	 */
+	ItemTooLarge: 'ItemTooLargeException',
+	/**
+	 * A batch operation could not complete all entries within the retry budget.
+	 * DynamoDB batch APIs return UnprocessedKeys/UnprocessedItems (HTTP 200) under
+	 * sustained throttling; when retries are exhausted we surface this so callers
+	 * can back off and resubmit rather than silently losing writes or mistaking a
+	 * throttled read for a missing item.
+	 *
+	 * The in-memory mock never throttles, so it never produces this error — the
+	 * constant is shared purely so catch-site handling is identical across both.
+	 */
+	BatchIncomplete: 'BatchIncompleteException',
+} as const;
+
+/**
+ * @internal Build an Error whose `name` carries the typed error code (so callers
+ * can match it with `isBlocksError`). Shared by the mock and AWS runtime so both
+ * produce identically shaped errors.
+ */
+export function blocksError(name: string, message: string): Error {
+	const err = new Error(`${name}: ${message}`);
+	err.name = name;
+	return err;
+}
+
+/**
+ * @internal Normalize a sort-key condition before it drives a query. Shared by
+ * the mock and AWS runtime so both treat the same inputs identically:
+ *
+ * - **Zero defined fields** (`undefined`, or a present-but-empty `{}` /
+ *   `{ createdAt: undefined }`) → returns `undefined`, i.e. "no sort-key filter,
+ *   query the whole partition". A present-but-empty object would otherwise
+ *   diverge: the mock's per-item matcher accepts everything (returns the whole
+ *   partition) while the AWS runtime registers `#sk` in `ExpressionAttributeNames`
+ *   with no clause that uses it, which DynamoDB rejects with `ValidationException`.
+ * - **Exactly one defined field** → returns the condition unchanged.
+ * - **More than one defined field** → throws `InvalidQuery`, because DynamoDB allows
+ *   only one sort-key condition per `KeyConditionExpression` (use `between` for ranges).
+ *
+ * @throws {DistributedTableErrors.InvalidQuery} If more than one sort-key field is defined.
+ */
+export function normalizeSortKeyCondition<C extends Record<string, unknown>>(
+	condition: C | undefined,
+): C | undefined {
+	if (!condition) return undefined;
+	const definedKeys = Object.keys(condition).filter(k => condition[k] !== undefined);
+	if (definedKeys.length === 0) return undefined;
+	if (definedKeys.length > 1) {
+		throw blocksError(DistributedTableErrors.InvalidQuery, DistributedTableMessages.multipleSortKeyConditions(definedKeys));
+	}
+	return condition;
+}
+
+/**
+ * @internal Validation messages shared by the mock and AWS runtime. Centralised
+ * here so the two implementations stay byte-for-byte in lockstep — parity tests
+ * assert the same wording against both.
+ */
+export const DistributedTableMessages = {
+	indexNotFound: (index: string | undefined) => `Index '${index}' not found`,
+	whereRequired: (pkField: string) =>
+		`query() requires a 'where' clause with partition key field '${pkField}'`,
+	partitionKeyEqualsRequired: (pkField: string) =>
+		`query() requires '${pkField}: { equals: value }' in the where clause (partition key must be an exact match)`,
+	multipleSortKeyConditions: (conditionKeys: string[]) =>
+		`Only one sort key condition is allowed per query (DynamoDB limitation). ` +
+		`Got: ${conditionKeys.join(', ')}. Use "between" for range queries.`,
+	emptyIfFieldEquals: 'ifFieldEquals must contain at least one field with a non-undefined value',
+	itemTooLarge: (bytes: number) =>
+		`Item size has exceeded the maximum allowed size of 400 KB (got ${bytes} bytes)`,
+	batchIncomplete: (operation: string, remaining: number, attempts: number) =>
+		`${operation} did not complete: ${remaining} entr${remaining === 1 ? 'y' : 'ies'} still unprocessed ` +
+		`after ${attempts} attempts (DynamoDB throttling or response-size limits). Retry with backoff.`,
+} as const;
+
+/**
+ * @internal Re-map DynamoDB's generic `ValidationException` to the intent-revealing
+ * `ItemTooLarge` name when (and only when) it was raised for an oversized item.
+ *
+ * DynamoDB raises a single `ValidationException` for many unrelated conditions, so
+ * we narrow on the size-specific message ("size has exceeded") before re-mapping —
+ * other `ValidationException` causes (malformed expressions, type mismatches) are
+ * left untouched and propagate as-is. This mirrors the mock's client-side size
+ * check so both layers are catchable with `isBlocksError(e, ItemTooLarge)`. The
+ * original DynamoDB error is preserved as `cause` (kept server-side per D-003) so
+ * its stack and requestId remain available for debugging.
+ */
+export function remapItemTooLarge(err: unknown): unknown {
+	if (err instanceof Error && err.name === 'ValidationException' && /size has exceeded/i.test(err.message)) {
+		const remapped = new Error(err.message, { cause: err });
+		remapped.name = DistributedTableErrors.ItemTooLarge;
+		return remapped;
+	}
+	return err;
+}

package/src/gsi-manager-lambda.ts

@@ -0,0 +1,305 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+	DynamoDBClient,
+	DescribeTableCommand,
+	UpdateTableCommand,
+	DeleteTableCommand,
+	CreateTableCommand,
+	ScanCommand,
+	BatchWriteItemCommand,
+	BillingMode,
+	ScalarAttributeType,
+	KeyType,
+} from '@aws-sdk/client-dynamodb';
+
+const dynamodb = new DynamoDBClient({});
+
+interface IndexConfig {
+	partitionKey: string;
+	sortKey?: string;
+	partitionKeyType?: 'S' | 'N' | 'B';
+	sortKeyType?: 'S' | 'N' | 'B';
+}
+
+interface CfnEvent {
+	RequestType: 'Create' | 'Update' | 'Delete';
+	PhysicalResourceId?: string;
+	ResourceProperties: {
+		TableName: string;
+		Indexes: Record<string, IndexConfig>;
+		SandboxMode?: string;
+	};
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+async function describeTable(tableName: string) {
+	const result = await dynamodb.send(new DescribeTableCommand({ TableName: tableName }));
+	return result.Table!;
+}
+
+function getCurrentGSIs(table: any): Record<string, { pk: string; sk?: string }> {
+	const gsis: Record<string, { pk: string; sk?: string }> = {};
+	for (const gsi of table.GlobalSecondaryIndexes ?? []) {
+		const pk = gsi.KeySchema?.find((k: any) => k.KeyType === 'HASH')?.AttributeName;
+		const sk = gsi.KeySchema?.find((k: any) => k.KeyType === 'RANGE')?.AttributeName;
+		if (pk) gsis[gsi.IndexName!] = { pk, sk };
+	}
+	return gsis;
+}
+
+function gsiMatchesDesired(table: any, desired: Record<string, IndexConfig>): boolean {
+	const current = getCurrentGSIs(table);
+	const currentNames = Object.keys(current);
+	const desiredNames = Object.keys(desired);
+
+	if (currentNames.length !== desiredNames.length) return false;
+	for (const name of desiredNames) {
+		if (!current[name]) return false;
+		if (current[name].pk !== desired[name].partitionKey) return false;
+		if (current[name].sk !== desired[name].sortKey) return false;
+	}
+	return true;
+}
+
+function isTableBusy(table: any): boolean {
+	if (table.TableStatus !== 'ACTIVE') return true;
+	for (const gsi of table.GlobalSecondaryIndexes ?? []) {
+		if (gsi.IndexStatus !== 'ACTIVE') return true;
+	}
+	return false;
+}
+
+// ── Sandbox fast path ───────────────────────────────────────────────────────
+
+async function recreateTableWithIndexes(tableName: string, desired: Record<string, IndexConfig>) {
+	console.log('⚠️  SANDBOX MODE: Recreating table with all GSIs (fast path)');
+
+	const table = await describeTable(tableName);
+
+	// Backup data
+	const items: any[] = [];
+	let lastKey: any;
+	do {
+		const result = await dynamodb.send(new ScanCommand({ TableName: tableName, ExclusiveStartKey: lastKey }));
+		items.push(...(result.Items ?? []));
+		lastKey = result.LastEvaluatedKey;
+	} while (lastKey);
+	console.log(`Backed up ${items.length} items`);
+
+	// Delete table
+	await dynamodb.send(new DeleteTableCommand({ TableName: tableName }));
+	while (true) {
+		try {
+			await dynamodb.send(new DescribeTableCommand({ TableName: tableName }));
+			await new Promise(r => setTimeout(r, 3000));
+		} catch (e: any) {
+			if (e.name === 'ResourceNotFoundException') break;
+			throw e;
+		}
+	}
+
+	// Collect all attribute definitions needed for keys
+	const usedAttrs = new Set<string>();
+	table.KeySchema!.forEach((k: any) => usedAttrs.add(k.AttributeName!));
+	for (const cfg of Object.values(desired)) {
+		usedAttrs.add(cfg.partitionKey);
+		if (cfg.sortKey) usedAttrs.add(cfg.sortKey);
+	}
+
+	const existingAttrMap = new Map<string, string>();
+	for (const attr of table.AttributeDefinitions ?? []) {
+		existingAttrMap.set(attr.AttributeName!, attr.AttributeType!);
+	}
+
+	const attrDefs = [...usedAttrs].map(name => ({
+		AttributeName: name,
+		AttributeType: (existingAttrMap.get(name) ??
+			Object.values(desired).find(c => c.partitionKey === name)?.partitionKeyType ??
+			Object.values(desired).find(c => c.sortKey === name)?.sortKeyType ??
+			ScalarAttributeType.S) as ScalarAttributeType,
+	}));
+
+	// Recreate with all GSIs
+	await dynamodb.send(new CreateTableCommand({
+		TableName: tableName,
+		KeySchema: table.KeySchema,
+		AttributeDefinitions: attrDefs,
+		BillingMode: BillingMode.PAY_PER_REQUEST,
+		GlobalSecondaryIndexes: Object.entries(desired).map(([name, cfg]) => ({
+			IndexName: name,
+			KeySchema: [
+				{ AttributeName: cfg.partitionKey, KeyType: KeyType.HASH },
+				...(cfg.sortKey ? [{ AttributeName: cfg.sortKey, KeyType: KeyType.RANGE }] : []),
+			],
+			Projection: { ProjectionType: 'ALL' as const },
+		})),
+	}));
+
+	// Wait for active
+	while (true) {
+		const t = await describeTable(tableName);
+		if (!isTableBusy(t)) break;
+		await new Promise(r => setTimeout(r, 3000));
+	}
+
+	// Restore data
+	for (let i = 0; i < items.length; i += 25) {
+		await dynamodb.send(new BatchWriteItemCommand({
+			RequestItems: { [tableName]: items.slice(i, i + 25).map(item => ({ PutRequest: { Item: item } })) },
+		}));
+	}
+	console.log(`✅ Sandbox: table recreated with ${Object.keys(desired).length} GSIs, ${items.length} items restored`);
+}
+
+// ── onEvent handler ─────────────────────────────────────────────────────────
+// Called once per Create/Update/Delete. Kicks off the first GSI change (or
+// the sandbox fast path). Returns immediately — isComplete polls for progress.
+
+export async function handler(event: CfnEvent) {
+	console.log('onEvent:', JSON.stringify(event, null, 2));
+
+	const { TableName, Indexes, SandboxMode } = event.ResourceProperties;
+	const desired = event.RequestType === 'Delete' ? {} : (Indexes ?? {});
+	const isSandbox = SandboxMode === 'true';
+
+	// On Create, we set the physical resource ID. On Update/Delete, we must
+	// echo back the original ID — CloudFormation rejects changes to it.
+	const physicalId = event.PhysicalResourceId ?? TableName;
+
+	// Check if already done
+	const table = await describeTable(TableName);
+	if (gsiMatchesDesired(table, desired) && !isTableBusy(table)) {
+		console.log('Already in desired state');
+		return { PhysicalResourceId: physicalId, Data: { Status: 'COMPLETE' } };
+	}
+
+	// Sandbox fast path: drop and recreate with all GSIs at once
+	if (isSandbox && Object.keys(desired).length > 0) {
+		await recreateTableWithIndexes(TableName, desired);
+		return { PhysicalResourceId: physicalId, Data: { Status: 'COMPLETE' } };
+	}
+
+	// Production path: initiate the first GSI change if table is idle.
+	// If table is busy (prior GSI still updating), just return — isComplete will poll.
+	if (!isTableBusy(table)) {
+		await initiateNextChange(TableName, table, desired);
+	}
+
+	return { PhysicalResourceId: physicalId, Data: { Status: 'IN_PROGRESS' } };
+}
+
+// ── isComplete handler ──────────────────────────────────────────────────────
+// Called periodically by the Provider framework. Checks if the table matches
+// the desired state. If a GSI update is in progress, returns IsComplete=false.
+// If the table is idle but doesn't match, initiates the next change.
+// Creations are performed before deletions when possible.
+
+export async function isCompleteHandler(event: any) {
+	console.log('isComplete:', JSON.stringify(event, null, 2));
+
+	const { TableName, Indexes, SandboxMode } = event.ResourceProperties;
+	const desired = event.RequestType === 'Delete' ? {} : (Indexes ?? {});
+
+	const table = await describeTable(TableName);
+
+	// If a GSI operation is in progress, wait for it
+	if (isTableBusy(table)) {
+		console.log('Table busy, waiting...');
+		return { IsComplete: false };
+	}
+
+	// If we match the desired state, we're done
+	if (gsiMatchesDesired(table, desired)) {
+		console.log('✅ All GSIs match desired state');
+		return { IsComplete: true };
+	}
+
+	// Table is idle but doesn't match — initiate the next change
+	await initiateNextChange(TableName, table, desired);
+	return { IsComplete: false };
+}
+
+// ── Initiate next GSI change ────────────────────────────────────────────────
+// Performs creations before deletions when possible.
+//
+// Edge case where deletion must happen first: if a desired GSI has the same
+// name as an existing GSI but different key schema. DynamoDB doesn't support
+// in-place GSI modification — the old one must be deleted before the new one
+// can be created. We detect this by checking if a current GSI name exists in
+// desired but with a different key schema.
+
+async function initiateNextChange(
+	tableName: string,
+	table: any,
+	desired: Record<string, IndexConfig>,
+) {
+	const current = getCurrentGSIs(table);
+	const existingAttrMap = new Map<string, string>();
+	for (const attr of table.AttributeDefinitions ?? []) {
+		existingAttrMap.set(attr.AttributeName!, attr.AttributeType!);
+	}
+
+	// 1. Check for schema-mismatched GSIs that must be deleted before recreation.
+	//    These take priority because the creation of the replacement can't proceed
+	//    until the old one is gone.
+	for (const [name, cur] of Object.entries(current)) {
+		const des = desired[name];
+		if (des && (cur.pk !== des.partitionKey || cur.sk !== des.sortKey)) {
+			console.log(`Deleting GSI '${name}' (schema mismatch — must delete before recreating)`);
+			await dynamodb.send(new UpdateTableCommand({
+				TableName: tableName,
+				GlobalSecondaryIndexUpdates: [{ Delete: { IndexName: name } }],
+			}));
+			return;
+		}
+	}
+
+	// 2. Create missing GSIs (creations before deletions)
+	for (const [name, cfg] of Object.entries(desired)) {
+		if (!current[name]) {
+			console.log(`Creating GSI '${name}'`);
+			const attrDefs: { AttributeName: string; AttributeType: ScalarAttributeType }[] = [];
+			attrDefs.push({
+				AttributeName: cfg.partitionKey,
+				AttributeType: (existingAttrMap.get(cfg.partitionKey) ?? cfg.partitionKeyType ?? ScalarAttributeType.S) as ScalarAttributeType,
+			});
+			if (cfg.sortKey) {
+				attrDefs.push({
+					AttributeName: cfg.sortKey,
+					AttributeType: (existingAttrMap.get(cfg.sortKey) ?? cfg.sortKeyType ?? ScalarAttributeType.S) as ScalarAttributeType,
+				});
+			}
+
+			await dynamodb.send(new UpdateTableCommand({
+				TableName: tableName,
+				AttributeDefinitions: attrDefs,
+				GlobalSecondaryIndexUpdates: [{
+					Create: {
+						IndexName: name,
+						KeySchema: [
+							{ AttributeName: cfg.partitionKey, KeyType: KeyType.HASH },
+							...(cfg.sortKey ? [{ AttributeName: cfg.sortKey, KeyType: KeyType.RANGE }] : []),
+						],
+						Projection: { ProjectionType: 'ALL' },
+					},
+				}],
+			}));
+			return;
+		}
+	}
+
+	// 3. Delete extra GSIs (only after all creations are done)
+	for (const name of Object.keys(current)) {
+		if (!desired[name]) {
+			console.log(`Deleting GSI '${name}' (no longer desired)`);
+			await dynamodb.send(new UpdateTableCommand({
+				TableName: tableName,
+				GlobalSecondaryIndexUpdates: [{ Delete: { IndexName: name } }],
+			}));
+			return;
+		}
+	}
+}