feat: add notContains operator support to filter DSL

Add $notContains to StringOperatorSchema, FieldOperatorsSchema, Filter<T>,
FILTER_OPERATORS, VALID_AST_OPERATORS, and AST_OPERATOR_MAP with both
'notcontains' and 'not_contains' AST aliases.

Fixes #34

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/spec/src/data/filter.test.ts

@@ -111,6 +111,11 @@ describe('StringOperatorSchema', () => {
     expect(() => StringOperatorSchema.parse(filter)).not.toThrow();
   });
 
+  it('should accept $notContains operator', () => {
+    const filter = { $notContains: 'spam' };
+    expect(() => StringOperatorSchema.parse(filter)).not.toThrow();
+  });
+
   it('should accept $endsWith operator', () => {
     const filter = { $endsWith: '.pdf' };
     expect(() => StringOperatorSchema.parse(filter)).not.toThrow();
@@ -826,6 +831,11 @@ describe('parseFilterAST', () => {
     expect(parseFilterAST(['name', 'like', 'John'])).toEqual({ name: { $contains: 'John' } });
   });
 
+  it('should convert notcontains/not_contains operator', () => {
+    expect(parseFilterAST(['name', 'notcontains', 'spam'])).toEqual({ name: { $notContains: 'spam' } });
+    expect(parseFilterAST(['name', 'not_contains', 'spam'])).toEqual({ name: { $notContains: 'spam' } });
+  });
+
   it('should convert startswith operator', () => {
     expect(parseFilterAST(['name', 'startswith', 'A'])).toEqual({ name: { $startsWith: 'A' } });
     expect(parseFilterAST(['name', 'starts_with', 'A'])).toEqual({ name: { $startsWith: 'A' } });
@@ -948,6 +958,8 @@ describe('isFilterAST', () => {
     expect(isFilterAST(['age', '>=', 18])).toBe(true);
     expect(isFilterAST(['role', 'in', ['admin', 'editor']])).toBe(true);
     expect(isFilterAST(['name', 'contains', 'John'])).toBe(true);
+    expect(isFilterAST(['name', 'notcontains', 'spam'])).toBe(true);
+    expect(isFilterAST(['name', 'not_contains', 'spam'])).toBe(true);
     expect(isFilterAST(['name', 'like', 'John'])).toBe(true);
     expect(isFilterAST(['created_at', 'between', ['2024-01-01', '2024-12-31']])).toBe(true);
     expect(isFilterAST(['deleted_at', 'is_null', null])).toBe(true);
@@ -1009,7 +1021,7 @@ describe('isFilterAST', () => {
 describe('VALID_AST_OPERATORS', () => {
   it('should contain all standard comparison operators', () => {
     const expected = ['=', '==', '!=', '<>', '>', '>=', '<', '<=', 'in', 'nin', 'not_in',
-      'contains', 'like', 'startswith', 'starts_with', 'endswith', 'ends_with',
+      'contains', 'notcontains', 'not_contains', 'like', 'startswith', 'starts_with', 'endswith', 'ends_with',
       'between', 'is_null', 'is_not_null'];
     for (const op of expected) {
       expect(VALID_AST_OPERATORS.has(op)).toBe(true);

packages/spec/src/data/filter.zod.ts

@@ -112,6 +112,9 @@ export const StringOperatorSchema = z.object({
   /** Contains substring - SQL: LIKE %?% | MongoDB: $regex */
   $contains: z.string().optional(),
 
+  /** Does not contain substring - SQL: NOT LIKE %?% | MongoDB: $not: $regex */
+  $notContains: z.string().optional(),
+  
   /** Starts with prefix - SQL: LIKE ?% | MongoDB: $regex */
   $startsWith: z.string().optional(),
 
@@ -163,6 +166,7 @@ export const FieldOperatorsSchema = z.object({
 
   // String-specific
   $contains: z.string().optional(),
+  $notContains: z.string().optional(),
   $startsWith: z.string().optional(),
   $endsWith: z.string().optional(),
 
@@ -272,6 +276,7 @@ export type Filter<T = any> = {
         $nin?: T[K][];
         $between?: T[K] extends number | Date ? [T[K], T[K]] : never;
         $contains?: T[K] extends string ? string : never;
+        $notContains?: T[K] extends string ? string : never;
         $startsWith?: T[K] extends string ? string : never;
         $endsWith?: T[K] extends string ? string : never;
         $null?: boolean;
@@ -346,7 +351,7 @@ export type NormalizedFilter = z.infer<typeof NormalizedFilterSchema>;
 export const VALID_AST_OPERATORS = new Set([
   '=', '==', '!=', '<>', '>', '>=', '<', '<=',
   'in', 'nin', 'not_in',
-  'contains', 'like',
+  'contains', 'notcontains', 'not_contains', 'like',
   'startswith', 'starts_with',
   'endswith', 'ends_with',
   'between',
@@ -418,6 +423,8 @@ const AST_OPERATOR_MAP: Record<string, string> = {
   'nin': '$nin',
   'not_in': '$nin',
   'contains': '$contains',
+  'notcontains': '$notContains',
+  'not_contains': '$notContains',
   'like': '$contains',
   'startswith': '$startsWith',
   'starts_with': '$startsWith',
@@ -532,7 +539,7 @@ export const FILTER_OPERATORS = [
   // Set & Range
   '$in', '$nin', '$between',
   // String
-  '$contains', '$startsWith', '$endsWith',
+  '$contains', '$notContains', '$startsWith', '$endsWith',
   // Special
   '$null', '$exists',
 ] as const;