@mastra/upstash 0.11.0-alpha.0 → 0.11.0-alpha.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/upstash",
-  "version": "0.11.0-alpha.0",
+  "version": "0.11.0-alpha.2",
   "description": "Upstash provider for Mastra - includes both vector and db storage capabilities",
   "type": "module",
   "main": "dist/index.js",
@@ -31,9 +31,9 @@
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.3",
-    "@internal/storage-test-utils": "0.0.8",
     "@internal/lint": "0.0.12",
-    "@mastra/core": "0.10.6-alpha.0"
+    "@mastra/core": "0.10.6-alpha.4",
+    "@internal/storage-test-utils": "0.0.8"
   },
   "peerDependencies": {
     "@mastra/core": ">=0.10.4-0 <0.11.0"

package/src/storage/index.ts

@@ -1,3 +1,4 @@
+import { MessageList } from '@mastra/core/agent';
 import type { MetricResult, TestInfo } from '@mastra/core/eval';
 import type { StorageThreadType, MastraMessageV1, MastraMessageV2 } from '@mastra/core/memory';
 import {
@@ -21,7 +22,6 @@ import type {
 } from '@mastra/core/storage';
 import type { WorkflowRunState } from '@mastra/core/workflows';
 import { Redis } from '@upstash/redis';
-import { MessageList } from '../../../../packages/core/dist/agent/index.cjs';
 
 export interface UpstashConfig {
   url: string;

package/src/vector/index.ts

@@ -18,6 +18,12 @@ import { UpstashFilterTranslator } from './filter';
 export class UpstashVector extends MastraVector {
   private client: Index;
 
+  /**
+   * Creates a new UpstashVector instance.
+   * @param {object} params - The parameters for the UpstashVector.
+   * @param {string} params.url - The URL of the Upstash vector index.
+   * @param {string} params.token - The token for the Upstash vector index.
+   */
   constructor({ url, token }: { url: string; token: string }) {
     super();
     this.client = new Index({
@@ -26,7 +32,12 @@ export class UpstashVector extends MastraVector {
     });
   }
 
-  async upsert({ indexName, vectors, metadata, ids }: UpsertVectorParams): Promise<string[]> {
+  /**
+   * Upserts vectors into the index.
+   * @param {UpsertVectorParams} params - The parameters for the upsert operation.
+   * @returns {Promise<string[]>} A promise that resolves to the IDs of the upserted vectors.
+   */
+  async upsert({ indexName: namespace, vectors, metadata, ids }: UpsertVectorParams): Promise<string[]> {
     const generatedIds = ids || vectors.map(() => crypto.randomUUID());
 
     const points = vectors.map((vector, index) => ({
@@ -36,28 +47,43 @@ export class UpstashVector extends MastraVector {
     }));
 
     await this.client.upsert(points, {
-      namespace: indexName,
+      namespace,
     });
     return generatedIds;
   }
 
+  /**
+   * Transforms a Mastra vector filter into an Upstash-compatible filter string.
+   * @param {VectorFilter} [filter] - The filter to transform.
+   * @returns {string | undefined} The transformed filter string, or undefined if no filter is provided.
+   */
   transformFilter(filter?: VectorFilter) {
     const translator = new UpstashFilterTranslator();
     return translator.translate(filter);
   }
 
+  /**
+   * Creates a new index. For Upstash, this is a no-op as indexes (known as namespaces in Upstash) are created on-the-fly.
+   * @param {CreateIndexParams} _params - The parameters for creating the index (ignored).
+   * @returns {Promise<void>} A promise that resolves when the operation is complete.
+   */
   async createIndex(_params: CreateIndexParams): Promise<void> {
-    console.log('No need to call createIndex for Upstash');
+    this.logger.debug('No need to call createIndex for Upstash');
   }
 
+  /**
+   * Queries the vector index.
+   * @param {QueryVectorParams} params - The parameters for the query operation. indexName is the namespace in Upstash.
+   * @returns {Promise<QueryResult[]>} A promise that resolves to the query results.
+   */
   async query({
-    indexName,
+    indexName: namespace,
     queryVector,
     topK = 10,
     filter,
     includeVector = false,
   }: QueryVectorParams): Promise<QueryResult[]> {
-    const ns = this.client.namespace(indexName);
+    const ns = this.client.namespace(namespace);
 
     const filterString = this.transformFilter(filter);
     const results = await ns.query({
@@ -77,6 +103,10 @@ export class UpstashVector extends MastraVector {
     }));
   }
 
+  /**
+   * Lists all namespaces in the Upstash vector index, which correspond to indexes.
+   * @returns {Promise<string[]>} A promise that resolves to a list of index names.
+   */
   async listIndexes(): Promise<string[]> {
     const indexes = await this.client.listNamespaces();
     return indexes.filter(Boolean);
@@ -85,30 +115,35 @@ export class UpstashVector extends MastraVector {
   /**
    * Retrieves statistics about a vector index.
    *
-   * @param {string} indexName - The name of the index to describe
+   * @param {string} indexName - The name of the namespace to describe
    * @returns A promise that resolves to the index statistics including dimension, count and metric
    */
-  async describeIndex({ indexName }: DescribeIndexParams): Promise<IndexStats> {
+  async describeIndex({ indexName: namespace }: DescribeIndexParams): Promise<IndexStats> {
     const info = await this.client.info();
 
     return {
       dimension: info.dimension,
-      count: info.namespaces?.[indexName]?.vectorCount || 0,
+      count: info.namespaces?.[namespace]?.vectorCount || 0,
       metric: info?.similarityFunction?.toLowerCase() as 'cosine' | 'euclidean' | 'dotproduct',
     };
   }
 
-  async deleteIndex({ indexName }: DeleteIndexParams): Promise<void> {
+  /**
+   * Deletes an index (namespace).
+   * @param {DeleteIndexParams} params - The parameters for the delete operation.
+   * @returns {Promise<void>} A promise that resolves when the deletion is complete.
+   */
+  async deleteIndex({ indexName: namespace }: DeleteIndexParams): Promise<void> {
     try {
-      await this.client.deleteNamespace(indexName);
+      await this.client.deleteNamespace(namespace);
     } catch (error) {
-      console.error('Failed to delete namespace:', error);
+      this.logger.error('Failed to delete namespace:', error);
     }
   }
 
   /**
    * Updates a vector by its ID with the provided vector and/or metadata.
-   * @param indexName - The name of the index containing the vector.
+   * @param indexName - The name of the namespace containing the vector.
    * @param id - The ID of the vector to update.
    * @param update - An object containing the vector and/or metadata to update.
    * @param update.vector - An optional array of numbers representing the new vector.
@@ -116,7 +151,7 @@ export class UpstashVector extends MastraVector {
    * @returns A promise that resolves when the update is complete.
    * @throws Will throw an error if no updates are provided or if the update operation fails.
    */
-  async updateVector({ indexName, id, update }: UpdateVectorParams): Promise<void> {
+  async updateVector({ indexName: namespace, id, update }: UpdateVectorParams): Promise<void> {
     try {
       if (!update.vector && !update.metadata) {
         throw new Error('No update data provided');
@@ -143,27 +178,27 @@ export class UpstashVector extends MastraVector {
       };
 
       await this.client.upsert(points, {
-        namespace: indexName,
+        namespace,
       });
     } catch (error: any) {
-      throw new Error(`Failed to update vector by id: ${id} for index name: ${indexName}: ${error.message}`);
+      throw new Error(`Failed to update vector by id: ${id} for index name: ${namespace}: ${error.message}`);
     }
   }
 
   /**
    * Deletes a vector by its ID.
-   * @param indexName - The name of the index containing the vector.
+   * @param indexName - The name of the namespace containing the vector.
    * @param id - The ID of the vector to delete.
    * @returns A promise that resolves when the deletion is complete.
    * @throws Will throw an error if the deletion operation fails.
    */
-  async deleteVector({ indexName, id }: DeleteVectorParams): Promise<void> {
+  async deleteVector({ indexName: namespace, id }: DeleteVectorParams): Promise<void> {
     try {
       await this.client.delete(id, {
-        namespace: indexName,
+        namespace,
       });
     } catch (error) {
-      console.error(`Failed to delete vector by id: ${id} for index name: ${indexName}:`, error);
+      this.logger.error(`Failed to delete vector by id: ${id} for namespace: ${namespace}:`, error);
     }
   }
 }