@mastra/dynamodb 0.0.2-alpha.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@mastra/dynamodb",
+  "version": "0.0.2-alpha.0",
+  "description": "DynamoDB storage adapter for Mastra",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@aws-sdk/client-dynamodb": "^3.0.0",
+    "@aws-sdk/lib-dynamodb": "^3.0.0",
+    "electrodb": "^3.4.1"
+  },
+  "peerDependencies": {
+    "@mastra/core": "^0.9.4"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.52.1",
+    "@types/node": "^20.17.27",
+    "@vitest/coverage-v8": "3.0.9",
+    "@vitest/ui": "3.0.9",
+    "axios": "^1.8.4",
+    "eslint": "^9.23.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9",
+    "@mastra/core": "0.10.0-alpha.1",
+    "@internal/lint": "0.0.5"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --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"
+  }
+}

package/src/entities/eval.ts

@@ -0,0 +1,102 @@
+import { Entity } from 'electrodb';
+import { baseAttributes } from './utils';
+
+export const evalEntity = new Entity({
+  model: {
+    entity: 'eval',
+    version: '1',
+    service: 'mastra',
+  },
+  attributes: {
+    entity: {
+      type: 'string',
+      required: true,
+    },
+    ...baseAttributes,
+    input: {
+      type: 'string',
+      required: true,
+    },
+    output: {
+      type: 'string',
+      required: true,
+    },
+    result: {
+      type: 'string', // JSON stringified
+      required: true,
+      // Stringify object on set
+      set: (value?: any) => {
+        if (value && typeof value !== 'string') {
+          return JSON.stringify(value);
+        }
+        return value;
+      },
+      // Parse JSON string to object on get
+      get: (value?: string) => {
+        if (value) {
+          return JSON.parse(value);
+        }
+        return value;
+      },
+    },
+    agent_name: {
+      type: 'string',
+      required: true,
+    },
+    metric_name: {
+      type: 'string',
+      required: true,
+    },
+    instructions: {
+      type: 'string',
+      required: true,
+    },
+    test_info: {
+      type: 'string', // JSON stringified
+      required: false,
+      // Stringify object on set
+      set: (value?: any) => {
+        if (value && typeof value !== 'string') {
+          return JSON.stringify(value);
+        }
+        return value;
+      },
+      // Parse JSON string to object on get
+      get: (value?: string) => {
+        return value;
+      },
+    },
+    global_run_id: {
+      type: 'string',
+      required: true,
+    },
+    run_id: {
+      type: 'string',
+      required: true,
+    },
+    created_at: {
+      type: 'string',
+      required: true,
+      // Initialize with current timestamp if not provided
+      default: () => new Date().toISOString(),
+      // Convert Date to ISO string on set
+      set: (value?: Date | string) => {
+        if (value instanceof Date) {
+          return value.toISOString();
+        }
+        return value || new Date().toISOString();
+      },
+    },
+  },
+  indexes: {
+    primary: {
+      pk: { field: 'pk', composite: ['entity', 'run_id'] },
+      sk: { field: 'sk', composite: [] },
+    },
+    byAgent: {
+      index: 'gsi1',
+      pk: { field: 'gsi1pk', composite: ['entity', 'agent_name'] },
+      sk: { field: 'gsi1sk', composite: ['created_at'] },
+    },
+  },
+});

package/src/entities/index.ts

@@ -0,0 +1,23 @@
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { Service } from 'electrodb';
+import { evalEntity } from './eval';
+import { messageEntity } from './message';
+import { threadEntity } from './thread';
+import { traceEntity } from './trace';
+import { workflowSnapshotEntity } from './workflow-snapshot';
+
+export function getElectroDbService(client: DynamoDBDocumentClient, tableName: string) {
+  return new Service(
+    {
+      thread: threadEntity,
+      message: messageEntity,
+      eval: evalEntity,
+      trace: traceEntity,
+      workflowSnapshot: workflowSnapshotEntity,
+    },
+    {
+      client,
+      table: tableName,
+    },
+  );
+}

package/src/entities/message.ts

@@ -0,0 +1,143 @@
+import { Entity } from 'electrodb';
+import { baseAttributes } from './utils';
+
+export const messageEntity = new Entity({
+  model: {
+    entity: 'message',
+    version: '1',
+    service: 'mastra',
+  },
+  attributes: {
+    entity: {
+      type: 'string',
+      required: true,
+    },
+    ...baseAttributes,
+    id: {
+      type: 'string',
+      required: true,
+    },
+    threadId: {
+      type: 'string',
+      required: true,
+    },
+    content: {
+      type: 'string',
+      required: true,
+      // Stringify content object on set if it's not already a string
+      set: (value?: string | void) => {
+        if (value && typeof value !== 'string') {
+          return JSON.stringify(value);
+        }
+        return value;
+      },
+      // Parse JSON string to object on get ONLY if it looks like JSON
+      get: (value?: string) => {
+        if (value && typeof value === 'string') {
+          try {
+            // Attempt to parse only if it might be JSON (e.g., starts with { or [)
+            if (value.startsWith('{') || value.startsWith('[')) {
+              return JSON.parse(value);
+            }
+          } catch {
+            // Ignore parse error, return original string
+            return value;
+          }
+        }
+        return value;
+      },
+    },
+    role: {
+      type: 'string',
+      required: true,
+    },
+    type: {
+      type: 'string',
+      default: 'text',
+    },
+    resourceId: {
+      type: 'string',
+      required: false,
+    },
+    toolCallIds: {
+      type: 'string',
+      required: false,
+      set: (value?: string[] | string) => {
+        if (Array.isArray(value)) {
+          return JSON.stringify(value);
+        }
+        return value;
+      },
+      // Parse JSON string to array on get
+      get: (value?: string) => {
+        if (value && typeof value === 'string') {
+          try {
+            return JSON.parse(value);
+          } catch {
+            // Return raw value on error, consistent with 'content' field
+            return value;
+          }
+        }
+        // If value was not a string, or if it was an empty string, return it as is.
+        return value;
+      },
+    },
+    toolCallArgs: {
+      type: 'string',
+      required: false,
+      set: (value?: Record<string, unknown>[] | string) => {
+        if (value && typeof value !== 'string') {
+          return JSON.stringify(value);
+        }
+        return value;
+      },
+      // Parse JSON string to object on get
+      get: (value?: string) => {
+        if (value && typeof value === 'string') {
+          try {
+            return JSON.parse(value);
+          } catch {
+            // Return raw value on error, consistent with 'content' field
+            return value;
+          }
+        }
+        // If value was not a string, or if it was an empty string, return it as is.
+        return value;
+      },
+    },
+    toolNames: {
+      type: 'string',
+      required: false,
+      set: (value?: string[] | string) => {
+        if (Array.isArray(value)) {
+          return JSON.stringify(value);
+        }
+        return value;
+      },
+      // Parse JSON string to array on get
+      get: (value?: string) => {
+        if (value && typeof value === 'string') {
+          try {
+            return JSON.parse(value);
+          } catch {
+            // Return raw value on error, consistent with 'content' field
+            return value;
+          }
+        }
+        // If value was not a string, or if it was an empty string, return it as is.
+        return value;
+      },
+    },
+  },
+  indexes: {
+    primary: {
+      pk: { field: 'pk', composite: ['entity', 'id'] },
+      sk: { field: 'sk', composite: ['entity'] },
+    },
+    byThread: {
+      index: 'gsi1',
+      pk: { field: 'gsi1pk', composite: ['entity', 'threadId'] },
+      sk: { field: 'gsi1sk', composite: ['createdAt'] },
+    },
+  },
+});

package/src/entities/thread.ts

@@ -0,0 +1,66 @@
+import { Entity } from 'electrodb';
+import { baseAttributes } from './utils';
+
+export const threadEntity = new Entity({
+  model: {
+    entity: 'thread',
+    version: '1',
+    service: 'mastra',
+  },
+  attributes: {
+    entity: {
+      type: 'string',
+      required: true,
+    },
+    ...baseAttributes,
+    id: {
+      type: 'string',
+      required: true,
+    },
+    resourceId: {
+      type: 'string',
+      required: true,
+    },
+    title: {
+      type: 'string',
+      required: true,
+    },
+    metadata: {
+      type: 'string',
+      required: false,
+      // Stringify metadata object on set if it's not already a string
+      set: (value?: Record<string, unknown> | string) => {
+        if (value && typeof value !== 'string') {
+          return JSON.stringify(value);
+        }
+        return value;
+      },
+      // Parse JSON string to object on get
+      get: (value?: string) => {
+        if (value && typeof value === 'string') {
+          try {
+            // Attempt to parse only if it might be JSON (e.g., starts with { or [)
+            if (value.startsWith('{') || value.startsWith('[')) {
+              return JSON.parse(value);
+            }
+          } catch {
+            // Ignore parse error, return original string
+            return value;
+          }
+        }
+        return value;
+      },
+    },
+  },
+  indexes: {
+    primary: {
+      pk: { field: 'pk', composite: ['entity', 'id'] },
+      sk: { field: 'sk', composite: ['id'] },
+    },
+    byResource: {
+      index: 'gsi1',
+      pk: { field: 'gsi1pk', composite: ['entity', 'resourceId'] },
+      sk: { field: 'gsi1sk', composite: ['createdAt'] },
+    },
+  },
+});

package/src/entities/trace.ts

@@ -0,0 +1,129 @@
+import { Entity } from 'electrodb';
+import { baseAttributes } from './utils';
+
+export const traceEntity = new Entity({
+  model: {
+    entity: 'trace',
+    version: '1',
+    service: 'mastra',
+  },
+  attributes: {
+    entity: {
+      type: 'string',
+      required: true,
+    },
+    ...baseAttributes,
+    id: {
+      type: 'string',
+      required: true,
+    },
+    parentSpanId: {
+      type: 'string',
+      required: false,
+    },
+    name: {
+      type: 'string',
+      required: true,
+    },
+    traceId: {
+      type: 'string',
+      required: true,
+    },
+    scope: {
+      type: 'string',
+      required: true,
+    },
+    kind: {
+      type: 'number',
+      required: true,
+    },
+    attributes: {
+      type: 'string', // JSON stringified
+      required: false,
+      // Stringify object on set
+      set: (value?: any) => {
+        if (value && typeof value !== 'string') {
+          return JSON.stringify(value);
+        }
+        return value;
+      },
+      // Parse JSON string to object on get
+      get: (value?: string) => {
+        return value ? JSON.parse(value) : value;
+      },
+    },
+    status: {
+      type: 'string', // JSON stringified
+      required: false,
+      // Stringify object on set
+      set: (value?: any) => {
+        if (value && typeof value !== 'string') {
+          return JSON.stringify(value);
+        }
+        return value;
+      },
+      // Parse JSON string to object on get
+      get: (value?: string) => {
+        return value;
+      },
+    },
+    events: {
+      type: 'string', // JSON stringified
+      required: false,
+      // Stringify object on set
+      set: (value?: any) => {
+        if (value && typeof value !== 'string') {
+          return JSON.stringify(value);
+        }
+        return value;
+      },
+      // Parse JSON string to object on get
+      get: (value?: string) => {
+        return value;
+      },
+    },
+    links: {
+      type: 'string', // JSON stringified
+      required: false,
+      // Stringify object on set
+      set: (value?: any) => {
+        if (value && typeof value !== 'string') {
+          return JSON.stringify(value);
+        }
+        return value;
+      },
+      // Parse JSON string to object on get
+      get: (value?: string) => {
+        return value;
+      },
+    },
+    other: {
+      type: 'string',
+      required: false,
+    },
+    startTime: {
+      type: 'number',
+      required: true,
+    },
+    endTime: {
+      type: 'number',
+      required: true,
+    },
+  },
+  indexes: {
+    primary: {
+      pk: { field: 'pk', composite: ['entity', 'id'] },
+      sk: { field: 'sk', composite: [] },
+    },
+    byName: {
+      index: 'gsi1',
+      pk: { field: 'gsi1pk', composite: ['entity', 'name'] },
+      sk: { field: 'gsi1sk', composite: ['startTime'] },
+    },
+    byScope: {
+      index: 'gsi2',
+      pk: { field: 'gsi2pk', composite: ['entity', 'scope'] },
+      sk: { field: 'gsi2sk', composite: ['startTime'] },
+    },
+  },
+});

package/src/entities/utils.ts

@@ -0,0 +1,51 @@
+export const baseAttributes = {
+  createdAt: {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    // Convert Date to ISO string on set
+    set: (value?: Date | string) => {
+      if (value instanceof Date) {
+        return value.toISOString();
+      }
+      return value || new Date().toISOString();
+    },
+    // Initialize with current timestamp if not provided
+    default: () => new Date().toISOString(),
+  },
+  updatedAt: {
+    type: 'string',
+    required: true,
+    // Convert Date to ISO string on set
+    set: (value?: Date | string) => {
+      if (value instanceof Date) {
+        return value.toISOString();
+      }
+      return value || new Date().toISOString();
+    },
+    // Always use current timestamp when creating/updating
+    default: () => new Date().toISOString(),
+  },
+  metadata: {
+    type: 'string', // JSON stringified
+    // Stringify objects on set
+    set: (value?: Record<string, unknown> | string) => {
+      if (value && typeof value !== 'string') {
+        return JSON.stringify(value);
+      }
+      return value;
+    },
+    // Parse JSON string to object on get
+    get: (value?: string) => {
+      if (value) {
+        try {
+          return JSON.parse(value);
+        } catch {
+          // If parsing fails, return the original string
+          return value;
+        }
+      }
+      return value;
+    },
+  },
+} as const;

package/src/entities/workflow-snapshot.ts

@@ -0,0 +1,56 @@
+import { Entity } from 'electrodb';
+import { baseAttributes } from './utils';
+
+export const workflowSnapshotEntity = new Entity({
+  model: {
+    entity: 'workflow_snapshot',
+    version: '1',
+    service: 'mastra',
+  },
+  attributes: {
+    entity: {
+      type: 'string',
+      required: true,
+    },
+    ...baseAttributes,
+    workflow_name: {
+      type: 'string',
+      required: true,
+    },
+    run_id: {
+      type: 'string',
+      required: true,
+    },
+    snapshot: {
+      type: 'string', // JSON stringified
+      required: true,
+      // Stringify snapshot object on set
+      set: (value?: any) => {
+        if (value && typeof value !== 'string') {
+          return JSON.stringify(value);
+        }
+        return value;
+      },
+      // Parse JSON string to object on get
+      get: (value?: string) => {
+        return value ? JSON.parse(value) : value;
+      },
+    },
+    resourceId: {
+      type: 'string',
+      required: false,
+    },
+  },
+  indexes: {
+    primary: {
+      pk: { field: 'pk', composite: ['entity', 'workflow_name'] },
+      sk: { field: 'sk', composite: ['run_id'] },
+    },
+    // GSI to allow querying by run_id efficiently without knowing the workflow_name
+    gsi2: {
+      index: 'gsi2',
+      pk: { field: 'gsi2pk', composite: ['entity', 'run_id'] },
+      sk: { field: 'gsi2sk', composite: ['workflow_name'] },
+    },
+  },
+});

package/src/index.ts

@@ -0,0 +1 @@
+export * from './storage';

package/src/storage/docker-compose.yml

@@ -0,0 +1,16 @@
+version: '3.8'
+
+services:
+  dynamodb-local:
+    image: amazon/dynamodb-local:latest
+    # Use host network mode for simpler connection from tests,
+    # or define ports if running in bridge mode.
+    # network_mode: host
+    ports:
+      - '8000:8000' # Map container port 8000 to host port 8000
+    command: ['-jar', 'DynamoDBLocal.jar', '-sharedDb']
+    volumes:
+      - dynamodb_data:/home/dynamodblocal/data
+
+volumes:
+  dynamodb_data: {}