@mastra/libsql 0.0.4 → 0.0.5-alpha.0

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,
@@ -9,6 +11,10 @@ import type {
   UpsertVectorParams,
   ParamsToArgs,
   QueryVectorArgs,
+  DescribeIndexParams,
+  DeleteIndexParams,
+  DeleteVectorParams,
+  UpdateVectorParams,
 } from '@mastra/core/vector';
 import type { VectorFilter } from '@mastra/core/vector/filter';
 import { LibSQLFilterTranslator } from './filter';
@@ -62,11 +68,21 @@ export class LibSQLVector extends MastraVector {
     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 +91,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,
@@ -107,11 +123,12 @@ export class LibSQLVector extends MastraVector {
     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(?),
@@ -162,17 +179,15 @@ export class LibSQLVector extends MastraVector {
     const { indexName, dimension } = params;
     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 +199,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 +212,15 @@ export class LibSQLVector extends MastraVector {
     }
   }
 
-  async deleteIndex(indexName: string): Promise<void> {
+  async deleteIndex(...args: ParamsToArgs<DeleteIndexParams>): Promise<void> {
+    const params = this.normalizeArgs<DeleteIndexParams>('deleteIndex', args);
+
+    const { indexName } = params;
     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 +248,19 @@ export class LibSQLVector extends MastraVector {
     }
   }
 
-  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;
     try {
+      const parsedIndexName = parseSqlIdentifier(indexName, 'index name');
       // Get table info including column info
       const tableInfoQuery = `
         SELECT sql 
@@ -240,11 +270,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 +283,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,
@@ -295,11 +325,12 @@ export class LibSQLVector extends MastraVector {
       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.
+   *
    * @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 +339,11 @@ 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(...args: ParamsToArgs<UpdateVectorParams>): Promise<void> {
+    const params = this.normalizeArgs<UpdateVectorParams>('updateVector', args);
+    const { indexName, id, update } = params;
     try {
+      const parsedIndexName = parseSqlIdentifier(indexName, 'index name');
       const updates = [];
       const args: InValue[] = [];
 
@@ -334,7 +364,7 @@ export class LibSQLVector extends MastraVector {
       args.push(id);
 
       const query = `
-        UPDATE ${indexName}
+        UPDATE ${parsedIndexName}
         SET ${updates.join(', ')}
         WHERE vector_id = ?;
       `;
@@ -363,7 +393,7 @@ export class LibSQLVector extends MastraVector {
       Please use deleteVector() instead. 
       deleteIndexById() will be removed on May 20th, 2025.`,
     );
-    await this.deleteVector(indexName, id);
+    await this.deleteVector({ indexName, id });
   }
 
   /**
@@ -373,10 +403,14 @@ 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(...args: ParamsToArgs<DeleteVectorParams>): Promise<void> {
+    const params = this.normalizeArgs<DeleteVectorParams>('deleteVector', args);
+
+    const { indexName, id } = params;
     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 +418,11 @@ export class LibSQLVector extends MastraVector {
     }
   }
 
-  async truncateIndex(indexName: string) {
+  async truncateIndex(...args: ParamsToArgs<DeleteIndexParams>): Promise<void> {
+    const params = this.normalizeArgs<DeleteIndexParams>('truncateIndex', args);
+    const { indexName } = params;
     await this.turso.execute({
-      sql: `DELETE FROM ${indexName}`,
+      sql: `DELETE FROM ${parseSqlIdentifier(indexName, 'index name')}`,
       args: [],
     });
   }