@mastra/libsql 0.10.4-alpha.0 → 0.10.4-alpha.2

package/src/vector/filter.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
+import type { LibSQLVectorFilter } from './filter';
 import { LibSQLFilterTranslator } from './filter';
 
 describe('LibSQLFilterTranslator', () => {
@@ -17,14 +18,8 @@ describe('LibSQLFilterTranslator', () => {
       });
     });
 
-    it('translates array to $in', () => {
-      expect(translator.translate({ field: ['a', 'b'] })).toEqual({
-        field: { $in: ['a', 'b'] },
-      });
-    });
-
     it('preserves comparison operators', () => {
-      const filter = {
+      const filter: LibSQLVectorFilter = {
         field1: { $eq: 'value' },
         field2: { $ne: 'value' },
         field3: { $gt: 5 },
@@ -55,7 +50,7 @@ describe('LibSQLFilterTranslator', () => {
           nested: {
             field: 'value',
           },
-        }),
+        } as any),
       ).toEqual({
         'nested.field': { $eq: 'value' },
       });
@@ -65,7 +60,8 @@ describe('LibSQLFilterTranslator', () => {
   // Array Operations
   describe('array operations', () => {
     it('translates array to $in', () => {
-      expect(translator.translate({ field: ['a', 'b'] })).toEqual({
+      const filter: LibSQLVectorFilter = { field: ['a', 'b'] };
+      expect(translator.translate(filter)).toEqual({
         field: { $in: ['a', 'b'] },
       });
     });
@@ -82,7 +78,7 @@ describe('LibSQLFilterTranslator', () => {
     it('handles empty arrays', () => {
       expect(
         translator.translate({
-          field: [],
+          field: [] as any,
         }),
       ).toEqual({
         field: { $in: [] },
@@ -128,7 +124,7 @@ describe('LibSQLFilterTranslator', () => {
   });
 
   // Array Operator Normalization
-  describe('array operator normalization', () => {
+  describe('Array operator normalization', () => {
     it('normalizes single values for $all', () => {
       expect(
         translator.translate({
@@ -173,7 +169,7 @@ describe('LibSQLFilterTranslator', () => {
   // Logical Operators
   describe('Logical Operators', () => {
     it('handles logical operators', () => {
-      const filter = {
+      const filter: LibSQLVectorFilter = {
         $and: [{ field1: { $eq: 'value1' } }, { field2: { $eq: 'value2' } }],
         $or: [{ field3: { $eq: 'value3' } }, { field4: { $eq: 'value4' } }],
       };
@@ -457,16 +453,6 @@ describe('LibSQLFilterTranslator', () => {
         field: { $eq: '' },
       });
     });
-
-    it('handles empty arrays', () => {
-      expect(
-        translator.translate({
-          field: [],
-        }),
-      ).toEqual({
-        field: { $in: [] },
-      });
-    });
   });
 
   // Complex Filter Structures
@@ -540,53 +526,10 @@ describe('LibSQLFilterTranslator', () => {
     });
   });
 
-  // Array Operator Normalization
-  describe('Array Operator Normalization', () => {
-    it('normalizes single values for $all', () => {
-      expect(
-        translator.translate({
-          field: { $all: 'value' },
-        }),
-      ).toEqual({
-        field: { $all: ['value'] },
-      });
-    });
-
-    it('normalizes single values for $in', () => {
-      expect(
-        translator.translate({
-          field: { $in: 'value' },
-        }),
-      ).toEqual({
-        field: { $in: ['value'] },
-      });
-    });
-
-    it('normalizes single values for $nin', () => {
-      expect(
-        translator.translate({
-          field: { $nin: 'value' },
-        }),
-      ).toEqual({
-        field: { $nin: ['value'] },
-      });
-    });
-
-    it('preserves arrays for array operators', () => {
-      expect(
-        translator.translate({
-          field: { $all: ['value1', 'value2'] },
-        }),
-      ).toEqual({
-        field: { $all: ['value1', 'value2'] },
-      });
-    });
-  });
-
   // Operator Support Validation
   describe('Operator Support Validation', () => {
     it('ensure all operator filters are supported', () => {
-      const supportedFilters = [
+      const supportedFilters: LibSQLVectorFilter[] = [
         // Basic comparison operators
         { field: { $eq: 'value' } },
         { field: { $ne: 'value' } },
@@ -612,12 +555,7 @@ describe('LibSQLFilterTranslator', () => {
         { $or: [{ field1: 'value1' }, { field2: 'value2' }] },
         { $nor: [{ field1: 'value1' }, { field2: 'value2' }] },
 
-        { $and: { field: 'value' } },
-        { $or: { field: 'value' } },
-        { $nor: { field: 'value' } },
-        { $not: { field: 'value' } },
-
-        { $or: [{ $and: { field1: 'value1' } }, { $not: { field2: 'value2' } }] },
+        { $or: [{ $and: [{ field1: 'value1' }] }, { $not: { field2: 'value2' } }] },
 
         { field: { $not: { $eq: 'value' } } },
         { field: { $not: { $in: ['value1', 'value2'] } } },
@@ -634,7 +572,7 @@ describe('LibSQLFilterTranslator', () => {
 
     it('throws error for $not if not an object', () => {
       expect(() => translator.translate({ $not: 'value' })).toThrow();
-      expect(() => translator.translate({ $not: [{ field: 'value' }] })).toThrow();
+      expect(() => translator.translate({ $not: [{ field: 'value' }] } as any)).toThrow();
     });
     it('throws error for $not if empty', () => {
       expect(() => translator.translate({ $not: {} })).toThrow();
@@ -646,21 +584,21 @@ describe('LibSQLFilterTranslator', () => {
       expect(() =>
         translator.translate({
           field: { $and: [{ $eq: 'value1' }, { $eq: 'value2' }] },
-        }),
+        } as any),
       ).toThrow();
 
       // $or cannot be used in field conditions
       expect(() =>
         translator.translate({
           field: { $or: [{ $eq: 'value1' }, { $eq: 'value2' }] },
-        }),
+        } as any),
       ).toThrow();
 
       // $nor cannot be used in field conditions
       expect(() =>
         translator.translate({
           field: { $nor: [{ $eq: 'value1' }, { $eq: 'value2' }] },
-        }),
+        } as any),
       ).toThrow();
     });
 
@@ -709,7 +647,7 @@ describe('LibSQLFilterTranslator', () => {
           field: {
             $gt: {
               $or: [{ subfield: 'value1' }, { subfield: 'value2' }],
-            },
+            } as any,
           },
         }),
       ).toThrow();
@@ -723,17 +661,17 @@ describe('LibSQLFilterTranslator', () => {
                 $and: [{ subfield: 'value1' }, { subfield: 'value2' }],
               },
             ],
-          },
+          } as any,
         }),
       ).toThrow();
     });
 
     it('validates $not operator structure', () => {
       // $not must be an object
-      expect(() => translator.translate({ field: { $not: 'value' } })).toThrow();
+      expect(() => translator.translate({ field: { $not: 'value' } } as any)).toThrow();
       expect(() => translator.translate({ field: { $not: ['value'] } })).toThrow();
       expect(() => translator.translate({ $not: 'value' })).toThrow();
-      expect(() => translator.translate({ $not: ['value'] })).toThrow();
+      expect(() => translator.translate({ $not: ['value'] } as any)).toThrow();
     });
 
     it('validates $not operator nesting', () => {
@@ -793,7 +731,7 @@ describe('LibSQLFilterTranslator', () => {
       const invalidFilters = [{ $gt: 100 }, { $in: ['value1', 'value2'] }, { $eq: true }];
 
       invalidFilters.forEach(filter => {
-        expect(() => translator.translate(filter)).toThrow(/Invalid top-level operator/);
+        expect(() => translator.translate(filter as any)).toThrow(/Invalid top-level operator/);
       });
     });
     it('allows logical operators at top level', () => {
@@ -815,13 +753,13 @@ describe('LibSQLFilterTranslator', () => {
       // Should throw for non-object values
       expect(() =>
         translator.translate({
-          field: { $elemMatch: 'value' },
+          field: { $elemMatch: 'value' } as any,
         }),
       ).toThrow('$elemMatch requires an object with conditions');
 
       expect(() =>
         translator.translate({
-          field: { $elemMatch: ['value'] },
+          field: { $elemMatch: ['value'] } as any,
         }),
       ).toThrow('$elemMatch requires an object with conditions');
     });
@@ -962,7 +900,7 @@ describe('LibSQLFilterTranslator', () => {
   // Unsupported Operations
   describe('unsupported operators', () => {
     it('throws on unsupported operators', () => {
-      expect(() => translator.translate({ field: { $regex: 'value' } })).toThrow();
+      expect(() => translator.translate({ field: { $regex: 'value' } } as any)).toThrow();
     });
   });
 });

package/src/vector/filter.ts

@@ -1,5 +1,19 @@
 import { BaseFilterTranslator } from '@mastra/core/vector/filter';
-import type { FieldCondition, VectorFilter, OperatorSupport } from '@mastra/core/vector/filter';
+import type { VectorFilter, OperatorSupport, OperatorValueMap, VectorFieldValue } from '@mastra/core/vector/filter';
+
+type LibSQLOperatorValueMap = Omit<
+  OperatorValueMap,
+  '$regex' | '$options' | '$in' | '$all' | '$nin' | '$eq' | '$ne'
+> & {
+  $size: number;
+  $contains: VectorFieldValue | Record<string, unknown>;
+  $all: VectorFieldValue;
+  $in: VectorFieldValue;
+  $nin: VectorFieldValue;
+  $eq: VectorFieldValue;
+  $ne: VectorFieldValue;
+};
+export type LibSQLVectorFilter = VectorFilter<keyof LibSQLOperatorValueMap, LibSQLOperatorValueMap>;
 
 /**
  * Translates MongoDB-style filters to LibSQL compatible filters.
@@ -11,7 +25,7 @@ import type { FieldCondition, VectorFilter, OperatorSupport } from '@mastra/core
  * - Can take either a single condition or an array of conditions
  *
  */
-export class LibSQLFilterTranslator extends BaseFilterTranslator {
+export class LibSQLFilterTranslator extends BaseFilterTranslator<LibSQLVectorFilter> {
   protected override getSupportedOperators(): OperatorSupport {
     return {
       ...BaseFilterTranslator.DEFAULT_OPERATORS,
@@ -20,7 +34,7 @@ export class LibSQLFilterTranslator extends BaseFilterTranslator {
     };
   }
 
-  translate(filter?: VectorFilter): VectorFilter {
+  translate(filter?: LibSQLVectorFilter): LibSQLVectorFilter {
     if (this.isEmpty(filter)) {
       return filter;
     }
@@ -28,7 +42,7 @@ export class LibSQLFilterTranslator extends BaseFilterTranslator {
     return this.translateNode(filter);
   }
 
-  private translateNode(node: VectorFilter | FieldCondition, currentPath: string = ''): any {
+  private translateNode(node: LibSQLVectorFilter, currentPath: string = ''): any {
     if (this.isRegex(node)) {
       throw new Error('Direct regex pattern format is not supported in LibSQL');
     }
@@ -74,7 +88,7 @@ export class LibSQLFilterTranslator extends BaseFilterTranslator {
 
       if (this.isLogicalOperator(key)) {
         result[key] = Array.isArray(value)
-          ? value.map((filter: VectorFilter) => this.translateNode(filter))
+          ? value.map((filter: LibSQLVectorFilter) => this.translateNode(filter))
           : this.translateNode(value);
       } else if (this.isOperator(key)) {
         if (this.isArrayOperator(key) && !Array.isArray(value) && key !== '$elemMatch') {

package/src/vector/index.test.ts

@@ -1130,7 +1130,7 @@ describe('LibSQLVector', () => {
           vectorDB.query({
             indexName,
             queryVector: [1, 0, 0],
-            filter: { price: { $invalid: 100 } },
+            filter: { price: { $invalid: 100 } } as any,
           }),
         ).rejects.toThrow('Unsupported operator: $invalid');
       });
@@ -1360,16 +1360,6 @@ describe('LibSQLVector', () => {
         });
       });
 
-      it('should throw error for invalid operator', async () => {
-        await expect(
-          vectorDB.query({
-            indexName,
-            queryVector: [1, 0, 0],
-            filter: { price: { $invalid: 100 } },
-          }),
-        ).rejects.toThrow('Unsupported operator: $invalid');
-      });
-
       it('should handle multiple logical operators at root level', async () => {
         const results = await vectorDB.query({
           indexName,

package/src/vector/index.ts

@@ -1,6 +1,7 @@
 import { createClient } from '@libsql/client';
 import type { Client as TursoClient, InValue } from '@libsql/client';
 
+import { ErrorCategory, ErrorDomain, MastraError } from '@mastra/core/error';
 import { parseSqlIdentifier } from '@mastra/core/utils';
 import { MastraVector } from '@mastra/core/vector';
 import type {
@@ -14,11 +15,11 @@ import type {
   DeleteVectorParams,
   UpdateVectorParams,
 } from '@mastra/core/vector';
-import type { VectorFilter } from '@mastra/core/vector/filter';
+import type { LibSQLVectorFilter } from './filter';
 import { LibSQLFilterTranslator } from './filter';
 import { buildFilterQuery } from './sql-builder';
 
-interface LibSQLQueryVectorParams extends QueryVectorParams {
+interface LibSQLQueryVectorParams extends QueryVectorParams<LibSQLVectorFilter> {
   minScore?: number;
 }
 
@@ -40,7 +41,7 @@ export interface LibSQLVectorConfig {
   initialBackoffMs?: number;
 }
 
-export class LibSQLVector extends MastraVector {
+export class LibSQLVector extends MastraVector<LibSQLVectorFilter> {
   private turso: TursoClient;
   private readonly maxRetries: number;
   private readonly initialBackoffMs: number;
@@ -108,7 +109,7 @@ export class LibSQLVector extends MastraVector {
     throw new Error('LibSQLVector: Max retries reached, but no error was re-thrown from the loop.');
   }
 
-  transformFilter(filter?: VectorFilter) {
+  transformFilter(filter?: LibSQLVectorFilter) {
     const translator = new LibSQLFilterTranslator();
     return translator.translate(filter);
   }
@@ -128,7 +129,18 @@ export class LibSQLVector extends MastraVector {
       if (!Array.isArray(queryVector) || !queryVector.every(x => typeof x === 'number' && Number.isFinite(x))) {
         throw new Error('queryVector must be an array of finite numbers');
       }
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_VECTOR_QUERY_INVALID_ARGS',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.USER,
+        },
+        error,
+      );
+    }
 
+    try {
       const parsedIndexName = parseSqlIdentifier(indexName, 'index name');
 
       const vectorStr = `[${queryVector.join(',')}]`;
@@ -165,13 +177,31 @@ export class LibSQLVector extends MastraVector {
         metadata: JSON.parse((metadata as string) ?? '{}'),
         ...(includeVector && embedding && { vector: JSON.parse(embedding as string) }),
       }));
-    } finally {
-      // client.release()
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_VECTOR_QUERY_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+        },
+        error,
+      );
     }
   }
 
   public upsert(args: UpsertVectorParams): Promise<string[]> {
-    return this.executeWriteOperationWithRetry(() => this.doUpsert(args), true);
+    try {
+      return this.executeWriteOperationWithRetry(() => this.doUpsert(args), true);
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_VECTOR_UPSERT_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+        },
+        error,
+      );
+    }
   }
 
   private async doUpsert({ indexName, vectors, metadata, ids }: UpsertVectorParams): Promise<string[]> {
@@ -218,7 +248,19 @@ export class LibSQLVector extends MastraVector {
   }
 
   public createIndex(args: CreateIndexParams): Promise<void> {
-    return this.executeWriteOperationWithRetry(() => this.doCreateIndex(args));
+    try {
+      return this.executeWriteOperationWithRetry(() => this.doCreateIndex(args));
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_VECTOR_CREATE_INDEX_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName: args.indexName, dimension: args.dimension },
+        },
+        error,
+      );
+    }
   }
 
   private async doCreateIndex({ indexName, dimension }: CreateIndexParams): Promise<void> {
@@ -247,7 +289,19 @@ export class LibSQLVector extends MastraVector {
   }
 
   public deleteIndex(args: DeleteIndexParams): Promise<void> {
-    return this.executeWriteOperationWithRetry(() => this.doDeleteIndex(args));
+    try {
+      return this.executeWriteOperationWithRetry(() => this.doDeleteIndex(args));
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_VECTOR_DELETE_INDEX_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName: args.indexName },
+        },
+        error,
+      );
+    }
   }
 
   private async doDeleteIndex({ indexName }: DeleteIndexParams): Promise<void> {
@@ -271,7 +325,14 @@ export class LibSQLVector extends MastraVector {
       });
       return result.rows.map(row => row.name as string);
     } catch (error: any) {
-      throw new Error(`Failed to list vector tables: ${error.message}`);
+      throw new MastraError(
+        {
+          id: 'LIBSQL_VECTOR_LIST_INDEXES_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+        },
+        error,
+      );
     }
   }
 
@@ -322,7 +383,15 @@ export class LibSQLVector extends MastraVector {
         metric,
       };
     } catch (e: any) {
-      throw new Error(`Failed to describe vector table: ${e.message}`);
+      throw new MastraError(
+        {
+          id: 'LIBSQL_VECTOR_DESCRIBE_INDEX_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName },
+        },
+        e,
+      );
     }
   }
 
@@ -357,7 +426,13 @@ export class LibSQLVector extends MastraVector {
     }
 
     if (updates.length === 0) {
-      throw new Error('No updates provided');
+      throw new MastraError({
+        id: 'LIBSQL_VECTOR_UPDATE_VECTOR_INVALID_ARGS',
+        domain: ErrorDomain.STORAGE,
+        category: ErrorCategory.USER,
+        details: { indexName, id },
+        text: 'No updates provided',
+      });
     }
     args.push(id);
     const query = `
@@ -365,10 +440,23 @@ export class LibSQLVector extends MastraVector {
         SET ${updates.join(', ')}
         WHERE vector_id = ?;
       `;
-    await this.turso.execute({
-      sql: query,
-      args,
-    });
+
+    try {
+      await this.turso.execute({
+        sql: query,
+        args,
+      });
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_VECTOR_UPDATE_VECTOR_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName, id },
+        },
+        error,
+      );
+    }
   }
 
   /**
@@ -379,7 +467,19 @@ export class LibSQLVector extends MastraVector {
    * @throws Will throw an error if the deletion operation fails.
    */
   public deleteVector(args: DeleteVectorParams): Promise<void> {
-    return this.executeWriteOperationWithRetry(() => this.doDeleteVector(args));
+    try {
+      return this.executeWriteOperationWithRetry(() => this.doDeleteVector(args));
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_VECTOR_DELETE_VECTOR_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName: args.indexName, id: args.id },
+        },
+        error,
+      );
+    }
   }
 
   private async doDeleteVector({ indexName, id }: DeleteVectorParams): Promise<void> {
@@ -391,7 +491,19 @@ export class LibSQLVector extends MastraVector {
   }
 
   public truncateIndex(args: DeleteIndexParams): Promise<void> {
-    return this.executeWriteOperationWithRetry(() => this._doTruncateIndex(args));
+    try {
+      return this.executeWriteOperationWithRetry(() => this._doTruncateIndex(args));
+    } catch (error) {
+      throw new MastraError(
+        {
+          id: 'LIBSQL_VECTOR_TRUNCATE_INDEX_FAILED',
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY,
+          details: { indexName: args.indexName },
+        },
+        error,
+      );
+    }
   }
 
   private async _doTruncateIndex({ indexName }: DeleteIndexParams): Promise<void> {

package/src/vector/sql-builder.ts

@@ -6,8 +6,8 @@ import type {
   ArrayOperator,
   ElementOperator,
   LogicalOperator,
-  VectorFilter,
 } from '@mastra/core/vector/filter';
+import type { LibSQLVectorFilter } from './filter';
 
 type OperatorType =
   | BasicOperator
@@ -372,7 +372,7 @@ function escapeLikePattern(str: string): string {
   return str.replace(/([%_\\])/g, '\\$1');
 }
 
-export function buildFilterQuery(filter: VectorFilter): FilterResult {
+export function buildFilterQuery(filter: LibSQLVectorFilter): FilterResult {
   if (!filter) {
     return { sql: '', values: [] };
   }
@@ -428,11 +428,11 @@ function buildCondition(key: string, value: any, parentPath: string): FilterResu
 
 function handleLogicalOperator(
   key: '$and' | '$or' | '$not' | '$nor',
-  value: VectorFilter[] | VectorFilter,
+  value: LibSQLVectorFilter[] | LibSQLVectorFilter,
   parentPath: string,
 ): FilterResult {
   // Handle empty conditions
-  if (!value || value.length === 0) {
+  if (!value || (Array.isArray(value) && value.length === 0)) {
     switch (key) {
       case '$and':
       case '$nor':
@@ -460,7 +460,7 @@ function handleLogicalOperator(
   const joinOperator = key === '$or' || key === '$nor' ? 'OR' : 'AND';
   const conditions = Array.isArray(value)
     ? value.map(f => {
-        const entries = Object.entries(f);
+        const entries = !!f ? Object.entries(f) : [];
         return entries.map(([k, v]) => buildCondition(k, v, key));
       })
     : [buildCondition(key, value, parentPath)];