@mastra/libsql 0.0.4 → 0.1.0-alpha.1

package/src/vector/index.ts

@@ -1,5 +1,7 @@
 import { createClient } from '@libsql/client';
 import type { Client as TursoClient, InValue } from '@libsql/client';
+
+import { parseSqlIdentifier } from '@mastra/core/utils';
 import { MastraVector } from '@mastra/core/vector';
 import type {
   IndexStats,
@@ -7,8 +9,10 @@ import type {
   QueryVectorParams,
   CreateIndexParams,
   UpsertVectorParams,
-  ParamsToArgs,
-  QueryVectorArgs,
+  DescribeIndexParams,
+  DeleteIndexParams,
+  DeleteVectorParams,
+  UpdateVectorParams,
 } from '@mastra/core/vector';
 import type { VectorFilter } from '@mastra/core/vector/filter';
 import { LibSQLFilterTranslator } from './filter';
@@ -18,8 +22,6 @@ interface LibSQLQueryParams extends QueryVectorParams {
   minScore?: number;
 }
 
-type LibSQLQueryArgs = [...QueryVectorArgs, number?];
-
 export class LibSQLVector extends MastraVector {
   private turso: TursoClient;
 
@@ -56,17 +58,30 @@ export class LibSQLVector extends MastraVector {
     return translator.translate(filter);
   }
 
-  async query(...args: ParamsToArgs<LibSQLQueryParams> | LibSQLQueryArgs): Promise<QueryResult[]> {
-    const params = this.normalizeArgs<LibSQLQueryParams, LibSQLQueryArgs>('query', args, ['minScore']);
-
+  async query({
+    indexName,
+    queryVector,
+    topK = 10,
+    filter,
+    includeVector = false,
+    minScore = 0,
+  }: LibSQLQueryParams): Promise<QueryResult[]> {
     try {
-      const { indexName, queryVector, topK = 10, filter, includeVector = false, minScore = 0 } = params;
+      if (!Number.isInteger(topK) || topK <= 0) {
+        throw new Error('topK must be a positive integer');
+      }
+      if (!Array.isArray(queryVector) || !queryVector.every(x => typeof x === 'number' && Number.isFinite(x))) {
+        throw new Error('queryVector must be an array of finite numbers');
+      }
+
+      const parsedIndexName = parseSqlIdentifier(indexName, 'index name');
 
       const vectorStr = `[${queryVector.join(',')}]`;
 
       const translatedFilter = this.transformFilter(filter);
       const { sql: filterQuery, values: filterValues } = buildFilterQuery(translatedFilter);
       filterValues.push(minScore);
+      filterValues.push(topK);
 
       const query = `
         WITH vector_scores AS (
@@ -75,14 +90,14 @@ export class LibSQLVector extends MastraVector {
             (1-vector_distance_cos(embedding, '${vectorStr}')) as score,
             metadata
             ${includeVector ? ', vector_extract(embedding) as embedding' : ''}
-          FROM ${indexName}
+          FROM ${parsedIndexName}
           ${filterQuery}
         )
         SELECT *
         FROM vector_scores
         WHERE score > ?
         ORDER BY score DESC
-        LIMIT ${topK}`;
+        LIMIT ?`;
 
       const result = await this.turso.execute({
         sql: query,
@@ -100,18 +115,16 @@ export class LibSQLVector extends MastraVector {
     }
   }
 
-  async upsert(...args: ParamsToArgs<UpsertVectorParams>): Promise<string[]> {
-    const params = this.normalizeArgs<UpsertVectorParams>('upsert', args);
-
-    const { indexName, vectors, metadata, ids } = params;
+  async upsert({ indexName, vectors, metadata, ids }: UpsertVectorParams): Promise<string[]> {
     const tx = await this.turso.transaction('write');
 
     try {
+      const parsedIndexName = parseSqlIdentifier(indexName, 'index name');
       const vectorIds = ids || vectors.map(() => crypto.randomUUID());
 
       for (let i = 0; i < vectors.length; i++) {
         const query = `
-          INSERT INTO ${indexName} (vector_id, embedding, metadata)
+          INSERT INTO ${parsedIndexName} (vector_id, embedding, metadata)
           VALUES (?, vector32(?), ?)
           ON CONFLICT(vector_id) DO UPDATE SET
             embedding = vector32(?),
@@ -156,23 +169,18 @@ export class LibSQLVector extends MastraVector {
     }
   }
 
-  async createIndex(...args: ParamsToArgs<CreateIndexParams>): Promise<void> {
-    const params = this.normalizeArgs<CreateIndexParams>('createIndex', args);
-
-    const { indexName, dimension } = params;
+  async createIndex({ indexName, dimension }: CreateIndexParams): Promise<void> {
     try {
       // Validate inputs
-      if (!indexName.match(/^[a-zA-Z_][a-zA-Z0-9_]*$/)) {
-        throw new Error('Invalid index name format');
-      }
       if (!Number.isInteger(dimension) || dimension <= 0) {
         throw new Error('Dimension must be a positive integer');
       }
+      const parsedIndexName = parseSqlIdentifier(indexName, 'index name');
 
       // Create the table with explicit schema
       await this.turso.execute({
         sql: `
-        CREATE TABLE IF NOT EXISTS ${indexName} (
+        CREATE TABLE IF NOT EXISTS ${parsedIndexName} (
           id SERIAL PRIMARY KEY,
           vector_id TEXT UNIQUE NOT NULL,
           embedding F32_BLOB(${dimension}),
@@ -184,8 +192,8 @@ export class LibSQLVector extends MastraVector {
 
       await this.turso.execute({
         sql: `
-        CREATE INDEX IF NOT EXISTS ${indexName}_vector_idx
-        ON ${indexName} (libsql_vector_idx(embedding))
+        CREATE INDEX IF NOT EXISTS ${parsedIndexName}_vector_idx
+        ON ${parsedIndexName} (libsql_vector_idx(embedding))
       `,
         args: [],
       });
@@ -197,11 +205,12 @@ export class LibSQLVector extends MastraVector {
     }
   }
 
-  async deleteIndex(indexName: string): Promise<void> {
+  async deleteIndex({ indexName }: DeleteIndexParams): Promise<void> {
     try {
+      const parsedIndexName = parseSqlIdentifier(indexName, 'index name');
       // Drop the table
       await this.turso.execute({
-        sql: `DROP TABLE IF EXISTS ${indexName}`,
+        sql: `DROP TABLE IF EXISTS ${parsedIndexName}`,
         args: [],
       });
     } catch (error: any) {
@@ -229,8 +238,15 @@ export class LibSQLVector extends MastraVector {
     }
   }
 
-  async describeIndex(indexName: string): Promise<IndexStats> {
+  /**
+   * Retrieves statistics about a vector index.
+   *
+   * @param {string} indexName - The name of the index to describe
+   * @returns A promise that resolves to the index statistics including dimension, count and metric
+   */
+  async describeIndex({ indexName }: DescribeIndexParams): Promise<IndexStats> {
     try {
+      const parsedIndexName = parseSqlIdentifier(indexName, 'index name');
       // Get table info including column info
       const tableInfoQuery = `
         SELECT sql 
@@ -240,11 +256,11 @@ export class LibSQLVector extends MastraVector {
       `;
       const tableInfo = await this.turso.execute({
         sql: tableInfoQuery,
-        args: [indexName],
+        args: [parsedIndexName],
       });
 
       if (!tableInfo.rows[0]?.sql) {
-        throw new Error(`Table ${indexName} not found`);
+        throw new Error(`Table ${parsedIndexName} not found`);
       }
 
       // Extract dimension from F32_BLOB definition
@@ -253,7 +269,7 @@ export class LibSQLVector extends MastraVector {
       // Get row count
       const countQuery = `
         SELECT COUNT(*) as count
-        FROM ${indexName};
+        FROM ${parsedIndexName};
       `;
       const countResult = await this.turso.execute({
         sql: countQuery,
@@ -273,33 +289,9 @@ export class LibSQLVector extends MastraVector {
     }
   }
 
-  /**
-   * @deprecated Use {@link updateVector} instead. This method will be removed on May 20th, 2025.
-   *
-   * Updates a vector by its ID with the provided vector and/or metadata.
-   * @param indexName - The name of the index 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.
-   * @param update.metadata - An optional record containing the new metadata.
-   * @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 updateIndexById(
-    indexName: string,
-    id: string,
-    update: { vector?: number[]; metadata?: Record<string, any> },
-  ): Promise<void> {
-    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);
-  }
-
   /**
    * Updates a vector by its ID with the provided vector and/or metadata.
+   *
    * @param indexName - The name of the index containing the vector.
    * @param id - The ID of the vector to update.
    * @param update - An object containing the vector and/or metadata to update.
@@ -308,12 +300,9 @@ export class LibSQLVector 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({ indexName, id, update }: UpdateVectorParams): Promise<void> {
     try {
+      const parsedIndexName = parseSqlIdentifier(indexName, 'index name');
       const updates = [];
       const args: InValue[] = [];
 
@@ -334,7 +323,7 @@ export class LibSQLVector extends MastraVector {
       args.push(id);
 
       const query = `
-        UPDATE ${indexName}
+        UPDATE ${parsedIndexName}
         SET ${updates.join(', ')}
         WHERE vector_id = ?;
       `;
@@ -348,24 +337,6 @@ export class LibSQLVector extends MastraVector {
     }
   }
 
-  /**
-   * @deprecated Use {@link deleteVector} instead. This method will be removed on May 20th, 2025.
-   *
-   * Deletes a vector by its ID.
-   * @param indexName - The name of the index 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 deleteIndexById(indexName: string, id: string): Promise<void> {
-    this.logger.warn(
-      `Deprecation Warning: deleteIndexById() is deprecated. 
-      Please use deleteVector() instead. 
-      deleteIndexById() will be removed on May 20th, 2025.`,
-    );
-    await this.deleteVector(indexName, id);
-  }
-
   /**
    * Deletes a vector by its ID.
    * @param indexName - The name of the index containing the vector.
@@ -373,10 +344,11 @@ export class LibSQLVector 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({ indexName, id }: DeleteVectorParams): Promise<void> {
     try {
+      const parsedIndexName = parseSqlIdentifier(indexName, 'index name');
       await this.turso.execute({
-        sql: `DELETE FROM ${indexName} WHERE vector_id = ?`,
+        sql: `DELETE FROM ${parsedIndexName} WHERE vector_id = ?`,
         args: [id],
       });
     } catch (error: any) {
@@ -384,9 +356,9 @@ export class LibSQLVector extends MastraVector {
     }
   }
 
-  async truncateIndex(indexName: string) {
+  async truncateIndex({ indexName }: DeleteIndexParams): Promise<void> {
     await this.turso.execute({
-      sql: `DELETE FROM ${indexName}`,
+      sql: `DELETE FROM ${parseSqlIdentifier(indexName, 'index name')}`,
       args: [],
     });
   }