@mastra/chroma 0.1.0-alpha.28

package/src/vector/filter.test.ts

@@ -0,0 +1,413 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+
+import { ChromaFilterTranslator } from './filter';
+
+describe('ChromaFilterTranslator', () => {
+  let translator: ChromaFilterTranslator;
+
+  beforeEach(() => {
+    translator = new ChromaFilterTranslator();
+  });
+
+  // Basic Filter Operations
+  describe('basic operations', () => {
+    it('handles empty filters', () => {
+      expect(translator.translate({})).toEqual({});
+      expect(translator.translate(null as any)).toEqual(null);
+      expect(translator.translate(undefined as any)).toEqual(undefined);
+    });
+
+    it('retains implicit equality', () => {
+      const filter = { field: 'value' };
+      expect(translator.translate(filter)).toEqual({ field: 'value' });
+    });
+
+    it('converts multiple top-level fields to $and', () => {
+      const filter = {
+        field1: 'value1',
+        field2: 'value2',
+      };
+      expect(translator.translate(filter)).toEqual({
+        $and: [{ field1: 'value1' }, { field2: 'value2' }],
+      });
+    });
+
+    it('handles multiple operators on same field', () => {
+      const filter = {
+        price: { $gt: 100, $lt: 200 },
+        quantity: { $gte: 10, $lte: 20 },
+      };
+      expect(translator.translate(filter)).toEqual({
+        $and: [
+          { price: { $gt: 100 } },
+          { price: { $lt: 200 } },
+          { quantity: { $gte: 10 } },
+          { quantity: { $lte: 20 } },
+        ],
+      });
+    });
+
+    it('normalizes date values', () => {
+      const date = new Date('2024-01-01');
+      const filter = { timestamp: { $gt: date } };
+      expect(translator.translate(filter)).toEqual({ timestamp: { $gt: date.toISOString() } });
+    });
+  });
+
+  // Array Operations
+  describe('array operations', () => {
+    it('handles arrays as $in operator', () => {
+      const filter = { tags: ['tag1', 'tag2'] };
+      expect(translator.translate(filter)).toEqual({ tags: { $in: ['tag1', 'tag2'] } });
+    });
+
+    it('handles empty array values', () => {
+      // $in with empty array is valid in Pinecone
+      expect(translator.translate({ tags: { $in: [] } })).toEqual({ tags: { $in: [] } });
+    });
+
+    it('handles arrays as direct values', () => {
+      // Direct array value should be converted to $in
+      expect(translator.translate({ field: ['value1', 'value2'] })).toEqual({ field: { $in: ['value1', 'value2'] } });
+
+      // Empty direct array
+      expect(translator.translate({ field: [] })).toEqual({ field: { $in: [] } });
+    });
+
+    describe('$in operator variations', () => {
+      it('handles $in with various values', () => {
+        // Empty array
+        expect(translator.translate({ field: { $in: [] } })).toEqual({ field: { $in: [] } });
+
+        // Single value
+        expect(translator.translate({ field: { $in: ['value'] } })).toEqual({ field: { $in: ['value'] } });
+
+        // Multiple values
+        expect(translator.translate({ field: { $in: [1, 'two', true] } })).toEqual({
+          field: { $in: [1, 'two', true] },
+        });
+
+        // With dates
+        const date = new Date('2024-01-01');
+        expect(translator.translate({ field: { $in: [date.toISOString()] } })).toEqual({
+          field: { $in: [date.toISOString()] },
+        });
+      });
+    });
+  });
+
+  // Logical Operators
+  describe('logical operators', () => {
+    it('handles logical operators', () => {
+      const filter = {
+        $or: [{ status: { $eq: 'active' } }, { age: { $gt: 25 } }],
+      };
+      expect(translator.translate(filter)).toEqual({
+        $or: [{ status: { $eq: 'active' } }, { age: { $gt: 25 } }],
+      });
+    });
+
+    it('handles nested logical operators', () => {
+      const filter = {
+        $and: [
+          { status: { $eq: 'active' } },
+          {
+            $or: [{ category: { $in: ['A', 'B'] } }, { $and: [{ price: { $gt: 100 } }, { stock: { $lt: 50 } }] }],
+          },
+        ],
+      };
+      expect(translator.translate(filter)).toEqual({
+        $and: [
+          { status: { $eq: 'active' } },
+          {
+            $or: [{ category: { $in: ['A', 'B'] } }, { $and: [{ price: { $gt: 100 } }, { stock: { $lt: 50 } }] }],
+          },
+        ],
+      });
+    });
+
+    it('handles nested arrays in logical operators', () => {
+      expect(
+        translator.translate({
+          $and: [{ field1: { $in: ['a', 'b'] } }, { field2: { $in: ['c', 'd'] } }],
+        }),
+      ).toEqual({
+        $and: [
+          { field1: { $in: ['a', 'b'] } },
+          {
+            field2: { $in: ['c', 'd'] },
+          },
+        ],
+      });
+    });
+
+    it('handles complex nested conditions', () => {
+      const filter = {
+        $or: [
+          { age: { $gt: 25 } },
+          {
+            status: { $eq: 'active' },
+            theme: 'dark',
+          },
+        ],
+      };
+      expect(translator.translate(filter)).toEqual({
+        $or: [
+          { age: { $gt: 25 } },
+          {
+            $and: [{ status: { $eq: 'active' } }, { theme: 'dark' }],
+          },
+        ],
+      });
+    });
+  });
+
+  // Nested Objects and Fields
+  describe('nested objects and fields', () => {
+    it('flattens nested objects to dot notation', () => {
+      const filter = {
+        user: {
+          profile: {
+            age: { $gt: 25 },
+          },
+        },
+      };
+      expect(translator.translate(filter)).toEqual({ 'user.profile.age': { $gt: 25 } });
+    });
+
+    it('preserves empty objects as exact match conditions', () => {
+      const filter = {
+        metadata: {},
+        'user.profile': {},
+      };
+
+      expect(translator.translate(filter)).toEqual({
+        $and: [{ metadata: {} }, { 'user.profile': {} }],
+      });
+    });
+
+    it('handles empty objects in logical operators', () => {
+      const filter = {
+        $or: [{}, { status: 'active' }],
+      };
+
+      expect(translator.translate(filter)).toEqual({
+        $or: [{}, { status: 'active' }],
+      });
+    });
+
+    it('preserves empty objects in nested structures', () => {
+      const filter = {
+        user: {
+          profile: {
+            settings: {},
+          },
+        },
+      };
+
+      expect(translator.translate(filter)).toEqual({
+        'user.profile.settings': {},
+      });
+    });
+
+    it('handles empty objects in comparison operators', () => {
+      const filter = {
+        metadata: { $eq: {} },
+      };
+
+      expect(translator.translate(filter)).toEqual({
+        metadata: { $eq: {} },
+      });
+    });
+
+    it('handles empty objects in array operators', () => {
+      const filter = {
+        tags: { $in: [{}] },
+      };
+
+      expect(translator.translate(filter)).toEqual({
+        tags: { $in: [{}] },
+      });
+    });
+
+    it('handles multiple empty nested fields', () => {
+      const filter = {
+        metadata: {},
+        settings: {},
+        config: { nested: {} },
+      };
+
+      expect(translator.translate(filter)).toEqual({
+        $and: [{ metadata: {} }, { settings: {} }, { 'config.nested': {} }],
+      });
+    });
+  });
+
+  // Operator Validation
+  describe('operator validation', () => {
+    describe('logical operator validation', () => {
+      it('allows $and and $or at root level', () => {
+        const validFilters = [
+          {
+            $and: [{ field1: 'value1' }, { field2: 'value2' }],
+          },
+          {
+            $or: [{ field1: 'value1' }, { field2: 'value2' }],
+          },
+          {
+            $and: [{ field1: 'value1' }],
+            $or: [{ field2: 'value2' }],
+          },
+        ];
+
+        validFilters.forEach(filter => {
+          expect(() => translator.translate(filter)).not.toThrow();
+        });
+      });
+
+      it('allows nested $and and $or within other logical operators', () => {
+        const validFilters = [
+          {
+            $and: [
+              { field1: 'value1' },
+              {
+                $or: [{ field2: 'value2' }, { field3: 'value3' }],
+              },
+            ],
+          },
+          {
+            $or: [
+              { field1: 'value1' },
+              {
+                $and: [{ field2: 'value2' }, { field3: 'value3' }],
+              },
+            ],
+          },
+        ];
+
+        validFilters.forEach(filter => {
+          expect(() => translator.translate(filter)).not.toThrow();
+        });
+      });
+
+      it('throws error for logical operators in field-level conditions', () => {
+        const invalidFilters = [
+          {
+            field: {
+              $and: [{ $eq: 'value1' }, { $eq: 'value2' }],
+            },
+          },
+          {
+            field: {
+              $or: [{ $eq: 'value1' }, { $eq: 'value2' }],
+            },
+          },
+          {
+            nested: {
+              field: {
+                $and: [{ $eq: 'value1' }, { $eq: 'value2' }],
+              },
+            },
+          },
+        ];
+
+        invalidFilters.forEach(filter => {
+          expect(() => translator.translate(filter)).toThrow(/cannot be used at field level/);
+        });
+      });
+
+      it('throws error for direct operators in logical operator arrays', () => {
+        const invalidFilters = [
+          {
+            $and: [{ $eq: 'value' }, { $gt: 100 }],
+          },
+          {
+            $or: [{ $in: ['value1', 'value2'] }],
+          },
+          {
+            $and: [{ field1: 'value1' }, { $or: [{ $eq: 'value2' }] }],
+          },
+        ];
+
+        invalidFilters.forEach(filter => {
+          expect(() => translator.translate(filter)).toThrow(/must contain field conditions/);
+        });
+      });
+
+      it('throws error for unsupported logical operators', () => {
+        const invalidFilters = [
+          {
+            $not: { field: 'value' },
+          },
+          {
+            $nor: [{ field: 'value' }],
+          },
+          {
+            $and: [{ field1: 'value1' }, { $nor: [{ field2: 'value2' }] }],
+          },
+          {
+            field: { $not: { $eq: 'value' } },
+          },
+        ];
+
+        invalidFilters.forEach(filter => {
+          expect(() => translator.translate(filter)).toThrow(/Unsupported operator/);
+        });
+      });
+    });
+
+    it('ensure all operator filters are supported', () => {
+      const supportedFilters = [
+        { field: { $eq: 'value' } },
+        { field: { $ne: 'value' } },
+        { field: { $gt: 'value' } },
+        { field: { $gte: 'value' } },
+        { field: { $lt: 'value' } },
+        { field: { $lte: 'value' } },
+        { field: { $in: ['value'] } },
+        { $and: [{ field: { $eq: 'value' } }] },
+        { $or: [{ field: { $eq: 'value' } }] },
+      ];
+      supportedFilters.forEach(filter => {
+        expect(() => translator.translate(filter)).not.toThrow();
+      });
+    });
+
+    it('throws error for unsupported operators', () => {
+      const unsupportedFilters = [
+        { field: { $regex: 'pattern' } },
+        { field: { $contains: 'value' } },
+        { field: { $exists: true } },
+        { field: { $elemMatch: { $gt: 5 } } },
+        { field: { $nor: [{ $eq: 'value' }] } },
+        { field: { $not: [{ $eq: 'value' }] } },
+        { field: { $regex: 'pattern', $options: 'i' } },
+        { field: { $all: [{ $eq: 'value' }] } },
+      ];
+
+      unsupportedFilters.forEach(filter => {
+        expect(() => translator.translate(filter)).toThrow(/Unsupported operator/);
+      });
+    });
+
+    it('throws error for regex operators', () => {
+      const filter = { field: /pattern/i };
+      expect(() => translator.translate(filter)).toThrow();
+    });
+    it('throws error for non-logical operators at top level', () => {
+      const invalidFilters = [{ $gt: 100 }, { $in: ['value1', 'value2'] }, { $eq: true }];
+
+      invalidFilters.forEach(filter => {
+        expect(() => translator.translate(filter)).toThrow(/Invalid top-level operator/);
+      });
+    });
+
+    it('allows logical operators at top level', () => {
+      const validFilters = [{ $and: [{ field: 'value' }] }, { $or: [{ field: 'value' }] }];
+
+      validFilters.forEach(filter => {
+        expect(() => translator.translate(filter)).not.toThrow();
+      });
+    });
+  });
+});

package/src/vector/filter.ts

@@ -0,0 +1,114 @@
+import { BaseFilterTranslator, FieldCondition, Filter, OperatorSupport, QueryOperator } from '@mastra/core/filter';
+
+/**
+ * Translator for Chroma filter queries.
+ * Maintains MongoDB-compatible syntax while ensuring proper validation
+ * and normalization of values.
+ */
+export class ChromaFilterTranslator extends BaseFilterTranslator {
+  protected override getSupportedOperators(): OperatorSupport {
+    return {
+      ...BaseFilterTranslator.DEFAULT_OPERATORS,
+      logical: ['$and', '$or'],
+      array: ['$in', '$nin'],
+      element: [],
+      regex: [],
+      custom: [],
+    };
+  }
+
+  translate(filter?: Filter): Filter | undefined {
+    if (this.isEmpty(filter)) return filter;
+    this.validateFilter(filter as Filter);
+
+    return this.translateNode(filter);
+  }
+
+  private translateNode(node: Filter | FieldCondition, currentPath: string = ''): any {
+    // Handle primitive values and arrays
+    if (this.isRegex(node)) {
+      throw new Error('Regex is not supported in Chroma');
+    }
+    if (this.isPrimitive(node)) return this.normalizeComparisonValue(node);
+    if (Array.isArray(node)) return { $in: this.normalizeArrayValues(node) };
+
+    const entries = Object.entries(node as Record<string, any>);
+    const firstEntry = entries[0];
+    // Handle single operator case
+    if (entries.length === 1 && firstEntry && this.isOperator(firstEntry[0])) {
+      const [operator, value] = firstEntry;
+      const translated = this.translateOperator(operator, value);
+      return this.isLogicalOperator(operator) ? { [operator]: translated } : translated;
+    }
+
+    // Process each entry
+    const result: Record<string, any> = {};
+    const multiOperatorConditions: any[] = [];
+
+    for (const [key, value] of entries) {
+      const newPath = currentPath ? `${currentPath}.${key}` : key;
+
+      if (this.isOperator(key)) {
+        result[key] = this.translateOperator(key, value);
+        continue;
+      }
+
+      if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        // Check for multiple operators on same field
+        const valueEntries = Object.entries(value);
+        if (valueEntries.every(([op]) => this.isOperator(op)) && valueEntries.length > 1) {
+          valueEntries.forEach(([op, opValue]) => {
+            multiOperatorConditions.push({
+              [newPath]: { [op]: this.normalizeComparisonValue(opValue) },
+            });
+          });
+          continue;
+        }
+
+        // Check if the nested object contains operators
+        if (Object.keys(value).length === 0) {
+          result[newPath] = this.translateNode(value);
+        } else {
+          const hasOperators = Object.keys(value).some(k => this.isOperator(k));
+          if (hasOperators) {
+            // For objects with operators, normalize each operator value
+            const normalizedValue: Record<string, any> = {};
+            for (const [op, opValue] of Object.entries(value)) {
+              normalizedValue[op] = this.isOperator(op) ? this.translateOperator(op, opValue) : opValue;
+            }
+            result[newPath] = normalizedValue;
+          } else {
+            // For objects without operators, flatten them
+            Object.assign(result, this.translateNode(value, newPath));
+          }
+        }
+      } else {
+        result[newPath] = this.translateNode(value);
+      }
+    }
+
+    // If we have multiple operators, return them combined with $and
+    if (multiOperatorConditions.length > 0) {
+      return { $and: multiOperatorConditions };
+    }
+
+    // Wrap in $and if there are multiple top-level fields
+    if (Object.keys(result).length > 1 && !currentPath) {
+      return {
+        $and: Object.entries(result).map(([key, value]) => ({ [key]: value })),
+      };
+    }
+
+    return result;
+  }
+
+  private translateOperator(operator: QueryOperator, value: any): any {
+    // Handle logical operators
+    if (this.isLogicalOperator(operator)) {
+      return Array.isArray(value) ? value.map(item => this.translateNode(item)) : this.translateNode(value);
+    }
+
+    // Handle comparison and element operators
+    return this.normalizeComparisonValue(value);
+  }
+}