@mastra/astra 0.2.15 → 0.2.16-alpha.0

package/.turbo/turbo-build.log

@@ -1,23 +1,23 @@
 
-> @mastra/astra@0.2.15-alpha.4 build /home/runner/work/mastra/mastra/stores/astra
+> @mastra/astra@0.2.16-alpha.0 build /home/runner/work/mastra/mastra/stores/astra
 > tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting
 
 CLI Building entry: src/index.ts
 CLI Using tsconfig: tsconfig.json
 CLI tsup v8.4.0
 TSC Build start
-TSC ⚡️ Build success in 6867ms
+TSC ⚡️ Build success in 4802ms
 DTS Build start
 CLI Target: es2022
 Analysis will use the bundled TypeScript version 5.8.3
 Writing package typings: /home/runner/work/mastra/mastra/stores/astra/dist/_tsup-dts-rollup.d.ts
 Analysis will use the bundled TypeScript version 5.8.3
 Writing package typings: /home/runner/work/mastra/mastra/stores/astra/dist/_tsup-dts-rollup.d.cts
-DTS ⚡️ Build success in 9832ms
+DTS ⚡️ Build success in 8269ms
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-CJS dist/index.cjs 13.28 KB
-CJS ⚡️ Build success in 663ms
-ESM dist/index.js 13.23 KB
-ESM ⚡️ Build success in 666ms
+CJS dist/index.cjs 13.91 KB
+CJS ⚡️ Build success in 681ms
+ESM dist/index.js 13.85 KB
+ESM ⚡️ Build success in 681ms

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/astra
 
+## 0.2.16-alpha.0
+
+### Patch Changes
+
+- d0ee3c6: Change all public functions and constructors in vector stores to use named args and prepare to phase out positional args
+- Updated dependencies [f53a6ac]
+- Updated dependencies [eabdcd9]
+- Updated dependencies [90be034]
+- Updated dependencies [99f050a]
+- Updated dependencies [d0ee3c6]
+- Updated dependencies [23f258c]
+- Updated dependencies [2672a05]
+  - @mastra/core@0.9.5-alpha.0
+
 ## 0.2.15
 
 ### Patch Changes

package/dist/_tsup-dts-rollup.d.cts

@@ -1,11 +1,15 @@
 import { BaseFilterTranslator } from '@mastra/core/vector/filter';
 import type { CreateIndexParams } from '@mastra/core/vector';
+import type { DeleteIndexParams } from '@mastra/core/vector';
+import type { DeleteVectorParams } from '@mastra/core/vector';
+import type { DescribeIndexParams } from '@mastra/core/vector';
 import type { IndexStats } from '@mastra/core/vector';
 import { MastraVector } from '@mastra/core/vector';
 import type { OperatorSupport } from '@mastra/core/vector/filter';
 import type { ParamsToArgs } from '@mastra/core/vector';
 import type { QueryResult } from '@mastra/core/vector';
 import type { QueryVectorParams } from '@mastra/core/vector';
+import type { UpdateVectorParams } from '@mastra/core/vector';
 import type { UpsertVectorParams } from '@mastra/core/vector';
 import type { VectorFilter } from '@mastra/core/vector/filter';
 
@@ -77,14 +81,21 @@ declare class AstraVector extends MastraVector {
      * @returns {Promise<string[]>} A promise that resolves to an array of collection names.
      */
     listIndexes(): Promise<string[]>;
-    describeIndex(indexName: string): Promise<IndexStats>;
+    /**
+     * Retrieves statistics about a vector index.
+     *
+     * @param params - The parameters for describing an index
+     * @param params.indexName - The name of the index to describe
+     * @returns A promise that resolves to the index statistics including dimension, count and metric
+     */
+    describeIndex(...args: ParamsToArgs<DescribeIndexParams>): Promise<IndexStats>;
     /**
      * Deletes the specified collection.
      *
      * @param {string} indexName - The name of the collection to delete.
      * @returns {Promise<void>} A promise that resolves when the collection is deleted.
      */
-    deleteIndex(indexName: string): Promise<void>;
+    deleteIndex(...args: ParamsToArgs<DeleteIndexParams>): Promise<void>;
     /**
      * @deprecated Use {@link updateVector} instead. This method will be removed on May 20th, 2025.
      *
@@ -111,10 +122,7 @@ declare class AstraVector 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.
      */
-    updateVector(indexName: string, id: string, update: {
-        vector?: number[];
-        metadata?: Record<string, any>;
-    }): Promise<void>;
+    updateVector(...args: ParamsToArgs<UpdateVectorParams>): Promise<void>;
     /**
      * @deprecated Use {@link deleteVector} instead. This method will be removed on May 20th, 2025.
      *
@@ -132,7 +140,7 @@ declare class AstraVector extends MastraVector {
      * @returns A promise that resolves when the deletion is complete.
      * @throws Will throw an error if the deletion operation fails.
      */
-    deleteVector(indexName: string, id: string): Promise<void>;
+    deleteVector(...args: ParamsToArgs<DeleteVectorParams>): Promise<void>;
 }
 export { AstraVector }
 export { AstraVector as AstraVector_alias_1 }

package/dist/_tsup-dts-rollup.d.ts

@@ -1,11 +1,15 @@
 import { BaseFilterTranslator } from '@mastra/core/vector/filter';
 import type { CreateIndexParams } from '@mastra/core/vector';
+import type { DeleteIndexParams } from '@mastra/core/vector';
+import type { DeleteVectorParams } from '@mastra/core/vector';
+import type { DescribeIndexParams } from '@mastra/core/vector';
 import type { IndexStats } from '@mastra/core/vector';
 import { MastraVector } from '@mastra/core/vector';
 import type { OperatorSupport } from '@mastra/core/vector/filter';
 import type { ParamsToArgs } from '@mastra/core/vector';
 import type { QueryResult } from '@mastra/core/vector';
 import type { QueryVectorParams } from '@mastra/core/vector';
+import type { UpdateVectorParams } from '@mastra/core/vector';
 import type { UpsertVectorParams } from '@mastra/core/vector';
 import type { VectorFilter } from '@mastra/core/vector/filter';
 
@@ -77,14 +81,21 @@ declare class AstraVector extends MastraVector {
      * @returns {Promise<string[]>} A promise that resolves to an array of collection names.
      */
     listIndexes(): Promise<string[]>;
-    describeIndex(indexName: string): Promise<IndexStats>;
+    /**
+     * Retrieves statistics about a vector index.
+     *
+     * @param params - The parameters for describing an index
+     * @param params.indexName - The name of the index to describe
+     * @returns A promise that resolves to the index statistics including dimension, count and metric
+     */
+    describeIndex(...args: ParamsToArgs<DescribeIndexParams>): Promise<IndexStats>;
     /**
      * Deletes the specified collection.
      *
      * @param {string} indexName - The name of the collection to delete.
      * @returns {Promise<void>} A promise that resolves when the collection is deleted.
      */
-    deleteIndex(indexName: string): Promise<void>;
+    deleteIndex(...args: ParamsToArgs<DeleteIndexParams>): Promise<void>;
     /**
      * @deprecated Use {@link updateVector} instead. This method will be removed on May 20th, 2025.
      *
@@ -111,10 +122,7 @@ declare class AstraVector 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.
      */
-    updateVector(indexName: string, id: string, update: {
-        vector?: number[];
-        metadata?: Record<string, any>;
-    }): Promise<void>;
+    updateVector(...args: ParamsToArgs<UpdateVectorParams>): Promise<void>;
     /**
      * @deprecated Use {@link deleteVector} instead. This method will be removed on May 20th, 2025.
      *
@@ -132,7 +140,7 @@ declare class AstraVector extends MastraVector {
      * @returns A promise that resolves when the deletion is complete.
      * @throws Will throw an error if the deletion operation fails.
      */
-    deleteVector(indexName: string, id: string): Promise<void>;
+    deleteVector(...args: ParamsToArgs<DeleteVectorParams>): Promise<void>;
 }
 export { AstraVector }
 export { AstraVector as AstraVector_alias_1 }

package/dist/index.cjs

@@ -147,12 +147,20 @@ var AstraVector = class extends vector.MastraVector {
   listIndexes() {
     return this.#db.listCollections({ nameOnly: true });
   }
-  async describeIndex(indexName) {
+  /**
+   * Retrieves statistics about a vector index.
+   *
+   * @param params - The parameters for describing an index
+   * @param params.indexName - The name of the index to describe
+   * @returns A promise that resolves to the index statistics including dimension, count and metric
+   */
+  async describeIndex(...args) {
+    const params = this.normalizeArgs("describeIndex", args);
+    const { indexName } = params;
     const collection = this.#db.collection(indexName);
     const optionsPromise = collection.options();
     const countPromise = collection.countDocuments({}, 100);
     const [options, count] = await Promise.all([optionsPromise, countPromise]);
-    console.log(options, count);
     const keys = Object.keys(metricMap);
     const metric = keys.find((key) => metricMap[key] === options.vector?.metric);
     return {
@@ -167,7 +175,9 @@ var AstraVector = class extends vector.MastraVector {
    * @param {string} indexName - The name of the collection to delete.
    * @returns {Promise<void>} A promise that resolves when the collection is deleted.
    */
-  async deleteIndex(indexName) {
+  async deleteIndex(...args) {
+    const params = this.normalizeArgs("deleteIndex", args);
+    const { indexName } = params;
     const collection = this.#db.collection(indexName);
     await collection.drop();
   }
@@ -187,7 +197,7 @@ var AstraVector = class extends vector.MastraVector {
     this.logger.warn(
       `Deprecation Warning: updateIndexById() is deprecated. Please use updateVector() instead. updateIndexById() will be removed on May 20th, 2025.`
     );
-    await this.updateVector(indexName, id, update);
+    await this.updateVector({ indexName, id, update });
   }
   /**
    * Updates a vector by its ID with the provided vector and/or metadata.
@@ -199,7 +209,9 @@ var AstraVector = class extends vector.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) {
+  async updateVector(...args) {
+    const params = this.normalizeArgs("updateVector", args);
+    const { indexName, id, update } = params;
     try {
       if (!update.vector && !update.metadata) {
         throw new Error("No updates provided");
@@ -232,7 +244,7 @@ var AstraVector = class extends vector.MastraVector {
       Please use deleteVector() instead. 
       deleteIndexById() will be removed on May 20th, 2025.`
     );
-    await this.deleteVector(indexName, id);
+    await this.deleteVector({ indexName, id });
   }
   /**
    * Deletes a vector by its ID.
@@ -241,7 +253,9 @@ var AstraVector = class extends vector.MastraVector {
    * @returns A promise that resolves when the deletion is complete.
    * @throws Will throw an error if the deletion operation fails.
    */
-  async deleteVector(indexName, id) {
+  async deleteVector(...args) {
+    const params = this.normalizeArgs("deleteVector", args);
+    const { indexName, id } = params;
     try {
       const collection = this.#db.collection(indexName);
       await collection.deleteOne({ id });

package/dist/index.js

@@ -145,12 +145,20 @@ var AstraVector = class extends MastraVector {
   listIndexes() {
     return this.#db.listCollections({ nameOnly: true });
   }
-  async describeIndex(indexName) {
+  /**
+   * Retrieves statistics about a vector index.
+   *
+   * @param params - The parameters for describing an index
+   * @param params.indexName - The name of the index to describe
+   * @returns A promise that resolves to the index statistics including dimension, count and metric
+   */
+  async describeIndex(...args) {
+    const params = this.normalizeArgs("describeIndex", args);
+    const { indexName } = params;
     const collection = this.#db.collection(indexName);
     const optionsPromise = collection.options();
     const countPromise = collection.countDocuments({}, 100);
     const [options, count] = await Promise.all([optionsPromise, countPromise]);
-    console.log(options, count);
     const keys = Object.keys(metricMap);
     const metric = keys.find((key) => metricMap[key] === options.vector?.metric);
     return {
@@ -165,7 +173,9 @@ var AstraVector = class extends MastraVector {
    * @param {string} indexName - The name of the collection to delete.
    * @returns {Promise<void>} A promise that resolves when the collection is deleted.
    */
-  async deleteIndex(indexName) {
+  async deleteIndex(...args) {
+    const params = this.normalizeArgs("deleteIndex", args);
+    const { indexName } = params;
     const collection = this.#db.collection(indexName);
     await collection.drop();
   }
@@ -185,7 +195,7 @@ var AstraVector = class extends MastraVector {
     this.logger.warn(
       `Deprecation Warning: updateIndexById() is deprecated. Please use updateVector() instead. updateIndexById() will be removed on May 20th, 2025.`
     );
-    await this.updateVector(indexName, id, update);
+    await this.updateVector({ indexName, id, update });
   }
   /**
    * Updates a vector by its ID with the provided vector and/or metadata.
@@ -197,7 +207,9 @@ var AstraVector = class 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) {
+  async updateVector(...args) {
+    const params = this.normalizeArgs("updateVector", args);
+    const { indexName, id, update } = params;
     try {
       if (!update.vector && !update.metadata) {
         throw new Error("No updates provided");
@@ -230,7 +242,7 @@ var AstraVector = class extends MastraVector {
       Please use deleteVector() instead. 
       deleteIndexById() will be removed on May 20th, 2025.`
     );
-    await this.deleteVector(indexName, id);
+    await this.deleteVector({ indexName, id });
   }
   /**
    * Deletes a vector by its ID.
@@ -239,7 +251,9 @@ var AstraVector = class extends MastraVector {
    * @returns A promise that resolves when the deletion is complete.
    * @throws Will throw an error if the deletion operation fails.
    */
-  async deleteVector(indexName, id) {
+  async deleteVector(...args) {
+    const params = this.normalizeArgs("deleteVector", args);
+    const { indexName, id } = params;
     try {
       const collection = this.#db.collection(indexName);
       await collection.deleteOne({ id });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/astra",
-  "version": "0.2.15",
+  "version": "0.2.16-alpha.0",
   "description": "Astra DB provider for Mastra - includes vector store capabilities",
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
   "license": "MIT",
   "dependencies": {
     "@datastax/astra-db-ts": "^1.5.0",
-    "@mastra/core": "^0.9.4"
+    "@mastra/core": "^0.9.5-alpha.0"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.52.5",

package/src/vector/index.test.ts

@@ -44,7 +44,7 @@ async function createIndexAndWait(
 }
 
 async function deleteIndexAndWait(vectorDB: AstraVector, indexName: string) {
-  await vectorDB.deleteIndex(indexName);
+  await vectorDB.deleteIndex({ indexName });
   const deleted = await waitForCondition(
     async () => {
       const newCollections = await vectorDB.listIndexes();
@@ -80,7 +80,7 @@ describe.skip('AstraVector Integration Tests', () => {
     });
     try {
       const collections = await vectorDB.listIndexes();
-      await Promise.all(collections.map(c => vectorDB.deleteIndex(c)));
+      await Promise.all(collections.map(c => vectorDB.deleteIndex({ indexName: c })));
       const deleted = await waitForCondition(
         async () => {
           const remainingCollections = await vectorDB.listIndexes();
@@ -104,12 +104,12 @@ describe.skip('AstraVector Integration Tests', () => {
   afterAll(async () => {
     // Cleanup: delete test collection
     try {
-      await vectorDB.deleteIndex(testIndexName);
+      await vectorDB.deleteIndex({ indexName: testIndexName });
     } catch (error) {
       console.error('Failed to delete test collection:', error);
     }
     try {
-      await vectorDB.deleteIndex(testIndexName2);
+      await vectorDB.deleteIndex({ indexName: testIndexName2 });
     } catch (error) {
       console.error('Failed to delete test collection:', error);
     }
@@ -121,7 +121,7 @@ describe.skip('AstraVector Integration Tests', () => {
     expect(indexes).toContain(testIndexName);
 
     // 2. Get collection stats
-    const initialStats = await vectorDB.describeIndex(testIndexName);
+    const initialStats = await vectorDB.describeIndex({ indexName: testIndexName });
     expect(initialStats).toEqual({
       dimension: 4,
       metric: 'cosine',
@@ -144,7 +144,7 @@ describe.skip('AstraVector Integration Tests', () => {
     // Wait for document count to update (with timeout)
     const countUpdated = await waitForCondition(
       async () => {
-        const stats = await vectorDB.describeIndex(testIndexName);
+        const stats = await vectorDB.describeIndex({ indexName: testIndexName });
         console.log('Current count:', stats.count);
         return stats.count === 4;
       },
@@ -176,7 +176,7 @@ describe.skip('AstraVector Integration Tests', () => {
     expect(filteredResults?.[0]?.metadata).toEqual({ label: 'vector2' });
 
     // Get final stats
-    const finalStats = await vectorDB.describeIndex(testIndexName);
+    const finalStats = await vectorDB.describeIndex({ indexName: testIndexName });
     console.log('Final stats:', finalStats);
 
     // More lenient assertion for document count
@@ -1224,12 +1224,12 @@ describe.skip('AstraVector Integration Tests', () => {
         metadata: newMetaData,
       };
 
-      await vectorDB.updateVector(indexName, idToBeUpdated, update);
+      await vectorDB.updateVector({ indexName, id: idToBeUpdated, update });
 
       await new Promise(resolve => setTimeout(resolve, 2000));
 
       const results = await vectorDB.query({
-        indexName: indexName,
+        indexName,
         queryVector: newVector,
         topK: 2,
         includeVector: true,
@@ -1256,11 +1256,11 @@ describe.skip('AstraVector Integration Tests', () => {
         metadata: newMetaData,
       };
 
-      await vectorDB.updateVector(indexName, idToBeUpdated, update);
+      await vectorDB.updateVector({ indexName, id: idToBeUpdated, update });
       await new Promise(resolve => setTimeout(resolve, 2000));
 
       const results = await vectorDB.query({
-        indexName: indexName,
+        indexName,
         queryVector: testVectors[0],
         topK: 2,
         includeVector: true,
@@ -1285,11 +1285,11 @@ describe.skip('AstraVector Integration Tests', () => {
         vector: newVector,
       };
 
-      await vectorDB.updateVector(indexName, idToBeUpdated, update);
+      await vectorDB.updateVector({ indexName, id: idToBeUpdated, update });
       await new Promise(resolve => setTimeout(resolve, 2000));
 
       const results = await vectorDB.query({
-        indexName: indexName,
+        indexName,
         queryVector: newVector,
         topK: 2,
         includeVector: true,
@@ -1303,7 +1303,7 @@ describe.skip('AstraVector Integration Tests', () => {
     });
 
     it('should throw exception when no updates are given', async () => {
-      await expect(vectorDB.updateVector(indexName, 'id', {})).rejects.toThrow('No updates provided');
+      await expect(vectorDB.updateVector({ indexName, id: 'id', update: {} })).rejects.toThrow('No updates provided');
     });
 
     it('should delete the vector by id', async () => {
@@ -1311,7 +1311,7 @@ describe.skip('AstraVector Integration Tests', () => {
       expect(ids).toHaveLength(4);
 
       const idToBeDeleted = ids[0];
-      await vectorDB.deleteVector(indexName, idToBeDeleted);
+      await vectorDB.deleteVector({ indexName, id: idToBeDeleted });
 
       const results = await vectorDB.query({
         indexName: indexName,
@@ -1331,7 +1331,7 @@ describe.skip('AstraVector Integration Tests', () => {
     });
 
     afterAll(async () => {
-      await vectorDB.deleteIndex(testIndexName);
+      await vectorDB.deleteIndex({ indexName: testIndexName });
     });
 
     it('should handle non-existent index queries', async () => {
@@ -1376,7 +1376,7 @@ describe.skip('AstraVector Integration Tests', () => {
         );
       } finally {
         // Cleanup
-        await vectorDB.deleteIndex(duplicateIndexName);
+        await vectorDB.deleteIndex({ indexName: duplicateIndexName });
       }
     });
   });

package/src/vector/index.ts

@@ -8,6 +8,10 @@ import type {
   UpsertVectorParams,
   QueryVectorParams,
   ParamsToArgs,
+  DescribeIndexParams,
+  DeleteIndexParams,
+  DeleteVectorParams,
+  UpdateVectorParams,
 } from '@mastra/core/vector';
 import type { VectorFilter } from '@mastra/core/vector/filter';
 
@@ -141,14 +145,23 @@ export class AstraVector extends MastraVector {
     return this.#db.listCollections({ nameOnly: true });
   }
 
-  async describeIndex(indexName: string): Promise<IndexStats> {
+  /**
+   * Retrieves statistics about a vector index.
+   *
+   * @param params - The parameters for describing an index
+   * @param params.indexName - The name of the index to describe
+   * @returns A promise that resolves to the index statistics including dimension, count and metric
+   */
+  async describeIndex(...args: ParamsToArgs<DescribeIndexParams>): Promise<IndexStats> {
+    const params = this.normalizeArgs<DescribeIndexParams>('describeIndex', args);
+
+    const { indexName } = params;
+
     const collection = this.#db.collection(indexName);
     const optionsPromise = collection.options();
     const countPromise = collection.countDocuments({}, 100);
     const [options, count] = await Promise.all([optionsPromise, countPromise]);
 
-    console.log(options, count);
-
     const keys = Object.keys(metricMap) as (keyof typeof metricMap)[];
     const metric = keys.find(key => metricMap[key] === options.vector?.metric);
     return {
@@ -164,7 +177,10 @@ export class AstraVector extends MastraVector {
    * @param {string} indexName - The name of the collection to delete.
    * @returns {Promise<void>} A promise that resolves when the collection is deleted.
    */
-  async deleteIndex(indexName: string): Promise<void> {
+  async deleteIndex(...args: ParamsToArgs<DeleteIndexParams>): Promise<void> {
+    const params = this.normalizeArgs<DeleteIndexParams>('deleteIndex', args);
+
+    const { indexName } = params;
     const collection = this.#db.collection(indexName);
     await collection.drop();
   }
@@ -189,7 +205,7 @@ export class AstraVector extends MastraVector {
     this.logger.warn(
       `Deprecation Warning: updateIndexById() is deprecated. Please use updateVector() instead. updateIndexById() will be removed on May 20th, 2025.`,
     );
-    await this.updateVector(indexName, id, update);
+    await this.updateVector({ indexName, id, update });
   }
 
   /**
@@ -202,11 +218,9 @@ export class AstraVector 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: string,
-    id: string,
-    update: { vector?: number[]; metadata?: Record<string, any> },
-  ): Promise<void> {
+  async updateVector(...args: ParamsToArgs<UpdateVectorParams>): Promise<void> {
+    const params = this.normalizeArgs<UpdateVectorParams>('updateVector', args);
+    const { indexName, id, update } = params;
     try {
       if (!update.vector && !update.metadata) {
         throw new Error('No updates provided');
@@ -244,7 +258,7 @@ export class AstraVector extends MastraVector {
       Please use deleteVector() instead. 
       deleteIndexById() will be removed on May 20th, 2025.`,
     );
-    await this.deleteVector(indexName, id);
+    await this.deleteVector({ indexName, id });
   }
 
   /**
@@ -254,7 +268,10 @@ export class AstraVector extends MastraVector {
    * @returns A promise that resolves when the deletion is complete.
    * @throws Will throw an error if the deletion operation fails.
    */
-  async deleteVector(indexName: string, id: string): Promise<void> {
+  async deleteVector(...args: ParamsToArgs<DeleteVectorParams>): Promise<void> {
+    const params = this.normalizeArgs<DeleteVectorParams>('deleteVector', args);
+
+    const { indexName, id } = params;
     try {
       const collection = this.#db.collection(indexName);
       await collection.deleteOne({ id });