@emulates/dynamodb 2.3.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog — @emulates/dynamodb
+
+## 2.3.1 (2026-10-06)
+
+Initial release.
+
+### Dependencies
+
+- `@emulates/sqlite`

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @emulates/dynamodb discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@emulates/dynamodb/`; no repository checkout is needed to discover the emulator's
+supported surface or documented behavior.
+
+## Capability and behavior sources
+
+| Question | Authoritative file | What it contains |
+| --- | --- | --- |
+| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
+| Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
+| Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
+| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
+| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `emulates.discovery`. |
+
+Read these together: the contract/capability matrix says *what* is available, while the README
+defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
+If prose and an executable surface disagree, report a parity mismatch instead of adding a
+consumer-side workaround.
+
+## Parity and oracle
+
+- Declared parity surface: **Items, indexes, and transactions**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- dynamodb`.
+- Evidence model: Run from an Emulates checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
+
+The npm package contains evidence summaries and the exact contract, not credentials or the
+repository-only parity harness. Self-parity/property and acceptance tests run in the Emulates
+repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
+
+## Runtime introspection
+
+- `GET /__admin/health`
+- `GET /__admin`
+- `GET /__admin/state`
+- `GET /__admin/requests`
+- `GET /__admin/metrics`
+- `GET /__admin/faults/presets`
+- `GET /__admin/ui`
+
+For HTTP services, use `x-emulates-namespace` (or the documented credential/path carrier) so
+parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
+designed for assertions and diagnosis by consuming test suites.
+
+## Report a mismatch or missing capability
+
+Follow the [agent reporting contract](https://github.com/crvouga/emulators/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual emulator result, expected oracle result or vendor
+documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
+customer data, prompts, PHI, card data, or unredacted recordings.
+
+Service key: `dynamodb`.

package/README.md

@@ -0,0 +1,58 @@
+# @emulates/dynamodb
+
+> Part of [Emulates](https://github.com/crvouga/emulators): high-fidelity, in-process emulators for APIs and databases.
+
+Stateful Amazon DynamoDB emulator for the AWS SDK v3 low-level client and `DynamoDBDocumentClient`. It preserves DynamoDB attribute types while modelling CRUD, expressions, indexes, pagination, batches, transactions, TTL, streams, and conditional writes without contacting AWS.
+
+## Install
+
+```bash
+npm install -D @emulates/dynamodb
+```
+
+ESM only. Node 22+ or Bun 1.2+.
+
+## Usage
+
+Point the SDK's `endpoint` option at the emulator. Fixture SigV4 credentials are accepted.
+
+```ts
+import { createServer } from "@emulates/dynamodb/server"
+
+const mock = await createServer({
+  tables: [
+    {
+      name: "records",
+      keySchema: [{ AttributeName: "pk", KeyType: "HASH" }],
+      items: [{ pk: { S: "fixture" }, status: { S: "ready" } }],
+    },
+  ],
+})
+const health = await fetch(`${mock.url}/__admin/health`)
+```
+
+Supported operations are CreateTable, DescribeTable, GetItem, PutItem, UpdateItem, DeleteItem, Query, Scan, BatchGetItem, BatchWriteItem, TransactGetItems, and TransactWriteItems. The expression subset includes expression name/value aliases, SET/ADD/REMOVE/DELETE, `if_not_exists`, `attribute_exists`, `attribute_not_exists`, `begins_with`, comparisons, BETWEEN, AND/OR, projection, conditions, limits, cursors, index ordering, and return values.
+
+### Admin and deterministic controls
+
+- Constructor fixtures define tables, indexes, typed items, and TTL attributes.
+- `GET /__admin/tables`, `/__admin/items?table=…`, and `/__admin/streams?table=…` inspect local state and ordered INSERT/MODIFY/REMOVE records.
+- Advance the shared emulator clock to expire TTL items without sleeps.
+- Fault presets are `throttled` and one-shot `unavailable`; generic fault rules can model unprocessed batch responses or eventual-read failures.
+
+The shared runtime also provides reset, timeline, request journal, metrics, faults, and namespace isolation through `x-emulates-namespace`, `/__admin/ns/<name>`, or SigV4 access-key mappings.
+
+### Deliberately not modelled
+
+PartiQL, control-plane operations outside Create/Describe, local/global table replication, IAM policy evaluation, encryption, backups, production capacity accounting, all DynamoDB expression grammar, real asynchronous streams, dashboards, and billing are not modelled.
+
+## API
+
+- `DynamoAPI`, `DynamoAPIOptions`, `DynamoSeedTable`: AWS JSON handler and fixtures.
+- `AttributeValue`, `Item`, `KeySchemaElement`, `DynamoIndex`, `DynamoItem`, `DynamoTable`, `StreamRecord`: typed state.
+- `createRuntime`, `DynamoRuntime`, `DynamoRuntimeOptions`: full Emulates runtime.
+- `DYNAMODB_NAMESPACE`, `DYNAMODB_PRESETS`, `accessKeyCredential`: constants and controls.
+- `document`, `operationIds`, `supportedOperationIds`: generated OpenAPI metadata.
+- `createServer`, `DynamoServerOptions`, `DEFAULT_PORT`, `serveTarget` from `./server`: Node HTTP adapter and CLI integration.
+
+Official oracle: [Amazon DynamoDB API Reference](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/Welcome.html).

package/SUPPORT.md

@@ -0,0 +1,11 @@
+# Amazon DynamoDB (Emulates subset) — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **1**
+- supported by the emulator: **1**
+- parity enabled: **1**
+
+| operationId | route | emulator | parity | notes |
+| --- | --- | --- | --- | --- |
+| `DynamoDbRpc` | `POST /` | ✅ supported | ⚠️ unsafe (opt-in) |  |