@mastra/mongodb 1.0.0-beta.9 → 1.0.0

package/dist/index.js

@@ -1,6 +1,6 @@
 import { MastraError, ErrorCategory, ErrorDomain } from '@mastra/core/error';
-import { createVectorErrorId, AgentsStorage, TABLE_AGENTS, createStorageErrorId, normalizePerPage, calculatePagination, MemoryStorage, TABLE_THREADS, TABLE_MESSAGES, TABLE_RESOURCES, safelyParseJSON, ObservabilityStorage, TABLE_SPANS, listTracesArgsSchema, ScoresStorage, TABLE_SCORERS, WorkflowsStorage, TABLE_WORKFLOW_SNAPSHOT, MastraStorage, TraceStatus, transformScoreRow as transformScoreRow$1 } from '@mastra/core/storage';
-import { MastraVector } from '@mastra/core/vector';
+import { createVectorErrorId, AgentsStorage, TABLE_AGENTS, createStorageErrorId, normalizePerPage, calculatePagination, MemoryStorage, TABLE_THREADS, TABLE_MESSAGES, TABLE_RESOURCES, safelyParseJSON, ObservabilityStorage, TABLE_SPANS, listTracesArgsSchema, ScoresStorage, TABLE_SCORERS, WorkflowsStorage, TABLE_WORKFLOW_SNAPSHOT, MastraCompositeStore, TraceStatus, transformScoreRow as transformScoreRow$1 } from '@mastra/core/storage';
+import { MastraVector, validateUpsertInput, validateVectorValues } from '@mastra/core/vector';
 import { MongoClient } from 'mongodb';
 import { v4 } from 'uuid';
 import { BaseFilterTranslator } from '@mastra/core/vector/filter';
@@ -11,7 +11,7 @@ import { saveScorePayloadSchema } from '@mastra/core/evals';
 
 // package.json
 var package_default = {
-  version: "1.0.0-beta.9"};
+  version: "1.0.0"};
 var MongoDBFilterTranslator = class extends BaseFilterTranslator {
   getSupportedOperators() {
     return {
@@ -105,7 +105,7 @@ var MongoDBVector = class extends MastraVector {
   client;
   db;
   collections;
-  embeddingFieldName = "embedding";
+  embeddingFieldName;
   metadataFieldName = "metadata";
   documentFieldName = "document";
   collectionForValidation = null;
@@ -114,8 +114,11 @@ var MongoDBVector = class extends MastraVector {
     euclidean: "euclidean",
     dotproduct: "dotProduct"
   };
-  constructor({ id, uri, dbName, options }) {
+  constructor({ id, uri, dbName, options, embeddingFieldPath }) {
     super({ id });
+    if (!uri) {
+      throw new Error('MongoDBVector requires a connection string. Provide "uri" in the constructor options.');
+    }
     const client = new MongoClient(uri, {
       ...options,
       driverInfo: {
@@ -126,6 +129,7 @@ var MongoDBVector = class extends MastraVector {
     this.client = client;
     this.db = this.client.db(dbName);
     this.collections = /* @__PURE__ */ new Map();
+    this.embeddingFieldName = embeddingFieldPath ?? "embedding";
   }
   // Public methods
   async connect() {
@@ -274,6 +278,8 @@ var MongoDBVector = class extends MastraVector {
     throw new Error(`Index "${indexNameInternal}" did not become ready within timeout`);
   }
   async upsert({ indexName, vectors, metadata, ids, documents }) {
+    validateUpsertInput("MONGODB", vectors, metadata, ids);
+    validateVectorValues("MONGODB", vectors);
     try {
       const collection = await this.getCollection(indexName);
       this.collectionForValidation = collection;
@@ -349,8 +355,8 @@ var MongoDBVector = class extends MastraVector {
         index: indexNameInternal,
         queryVector,
         path: this.embeddingFieldName,
-        numCandidates: 100,
-        limit: topK
+        numCandidates: Math.min(1e4, Math.max(100, topK)),
+        limit: Math.min(1e4, topK)
       };
       if (Object.keys(combinedFilter).length > 0) {
         const filterWithExclusion = {
@@ -857,11 +863,21 @@ function resolveMongoDBConfig(config) {
       );
     }
   }
+  const connectionString = config.uri ?? config.url;
+  if (!connectionString) {
+    throw new MastraError({
+      id: createStorageErrorId("MONGODB", "CONSTRUCTOR", "MISSING_URI"),
+      domain: ErrorDomain.STORAGE,
+      category: ErrorCategory.USER,
+      details: { dbName: config?.dbName },
+      text: 'MongoDBStore requires a connection string. Provide "uri" (recommended) or "url" in the constructor options.'
+    });
+  }
   try {
     return MongoDBConnector.fromDatabaseConfig({
       id: "id" in config ? config.id : "domain",
       options: config.options,
-      url: config.url,
+      url: connectionString,
       dbName: config.dbName
     });
   } catch (error) {
@@ -870,7 +886,7 @@ function resolveMongoDBConfig(config) {
         id: createStorageErrorId("MONGODB", "CONSTRUCTOR", "FAILED"),
         domain: ErrorDomain.STORAGE,
         category: ErrorCategory.USER,
-        details: { url: config?.url, dbName: config?.dbName }
+        details: { uri: config?.uri ?? "", url: config?.url ?? "", dbName: config?.dbName ?? "" }
       },
       error
     );
@@ -1335,10 +1351,12 @@ var MemoryStorageMongoDB = class _MemoryStorageMongoDB extends MemoryStorage {
         query.resourceId = resourceId;
       }
       if (filter?.dateRange?.start) {
-        query.createdAt = { ...query.createdAt, $gte: filter.dateRange.start };
+        const startOp = filter.dateRange.startExclusive ? "$gt" : "$gte";
+        query.createdAt = { ...query.createdAt, [startOp]: formatDateForMongoDB(filter.dateRange.start) };
       }
       if (filter?.dateRange?.end) {
-        query.createdAt = { ...query.createdAt, $lte: filter.dateRange.end };
+        const endOp = filter.dateRange.endExclusive ? "$lt" : "$lte";
+        query.createdAt = { ...query.createdAt, [endOp]: formatDateForMongoDB(filter.dateRange.end) };
       }
       const total = await collection.countDocuments(query);
       const messages = [];
@@ -1669,25 +1687,48 @@ var MemoryStorageMongoDB = class _MemoryStorageMongoDB extends MemoryStorage {
       );
     }
   }
-  async listThreadsByResourceId(args) {
+  async listThreads(args) {
+    const { page = 0, perPage: perPageInput, orderBy, filter } = args;
+    try {
+      this.validatePaginationInput(page, perPageInput ?? 100);
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: createStorageErrorId("MONGODB", "LIST_THREADS", "INVALID_PAGE"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.USER,
+          details: { page, ...perPageInput !== void 0 && { perPage: perPageInput } }
+        },
+        error instanceof Error ? error : new Error("Invalid pagination parameters")
+      );
+    }
+    const perPage = normalizePerPage(perPageInput, 100);
+    try {
+      this.validateMetadataKeys(filter?.metadata);
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: createStorageErrorId("MONGODB", "LIST_THREADS", "INVALID_METADATA_KEY"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.USER,
+          details: { metadataKeys: filter?.metadata ? Object.keys(filter.metadata).join(", ") : "" }
+        },
+        error instanceof Error ? error : new Error("Invalid metadata key")
+      );
+    }
     try {
-      const { resourceId, page = 0, perPage: perPageInput, orderBy } = args;
-      if (page < 0) {
-        throw new MastraError(
-          {
-            id: createStorageErrorId("MONGODB", "LIST_THREADS_BY_RESOURCE_ID", "INVALID_PAGE"),
-            domain: ErrorDomain.STORAGE,
-            category: ErrorCategory.USER,
-            details: { page }
-          },
-          new Error("page must be >= 0")
-        );
-      }
-      const perPage = normalizePerPage(perPageInput, 100);
       const { offset, perPage: perPageForResponse } = calculatePagination(page, perPageInput, perPage);
       const { field, direction } = this.parseOrderBy(orderBy);
       const collection = await this.getCollection(TABLE_THREADS);
-      const query = { resourceId };
+      const query = {};
+      if (filter?.resourceId) {
+        query.resourceId = filter.resourceId;
+      }
+      if (filter?.metadata && Object.keys(filter.metadata).length > 0) {
+        for (const [key, value] of Object.entries(filter.metadata)) {
+          query[`metadata.${key}`] = value;
+        }
+      }
       const total = await collection.countDocuments(query);
       if (perPage === 0) {
         return {
@@ -1721,10 +1762,13 @@ var MemoryStorageMongoDB = class _MemoryStorageMongoDB extends MemoryStorage {
     } catch (error) {
       throw new MastraError(
         {
-          id: createStorageErrorId("MONGODB", "LIST_THREADS_BY_RESOURCE_ID", "FAILED"),
+          id: createStorageErrorId("MONGODB", "LIST_THREADS", "FAILED"),
           domain: ErrorDomain.STORAGE,
           category: ErrorCategory.THIRD_PARTY,
-          details: { resourceId: args.resourceId }
+          details: {
+            ...filter?.resourceId && { resourceId: filter.resourceId },
+            hasMetadataFilter: !!filter?.metadata
+          }
         },
         error
       );
@@ -1906,8 +1950,220 @@ var ObservabilityMongoDB = class _ObservabilityMongoDB extends ObservabilityStor
     }
   }
   async init() {
+    const uniqueIndexExists = await this.spansUniqueIndexExists();
+    if (!uniqueIndexExists) {
+      const duplicateInfo = await this.checkForDuplicateSpans();
+      if (duplicateInfo.hasDuplicates) {
+        const errorMessage = `
+===========================================================================
+MIGRATION REQUIRED: Duplicate spans detected in ${TABLE_SPANS} collection
+===========================================================================
+
+Found ${duplicateInfo.duplicateCount} duplicate (traceId, spanId) combinations.
+
+The spans collection requires a unique index on (traceId, spanId), but your
+database contains duplicate entries that must be resolved first.
+
+To fix this, run the manual migration command:
+
+  npx mastra migrate
+
+This command will:
+  1. Remove duplicate spans (keeping the most complete/recent version)
+  2. Add the required unique index
+
+Note: This migration may take some time for large collections.
+===========================================================================
+`;
+        throw new MastraError({
+          id: createStorageErrorId("MONGODB", "MIGRATION_REQUIRED", "DUPLICATE_SPANS"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.USER,
+          text: errorMessage
+        });
+      }
+    }
+    await this.createDefaultIndexes();
+    await this.createCustomIndexes();
+  }
+  /**
+   * Checks if the unique index on (spanId, traceId) already exists on the spans collection.
+   * Used to skip deduplication when the index already exists (migration already complete).
+   */
+  async spansUniqueIndexExists() {
+    try {
+      const collection = await this.getCollection(TABLE_SPANS);
+      const indexes = await collection.indexes();
+      return indexes.some((idx) => idx.unique === true && idx.key?.spanId === 1 && idx.key?.traceId === 1);
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Checks for duplicate (traceId, spanId) combinations in the spans collection.
+   * Returns information about duplicates for logging/CLI purposes.
+   */
+  async checkForDuplicateSpans() {
+    try {
+      const collection = await this.getCollection(TABLE_SPANS);
+      const result = await collection.aggregate([
+        {
+          $group: {
+            _id: { traceId: "$traceId", spanId: "$spanId" },
+            count: { $sum: 1 }
+          }
+        },
+        { $match: { count: { $gt: 1 } } },
+        { $count: "duplicateCount" }
+      ]).toArray();
+      const duplicateCount = result[0]?.duplicateCount ?? 0;
+      return {
+        hasDuplicates: duplicateCount > 0,
+        duplicateCount
+      };
+    } catch (error) {
+      this.logger?.debug?.(`Could not check for duplicates: ${error}`);
+      return { hasDuplicates: false, duplicateCount: 0 };
+    }
+  }
+  /**
+   * Manually run the spans migration to deduplicate and add the unique index.
+   * This is intended to be called from the CLI when duplicates are detected.
+   *
+   * @returns Migration result with status and details
+   */
+  async migrateSpans() {
+    const indexExists = await this.spansUniqueIndexExists();
+    if (indexExists) {
+      return {
+        success: true,
+        alreadyMigrated: true,
+        duplicatesRemoved: 0,
+        message: `Migration already complete. Unique index exists on ${TABLE_SPANS} collection.`
+      };
+    }
+    const duplicateInfo = await this.checkForDuplicateSpans();
+    if (duplicateInfo.hasDuplicates) {
+      this.logger?.info?.(
+        `Found ${duplicateInfo.duplicateCount} duplicate (traceId, spanId) combinations. Starting deduplication...`
+      );
+      await this.deduplicateSpans();
+    } else {
+      this.logger?.info?.(`No duplicate spans found.`);
+    }
     await this.createDefaultIndexes();
     await this.createCustomIndexes();
+    return {
+      success: true,
+      alreadyMigrated: false,
+      duplicatesRemoved: duplicateInfo.duplicateCount,
+      message: duplicateInfo.hasDuplicates ? `Migration complete. Removed duplicates and added unique index to ${TABLE_SPANS} collection.` : `Migration complete. Added unique index to ${TABLE_SPANS} collection.`
+    };
+  }
+  /**
+   * Check migration status for the spans collection.
+   * Returns information about whether migration is needed.
+   */
+  async checkSpansMigrationStatus() {
+    const indexExists = await this.spansUniqueIndexExists();
+    if (indexExists) {
+      return {
+        needsMigration: false,
+        hasDuplicates: false,
+        duplicateCount: 0,
+        constraintExists: true,
+        tableName: TABLE_SPANS
+      };
+    }
+    const duplicateInfo = await this.checkForDuplicateSpans();
+    return {
+      needsMigration: true,
+      hasDuplicates: duplicateInfo.hasDuplicates,
+      duplicateCount: duplicateInfo.duplicateCount,
+      constraintExists: false,
+      tableName: TABLE_SPANS
+    };
+  }
+  /**
+   * Deduplicates spans with the same (traceId, spanId) combination.
+   * This is needed for databases that existed before the unique constraint was added.
+   *
+   * Priority for keeping spans:
+   * 1. Completed spans (endedAt IS NOT NULL) over incomplete spans
+   * 2. Most recent updatedAt
+   * 3. Most recent createdAt (as tiebreaker)
+   *
+   * Note: This prioritizes migration completion over perfect data preservation.
+   * Old trace data may be lost, which is acceptable for this use case.
+   */
+  async deduplicateSpans() {
+    try {
+      const collection = await this.getCollection(TABLE_SPANS);
+      const duplicateCheck = await collection.aggregate([
+        {
+          $group: {
+            _id: { traceId: "$traceId", spanId: "$spanId" },
+            count: { $sum: 1 }
+          }
+        },
+        { $match: { count: { $gt: 1 } } },
+        { $limit: 1 }
+      ]).toArray();
+      if (duplicateCheck.length === 0) {
+        this.logger?.debug?.("No duplicate spans found");
+        return;
+      }
+      this.logger?.info?.("Duplicate spans detected, starting deduplication...");
+      const idsToDelete = await collection.aggregate([
+        // Sort by priority (affects which document $first picks within each group)
+        {
+          $sort: {
+            // Completed spans first (endedAt exists and is not null)
+            endedAt: -1,
+            updatedAt: -1,
+            createdAt: -1
+          }
+        },
+        // Group by (traceId, spanId), keeping the first (best) _id and all _ids
+        {
+          $group: {
+            _id: { traceId: "$traceId", spanId: "$spanId" },
+            keepId: { $first: "$_id" },
+            // The best one to keep (after sort)
+            allIds: { $push: "$_id" },
+            // All ObjectIds (just 12 bytes each, not full docs)
+            count: { $sum: 1 }
+          }
+        },
+        // Only consider groups with duplicates
+        { $match: { count: { $gt: 1 } } },
+        // Get IDs to delete (allIds minus keepId)
+        {
+          $project: {
+            idsToDelete: {
+              $filter: {
+                input: "$allIds",
+                cond: { $ne: ["$$this", "$keepId"] }
+              }
+            }
+          }
+        },
+        // Unwind to get flat list of IDs
+        { $unwind: "$idsToDelete" },
+        // Just output the ID
+        { $project: { _id: "$idsToDelete" } }
+      ]).toArray();
+      if (idsToDelete.length === 0) {
+        this.logger?.debug?.("No duplicates to delete after aggregation");
+        return;
+      }
+      const deleteResult = await collection.deleteMany({
+        _id: { $in: idsToDelete.map((d) => d._id) }
+      });
+      this.logger?.info?.(`Deduplication complete: removed ${deleteResult.deletedCount} duplicate spans`);
+    } catch (error) {
+      this.logger?.warn?.("Failed to deduplicate spans:", error);
+    }
   }
   async dangerouslyClearAll() {
     const collection = await this.getCollection(TABLE_SPANS);
@@ -2189,7 +2445,7 @@ var ObservabilityMongoDB = class _ObservabilityMongoDB extends ObservabilityStor
             // No children with errors
           }
         ];
-        const countResult = await collection.aggregate([...pipeline, { $count: "total" }]).toArray();
+        const countResult = await collection.aggregate([...pipeline, { $count: "total" }], { allowDiskUse: true }).toArray();
         const count2 = countResult[0]?.total || 0;
         if (count2 === 0) {
           return {
@@ -2226,7 +2482,7 @@ var ObservabilityMongoDB = class _ObservabilityMongoDB extends ObservabilityStor
             { $project: { _errorSpans: 0 } }
           ];
         }
-        const spans2 = await collection.aggregate(aggregationPipeline).toArray();
+        const spans2 = await collection.aggregate(aggregationPipeline, { allowDiskUse: true }).toArray();
         return {
           pagination: {
             total: count2,
@@ -2252,18 +2508,21 @@ var ObservabilityMongoDB = class _ObservabilityMongoDB extends ObservabilityStor
       let spans;
       if (sortField === "endedAt") {
         const nullSortValue = sortDirection === -1 ? 0 : 1;
-        spans = await collection.aggregate([
-          { $match: mongoFilter },
-          {
-            $addFields: {
-              _endedAtNull: { $cond: [{ $eq: ["$endedAt", null] }, nullSortValue, sortDirection === -1 ? 1 : 0] }
-            }
-          },
-          { $sort: { _endedAtNull: 1, [sortField]: sortDirection } },
-          { $skip: page * perPage },
-          { $limit: perPage },
-          { $project: { _endedAtNull: 0 } }
-        ]).toArray();
+        spans = await collection.aggregate(
+          [
+            { $match: mongoFilter },
+            {
+              $addFields: {
+                _endedAtNull: { $cond: [{ $eq: ["$endedAt", null] }, nullSortValue, sortDirection === -1 ? 1 : 0] }
+              }
+            },
+            { $sort: { _endedAtNull: 1, [sortField]: sortDirection } },
+            { $skip: page * perPage },
+            { $limit: perPage },
+            { $project: { _endedAtNull: 0 } }
+          ],
+          { allowDiskUse: true }
+        ).toArray();
       } else {
         spans = await collection.find(mongoFilter).sort({ [sortField]: sortDirection }).skip(page * perPage).limit(perPage).toArray();
       }
@@ -2579,7 +2838,7 @@ var ScoresStorageMongoDB = class _ScoresStorageMongoDB extends ScoresStorage {
         };
       }
       const end = perPageInput === false ? total : start + perPage;
-      let cursor = collection.find(query).sort({ createdAt: "desc" }).skip(start);
+      let cursor = collection.find(query).sort({ createdAt: -1 }).skip(start);
       if (perPageInput !== false) {
         cursor = cursor.limit(perPage);
       }
@@ -2628,7 +2887,7 @@ var ScoresStorageMongoDB = class _ScoresStorageMongoDB extends ScoresStorage {
         };
       }
       const end = perPageInput === false ? total : start + perPage;
-      let cursor = collection.find({ runId }).sort({ createdAt: "desc" }).skip(start);
+      let cursor = collection.find({ runId }).sort({ createdAt: -1 }).skip(start);
       if (perPageInput !== false) {
         cursor = cursor.limit(perPage);
       }
@@ -2678,7 +2937,7 @@ var ScoresStorageMongoDB = class _ScoresStorageMongoDB extends ScoresStorage {
         };
       }
       const end = perPageInput === false ? total : start + perPage;
-      let cursor = collection.find({ entityId, entityType }).sort({ createdAt: "desc" }).skip(start);
+      let cursor = collection.find({ entityId, entityType }).sort({ createdAt: -1 }).skip(start);
       if (perPageInput !== false) {
         cursor = cursor.limit(perPage);
       }
@@ -2729,7 +2988,7 @@ var ScoresStorageMongoDB = class _ScoresStorageMongoDB extends ScoresStorage {
         };
       }
       const end = perPageInput === false ? total : start + perPage;
-      let cursor = collection.find(query).sort({ createdAt: "desc" }).skip(start);
+      let cursor = collection.find(query).sort({ createdAt: -1 }).skip(start);
       if (perPageInput !== false) {
         cursor = cursor.limit(perPage);
       }
@@ -3022,7 +3281,7 @@ var WorkflowsStorageMongoDB = class _WorkflowsStorageMongoDB extends WorkflowsSt
       try {
         parsedSnapshot = typeof row.snapshot === "string" ? safelyParseJSON(row.snapshot) : row.snapshot;
       } catch (e) {
-        console.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
+        this.logger.warn(`Failed to parse snapshot for workflow ${row.workflow_name}: ${e}`);
       }
     }
     return {
@@ -3037,7 +3296,7 @@ var WorkflowsStorageMongoDB = class _WorkflowsStorageMongoDB extends WorkflowsSt
 };
 
 // src/storage/index.ts
-var MongoDBStore = class extends MastraStorage {
+var MongoDBStore = class extends MastraCompositeStore {
   #connector;
   stores;
   constructor(config) {