{"_id":"@caleblawson/dynamodb","name":"@caleblawson/dynamodb","dist-tags":{"latest":"0.11.1-alpha.0"},"versions":{"0.11.1-alpha.0":{"name":"@caleblawson/dynamodb","version":"0.11.1-alpha.0","description":"DynamoDB storage adapter for Mastra","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}},"./package.json":"./package.json"},"dependencies":{"@aws-sdk/client-dynamodb":"^3.828.0","@aws-sdk/lib-dynamodb":"^3.828.0","electrodb":"^3.4.3"},"peerDependencies":{"@mastra/core":">=0.10.4-0 <0.11.0"},"devDependencies":{"@microsoft/api-extractor":"^7.52.8","@types/node":"^20.19.0","@vitest/coverage-v8":"3.2.3","@vitest/ui":"3.2.3","axios":"^1.10.0","eslint":"^9.28.0","tsup":"^8.5.0","typescript":"^5.8.3","vitest":"^3.2.3","@internal/lint":"0.0.13","@internal/storage-test-utils":"0.0.9","@mastra/core":"npm:@caleblawson/core@0.10.7-alpha.0"},"scripts":{"build":"tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting","dev":"tsup --watch","clean":"rm -rf dist","lint":"eslint .","pretest":"docker compose up -d","test":"vitest run","posttest":"docker compose down -v","pretest:watch":"docker compose up -d","test:watch":"vitest watch","posttest:watch":"docker compose down -v","typecheck":"tsc --noEmit"},"gitHead":"c31e90130a5c9765c23f688ecea70adc6164543d","_id":"@caleblawson/dynamodb@0.11.1-alpha.0","_integrity":"sha512-ZohOb09UtvHf1x0jYRR3koGHFS2hbeWpPxQyqolvoqFnzYBxASG3p6EbQb1jm+t5ZrE88zvQIOnGjgHOvYYG1Q==","_resolved":"C:\\Users\\caleb\\AppData\\Local\\Temp\\2d9a9df57d2770490462a162abd84ec2\\caleblawson-dynamodb-0.11.1-alpha.0.tgz","_from":"file:caleblawson-dynamodb-0.11.1-alpha.0.tgz","_nodeVersion":"21.2.0","_npmVersion":"10.2.3","dist":{"integrity":"sha512-ZohOb09UtvHf1x0jYRR3koGHFS2hbeWpPxQyqolvoqFnzYBxASG3p6EbQb1jm+t5ZrE88zvQIOnGjgHOvYYG1Q==","shasum":"8d37545314bba6c7a392299590ff8f2a65fe8111","tarball":"https://registry.npmjs.org/@caleblawson/dynamodb/-/dynamodb-0.11.1-alpha.0.tgz","fileCount":20,"unpackedSize":267990,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIB+BA1/PJ3rH7doyb02HaT30M3onl0cxLKERUbdPkoASAiB7RgljQIlVQCDX1xwNDZhF2Ou0UsY7IVNtxKfksLC1mA=="}]},"_npmUser":{"name":"caleblawson","email":"caleb.lawson@dynapt.com","actor":{"name":"caleblawson","email":"caleb.lawson@dynapt.com","type":"user"}},"directories":{},"maintainers":[{"name":"caleblawson","email":"caleb.lawson@dynapt.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dynamodb_0.11.1-alpha.0_1750619806039_0.030479382405116384"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-22T19:16:45.944Z","0.11.1-alpha.0":"2025-06-22T19:16:46.266Z","modified":"2025-06-22T19:16:46.575Z"},"maintainers":[{"name":"caleblawson","email":"caleb.lawson@dynapt.com"}],"description":"DynamoDB storage adapter for Mastra","readme":"# @mastra/dynamodb\r\n\r\nA DynamoDB storage implementation for Mastra using a single-table design pattern with ElectroDB.\r\n\r\n## Features\r\n\r\n- Efficient single-table design for all Mastra storage needs\r\n- Based on ElectroDB for type-safe DynamoDB access\r\n- Support for AWS credentials, regions, and endpoints\r\n- Compatible with AWS DynamoDB Local for development\r\n- Thread, Message, Trace, Eval, and Workflow operations\r\n- Optimized for serverless environments\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @mastra/dynamodb\r\n# or\r\npnpm add @mastra/dynamodb\r\n# or\r\nyarn add @mastra/dynamodb\r\n```\r\n\r\n## Prerequisites\r\n\r\nBefore using this package, you need to create a DynamoDB table with the required structure. See [TABLE_SETUP.md](./TABLE_SETUP.md) for detailed instructions on how to set up the table using CloudFormation or AWS CDK.\r\n\r\n## Usage\r\n\r\n### Basic Usage\r\n\r\n```typescript\r\nimport { Memory } from '@mastra/memory';\r\nimport { DynamoDBStore } from '@mastra/dynamodb';\r\nimport { PineconeVector } from '@mastra/pinecone';\r\n\r\n// Initialize the DynamoDB storage\r\nconst storage = new DynamoDBStore({\r\n  name: 'dynamodb',\r\n  config: {\r\n    region: 'us-east-1',\r\n    tableName: 'mastra-single-table', // Name of your DynamoDB table\r\n  },\r\n});\r\n\r\n// Initialize vector store (if using semantic recall)\r\nconst vector = new PineconeVector({\r\n  apiKey: process.env.PINECONE_API_KEY,\r\n  environment: process.env.PINECONE_ENVIRONMENT,\r\n  index: process.env.PINECONE_INDEX,\r\n});\r\n\r\n// Memory combines storage (like DynamoDBStore) with an optional vector store for recall\r\n// Create memory with DynamoDB storage\r\nconst memory = new Memory({\r\n  storage,\r\n  vector,\r\n  options: {\r\n    lastMessages: 10,\r\n    semanticRecall: true,\r\n  },\r\n});\r\n```\r\n\r\n### Local Development\r\n\r\nFor local development, you can use DynamoDB Local:\r\n\r\n```typescript\r\nconst storage = new DynamoDBStore({\r\n  name: 'dynamodb',\r\n  config: {\r\n    region: 'us-east-1',\r\n    tableName: 'mastra-single-table',\r\n    endpoint: 'http://localhost:8000', // Local DynamoDB endpoint\r\n  },\r\n});\r\n```\r\n\r\n### AWS IAM Permissions\r\n\r\nThe IAM role or user used by this package needs the following permissions:\r\n\r\n```json\r\n{\r\n  \"Version\": \"2012-10-17\",\r\n  \"Statement\": [\r\n    {\r\n      \"Effect\": \"Allow\",\r\n      \"Action\": [\r\n        \"dynamodb:DescribeTable\",\r\n        \"dynamodb:GetItem\",\r\n        \"dynamodb:PutItem\",\r\n        \"dynamodb:UpdateItem\",\r\n        \"dynamodb:DeleteItem\",\r\n        \"dynamodb:Query\",\r\n        \"dynamodb:Scan\",\r\n        \"dynamodb:BatchGetItem\",\r\n        \"dynamodb:BatchWriteItem\"\r\n      ],\r\n      \"Resource\": [\r\n        \"arn:aws:dynamodb:*:*:table/${YOUR_TABLE_NAME}\",\r\n        \"arn:aws:dynamodb:*:*:table/${YOUR_TABLE_NAME}/index/*\"\r\n      ]\r\n    }\r\n  ]\r\n}\r\n```\r\n\r\n## Configuration Options\r\n\r\nThe `DynamoDBStore` constructor accepts the following configuration options:\r\n\r\n| Option               | Type   | Required | Description                                                |\r\n| -------------------- | ------ | -------- | ---------------------------------------------------------- |\r\n| `name`               | string | Yes      | A name for the storage instance                            |\r\n| `config.region`      | string | No       | AWS region (default: 'us-east-1')                          |\r\n| `config.tableName`   | string | Yes      | The name of your DynamoDB table                            |\r\n| `config.endpoint`    | string | No       | Custom endpoint for DynamoDB (e.g., for local development) |\r\n| `config.credentials` | object | No       | AWS credentials (accessKeyId, secretAccessKey)             |\r\n\r\n## Architectural Approach\r\n\r\nThis storage adapter utilizes a **single-table design pattern** leveraging [ElectroDB](https://electrodb.dev/), which is a common and recommended approach for DynamoDB. This differs architecturally from relational database adapters (like `@mastra/pg` or `@mastra/libsql`) that typically use multiple tables, each dedicated to a specific entity (threads, messages, etc.).\r\n\r\nKey aspects of this approach:\r\n\r\n- **DynamoDB Native:** The single-table design is optimized for DynamoDB's key-value and query capabilities, often leading to better performance and scalability compared to mimicking relational models.\r\n- **External Table Management:** Unlike some adapters that might offer helper functions to create tables via code, this adapter **expects the DynamoDB table and its associated Global Secondary Indexes (GSIs) to be provisioned externally** before use. Please refer to `TABLE_SETUP.md` for detailed instructions using tools like AWS CloudFormation or CDK. The adapter focuses solely on interacting with the pre-existing table structure.\r\n- **Consistency via Interface:** While the underlying storage model differs, this adapter adheres to the same `MastraStorage` interface as other adapters, ensuring it can be used interchangeably within the Mastra `Memory` component.\r\n\r\n## Advantage of Single-Table Design\r\n\r\nThis implementation uses a single-table design pattern with ElectroDB, which offers several advantages within the context of DynamoDB:\r\n\r\n1. **Lower cost**: One table means fewer read/write capacity units to provision\r\n2. **Better performance**: Related data is stored together for faster access\r\n3. **Simplified administration**: Only one table to monitor and back up\r\n4. **Reduced complexity**: Consistent access patterns across entities\r\n5. **Transaction support**: Atomic operations across different entity types\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md","_rev":"1-1266ecba9f95d7336d5d4ec9c6c0a830"}