@aws-blocks/bb-distributed-table 0.1.0

package/LICENSE

@@ -0,0 +1,174 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.

package/README.md

@@ -0,0 +1,292 @@
+# DistributedTable
+
+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`.
+
+## API
+
+```typescript
+const table = new DistributedTable(scope, id, options)
+```
+
+> **Type inference (important):** Do **not** pass a single explicit type argument like `new DistributedTable<MyType>(...)`. Doing so pins only `T` and lets the key/index generics fall back to their broad defaults, which breaks key-type inference — `get()` and `query({ where })` will then demand *every* field of the type instead of just the key fields. Either let all generics infer (`new DistributedTable(scope, id, { schema, key, indexes })` with no explicit `<...>`), or pass all three generics. Note that `as const` alone does **not** fix it.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `get(key)` | `Promise<T \| null>` | Retrieve a single item by primary key. |
+| `put(item, options?)` | `Promise<void>` | Store an item. Overwrites unless conditions are set. |
+| `delete(key, options?)` | `Promise<void>` | Remove an item by primary key. |
+| `query(options)` | `AsyncIterable<T>` | Query items by index or primary key. |
+| `scan(options?)` | `AsyncIterable<T>` | Enumerate all items. Expensive on large datasets. |
+| `getBatch(keys)` | `Promise<(T \| null)[]>` | Retrieve multiple items by key. |
+| `putBatch(items)` | `Promise<void>` | Store multiple items. |
+| `deleteBatch(keys)` | `Promise<void>` | Remove multiple items by key. |
+| `DistributedTable.fromExisting(tableName)` | `ExternalTableRef` | Wrap a pre-existing DynamoDB table. |
+
+**Runtime only.** Data methods (`get`, `put`, `delete`, `query`, `scan`, `getBatch`, `putBatch`, `deleteBatch`) run at request time — call them inside an `ApiNamespace` method, `RawRoute` handler, job handler, or a runtime script, **not** at the top level of your `aws-blocks/index.ts`. Top-level code runs during CDK synth, where the block resolves to its infrastructure construct (no data methods), so a top-level call throws `table.<method> is not a function` (throws `TypeError` at runtime if called during CDK synth). To seed data, do it from inside a handler or a separate runtime script. Constructing the block at module scope is fine; only method calls must move into handlers.
+
+> **Collecting `scan()` results:** like `query()`, `scan()` returns an `AsyncIterable` — collect with `await Array.fromAsync(table.scan())` or iterate with `for await`. Prefer `query()` over `scan()` (scans read every item).
+
+### Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `schema` | `StandardSchemaV1` | Yes | Runtime validation schema (Zod, Valibot, ArkType, etc.). Type `T` is inferred from the schema. |
+| `key` | `TableKeyConfig<T>` | Yes | Primary key configuration: `{ partitionKey, sortKey? }`. Field names must exist in the schema. |
+| `indexes` | `Record<string, TableKeyConfig<T>>` | No | Global secondary index definitions. |
+| `ttl` | `keyof T & string` | No | Enable DynamoDB TTL on the specified attribute. The field should contain a Unix epoch timestamp in seconds. |
+| `table` | `ExternalTableRef` | No | Wrap an existing DynamoDB table instead of creating one. |
+| `logger` | `ChildLogger` | No | Optional logger for internal operations. When omitted, a default Logger at error level is created. |
+
+### Key Object Pattern
+
+All methods that accept a key (`get`, `delete`, `getBatch`, `deleteBatch`) take a key object with the partition key field (and sort key field if defined). The key type is computed from your schema and key configuration — TypeScript enforces exactly the right fields:
+
+```typescript
+// Table with partition key + sort key
+const orders = new DistributedTable(scope, 'orders', {
+  schema: orderSchema,
+  key: { partitionKey: 'userId', sortKey: 'orderId' },
+});
+
+// Key object requires both fields
+await orders.get({ userId: 'alice', orderId: '001' });
+
+// Table with partition key only
+const settings = new DistributedTable(scope, 'settings', {
+  schema: settingsSchema,
+  key: { partitionKey: 'settingId' },
+});
+
+// Key object requires only the partition key
+await settings.get({ settingId: 'theme' });
+```
+
+### Query
+
+`query()` takes a single options object. Specify `index` to query a GSI, or omit it to query the primary key. The `where` clause is type-safe — field names and condition types are computed from the index (or primary key) definition.
+
+```typescript
+// Query a GSI
+for await (const order of orders.query({
+  index: 'byStatus',
+  where: { status: { equals: 'pending' } },
+  limit: 10,
+  order: 'desc',
+})) {
+  console.log(order);
+}
+
+// Query the primary key (omit index)
+for await (const order of orders.query({
+  where: { userId: { equals: 'alice' }, orderId: { beginsWith: '2024-' } },
+})) {
+  console.log(order);
+}
+```
+
+> **Tip:** When collecting all results into an array, use `Array.fromAsync()` instead of a manual loop:
+> ```typescript
+> const pending = await Array.fromAsync(orders.query({
+>   index: 'byStatus',
+>   where: { status: { equals: 'pending' } },
+> }));
+> ```
+
+**Query options:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `index` | `keyof Indexes` | No | GSI to query. Omit to query the primary key. |
+| `where` | `KeyCondition<T, K>` | Yes | Key conditions. Partition key requires `{ equals }`. Sort key supports `equals`, `greaterThan`, `lessThan`, `between`, `beginsWith`, etc. |
+| `limit` | `number` | No | Maximum number of items to return. |
+| `order` | `'asc' \| 'desc'` | No | Sort direction on the sort key. Defaults to `'asc'`. |
+
+### Conditional Operations
+
+Both `put` and `delete` accept optional conditions:
+
+```typescript
+// Only write if key doesn't exist (idempotent create)
+await table.put(item, { ifNotExists: true });
+
+// Only write if existing item's field matches (optimistic locking)
+await table.put(updatedItem, { ifFieldEquals: { version: 3 } });
+
+// Only delete if item exists
+await table.delete(key, { ifExists: true });
+
+// Only delete if field matches
+await table.delete(key, { ifFieldEquals: { status: 'archived' } });
+```
+
+All condition failures throw with `error.name === DistributedTableErrors.ConditionalCheckFailed`.
+
+> **No partial update:** There is no `update()` or `patch()` method. To change a field, do a read-modify-write — `get()` the item, mutate it, then `put()` the full item back. For safe concurrent updates, pass `{ ifFieldEquals: { version: <previous> } }` to `put()` so the write fails (via `ConditionalCheckFailed`) if another writer changed the item in the meantime (optimistic locking).
+
+### Error Handling
+
+Errors thrown by DistributedTable carry an `error.name` you can match with `isBlocksError`:
+
+| Constant | `error.name` | Thrown when |
+|----------|--------------|-------------|
+| `DistributedTableErrors.ConditionalCheckFailed` | `ConditionalCheckFailedException` | An `ifNotExists` / `ifExists` / `ifFieldEquals` condition failed. |
+| `DistributedTableErrors.ValidationFailed` | `ValidationFailedException` | An item failed the configured `schema` validation on `put()` / `putBatch()`. |
+| `DistributedTableErrors.InvalidQuery` | `InvalidQueryException` | The query/condition shape is wrong: missing `where`, partition key not given as `{ equals }`, unknown index, multiple sort-key conditions, or an empty `ifFieldEquals`. A caller bug. |
+| `DistributedTableErrors.ItemTooLarge` | `ItemTooLargeException` | A `put`/`putBatch` item exceeds DynamoDB's 400 KB per-item size limit. |
+| `DistributedTableErrors.BatchIncomplete` | `BatchIncompleteException` | A batch op left entries unprocessed after the retry budget (sustained throttling). AWS runtime only. |
+
+```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
+  }
+  if (isBlocksError(e, DistributedTableErrors.ItemTooLarge)) {
+    // item > 400 KB — split it or store a reference instead
+  }
+  throw e;
+}
+```
+
+## Examples
+
+### Basic CRUD
+
+> The examples use Zod, but `schema` accepts any StandardSchemaV1 implementation (Zod, Valibot, ArkType). Install your chosen library, e.g. `npm install zod`.
+
+```typescript
+import { z } from 'zod';
+
+const orderSchema = z.object({
+  userId: z.string(),
+  orderId: z.string(),
+  total: z.number(),
+  status: z.string(),
+  createdAt: z.number(),
+});
+
+const orders = new DistributedTable(scope, 'orders', {
+  schema: orderSchema,
+  key: { partitionKey: 'userId', sortKey: 'orderId' },
+});
+
+export const api = new ApiNamespace(scope, 'api', (context) => ({
+  async getOrder(userId: string, orderId: string) {
+    return await orders.get({ userId, orderId });
+  },
+  async createOrder(order: z.infer<typeof orderSchema>) {
+    await orders.put(order, { ifNotExists: true });
+  },
+  async deleteOrder(userId: string, orderId: string) {
+    await orders.delete({ userId, orderId });
+  },
+}));
+```
+
+### Query with Sort Key Conditions
+
+```typescript
+const orders = new DistributedTable(scope, 'orders', {
+  schema: orderSchema,
+  key: { partitionKey: 'userId', sortKey: 'orderId' },
+  indexes: {
+    byDate: { partitionKey: 'userId', sortKey: 'createdAt' },
+  },
+});
+
+// Ctrl+Space on the where object shows: userId, createdAt
+// userId requires { equals }, createdAt supports greaterThan, between, etc.
+const results = [];
+for await (const order of orders.query({
+  index: 'byDate',
+  where: {
+    userId: { equals: 'alice' },
+    createdAt: { greaterThan: Date.now() - 86400000 },
+  },
+})) {
+  results.push(order);
+}
+```
+
+### TTL (Auto-Expiring Items)
+
+```typescript
+const sessions = new DistributedTable(scope, 'sessions', {
+  schema: sessionSchema,
+  key: { partitionKey: 'sessionId' },
+  ttl: 'expiresAt',
+});
+
+// DynamoDB automatically deletes items after the TTL timestamp
+await sessions.put({
+  sessionId: 'abc123',
+  userId: 'alice',
+  expiresAt: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
+});
+```
+
+### Batch Operations
+
+```typescript
+// Write many items
+await orders.putBatch([order1, order2, order3]);
+
+// Read many items
+const items = await orders.getBatch([
+  { userId: 'alice', orderId: '001' },
+  { userId: 'bob', orderId: '002' },
+]);
+
+// Delete many items
+await orders.deleteBatch([
+  { userId: 'alice', orderId: '001' },
+  { userId: 'bob', orderId: '002' },
+]);
+```
+
+### Wrapping an Existing Table
+
+```typescript
+const legacy = new DistributedTable(scope, 'legacy', {
+  schema: orderSchema,
+  key: { partitionKey: 'userId', sortKey: 'orderId' },
+  table: DistributedTable.fromExisting('my-existing-table'),
+});
+```
+
+## 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 when multiple writers are possible
+- Prefer `query()` over `scan()` — scans read every item and are expensive
+
+## Scaling & Cost (AWS)
+
+- **Billing:** PAY_PER_REQUEST — no provisioned capacity to manage
+- **Latency:** Single-digit ms reads and writes
+- **Throughput:** Scales automatically, no upper limit on table size
+- **Item size limit:** 400 KB per item
+- **GSI limit:** Up to 20 global secondary indexes per table
+- **Cost:** ~$1.25 per million writes, ~$0.25 per million reads
+- **Durability:** 99.999999999% (11 nines) across 3 AZs
+
+## Local Development
+
+Mock data persists to disk at `.bb-data/{fullId}/` across dev server restarts. Wipe with `rm -rf .bb-data`. The mock validates the 400 KB item size limit, schema validation, and conditional check failures, matching AWS behavior. Index queries are implemented via in-memory filtering — correctness is preserved but performance characteristics differ from DynamoDB.
+
+
+
+## See Also
+
+- [DESIGN.md](./DESIGN.md) — Infrastructure details, mock parity gaps, and design decisions

package/dist/errors.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 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 declare const DistributedTableErrors: {
+    readonly ConditionalCheckFailed: "ConditionalCheckFailedException";
+    readonly 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.
+     */
+    readonly 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.
+     */
+    readonly 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.
+     */
+    readonly BatchIncomplete: "BatchIncompleteException";
+};
+/**
+ * @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 declare function blocksError(name: string, message: string): Error;
+/**
+ * @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 declare function normalizeSortKeyCondition<C extends Record<string, unknown>>(condition: C | undefined): C | undefined;
+/**
+ * @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 declare const DistributedTableMessages: {
+    readonly indexNotFound: (index: string | undefined) => string;
+    readonly whereRequired: (pkField: string) => string;
+    readonly partitionKeyEqualsRequired: (pkField: string) => string;
+    readonly multipleSortKeyConditions: (conditionKeys: string[]) => string;
+    readonly emptyIfFieldEquals: "ifFieldEquals must contain at least one field with a non-undefined value";
+    readonly itemTooLarge: (bytes: number) => string;
+    readonly batchIncomplete: (operation: string, remaining: number, attempts: number) => string;
+};
+/**
+ * @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 declare function remapItemTooLarge(err: unknown): unknown;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,sBAAsB;;;IAGlC;;;;;;;;;;;OAWG;;IAEH;;;;;;;;;;;;OAYG;;IAEH;;;;;;;;;OASG;;CAEM,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAIhE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,SAAS,EAAE,CAAC,GAAG,SAAS,GACtB,CAAC,GAAG,SAAS,CAQf;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;oCACb,MAAM,GAAG,SAAS;sCAChB,MAAM;mDAEO,MAAM;wDAED,MAAM,EAAE;;mCAI7B,MAAM;0CAEC,MAAM,aAAa,MAAM,YAAY,MAAM;CAG/D,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAOvD"}