feat: add $nin filter operator for exclusion queries

src/filter.ts

@@ -59,6 +59,12 @@ function compileOp(ref: string, op: FilterOperator, mode: FilterMode): CompiledF
     const placeholders = op.$in.map(() => '?').join(', ')
     return { sql: `${ref} IN (${placeholders})`, params: [...op.$in] }
   }
+  if ('$nin' in op) {
+    if (op.$nin.length === 0)
+      return { sql: '1 = 1', params: [] }
+    const placeholders = op.$nin.map(() => '?').join(', ')
+    return { sql: `${ref} NOT IN (${placeholders})`, params: [...op.$nin] }
+  }
   if ('$prefix' in op)
     return { sql: `${ref} LIKE ? ESCAPE '\\'`, params: [`${escapeLike(op.$prefix)}%`] }
   if ('$contains' in op)
@@ -116,6 +122,8 @@ function matchOp(actual: unknown, op: FilterOperator): boolean {
     return typeof actual === 'number' && actual <= op.$lte
   if ('$in' in op)
     return op.$in.includes(actual as string | number)
+  if ('$nin' in op)
+    return op.$nin.length === 0 || (actual != null && !op.$nin.includes(actual as string | number))
   if ('$prefix' in op)
     return typeof actual === 'string' && actual.startsWith(op.$prefix)
   if ('$contains' in op)

src/types.ts

@@ -65,6 +65,7 @@ export type FilterOperator
     | { $lt: number }
     | { $lte: number }
     | { $in: (string | number)[] }
+    | { $nin: (string | number)[] }
     | { $prefix: string }
     | { $contains: string }
     | { $exists: boolean }

test/filter.test.ts

@@ -21,6 +21,7 @@ describe('searchFilter types', () => {
     expectTypeOf<boolean>().toMatchTypeOf<FilterValue>()
     expectTypeOf<{ $gt: number }>().toMatchTypeOf<FilterValue>()
     expectTypeOf<{ $in: string[] }>().toMatchTypeOf<FilterValue>()
+    expectTypeOf<{ $nin: string[] }>().toMatchTypeOf<FilterValue>()
     expectTypeOf<{ $prefix: string }>().toMatchTypeOf<FilterValue>()
     expectTypeOf<{ $contains: string }>().toMatchTypeOf<FilterValue>()
     expectTypeOf<{ $exists: boolean }>().toMatchTypeOf<FilterValue>()
@@ -110,6 +111,18 @@ describe('compileFilter', () => {
       expect(result.params).toEqual([])
     })
 
+    it('compiles $nin', () => {
+      const result = compileFilter({ tag: { $nin: ['a', 'b'] } }, 'json')
+      expect(result.sql).toBe(`json_extract(metadata, '$.tag') NOT IN (?, ?)`)
+      expect(result.params).toEqual(['a', 'b'])
+    })
+
+    it('compiles $nin with empty array to always-true clause', () => {
+      const result = compileFilter({ tag: { $nin: [] } }, 'json')
+      expect(result.sql).toBe('1 = 1')
+      expect(result.params).toEqual([])
+    })
+
     it('compiles $prefix', () => {
       const result = compileFilter({ path: { $prefix: '/docs/' } }, 'json')
       expect(result.sql).toBe(`json_extract(metadata, '$.path') LIKE ? ESCAPE '\\'`)
@@ -184,6 +197,18 @@ describe('compileFilter', () => {
       expect(result.params).toEqual([])
     })
 
+    it('compiles $nin', () => {
+      const result = compileFilter({ status: { $nin: ['deleted', 'archived'] } }, 'jsonb')
+      expect(result.sql).toBe(`metadata->>'status' NOT IN (?, ?)`)
+      expect(result.params).toEqual(['deleted', 'archived'])
+    })
+
+    it('compiles $nin with empty array to always-true clause', () => {
+      const result = compileFilter({ tag: { $nin: [] } }, 'jsonb')
+      expect(result.sql).toBe('1 = 1')
+      expect(result.params).toEqual([])
+    })
+
     it('compiles $prefix', () => {
       const result = compileFilter({ name: { $prefix: 'foo' } }, 'jsonb')
       expect(result.sql).toBe(`metadata->>'name' LIKE ? ESCAPE '\\'`)
@@ -324,6 +349,25 @@ describe('matchesFilter', () => {
     expect(matchesFilter({ x: { $in: [] } }, { x: 1 })).toBe(false)
   })
 
+  it('matches $nin', () => {
+    expect(matchesFilter({ x: { $nin: ['a', 'b'] } }, { x: 'c' })).toBe(true)
+    expect(matchesFilter({ x: { $nin: ['a', 'b'] } }, { x: 'a' })).toBe(false)
+    expect(matchesFilter({ x: { $nin: [1, 2] } }, { x: 3 })).toBe(true)
+    expect(matchesFilter({ x: { $nin: [1, 2] } }, { x: 1 })).toBe(false)
+  })
+
+  it('$nin with empty array matches everything', () => {
+    expect(matchesFilter({ x: { $nin: [] } }, { x: 'a' })).toBe(true)
+    expect(matchesFilter({ x: { $nin: [] } }, { x: 1 })).toBe(true)
+    expect(matchesFilter({ x: { $nin: [] } }, { other: 1 })).toBe(true)
+    expect(matchesFilter({ x: { $nin: [] } }, {})).toBe(true)
+  })
+
+  it('$nin returns false for missing field (matches SQL NULL semantics)', () => {
+    expect(matchesFilter({ x: { $nin: ['a'] } }, { other: 1 })).toBe(false)
+    expect(matchesFilter({ x: { $nin: ['a'] } }, {})).toBe(false)
+  })
+
   it('matches $prefix', () => {
     expect(matchesFilter({ path: { $prefix: '/docs/' } }, { path: '/docs/intro' })).toBe(true)
     expect(matchesFilter({ path: { $prefix: '/docs/' } }, { path: '/blog/post' })).toBe(false)
@@ -431,6 +475,19 @@ describe('sqlite-fts filter', () => {
     await db.close?.()
   })
 
+  it('filters by $nin', async () => {
+    const db = await sqliteFts({ path: ':memory:' })
+    await db.index([
+      { id: '1', content: 'hello world', metadata: { type: 'markdown' } },
+      { id: '2', content: 'hello earth', metadata: { type: 'code' } },
+      { id: '3', content: 'hello mars', metadata: { type: 'docs' } },
+    ])
+    const results = await db.search('hello', { filter: { type: { $nin: ['code', 'docs'] } }, returnMetadata: true })
+    expect(results).toHaveLength(1)
+    expect(results[0]!.id).toBe('1')
+    await db.close?.()
+  })
+
   it('returns no results for empty $in array', async () => {
     const db = await sqliteFts({ path: ':memory:' })
     await db.index([