@aws-blocks/bb-distributed-table 0.1.0

package/dist/index.cdk.test.js

@@ -0,0 +1,93 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CDK-side regression tests for DistributedTable.
+ *
+ * History: DistributedTable.fromExisting was advertised in the runtime build
+ * but the CDK constructor unconditionally provisioned a new DynamoDB table
+ * AND the static factory was missing entirely from the CDK class. These
+ * tests pin the fix and ensure GSI custom resources are NOT created when
+ * binding to an external table.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert';
+import * as cdk from 'aws-cdk-lib';
+import { Template } from 'aws-cdk-lib/assertions';
+import { Scope, DEFAULT_NODE_RUNTIME } from '@aws-blocks/core/cdk';
+import { z } from 'zod';
+import { DistributedTable } from './index.cdk.js';
+const userSchema = z.object({
+    userId: z.string(),
+    email: z.string(),
+    createdAt: z.number(),
+});
+class StubBlocksStack extends cdk.Stack {
+    handler;
+    id;
+    constructor(scope, id) {
+        super(scope, id);
+        this.id = id;
+        globalThis.CURRENT_BLOCKS_STACK = this;
+        this.handler = new cdk.aws_lambda.Function(this, 'StubHandler', {
+            runtime: DEFAULT_NODE_RUNTIME,
+            handler: 'index.handler',
+            code: cdk.aws_lambda.Code.fromInline('exports.handler = async () => {};'),
+        });
+    }
+}
+function setup() {
+    const app = new cdk.App();
+    const stack = new StubBlocksStack(app, 'TestStack');
+    const parent = new Scope('app');
+    return { stack, parent };
+}
+test('CDK: default DistributedTable provisions a DynamoDB table', () => {
+    const { stack, parent } = setup();
+    new DistributedTable(parent, 'users', {
+        schema: userSchema,
+        key: { partitionKey: 'userId', sortKey: 'createdAt' },
+    });
+    const template = Template.fromStack(stack);
+    template.resourceCountIs('AWS::DynamoDB::Table', 1);
+});
+test('CDK: DistributedTable.fromExisting does NOT provision a table (regression)', () => {
+    const { stack, parent } = setup();
+    new DistributedTable(parent, 'users', {
+        schema: userSchema,
+        key: { partitionKey: 'userId', sortKey: 'createdAt' },
+        table: DistributedTable.fromExisting('preexisting-users-table'),
+    });
+    const template = Template.fromStack(stack);
+    template.resourceCountIs('AWS::DynamoDB::Table', 0);
+});
+test('CDK: DistributedTable.fromExisting with indexes does NOT provision the GSI custom resource', () => {
+    const { stack, parent } = setup();
+    new DistributedTable(parent, 'users', {
+        schema: userSchema,
+        key: { partitionKey: 'userId', sortKey: 'createdAt' },
+        indexes: {
+            byEmail: { partitionKey: 'email' },
+        },
+        table: DistributedTable.fromExisting('preexisting-users-table'),
+    });
+    const template = Template.fromStack(stack);
+    // The GSI manager is realized as a Provider (Lambda + custom resource).
+    // `fromExisting` must opt out of touching indexes — the customer owns
+    // the existing table's index lifecycle.
+    template.resourceCountIs('AWS::CloudFormation::CustomResource', 0);
+});
+test('CDK: DistributedTable.fromExisting returns a branded ref', () => {
+    const ref = DistributedTable.fromExisting('foo');
+    assert.strictEqual(ref.tableName, 'foo');
+    assert.strictEqual(ref.__brand, 'ExternalTableRef');
+});
+test('CDK: calling a runtime data method throws an actionable error (not a cryptic TypeError)', () => {
+    const { parent } = setup();
+    const table = new DistributedTable(parent, 'users', {
+        schema: userSchema,
+        key: { partitionKey: 'userId', sortKey: 'createdAt' },
+    });
+    for (const method of ['get', 'put', 'delete', 'query', 'scan', 'getBatch', 'putBatch', 'deleteBatch']) {
+        assert.throws(() => table[method]('k'), /cannot be called during CDK synth/, `${method}() should throw the actionable synth-time error`);
+    }
+});

package/dist/index.mock.d.ts

@@ -0,0 +1,101 @@
+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';
+/**
+ * Structured data storage backed by DynamoDB with secondary indexes and
+ * rich query capabilities.
+ *
+ * **When to use:** You need to query by multiple fields, use composite keys,
+ * or perform sort-key-based range queries. Good for entities with relationships,
+ * time-series data, and access patterns that require multiple indexes.
+ *
+ * **When NOT to use:** If you only need single-key lookups, use `KVStore`.
+ * If you need full SQL (joins, aggregations), use `Database`.
+ *
+ * **Best practices:**
+ * - Design partition keys for even data distribution (e.g., `userId`, `tenantId`)
+ * - Use sort keys for range queries (e.g., timestamps, alphabetical ordering)
+ * - Define GSIs upfront for known access patterns — adding them later requires backfill
+ * - Use `{ ifNotExists: true }` for idempotent creates
+ * - Use `{ ifFieldEquals }` for optimistic locking (compare-and-swap)
+ *
+ * **Scaling:** PAY_PER_REQUEST billing. Single-digit ms reads/writes.
+ * Throughput scales automatically. Items limited to 400 KB.
+ * GSIs have separate throughput and may throttle independently.
+ */
+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>;
+    private filePath;
+    private data;
+    private schema;
+    private keyConfig;
+    private indexes;
+    /** @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. The input object's fields are determined by the index:
+     * - Partition key field: required, `{ equals: value }`
+     * - Sort key field (if defined): optional, supports `equals`, `greaterThan`,
+     *   `lessThan`, `between`, `beginsWith` (strings only), etc.
+     *
+     * @example
+     * ```typescript
+     * // Primary key query
+     * 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: 'byStatus',
+     *   where: { status: { equals: 'pending' } },
+     *   limit: 10,
+     *   order: 'desc',
+     * })) { ... }
+     * ```
+     *
+     * @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>;
+    /**
+     * Fetch multiple items by key in batches. Returns results positionally —
+     * `null` for keys with no matching item.
+     *
+     * @throws {DistributedTableErrors.BatchIncomplete} (AWS runtime only) If DynamoDB
+     *   leaves keys unprocessed after the retry budget is exhausted, typically under
+     *   sustained throttling. The local mock never throttles, so it does not throw this.
+     */
+    getBatch(keys: TableKey<T, K>[]): Promise<(T | null)[]>;
+    /**
+     * Write multiple items in batches. Each item is schema-validated first.
+     *
+     * @throws {DistributedTableErrors.BatchIncomplete} (AWS runtime only) If DynamoDB
+     *   leaves writes unprocessed after the retry budget is exhausted, typically under
+     *   sustained throttling. The local mock never throttles, so it does not throw this.
+     */
+    putBatch(items: T[]): Promise<void>;
+    /**
+     * Delete multiple items by key in batches.
+     *
+     * @throws {DistributedTableErrors.BatchIncomplete} (AWS runtime only) If DynamoDB
+     *   leaves deletes unprocessed after the retry budget is exhausted, typically under
+     *   sustained throttling. The local mock never throttles, so it does not throw this.
+     */
+    deleteBatch(keys: TableKey<T, K>[]): Promise<void>;
+    static fromExisting(tableName: string): ExternalTableRef;
+    private checkFieldEquals;
+    private serializeKey;
+    private loadFromDisk;
+    private flushToDisk;
+}
+import type { QueryOptions } from './types.js';
+import type { ChildLogger } from '@aws-blocks/bb-logger';
+//# sourceMappingURL=index.mock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.mock.d.ts","sourceRoot":"","sources":["../src/index.mock.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAA0B,MAAM,kBAAkB,CAAC;AAEjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAMpD,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,EAEhB,WAAW,EACX,UAAU,EACV,aAAa,EACb,QAAQ,EACR,MAAM,YAAY,CAAC;AA4DpB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,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,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,IAAI,CAAiB;IAC7B,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,OAAO,CAAU;IAEzB,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;IAW5F,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAI3C,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBpD,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAc5E;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,KAAK,CACX,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,GAClC,aAAa,CAAC,CAAC,CAAC;IAoDZ,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,CAAC,CAAC;IAQpD;;;;;;;OAOG;IACG,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;IAI7D;;;;;;OAMG;IACG,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAczC;;;;;;OAMG;IACG,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxD,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB;IAMxD,OAAO,CAAC,gBAAgB;IAiBxB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,WAAW;CAGnB;AAOD,OAAO,KAAK,EAAgE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE7G,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.mock.js

@@ -0,0 +1,301 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { Scope, registerSdkIdentifiers } from '@aws-blocks/core';
+import { getMockDataDir } from '@aws-blocks/core/bb-utils';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { BB_NAME, BB_VERSION } from './version.js';
+export { DistributedTableErrors } from './errors.js';
+import { DistributedTableErrors, DistributedTableMessages, blocksError, normalizeSortKeyCondition } from './errors.js';
+// ── Helpers ─────────────────────────────────────────────────────────────────
+const MAX_ITEM_BYTES = 400 * 1024;
+async function validateSchema(schema, value) {
+    const result = schema['~standard'].validate(value);
+    const resolved = result instanceof Promise ? await result : result;
+    if (resolved.issues) {
+        throw blocksError(DistributedTableErrors.ValidationFailed, resolved.issues[0].message);
+    }
+}
+function matchesSortKeyCondition(value, condition) {
+    if ('equals' in condition && condition.equals !== undefined && value !== condition.equals)
+        return false;
+    if ('greaterThan' in condition && condition.greaterThan !== undefined && !(value > condition.greaterThan))
+        return false;
+    if ('greaterThanOrEqual' in condition && condition.greaterThanOrEqual !== undefined && !(value >= condition.greaterThanOrEqual))
+        return false;
+    if ('lessThan' in condition && condition.lessThan !== undefined && !(value < condition.lessThan))
+        return false;
+    if ('lessThanOrEqual' in condition && condition.lessThanOrEqual !== undefined && !(value <= condition.lessThanOrEqual))
+        return false;
+    if ('between' in condition && condition.between && !(value >= condition.between[0] && value <= condition.between[1]))
+        return false;
+    if ('beginsWith' in condition && condition.beginsWith !== undefined) {
+        if (typeof value !== 'string' || !value.startsWith(condition.beginsWith))
+            return false;
+    }
+    return true;
+}
+/**
+ * Order-independent structural equality, used to compare `ifFieldEquals` values
+ * against stored attributes. DynamoDB Maps are an unordered collection of
+ * name-value pairs, so `{ a, b }` and `{ b, a }` are the same value — a plain
+ * `JSON.stringify` compare would wrongly treat them as different and fail the
+ * condition. Arrays remain order-sensitive (DynamoDB Lists are ordered).
+ */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null)
+        return a === b;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (typeof a === 'object' && typeof b === 'object') {
+        const aKeys = Object.keys(a);
+        const bKeys = Object.keys(b);
+        if (aKeys.length !== bKeys.length)
+            return false;
+        return aKeys.every(k => Object.prototype.hasOwnProperty.call(b, k) &&
+            deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+// ── DistributedTable (mock) ─────────────────────────────────────────────────
+/**
+ * Structured data storage backed by DynamoDB with secondary indexes and
+ * rich query capabilities.
+ *
+ * **When to use:** You need to query by multiple fields, use composite keys,
+ * or perform sort-key-based range queries. Good for entities with relationships,
+ * time-series data, and access patterns that require multiple indexes.
+ *
+ * **When NOT to use:** If you only need single-key lookups, use `KVStore`.
+ * If you need full SQL (joins, aggregations), use `Database`.
+ *
+ * **Best practices:**
+ * - Design partition keys for even data distribution (e.g., `userId`, `tenantId`)
+ * - Use sort keys for range queries (e.g., timestamps, alphabetical ordering)
+ * - Define GSIs upfront for known access patterns — adding them later requires backfill
+ * - Use `{ ifNotExists: true }` for idempotent creates
+ * - Use `{ ifFieldEquals }` for optimistic locking (compare-and-swap)
+ *
+ * **Scaling:** PAY_PER_REQUEST billing. Single-digit ms reads/writes.
+ * Throughput scales automatically. Items limited to 400 KB.
+ * GSIs have separate throughput and may throttle independently.
+ */
+export class DistributedTable extends Scope {
+    options;
+    filePath;
+    data;
+    schema;
+    keyConfig;
+    indexes;
+    /** @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' });
+        this.filePath = join(getMockDataDir(this), 'data.json');
+        this.data = this.loadFromDisk();
+        this.schema = options.schema;
+        this.keyConfig = options.key;
+        this.indexes = (options.indexes ?? {});
+        registerSdkIdentifiers(this.fullId, { tableName: `mock-${this.fullId}`.substring(0, 255) });
+    }
+    async get(key) {
+        return this.data.get(this.serializeKey(key)) ?? null;
+    }
+    async put(item, options) {
+        await validateSchema(this.schema, item);
+        const serialized = JSON.stringify(item);
+        if (Buffer.byteLength(serialized, 'utf8') > MAX_ITEM_BYTES) {
+            throw blocksError(DistributedTableErrors.ItemTooLarge, DistributedTableMessages.itemTooLarge(Buffer.byteLength(serialized, 'utf8')));
+        }
+        const keyStr = this.serializeKey(item);
+        if (options?.ifNotExists && this.data.has(keyStr)) {
+            throw blocksError(DistributedTableErrors.ConditionalCheckFailed, 'The conditional request failed');
+        }
+        if (options?.ifFieldEquals) {
+            this.checkFieldEquals(keyStr, options.ifFieldEquals);
+        }
+        this.data.set(keyStr, item);
+        this.flushToDisk();
+    }
+    async delete(key, options) {
+        const keyStr = this.serializeKey(key);
+        if (options?.ifExists && !this.data.has(keyStr)) {
+            throw blocksError(DistributedTableErrors.ConditionalCheckFailed, 'The conditional request failed');
+        }
+        if (options?.ifFieldEquals) {
+            this.checkFieldEquals(keyStr, options.ifFieldEquals);
+        }
+        this.data.delete(keyStr);
+        this.flushToDisk();
+    }
+    /**
+     * Query items by index. The input object's fields are determined by the index:
+     * - Partition key field: required, `{ equals: value }`
+     * - Sort key field (if defined): optional, supports `equals`, `greaterThan`,
+     *   `lessThan`, `between`, `beginsWith` (strings only), etc.
+     *
+     * @example
+     * ```typescript
+     * // Primary key query
+     * 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: 'byStatus',
+     *   where: { status: { equals: 'pending' } },
+     *   limit: 10,
+     *   order: 'desc',
+     * })) { ... }
+     * ```
+     *
+     * @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 up front — before scanning data — so the
+        // mock behaves identically to the AWS runtime regardless of stored data:
+        // a present-but-empty condition ({} / all-undefined) becomes "no filter"
+        // (query the whole partition) and multiple conditions are rejected eagerly,
+        // even on an empty table or a partition with no matches (where the per-item
+        // filter would never run).
+        const skCondition = skField
+            ? normalizeSortKeyCondition(options.where[skField])
+            : undefined;
+        const items = [];
+        for (const item of this.data.values()) {
+            if (item[pkField] !== pkValue)
+                continue;
+            if (skField && skCondition) {
+                if (!matchesSortKeyCondition(item[skField], skCondition))
+                    continue;
+            }
+            items.push(item);
+        }
+        if (skField) {
+            const dir = options.order === 'desc' ? -1 : 1;
+            items.sort((a, b) => {
+                const av = a[skField], bv = b[skField];
+                return (av < bv ? -1 : av > bv ? 1 : 0) * dir;
+            });
+        }
+        let count = 0;
+        for (const item of items) {
+            yield item;
+            if (options.limit && ++count >= options.limit)
+                return;
+        }
+    }
+    async *scan(options) {
+        let count = 0;
+        for (const item of this.data.values()) {
+            yield item;
+            if (options?.limit && ++count >= options.limit)
+                return;
+        }
+    }
+    /**
+     * Fetch multiple items by key in batches. Returns results positionally —
+     * `null` for keys with no matching item.
+     *
+     * @throws {DistributedTableErrors.BatchIncomplete} (AWS runtime only) If DynamoDB
+     *   leaves keys unprocessed after the retry budget is exhausted, typically under
+     *   sustained throttling. The local mock never throttles, so it does not throw this.
+     */
+    async getBatch(keys) {
+        return keys.map(key => this.data.get(this.serializeKey(key)) ?? null);
+    }
+    /**
+     * Write multiple items in batches. Each item is schema-validated first.
+     *
+     * @throws {DistributedTableErrors.BatchIncomplete} (AWS runtime only) If DynamoDB
+     *   leaves writes unprocessed after the retry budget is exhausted, typically under
+     *   sustained throttling. The local mock never throttles, so it does not throw this.
+     */
+    async putBatch(items) {
+        for (const item of items) {
+            await validateSchema(this.schema, item);
+            const serialized = JSON.stringify(item);
+            if (Buffer.byteLength(serialized, 'utf8') > MAX_ITEM_BYTES) {
+                throw blocksError(DistributedTableErrors.ItemTooLarge, DistributedTableMessages.itemTooLarge(Buffer.byteLength(serialized, 'utf8')));
+            }
+        }
+        for (const item of items) {
+            this.data.set(this.serializeKey(item), item);
+        }
+        this.flushToDisk();
+    }
+    /**
+     * Delete multiple items by key in batches.
+     *
+     * @throws {DistributedTableErrors.BatchIncomplete} (AWS runtime only) If DynamoDB
+     *   leaves deletes unprocessed after the retry budget is exhausted, typically under
+     *   sustained throttling. The local mock never throttles, so it does not throw this.
+     */
+    async deleteBatch(keys) {
+        for (const key of keys)
+            this.data.delete(this.serializeKey(key));
+        this.flushToDisk();
+    }
+    static fromExisting(tableName) {
+        return { __brand: 'ExternalTableRef', tableName };
+    }
+    // ── Internal ────────────────────────────────────────────────────────────
+    checkFieldEquals(keyStr, fields) {
+        const entries = Object.entries(fields).filter(([, v]) => v !== undefined);
+        if (entries.length === 0) {
+            throw blocksError(DistributedTableErrors.InvalidQuery, DistributedTableMessages.emptyIfFieldEquals);
+        }
+        const existing = this.data.get(keyStr);
+        if (!existing) {
+            throw blocksError(DistributedTableErrors.ConditionalCheckFailed, 'The conditional request failed');
+        }
+        for (const [field, value] of entries) {
+            if (!deepEqual(existing[field], value)) {
+                throw blocksError(DistributedTableErrors.ConditionalCheckFailed, 'The conditional request failed');
+            }
+        }
+    }
+    serializeKey(key) {
+        const parts = [key[this.keyConfig.partitionKey]];
+        if (this.keyConfig.sortKey)
+            parts.push(key[this.keyConfig.sortKey]);
+        return JSON.stringify(parts);
+    }
+    loadFromDisk() {
+        if (!existsSync(this.filePath))
+            return new Map();
+        try {
+            return new Map(JSON.parse(readFileSync(this.filePath, 'utf8')));
+        }
+        catch {
+            return new Map();
+        }
+    }
+    flushToDisk() {
+        writeFileSync(this.filePath, JSON.stringify([...this.data.entries()], null, 2));
+    }
+}
+import { Logger } from '@aws-blocks/bb-logger';

package/dist/index.test.d.ts

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

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

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