@quaesitor-textus/mongo 0.2.0

package/dist/startSearchSync-Bk7Na8Do.d.ts

@@ -0,0 +1,39 @@
+import { Collection } from 'mongodb';
+import { SearchOptions } from '@quaesitor-textus/core';
+
+interface MongoSearchTarget {
+    fields: string[];
+    options?: SearchOptions;
+    queryModes?: SearchOptions[];
+}
+interface MongoSearchConfig {
+    namespace?: string;
+    ngramSizes?: number[];
+    targets: Record<string, MongoSearchTarget>;
+}
+declare const DEFAULT_NAMESPACE = "_qt";
+declare const DEFAULT_NGRAM_SIZES: number[];
+
+type SearchSyncEvent = {
+    type: 'indexing-started';
+} | {
+    type: 'indexing-finished';
+    count: number;
+    durationMs: number;
+} | {
+    type: 'indexed';
+    id: unknown;
+};
+type SearchSyncListener = (event: SearchSyncEvent) => void;
+interface SearchSync {
+    on(listener: SearchSyncListener): void;
+    off(listener: SearchSyncListener): void;
+    stop(): Promise<void>;
+}
+interface StartSearchSyncOptions {
+    idleMs?: number;
+    backfill?: boolean;
+}
+declare function startSearchSync(collection: Collection, config: MongoSearchConfig, options?: StartSearchSyncOptions): SearchSync;
+
+export { DEFAULT_NAMESPACE as D, type MongoSearchTarget as M, type SearchSync as S, type MongoSearchConfig as a, DEFAULT_NGRAM_SIZES as b, type SearchSyncEvent as c, type SearchSyncListener as d, type StartSearchSyncOptions as e, startSearchSync as s };

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@quaesitor-textus/mongo",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Server-side MongoDB companion for quaesitor-textus: n-gram-indexed, diacritic/case-insensitive substring search reproducing the client-side matching, a change-stream sync watcher, and live SSE search (Fastify/Express/Next adapters).",
+  "license": "Apache-2.0",
+  "keywords": [
+    "mongodb",
+    "full-text-search",
+    "search",
+    "ngram",
+    "diacritics",
+    "sse",
+    "change-streams",
+    "quaesitor-textus"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/csillag/quaesitor-textus.git",
+    "directory": "packages/mongo"
+  },
+  "homepage": "https://github.com/csillag/quaesitor-textus/tree/main/packages/mongo#readme",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    },
+    "./fastify": {
+      "types": "./dist/adapters/fastify.d.ts",
+      "development": "./src/adapters/fastify.ts",
+      "require": "./dist/adapters/fastify.cjs",
+      "import": "./dist/adapters/fastify.js"
+    },
+    "./express": {
+      "types": "./dist/adapters/express.d.ts",
+      "development": "./src/adapters/express.ts",
+      "require": "./dist/adapters/express.cjs",
+      "import": "./dist/adapters/express.js"
+    },
+    "./next/app": {
+      "types": "./dist/adapters/next-app.d.ts",
+      "development": "./src/adapters/next-app.ts",
+      "require": "./dist/adapters/next-app.cjs",
+      "import": "./dist/adapters/next-app.js"
+    },
+    "./next/pages": {
+      "types": "./dist/adapters/next-pages.d.ts",
+      "development": "./src/adapters/next-pages.ts",
+      "require": "./dist/adapters/next-pages.cjs",
+      "import": "./dist/adapters/next-pages.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@quaesitor-textus/core": "0.2.0"
+  },
+  "peerDependencies": {
+    "mongodb": ">=5",
+    "fastify": "^4 || ^5"
+  },
+  "peerDependenciesMeta": {
+    "fastify": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "fastify": "^4.0.0",
+    "mongodb": "^6.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/adapters/express.ts

@@ -0,0 +1,8 @@
+// Express adapter. Express's Request/Response are subtypes of Node's
+// IncomingMessage/ServerResponse, so the shared Node-response adapter accepts
+// them directly — no dependency on express itself.
+//
+//   import { streamLiveSearch } from '@quaesitor-textus/mongo/express'
+//   app.get('/api/live', (req, res) => streamLiveSearch(req, res, { sync, collection, config, filter }))
+export { streamToNodeResponse as streamLiveSearch } from './shared'
+export type { StreamLiveSearchOptions } from './shared'

package/src/adapters/fastify.ts

@@ -0,0 +1,19 @@
+import type { FastifyReply, FastifyRequest } from 'fastify'
+import { runLiveSearch, SSE_HEADERS } from './shared'
+import type { StreamLiveSearchOptions } from './shared'
+
+export type { StreamLiveSearchOptions }
+
+// Stream a live search to a Fastify reply as Server-Sent Events. Fastify needs
+// `reply.hijack()` so it does not try to send its own response; everything else
+// is the shared wiring.
+export function streamLiveSearch(
+  request: FastifyRequest,
+  reply: FastifyReply,
+  opts: StreamLiveSearchOptions,
+): void {
+  reply.raw.writeHead(200, SSE_HEADERS)
+  reply.hijack()
+  const { stop } = runLiveSearch(opts, (chunk) => reply.raw.write(chunk))
+  request.raw.on('close', stop)
+}

package/src/adapters/next-app.ts

@@ -0,0 +1,27 @@
+import { runLiveSearch, SSE_HEADERS } from './shared'
+import type { StreamLiveSearchOptions } from './shared'
+
+export type { StreamLiveSearchOptions }
+
+// Next.js App Router (and any Web/Fetch runtime, e.g. edge): returns a streaming
+// Response backed by a ReadableStream. Uses only Web standard APIs, so it has no
+// dependency on next.
+//
+//   import { liveSearchResponse } from '@quaesitor-textus/mongo/next/app'
+//   export async function GET(request: Request) {
+//     // parse the filter from request.url, build the Mongo filter, then:
+//     return liveSearchResponse({ sync, collection, config, filter })
+//   }
+export function liveSearchResponse(opts: StreamLiveSearchOptions): Response {
+  const encoder = new TextEncoder()
+  let handle: { stop: () => void } | undefined
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      handle = runLiveSearch(opts, (chunk) => controller.enqueue(encoder.encode(chunk)))
+    },
+    cancel() {
+      handle?.stop()
+    },
+  })
+  return new Response(stream, { headers: SSE_HEADERS })
+}

package/src/adapters/next-pages.ts

@@ -0,0 +1,11 @@
+// Next.js Pages Router adapter. NextApiRequest/NextApiResponse extend Node's
+// http types, so the shared Node-response adapter accepts them directly — no
+// dependency on next itself.
+//
+//   import { streamLiveSearch } from '@quaesitor-textus/mongo/next/pages'
+//   export default function handler(req, res) {
+//     streamLiveSearch(req, res, { sync, collection, config, filter })
+//   }
+//   export const config = { api: { responseLimit: false } } // allow long-lived SSE
+export { streamToNodeResponse as streamLiveSearch } from './shared'
+export type { StreamLiveSearchOptions } from './shared'

package/src/adapters/shared.ts

@@ -0,0 +1,61 @@
+import type { Collection, Document, Filter } from 'mongodb'
+import type { IncomingMessage, ServerResponse } from 'http'
+import type { MongoSearchConfig } from '../config'
+import type { SearchSync } from '../startSearchSync'
+import { createLiveSearch } from '../createLiveSearch'
+import { formatSse, sseComment } from '../sse'
+
+export const SSE_HEADERS = {
+  'Content-Type': 'text/event-stream',
+  'Cache-Control': 'no-cache',
+  Connection: 'keep-alive',
+} as const
+
+export interface StreamLiveSearchOptions {
+  sync: SearchSync
+  collection: Collection
+  config: MongoSearchConfig
+  filter: Filter<Document>
+  sort?: { field: string; dir: 1 | -1 }
+  cap?: number
+  heartbeatMs?: number
+}
+
+// Core wiring shared by every adapter: pipe a live search to a write() sink and
+// run a heartbeat. Returns stop() (clears the heartbeat + detaches the watcher
+// listener). All search behavior lives in createLiveSearch; adapters only own
+// their framework's headers and disconnect signal.
+export function runLiveSearch(
+  opts: StreamLiveSearchOptions,
+  write: (chunk: string) => void,
+): { stop: () => void } {
+  const sendEvent = (e: unknown) => write(formatSse(e))
+  const live = createLiveSearch({
+    sync: opts.sync,
+    collection: opts.collection,
+    config: opts.config,
+    filter: opts.filter,
+    sort: opts.sort,
+    cap: opts.cap,
+    sendEvent,
+  })
+  const hb = setInterval(() => write(sseComment()), opts.heartbeatMs ?? 25000)
+  return {
+    stop: () => {
+      clearInterval(hb)
+      live.stop()
+    },
+  }
+}
+
+// Adapter for any Node http-style response — Express and Next.js Pages Router
+// pass objects that are subtypes of IncomingMessage/ServerResponse.
+export function streamToNodeResponse(
+  req: IncomingMessage,
+  res: ServerResponse,
+  opts: StreamLiveSearchOptions,
+): void {
+  res.writeHead(200, SSE_HEADERS)
+  const { stop } = runLiveSearch(opts, (chunk) => res.write(chunk))
+  req.on('close', stop)
+}

package/src/buildTextSearchFilter.test.ts

@@ -0,0 +1,30 @@
+import { describe, it, expect } from 'vitest'
+import { buildTextSearchFilter } from './buildTextSearchFilter'
+import type { MongoSearchConfig } from './config'
+
+const config: MongoSearchConfig = {
+  targets: { author: { fields: ['author'], queryModes: [{ caseSensitive: true }] } },
+}
+
+describe('buildTextSearchFilter', () => {
+  it('empty patterns match everything', () => {
+    expect(buildTextSearchFilter('author', [], config)).toEqual({})
+  })
+  it('builds ngram $all + per-pattern verify regex (base mode)', () => {
+    const f = buildTextSearchFilter('author', ['café'], config) as any
+    const ngram = f.$and[0]['_qt.author.ngrams'].$all
+    expect(ngram).toContain('ca')      // fully folded ngrams
+    expect(f.$and[1]['_qt.author.norm'].$regex).toBe('cafe')
+  })
+  it('selects the case-sensitive verify field + folding', () => {
+    const f = buildTextSearchFilter('author', ['Café'], config, { caseSensitive: true }) as any
+    expect(f.$and[1]['_qt.author.norm_cs'].$regex).toBe('Cafe')
+  })
+  it('escapes regex metacharacters in the verify pattern', () => {
+    const f = buildTextSearchFilter('author', ['a.b'], config) as any
+    expect(f.$and[1]['_qt.author.norm'].$regex).toBe('a\\.b')
+  })
+  it('throws on unknown target', () => {
+    expect(() => buildTextSearchFilter('nope', ['x'], config)).toThrow(/Unknown search target/)
+  })
+})

package/src/buildTextSearchFilter.ts

@@ -0,0 +1,34 @@
+import { normalizeText, toNgrams } from '@quaesitor-textus/core'
+import type { SearchOptions } from '@quaesitor-textus/core'
+import type { Document, Filter } from 'mongodb'
+import type { MongoSearchConfig } from './config'
+import { DEFAULT_NAMESPACE, DEFAULT_NGRAM_SIZES } from './config'
+import { modeKey, escapeRegex } from './modes'
+
+export function buildTextSearchFilter(
+  target: string,
+  patterns: string[],
+  config: MongoSearchConfig,
+  options?: SearchOptions,
+): Filter<Document> {
+  if (patterns.length === 0) return {}
+  const ns = config.namespace ?? DEFAULT_NAMESPACE
+  const sizes = config.ngramSizes ?? DEFAULT_NGRAM_SIZES
+  const t = config.targets[target]
+  if (!t) throw new Error(`Unknown search target: ${target}`)
+  const mode = options ?? t.options ?? {}
+
+  const ngramField = `${ns}.${target}.ngrams`
+  const verifyField = `${ns}.${target}.${modeKey(mode)}`
+
+  // Index-backed superset pre-filter: all fully-folded n-grams of all patterns.
+  const ngramTerms = [
+    ...new Set(patterns.flatMap(p => toNgrams(normalizeText(p, {}), sizes))),
+  ]
+  // Verify: every pattern must be a substring of the mode-folded verify string (AND).
+  const verifyConditions = patterns.map(p => ({
+    [verifyField]: { $regex: escapeRegex(normalizeText(p, mode)) },
+  }))
+
+  return { $and: [{ [ngramField]: { $all: ngramTerms } }, ...verifyConditions] } as Filter<Document>
+}

package/src/computeSearchFields.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest'
+import { computeSearchFields } from './computeSearchFields'
+import type { MongoSearchConfig } from './config'
+
+const config: MongoSearchConfig = {
+  targets: {
+    author: { fields: ['author'], queryModes: [{ caseSensitive: true }] },
+  },
+}
+
+describe('computeSearchFields', () => {
+  it('stores fully-folded ngrams and per-mode verify strings', () => {
+    const out = computeSearchFields({ author: 'Café' }, config) as any
+    expect(out._qt.author.norm).toBe('cafe')        // folded: diacritics stripped + lowercased
+    expect(out._qt.author.norm_cs).toBe('Cafe')     // case-sensitive: diacritics stripped, case kept
+    expect(out._qt.author.ngrams).toContain('ca')
+    expect(out._qt.author.ngrams).toContain('caf')
+  })
+  it('respects a custom namespace', () => {
+    const out = computeSearchFields({ author: 'x' }, { namespace: 'qt', targets: config.targets }) as any
+    expect(out.qt.author).toBeDefined()
+  })
+})

package/src/computeSearchFields.ts

@@ -0,0 +1,31 @@
+import { buildCorpus, normalizeText, toNgrams } from '@quaesitor-textus/core'
+import type { MongoSearchConfig } from './config'
+import { DEFAULT_NAMESPACE, DEFAULT_NGRAM_SIZES } from './config'
+import { modeKey, targetModes } from './modes'
+import { searchFieldsVersion } from './version'
+
+export function computeSearchFields(
+  doc: unknown,
+  config: MongoSearchConfig,
+): Record<string, unknown> {
+  const ns = config.namespace ?? DEFAULT_NAMESPACE
+  const sizes = config.ngramSizes ?? DEFAULT_NGRAM_SIZES
+  const targets: Record<string, unknown> = {}
+
+  for (const [name, target] of Object.entries(config.targets)) {
+    const corpus = buildCorpus(doc, target.fields)
+    const entry: Record<string, unknown> = {
+      // n-grams are built on the fully-folded corpus (the coarsest fold) so the
+      // index is a superset filter valid for every query mode.
+      ngrams: toNgrams(normalizeText(corpus, {}), sizes),
+    }
+    for (const mode of targetModes(target)) {
+      entry[modeKey(mode)] = normalizeText(corpus, mode)
+    }
+    targets[name] = entry
+  }
+  // Stamp the derivation version (code + config fingerprint) so a stale-aware
+  // backfill can detect and re-derive documents after an upgrade or config change.
+  targets._v = searchFieldsVersion(config)
+  return { [ns]: targets }
+}

package/src/config.ts

@@ -0,0 +1,14 @@
+import type { SearchOptions } from '@quaesitor-textus/core'
+
+export interface MongoSearchTarget {
+  fields: string[]
+  options?: SearchOptions          // base/default query mode; defaults to {} (fully folded)
+  queryModes?: SearchOptions[]     // additional runtime-selectable modes
+}
+export interface MongoSearchConfig {
+  namespace?: string               // default "_qt"
+  ngramSizes?: number[]            // default [2, 3]
+  targets: Record<string, MongoSearchTarget>
+}
+export const DEFAULT_NAMESPACE = '_qt'
+export const DEFAULT_NGRAM_SIZES = [2, 3]

package/src/createLiveSearch.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import { MongoClient } from 'mongodb'
+import { computeSearchFields, createSearchIndexes, buildTextSearchFilter, startSearchSync, createLiveSearch } from './index'
+import type { MongoSearchConfig } from './config'
+import type { LiveEvent } from './createLiveSearch'
+
+const URL = process.env.MONGO_URL ?? 'mongodb://localhost:27018/?directConnection=true'
+const config: MongoSearchConfig = { targets: { name: { fields: ['name'] } } }
+let client: MongoClient
+let available = true
+
+beforeAll(async () => {
+  try {
+    client = await MongoClient.connect(URL, { serverSelectionTimeoutMS: 1500 })
+    const col = client.db('qt_live_test').collection('docs')
+    await col.deleteMany({})
+    await col.insertMany([{ _id: 'a', name: 'Émile Zola', ...computeSearchFields({ name: 'Émile Zola' }, config) }] as never[])
+    await createSearchIndexes(col, config)
+  } catch { available = false }
+})
+afterAll(async () => { await client?.close() })
+
+describe('createLiveSearch', () => {
+  it('emits a snapshot of current matches', async () => {
+    if (!available) return
+    const col = client.db('qt_live_test').collection('docs')
+    const sync = startSearchSync(col, config)
+    const events: LiveEvent[] = []
+    const live = createLiveSearch({ sync, collection: col, config, filter: buildTextSearchFilter('name', ['zola'], config), sendEvent: e => events.push(e) })
+    await new Promise(r => setTimeout(r, 300))
+    expect(events[0]?.type).toBe('snapshot')
+    expect((events[0] as any).items.map((d: any) => d._id)).toContain('a')
+    live.stop(); await sync.stop()
+  })
+
+  it('pushes a match for a newly-inserted matching doc', async () => {
+    if (!available) return
+    const col = client.db('qt_live_test').collection('docs')
+    const sync = startSearchSync(col, config)
+    const events: LiveEvent[] = []
+    const live = createLiveSearch({ sync, collection: col, config, filter: buildTextSearchFilter('name', ['borges'], config), sendEvent: e => events.push(e) })
+    await new Promise(r => setTimeout(r, 200))
+    await col.insertOne({ _id: 'b', name: 'Jorge Luis Borges' } as never) // raw; watcher derives
+    await new Promise(r => setTimeout(r, 1500))
+    expect(events.some(e => e.type === 'match' && (e as any).item._id === 'b')).toBe(true)
+    live.stop(); await sync.stop()
+  })
+})

package/src/createLiveSearch.ts

@@ -0,0 +1,57 @@
+import type { Collection, Document, Filter } from 'mongodb'
+import type { MongoSearchConfig } from './config'
+import type { SearchSync, SearchSyncEvent } from './startSearchSync'
+
+export type LiveEvent =
+  | { type: 'snapshot'; items: Document[] }
+  | { type: 'match'; item: Document }
+  | { type: 'capped' }
+
+export interface CreateLiveSearchOptions {
+  sync: SearchSync
+  collection: Collection
+  config: MongoSearchConfig
+  filter: Filter<Document>
+  sort?: { field: string; dir: 1 | -1 }
+  cap?: number
+  sendEvent: (event: LiveEvent) => void
+}
+
+// Transport-agnostic live search: emits the current matching set (capped), then
+// one `match` per newly-indexed document that matches `filter`, then `capped`.
+export function createLiveSearch(opts: CreateLiveSearchOptions): { stop: () => void } {
+  const { sync, collection, config: _config, filter, sort, cap = 500, sendEvent } = opts
+  const seen = new Set<string>()
+  let count = 0
+  let capped = false
+
+  const idOf = (doc: Document) => String(doc._id)
+
+  // Initial snapshot (sorted for a nicer first paint; client re-sorts anyway).
+  const cursor = collection.find(filter)
+  if (sort) cursor.sort({ [sort.field]: sort.dir })
+  void cursor.limit(cap).toArray().then((items) => {
+    for (const it of items) seen.add(idOf(it))
+    count = items.length
+    sendEvent({ type: 'snapshot', items })
+    if (count >= cap) { capped = true; sendEvent({ type: 'capped' }) }
+  }).catch(() => sendEvent({ type: 'snapshot', items: [] }))
+
+  const listener = (e: SearchSyncEvent) => {
+    if (e.type !== 'indexed' || capped) return
+    void collection.findOne({ $and: [{ _id: e.id as any }, filter] })
+      .then((doc) => {
+        if (!doc || capped) return
+        const id = idOf(doc)
+        if (seen.has(id)) return
+        seen.add(id)
+        count += 1
+        sendEvent({ type: 'match', item: doc })
+        if (count >= cap) { capped = true; sendEvent({ type: 'capped' }) }
+      })
+      .catch(() => { /* skip a failed match-test; keep the stream alive */ })
+  }
+  sync.on(listener)
+
+  return { stop: () => sync.off(listener) }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export type { MongoSearchConfig, MongoSearchTarget } from './config'
+export { DEFAULT_NAMESPACE, DEFAULT_NGRAM_SIZES } from './config'
+export { modeKey, targetModes, escapeRegex } from './modes'
+export { computeSearchFields } from './computeSearchFields'
+export { SEARCH_FIELDS_VERSION, searchFieldsVersion } from './version'
+export { searchIndexSpecs, createSearchIndexes } from './searchIndexes'
+export { buildTextSearchFilter } from './buildTextSearchFilter'
+export { startSearchSync } from './startSearchSync'
+export { createLiveSearch } from './createLiveSearch'
+export type { LiveEvent, CreateLiveSearchOptions } from './createLiveSearch'
+export { formatSse, sseComment } from './sse'
+export type { SearchSync, SearchSyncEvent, SearchSyncListener, StartSearchSyncOptions } from './startSearchSync'

package/src/modes.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from 'vitest'
+import { modeKey, targetModes, escapeRegex } from './modes'
+
+describe('modeKey', () => {
+  it('base mode is norm', () => { expect(modeKey()).toBe('norm'); expect(modeKey({})).toBe('norm') })
+  it('case-sensitive', () => { expect(modeKey({ caseSensitive: true })).toBe('norm_cs') })
+  it('diacritic-sensitive', () => { expect(modeKey({ diacriticSensitive: true })).toBe('norm_ds') })
+  it('both', () => { expect(modeKey({ caseSensitive: true, diacriticSensitive: true })).toBe('norm_cs_ds') })
+})
+describe('targetModes', () => {
+  it('includes base + queryModes, deduped', () => {
+    const modes = targetModes({ fields: ['a'], queryModes: [{ caseSensitive: true }, {}] })
+    expect(modes.map(modeKey)).toEqual(['norm', 'norm_cs'])
+  })
+})
+describe('escapeRegex', () => {
+  it('escapes regex metacharacters', () => {
+    expect(escapeRegex('a.*b')).toBe('a\\.\\*b')
+  })
+})

package/src/modes.ts

@@ -0,0 +1,24 @@
+import type { SearchOptions } from '@quaesitor-textus/core'
+import type { MongoSearchTarget } from './config'
+
+export function modeKey(o: SearchOptions = {}): string {
+  let k = 'norm'
+  if (o.caseSensitive) k += '_cs'
+  if (o.diacriticSensitive) k += '_ds'
+  return k
+}
+
+export function targetModes(t: MongoSearchTarget): SearchOptions[] {
+  const modes = [t.options ?? {}, ...(t.queryModes ?? [])]
+  const seen = new Set<string>()
+  const out: SearchOptions[] = []
+  for (const m of modes) {
+    const k = modeKey(m)
+    if (!seen.has(k)) { seen.add(k); out.push(m) }
+  }
+  return out
+}
+
+export function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}

package/src/parity.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import { MongoClient } from 'mongodb'
+import { matchItem, buildCorpus } from '@quaesitor-textus/core'
+import { computeSearchFields, createSearchIndexes, buildTextSearchFilter } from './index'
+import type { MongoSearchConfig } from './config'
+
+const URL = process.env.MONGO_URL ?? 'mongodb://localhost:27018/?replicaSet=rs0'
+const config: MongoSearchConfig = {
+  targets: { name: { fields: ['name'], queryModes: [{ caseSensitive: true }] } },
+}
+const DOCS = [
+  { name: 'Gabriel García Márquez' },
+  { name: 'GARCIA lopez' },
+  { name: 'Wei Ng' },
+  { name: 'Plain Author' },
+  { name: 'café society' },
+]
+
+let client: MongoClient
+let available = true
+
+beforeAll(async () => {
+  try {
+    client = await MongoClient.connect(URL, { serverSelectionTimeoutMS: 1500 })
+    const col = client.db('qt_parity_test').collection('docs')
+    await col.deleteMany({})
+    await col.insertMany(DOCS.map(d => ({ ...d, ...computeSearchFields(d, config) })))
+    await createSearchIndexes(col, config)
+  } catch {
+    available = false
+  }
+})
+afterAll(async () => { await client?.close() })
+
+async function serverMatches(patterns: string[], options?: any): Promise<string[]> {
+  const col = client.db('qt_parity_test').collection('docs')
+  const filter = buildTextSearchFilter('name', patterns, config, options)
+  const rows = await col.find(filter).toArray()
+  return rows.map(r => r.name).sort()
+}
+function clientMatches(patterns: string[], options?: any): string[] {
+  return DOCS.filter(d => matchItem(buildCorpus(d, ['name']), patterns, options))
+    .map(d => d.name).sort()
+}
+
+describe('client↔server parity', () => {
+  const cases: Array<{ patterns: string[]; options?: any }> = [
+    { patterns: ['garcia'] },                          // diacritic + case insensitive
+    { patterns: ['ng'] },                              // 2-char (bigram path)
+    { patterns: ['cafe'] },                            // diacritic fold
+    { patterns: ['garcia', 'marquez'] },               // multi-pattern AND
+    { patterns: ['GARCIA'], options: { caseSensitive: true } }, // case-sensitive mode
+  ]
+  for (const c of cases) {
+    it(`parity: ${JSON.stringify(c)}`, async () => {
+      if (!available) return
+      expect(await serverMatches(c.patterns, c.options)).toEqual(clientMatches(c.patterns, c.options))
+    })
+  }
+})

package/src/searchIndexes.test.ts

@@ -0,0 +1,12 @@
+import { describe, it, expect } from 'vitest'
+import { searchIndexSpecs } from './searchIndexes'
+
+describe('searchIndexSpecs', () => {
+  it('one multikey index per target', () => {
+    const specs = searchIndexSpecs({ targets: { author: { fields: ['author'] }, title: { fields: ['title'] } } })
+    expect(specs).toEqual([
+      { key: { '_qt.author.ngrams': 1 }, name: '_qt_author_ngrams' },
+      { key: { '_qt.title.ngrams': 1 },  name: '_qt_title_ngrams'  },
+    ])
+  })
+})

package/src/searchIndexes.ts

@@ -0,0 +1,22 @@
+import type { Collection } from 'mongodb'
+import type { MongoSearchConfig } from './config'
+import { DEFAULT_NAMESPACE } from './config'
+
+export function searchIndexSpecs(
+  config: MongoSearchConfig,
+): Array<{ key: Record<string, 1>; name: string }> {
+  const ns = config.namespace ?? DEFAULT_NAMESPACE
+  return Object.keys(config.targets).map(name => ({
+    key: { [`${ns}.${name}.ngrams`]: 1 },
+    name: `${ns}_${name}_ngrams`,
+  }))
+}
+
+export async function createSearchIndexes(
+  collection: Collection,
+  config: MongoSearchConfig,
+): Promise<void> {
+  for (const spec of searchIndexSpecs(config)) {
+    await collection.createIndex(spec.key, { name: spec.name })
+  }
+}