@aws-blocks/bb-distributed-table 0.1.0

package/dist/index.aws.d.ts

@@ -0,0 +1,59 @@
+import { Scope } from '@aws-blocks/core';
+import type { ScopeParent } from '@aws-blocks/core';
+export { DistributedTableErrors } from './errors.js';
+export type { TableKeyConfig, DistributedTableOptions, ExternalTableRef, TableKey, PartitionKeyCondition, SortKeyCondition, KeyCondition, QueryOptions, ScanOptions, PutOptions, DeleteOptions, } from './types.js';
+import type { TableKeyConfig, DistributedTableOptions, ExternalTableRef, ScanOptions, PutOptions, DeleteOptions, TableKey } from './types.js';
+import type { QueryOptions } from './types.js';
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+export declare class DistributedTable<T, K extends TableKeyConfig<T> = TableKeyConfig<T>, Indexes extends Record<string, TableKeyConfig<T>> = Record<string, TableKeyConfig<T>>> extends Scope {
+    options: DistributedTableOptions<T, K, Indexes>;
+    readonly bbName = "DistributedTable";
+    private schema;
+    private keyConfig;
+    private indexes;
+    private docClient;
+    /** @internal Logger for internal operations. Defaults to error-level when not provided. */
+    protected log: ChildLogger;
+    constructor(scope: ScopeParent, id: string, options: DistributedTableOptions<T, K, Indexes>);
+    get(key: TableKey<T, K>): Promise<T | null>;
+    put(item: T, options?: PutOptions<T>): Promise<void>;
+    delete(key: TableKey<T, K>, options?: DeleteOptions<T>): Promise<void>;
+    /**
+     * Query items by index, yielding matches as an async stream with automatic
+     * pagination over DynamoDB's `LastEvaluatedKey`.
+     *
+     * @throws {DistributedTableErrors.InvalidQuery} If `options.index` does not exist,
+     *   the `where` clause is missing, the partition key is not given as
+     *   `{ equals: value }`, or more than one sort-key condition is supplied
+     *   (DynamoDB allows only one per query — use `between` for ranges).
+     */
+    query(options: QueryOptions<T, K, Indexes>): AsyncIterable<T>;
+    scan(options?: ScanOptions): AsyncIterable<T>;
+    getBatch(keys: TableKey<T, K>[]): Promise<(T | null)[]>;
+    putBatch(items: T[]): Promise<void>;
+    deleteBatch(keys: TableKey<T, K>[]): Promise<void>;
+    static fromExisting(tableName: string): ExternalTableRef;
+    private validateItem;
+    private buildKey;
+    private backoff;
+    /**
+     * Run a DynamoDB batch operation, resubmitting any unprocessed entries with
+     * exponential backoff. DynamoDB batch APIs can succeed partially (HTTP 200 with
+     * UnprocessedKeys/UnprocessedItems) under throttling or the 16 MB response cap,
+     * so the leftovers must be retried by the caller.
+     *
+     * If entries remain unprocessed after MAX_BATCH_ATTEMPTS, this throws a
+     * BatchIncomplete error rather than returning quietly: for writes/deletes a
+     * silent return would drop data, and for reads it would be indistinguishable
+     * from a missing item. Callers should back off and resubmit.
+     * See: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.Errors.html#Programming.Errors.BatchOperations
+     *
+     * @param operation Human-readable operation name used in the exhaustion error.
+     * @param initial Entries to submit on the first attempt.
+     * @param send Performs one batch call and returns the entries DynamoDB did not process.
+     */
+    private retryUnprocessed;
+    private applyFieldEqualsCondition;
+    private buildQueryCommand;
+}
+//# sourceMappingURL=index.aws.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.aws.d.ts","sourceRoot":"","sources":["../src/index.aws.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,KAAK,EAA6C,MAAM,kBAAkB,CAAC;AACpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EACX,cAAc,EACd,uBAAuB,EACvB,gBAAgB,EAChB,QAAQ,EACR,qBAAqB,EACrB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,aAAa,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EACX,cAAc,EACd,uBAAuB,EACvB,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,aAAa,EAGb,QAAQ,EACR,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAgB,YAAY,EAAE,MAAM,YAAY,CAAC;AAE7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAwBzD,qBAAa,gBAAgB,CAC5B,CAAC,EACD,CAAC,SAAS,cAAc,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,EAC/C,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,CACpF,SAAQ,KAAK;IAUqC,OAAO,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC;IATlG,QAAQ,CAAC,MAAM,sBAAW;IAC1B,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,SAAS,CAAyB;IAE1C,2FAA2F;IAC3F,SAAS,CAAC,GAAG,EAAE,WAAW,CAAC;gBAEf,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAS,OAAO,EAAE,uBAAuB,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC;IAc5F,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAQ3C,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBpD,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5E;;;;;;;;OAQG;IACI,KAAK,CACX,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,GAClC,aAAa,CAAC,CAAC,CAAC;IAsCZ,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,CAAC,CAAC;IAoB9C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;IAsBvD,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBnC,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBxD,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB;YAM1C,YAAY;IAQ1B,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,OAAO;IAWf;;;;;;;;;;;;;;;OAeG;YACW,gBAAgB;IAkB9B,OAAO,CAAC,yBAAyB;IAkBjC,OAAO,CAAC,iBAAiB;CA4CzB"}

package/dist/index.aws.js

@@ -0,0 +1,310 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient, GetCommand, PutCommand, DeleteCommand, QueryCommand, ScanCommand, BatchGetCommand, BatchWriteCommand, } from '@aws-sdk/lib-dynamodb';
+import { Scope, registerSdkIdentifiers, getSdkIdentifiers } from '@aws-blocks/core';
+import { BB_NAME, BB_VERSION } from './version.js';
+export { DistributedTableErrors } from './errors.js';
+import { DistributedTableErrors, DistributedTableMessages, blocksError, normalizeSortKeyCondition, remapItemTooLarge } from './errors.js';
+import { Logger } from '@aws-blocks/bb-logger';
+// ── Helpers ─────────────────────────────────────────────────────────────────
+// DynamoDB batch API limits and retry tuning.
+// BatchGetItem accepts up to 100 keys per call; BatchWriteItem up to 25 requests.
+// Both can return UnprocessedKeys/UnprocessedItems on partial success (e.g. throttling
+// or the 16 MB response cap), which the caller must resubmit with backoff.
+// See: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.Errors.html#Programming.Errors.BatchOperations
+const BATCH_GET_MAX_KEYS = 100;
+const BATCH_WRITE_MAX_REQUESTS = 25;
+const MAX_BATCH_ATTEMPTS = 5;
+const BASE_BACKOFF_MS = 50;
+const MAX_BACKOFF_MS = 5000;
+/** Split an array into chunks of at most `size` elements. */
+function chunked(items, size) {
+    const chunks = [];
+    for (let i = 0; i < items.length; i += size) {
+        chunks.push(items.slice(i, i + size));
+    }
+    return chunks;
+}
+export class DistributedTable extends Scope {
+    options;
+    bbName = BB_NAME;
+    schema;
+    keyConfig;
+    indexes;
+    docClient;
+    /** @internal Logger for internal operations. Defaults to error-level when not provided. */
+    log;
+    constructor(scope, id, options) {
+        super(id, { parent: scope, bbName: BB_NAME, bbVersion: BB_VERSION });
+        this.options = options;
+        this.log = options?.logger ?? new Logger(this, 'logger', { level: 'error' });
+        const tableName = options.table?.tableName ?? this.fullId.substring(0, 255);
+        this.schema = options.schema;
+        this.keyConfig = options.key;
+        this.indexes = (options.indexes ?? {});
+        const client = new DynamoDBClient({
+            customUserAgent: this.buildUserAgentChain(),
+        });
+        this.docClient = DynamoDBDocumentClient.from(client);
+        registerSdkIdentifiers(this.fullId, { tableName });
+    }
+    async get(key) {
+        const result = await this.docClient.send(new GetCommand({
+            TableName: getSdkIdentifiers(this).tableName,
+            Key: this.buildKey(key),
+        }));
+        return result.Item ?? null;
+    }
+    async put(item, options) {
+        await this.validateItem(item);
+        const command = { TableName: getSdkIdentifiers(this).tableName, Item: item };
+        if (options?.ifNotExists) {
+            command.ConditionExpression = 'attribute_not_exists(#pk)';
+            command.ExpressionAttributeNames = { '#pk': this.keyConfig.partitionKey };
+        }
+        else if (options?.ifFieldEquals) {
+            this.applyFieldEqualsCondition(command, options.ifFieldEquals);
+        }
+        try {
+            await this.docClient.send(new PutCommand(command));
+        }
+        catch (err) {
+            throw remapItemTooLarge(err);
+        }
+    }
+    async delete(key, options) {
+        const command = { TableName: getSdkIdentifiers(this).tableName, Key: this.buildKey(key) };
+        if (options?.ifExists) {
+            command.ConditionExpression = 'attribute_exists(#pk)';
+            command.ExpressionAttributeNames = { '#pk': this.keyConfig.partitionKey };
+        }
+        else if (options?.ifFieldEquals) {
+            this.applyFieldEqualsCondition(command, options.ifFieldEquals);
+        }
+        await this.docClient.send(new DeleteCommand(command));
+    }
+    /**
+     * Query items by index, yielding matches as an async stream with automatic
+     * pagination over DynamoDB's `LastEvaluatedKey`.
+     *
+     * @throws {DistributedTableErrors.InvalidQuery} If `options.index` does not exist,
+     *   the `where` clause is missing, the partition key is not given as
+     *   `{ equals: value }`, or more than one sort-key condition is supplied
+     *   (DynamoDB allows only one per query — use `between` for ranges).
+     */
+    async *query(options) {
+        const indexConfig = options.index ? this.indexes[options.index] : this.keyConfig;
+        if (!indexConfig)
+            throw blocksError(DistributedTableErrors.InvalidQuery, DistributedTableMessages.indexNotFound(options.index));
+        const pkField = indexConfig.partitionKey;
+        const skField = indexConfig.sortKey;
+        if (!options.where) {
+            throw blocksError(DistributedTableErrors.InvalidQuery, DistributedTableMessages.whereRequired(pkField));
+        }
+        const pkValue = options.where[pkField]?.equals;
+        if (pkValue === undefined) {
+            throw blocksError(DistributedTableErrors.InvalidQuery, DistributedTableMessages.partitionKeyEqualsRequired(pkField));
+        }
+        // Normalize the sort-key condition before building the query: a present-but-
+        // empty condition ({} / all-undefined) becomes "no filter" (otherwise we'd
+        // register #sk in ExpressionAttributeNames with no clause and DynamoDB would
+        // reject it), and more than one condition is rejected before issuing a call.
+        const skCondition = skField
+            ? normalizeSortKeyCondition(options.where[skField])
+            : undefined;
+        let lastEvaluatedKey;
+        let count = 0;
+        do {
+            const command = this.buildQueryCommand(options.index, pkField, pkValue, skField, skCondition, lastEvaluatedKey, options);
+            const result = await this.docClient.send(command);
+            for (const item of result.Items ?? []) {
+                yield item;
+                if (options.limit && ++count >= options.limit)
+                    return;
+            }
+            lastEvaluatedKey = result.LastEvaluatedKey;
+        } while (lastEvaluatedKey);
+    }
+    async *scan(options) {
+        let lastEvaluatedKey;
+        let count = 0;
+        do {
+            const result = await this.docClient.send(new ScanCommand({
+                TableName: getSdkIdentifiers(this).tableName,
+                ExclusiveStartKey: lastEvaluatedKey,
+                Limit: options?.limit,
+            }));
+            for (const item of result.Items ?? []) {
+                yield item;
+                if (options?.limit && ++count >= options.limit)
+                    return;
+            }
+            lastEvaluatedKey = result.LastEvaluatedKey;
+        } while (lastEvaluatedKey);
+    }
+    async getBatch(keys) {
+        const results = new Map();
+        const tableName = getSdkIdentifiers(this).tableName;
+        for (const chunk of chunked(keys, BATCH_GET_MAX_KEYS)) {
+            await this.retryUnprocessed('getBatch', chunk.map(k => this.buildKey(k)), async (pendingKeys) => {
+                const resp = await this.docClient.send(new BatchGetCommand({
+                    RequestItems: { [tableName]: { Keys: pendingKeys } },
+                }));
+                for (const item of resp.Responses?.[tableName] ?? []) {
+                    results.set(JSON.stringify(this.buildKey(item)), item);
+                }
+                return resp.UnprocessedKeys?.[tableName]?.Keys;
+            });
+        }
+        return keys.map(key => results.get(JSON.stringify(this.buildKey(key))) ?? null);
+    }
+    async putBatch(items) {
+        for (const item of items)
+            await this.validateItem(item);
+        const tableName = getSdkIdentifiers(this).tableName;
+        for (const chunk of chunked(items, BATCH_WRITE_MAX_REQUESTS)) {
+            await this.retryUnprocessed('putBatch', chunk.map(item => ({ PutRequest: { Item: item } })), async (requests) => {
+                try {
+                    const resp = await this.docClient.send(new BatchWriteCommand({
+                        RequestItems: { [tableName]: requests },
+                    }));
+                    return resp.UnprocessedItems?.[tableName];
+                }
+                catch (err) {
+                    throw remapItemTooLarge(err);
+                }
+            });
+        }
+    }
+    async deleteBatch(keys) {
+        const tableName = getSdkIdentifiers(this).tableName;
+        for (const chunk of chunked(keys, BATCH_WRITE_MAX_REQUESTS)) {
+            await this.retryUnprocessed('deleteBatch', chunk.map(key => ({ DeleteRequest: { Key: this.buildKey(key) } })), async (requests) => {
+                const resp = await this.docClient.send(new BatchWriteCommand({
+                    RequestItems: { [tableName]: requests },
+                }));
+                return resp.UnprocessedItems?.[tableName];
+            });
+        }
+    }
+    static fromExisting(tableName) {
+        return { __brand: 'ExternalTableRef', tableName };
+    }
+    // ── Internal ────────────────────────────────────────────────────────────
+    async validateItem(item) {
+        const result = this.schema['~standard'].validate(item);
+        const resolved = result instanceof Promise ? await result : result;
+        if (resolved.issues) {
+            throw blocksError(DistributedTableErrors.ValidationFailed, resolved.issues[0].message);
+        }
+    }
+    buildKey(key) {
+        const result = { [this.keyConfig.partitionKey]: key[this.keyConfig.partitionKey] };
+        if (this.keyConfig.sortKey)
+            result[this.keyConfig.sortKey] = key[this.keyConfig.sortKey];
+        return result;
+    }
+    backoff(attempt) {
+        // Exponential backoff with equal jitter: keep half the delay as a floor and
+        // randomise the other half. Full jitter (random * cap) can collapse to ~0ms
+        // and lets concurrent callers re-collide; equal jitter preserves a minimum
+        // spacing while still de-synchronising retries under shared throttling.
+        // See: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.Errors.html#Programming.Errors.BatchOperations
+        const capped = Math.min(BASE_BACKOFF_MS * Math.pow(2, attempt), MAX_BACKOFF_MS);
+        const ms = capped / 2 + Math.random() * (capped / 2);
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Run a DynamoDB batch operation, resubmitting any unprocessed entries with
+     * exponential backoff. DynamoDB batch APIs can succeed partially (HTTP 200 with
+     * UnprocessedKeys/UnprocessedItems) under throttling or the 16 MB response cap,
+     * so the leftovers must be retried by the caller.
+     *
+     * If entries remain unprocessed after MAX_BATCH_ATTEMPTS, this throws a
+     * BatchIncomplete error rather than returning quietly: for writes/deletes a
+     * silent return would drop data, and for reads it would be indistinguishable
+     * from a missing item. Callers should back off and resubmit.
+     * See: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.Errors.html#Programming.Errors.BatchOperations
+     *
+     * @param operation Human-readable operation name used in the exhaustion error.
+     * @param initial Entries to submit on the first attempt.
+     * @param send Performs one batch call and returns the entries DynamoDB did not process.
+     */
+    async retryUnprocessed(operation, initial, send) {
+        let pending = initial;
+        for (let attempt = 0; attempt < MAX_BATCH_ATTEMPTS && pending && pending.length > 0; attempt++) {
+            if (attempt > 0)
+                await this.backoff(attempt);
+            pending = await send(pending);
+        }
+        if (pending && pending.length > 0) {
+            throw blocksError(DistributedTableErrors.BatchIncomplete, DistributedTableMessages.batchIncomplete(operation, pending.length, MAX_BATCH_ATTEMPTS));
+        }
+    }
+    applyFieldEqualsCondition(command, fields) {
+        const entries = Object.entries(fields).filter(([, v]) => v !== undefined);
+        if (entries.length === 0) {
+            throw blocksError(DistributedTableErrors.InvalidQuery, DistributedTableMessages.emptyIfFieldEquals);
+        }
+        const conditions = [];
+        const names = {};
+        const values = {};
+        entries.forEach(([field, value], i) => {
+            conditions.push(`#field${i} = :val${i}`);
+            names[`#field${i}`] = field;
+            values[`:val${i}`] = value;
+        });
+        command.ConditionExpression = conditions.join(' AND ');
+        command.ExpressionAttributeNames = names;
+        command.ExpressionAttributeValues = values;
+    }
+    buildQueryCommand(indexName, pkField, pkValue, skField, skCondition, exclusiveStartKey, options) {
+        let expr = '#pk = :pkval';
+        const names = { '#pk': pkField };
+        const values = { ':pkval': pkValue };
+        if (skField && skCondition) {
+            names['#sk'] = skField;
+            if ('equals' in skCondition && skCondition.equals !== undefined) {
+                expr += ' AND #sk = :skval';
+                values[':skval'] = skCondition.equals;
+            }
+            else if ('greaterThan' in skCondition && skCondition.greaterThan !== undefined) {
+                expr += ' AND #sk > :skval';
+                values[':skval'] = skCondition.greaterThan;
+            }
+            else if ('greaterThanOrEqual' in skCondition && skCondition.greaterThanOrEqual !== undefined) {
+                expr += ' AND #sk >= :skval';
+                values[':skval'] = skCondition.greaterThanOrEqual;
+            }
+            else if ('lessThan' in skCondition && skCondition.lessThan !== undefined) {
+                expr += ' AND #sk < :skval';
+                values[':skval'] = skCondition.lessThan;
+            }
+            else if ('lessThanOrEqual' in skCondition && skCondition.lessThanOrEqual !== undefined) {
+                expr += ' AND #sk <= :skval';
+                values[':skval'] = skCondition.lessThanOrEqual;
+            }
+            else if ('between' in skCondition && skCondition.between) {
+                expr += ' AND #sk BETWEEN :skval1 AND :skval2';
+                values[':skval1'] = skCondition.between[0];
+                values[':skval2'] = skCondition.between[1];
+            }
+            else if ('beginsWith' in skCondition && skCondition.beginsWith !== undefined) {
+                expr += ' AND begins_with(#sk, :skval)';
+                values[':skval'] = skCondition.beginsWith;
+            }
+        }
+        return new QueryCommand({
+            TableName: getSdkIdentifiers(this).tableName,
+            IndexName: indexName || undefined,
+            KeyConditionExpression: expr,
+            ExpressionAttributeNames: names,
+            ExpressionAttributeValues: values,
+            ExclusiveStartKey: exclusiveStartKey,
+            Limit: options?.limit,
+            ScanIndexForward: options?.order === 'desc' ? false : undefined,
+        });
+    }
+}
+// ── Query input helper type ─────────────────────────────────────────────────

package/dist/index.browser.d.ts

@@ -0,0 +1,5 @@
+export declare class DistributedTable {
+    constructor(...args: any[]);
+}
+export { DistributedTableErrors } from './errors.js';
+//# sourceMappingURL=index.browser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.browser.d.ts","sourceRoot":"","sources":["../src/index.browser.ts"],"names":[],"mappings":"AAIA,qBAAa,gBAAgB;gBAChB,GAAG,IAAI,EAAE,GAAG,EAAE;CAC1B;AACD,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.browser.js

@@ -0,0 +1,7 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+// Browser stub - DistributedTable runs server-side only
+export class DistributedTable {
+    constructor(...args) { }
+}
+export { DistributedTableErrors } from './errors.js';

package/dist/index.cdk.d.ts

@@ -0,0 +1,27 @@
+import { Scope } from '@aws-blocks/core/cdk';
+import type { ScopeParent } from '@aws-blocks/core';
+import type { ExternalTableRef } from './types.js';
+export { DistributedTableErrors } from './errors.js';
+export type { DistributedTableOptions, TableKeyConfig, TableKey, PutOptions, DeleteOptions, QueryOptions, ScanOptions, ExternalTableRef } from './types.js';
+export declare class DistributedTable<T = any> extends Scope {
+    options: any;
+    private table;
+    /**
+     * Reference an existing DynamoDB table instead of provisioning a new one.
+     * Mirrors the same factory exposed by the runtime build so the same code
+     * works in both contexts. The customer is responsible for ensuring the
+     * pre-existing table already has any required GSIs configured — Blocks
+     * will not modify the table when this factory is used.
+     */
+    static fromExisting(tableName: string): ExternalTableRef;
+    constructor(scope: ScopeParent, id: string, options: any);
+    get(..._args: unknown[]): never;
+    put(..._args: unknown[]): never;
+    delete(..._args: unknown[]): never;
+    query(..._args: unknown[]): never;
+    scan(..._args: unknown[]): never;
+    getBatch(..._args: unknown[]): never;
+    putBatch(..._args: unknown[]): never;
+    deleteBatch(..._args: unknown[]): never;
+}
+//# sourceMappingURL=index.cdk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.cdk.d.ts","sourceRoot":"","sources":["../src/index.cdk.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,KAAK,EAAoC,MAAM,sBAAsB,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EAAE,uBAAuB,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE5J,qBAAa,gBAAgB,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,KAAK;IAcA,OAAO,EAAE,GAAG;IAb/D,OAAO,CAAC,KAAK,CAAS;IAEtB;;;;;;OAMG;IACH,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB;gBAI5C,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAS,OAAO,EAAE,GAAG;IAmG/D,GAAG,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IAC/B,GAAG,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IAC/B,MAAM,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IAClC,KAAK,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IACjC,IAAI,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IAChC,QAAQ,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IACpC,QAAQ,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;IACpC,WAAW,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK;CACvC"}

package/dist/index.cdk.js

@@ -0,0 +1,180 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Table, AttributeType, BillingMode } from 'aws-cdk-lib/aws-dynamodb';
+import * as cdk from 'aws-cdk-lib';
+import { CustomResource, Duration } from 'aws-cdk-lib';
+import { Code, Function as LambdaFunction } from 'aws-cdk-lib/aws-lambda';
+import { Provider } from 'aws-cdk-lib/custom-resources';
+import { PolicyStatement } from 'aws-cdk-lib/aws-iam';
+import { Scope, synthGuard, DEFAULT_NODE_RUNTIME } from '@aws-blocks/core/cdk';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+export { DistributedTableErrors } from './errors.js';
+export class DistributedTable extends Scope {
+    options;
+    table;
+    /**
+     * Reference an existing DynamoDB table instead of provisioning a new one.
+     * Mirrors the same factory exposed by the runtime build so the same code
+     * works in both contexts. The customer is responsible for ensuring the
+     * pre-existing table already has any required GSIs configured — Blocks
+     * will not modify the table when this factory is used.
+     */
+    static fromExisting(tableName) {
+        return { __brand: 'ExternalTableRef', tableName };
+    }
+    constructor(scope, id, options) {
+        super(id, { parent: scope });
+        this.options = options;
+        const config = options;
+        if (config?.table) {
+            // `fromExisting`: don't provision; bind to the pre-existing table by name
+            // and grant the runtime Lambda read/write + index query access.
+            // We deliberately skip the GSI custom resource — the customer owns the
+            // table's index lifecycle when they bring their own.
+            this.table = Table.fromTableName(this, 'table', config.table.tableName);
+            this.table.grantReadWriteData(this.handler);
+            this.handler.addToRolePolicy(new PolicyStatement({
+                actions: ['dynamodb:Query'],
+                resources: [`${this.table.tableArn}/index/*`],
+            }));
+            return;
+        }
+        const tableName = this.fullId.substring(0, 255);
+        const isSandbox = this.node.tryGetContext('sandboxMode') === 'true';
+        // Probe the schema's validate() to determine if a key field is numeric.
+        // Sends a test value of 0 for the field — if validation doesn't flag it,
+        // the field accepts numbers. Uses only the StandardSchemaV1 interface.
+        const isNumericField = (fieldName) => {
+            const probe = { [fieldName]: 0 };
+            const result = config.schema['~standard'].validate(probe);
+            // validate may return sync or async; at synth time schemas are sync
+            if (result && 'issues' in result && result.issues) {
+                return !result.issues.some((i) => i.path?.length === 1 && i.path[0] === fieldName);
+            }
+            return true; // no issues for this field → numeric
+        };
+        const getDdbType = (fieldName) => isNumericField(fieldName) ? AttributeType.NUMBER : AttributeType.STRING;
+        this.table = new Table(this, 'table', {
+            tableName,
+            partitionKey: {
+                name: config.key.partitionKey,
+                type: getDdbType(config.key.partitionKey),
+            },
+            sortKey: config.key.sortKey ? {
+                name: config.key.sortKey,
+                type: getDdbType(config.key.sortKey),
+            } : undefined,
+            billingMode: BillingMode.PAY_PER_REQUEST,
+            timeToLiveAttribute: config.ttl || undefined,
+        });
+        this.table.grantReadWriteData(this.handler);
+        // Explicit index query permissions
+        this.handler.addToRolePolicy(new PolicyStatement({
+            actions: ['dynamodb:Query'],
+            resources: [`${this.table.tableArn}/index/*`],
+        }));
+        // Add GSI manager if indexes are defined
+        if (config.indexes && Object.keys(config.indexes).length > 0) {
+            const gsiProvider = getOrCreateGsiProvider(cdk.Stack.of(this));
+            gsiProvider.addTableArn(this.table.tableArn, isSandbox);
+            const indexesWithTypes = {};
+            for (const [indexName, indexConfig] of Object.entries(config.indexes)) {
+                indexesWithTypes[indexName] = {
+                    partitionKey: indexConfig.partitionKey,
+                    sortKey: indexConfig.sortKey,
+                    partitionKeyType: getDdbType(indexConfig.partitionKey) === AttributeType.NUMBER ? 'N' : 'S',
+                    sortKeyType: indexConfig.sortKey
+                        ? (getDdbType(indexConfig.sortKey) === AttributeType.NUMBER ? 'N' : 'S')
+                        : undefined,
+                };
+            }
+            const gsiResource = new CustomResource(this, 'gsi-resource', {
+                serviceToken: gsiProvider.serviceToken,
+                properties: {
+                    TableName: this.table.tableName,
+                    Indexes: indexesWithTypes,
+                    SandboxMode: isSandbox ? 'true' : 'false',
+                    Version: '3',
+                },
+            });
+            gsiResource.node.addDependency(this.table);
+        }
+    }
+    // ── Runtime methods are not available during CDK synth ────────────────
+    // Under `--conditions=cdk` a DistributedTable resolves to this construct,
+    // which only provisions infrastructure. The data methods live in the runtime
+    // build; calling them at module top-level (which runs during synth) would
+    // otherwise fail with a cryptic `X is not a function`. These stubs turn that
+    // into an actionable message.
+    get(..._args) { return synthGuard('DistributedTable', 'get'); }
+    put(..._args) { return synthGuard('DistributedTable', 'put'); }
+    delete(..._args) { return synthGuard('DistributedTable', 'delete'); }
+    query(..._args) { return synthGuard('DistributedTable', 'query'); }
+    scan(..._args) { return synthGuard('DistributedTable', 'scan'); }
+    getBatch(..._args) { return synthGuard('DistributedTable', 'getBatch'); }
+    putBatch(..._args) { return synthGuard('DistributedTable', 'putBatch'); }
+    deleteBatch(..._args) { return synthGuard('DistributedTable', 'deleteBatch'); }
+}
+// ── Shared GSI Manager Provider (one per stack) ─────────────────────────────
+const GSI_PROVIDER_KEY = Symbol.for('BLOCKS_GSI_MANAGER_PROVIDER');
+function getOrCreateGsiProvider(stack) {
+    const existing = stack[GSI_PROVIDER_KEY];
+    if (existing)
+        return existing;
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const tableArns = [];
+    const sandboxTableArns = [];
+    const gsiManagerLambda = new LambdaFunction(stack, 'KitGsiManager', {
+        runtime: DEFAULT_NODE_RUNTIME,
+        handler: 'index.handler',
+        code: Code.fromAsset(join(__dirname, 'gsi-manager-lambda')),
+        timeout: Duration.minutes(15),
+    });
+    const gsiIsCompleteLambda = new LambdaFunction(stack, 'KitGsiIsComplete', {
+        runtime: DEFAULT_NODE_RUNTIME,
+        handler: 'index.isCompleteHandler',
+        code: Code.fromAsset(join(__dirname, 'gsi-manager-lambda')),
+        timeout: Duration.minutes(1),
+    });
+    // Production permissions — lazily resolved so ARNs accumulate as tables register
+    gsiManagerLambda.addToRolePolicy(new PolicyStatement({
+        actions: ['dynamodb:DescribeTable', 'dynamodb:UpdateTable'],
+        resources: cdk.Lazy.list({ produce: () => tableArns }),
+    }));
+    gsiIsCompleteLambda.addToRolePolicy(new PolicyStatement({
+        actions: ['dynamodb:DescribeTable', 'dynamodb:UpdateTable'],
+        resources: cdk.Lazy.list({ produce: () => tableArns }),
+    }));
+    // Sandbox permissions — only added if any table requests sandbox mode
+    let sandboxPolicyAdded = false;
+    const provider = new Provider(stack, 'KitGsiProvider', {
+        onEventHandler: gsiManagerLambda,
+        isCompleteHandler: gsiIsCompleteLambda,
+        queryInterval: Duration.seconds(10),
+        totalTimeout: Duration.hours(2),
+    });
+    const shared = {
+        serviceToken: provider.serviceToken,
+        addTableArn: (tableArn, isSandbox) => {
+            tableArns.push(tableArn);
+            if (isSandbox) {
+                sandboxTableArns.push(tableArn);
+                if (!sandboxPolicyAdded) {
+                    sandboxPolicyAdded = true;
+                    gsiManagerLambda.addToRolePolicy(new PolicyStatement({
+                        actions: [
+                            'dynamodb:DeleteTable',
+                            'dynamodb:CreateTable',
+                            'dynamodb:Scan',
+                            'dynamodb:BatchWriteItem',
+                        ],
+                        resources: cdk.Lazy.list({ produce: () => sandboxTableArns }),
+                    }));
+                }
+            }
+        },
+    };
+    stack[GSI_PROVIDER_KEY] = shared;
+    return shared;
+}

package/dist/index.cdk.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.cdk.test.d.ts.map

package/dist/index.cdk.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cdk.test.d.ts","sourceRoot":"","sources":["../src/index.cdk.test.ts"],"names":[],"mappings":""}