@strav/search 0.4.31 → 1.0.0-alpha.33

package/src/drivers/postgres/engine/query_compiler.ts

@@ -1,165 +0,0 @@
-import type { SearchOptions } from '../../../types.ts'
-import type { FieldRegistry } from './field_registry.ts'
-import { compileFilter } from '../filters/filter_compiler.ts'
-import { quoteIdent, quoteLiteral, indexTableName } from '../storage/identifiers.ts'
-
-export interface CompiledSearch {
-  /** Main SELECT returning hits + score + snippets. */
-  sql: string
-  /** Bound parameters for the SELECT. */
-  params: unknown[]
-  /** COUNT(*) variant for totalHits (uses the same MATCH + filter, no rank/snippets). */
-  countSql: string
-  countParams: unknown[]
-  /** Names of headlight columns we asked PG to return (`__snip_<field>`). */
-  snippetColumns: string[]
-}
-
-const DEFAULT_HEADLINE_OPTIONS =
-  'StartSel=<mark>,StopSel=</mark>,MaxWords=35,MinWords=15,ShortWord=0,HighlightAll=false,MaxFragments=2'
-
-/** ts_rank_cd normalization bitmask. 1 = divide by 1+log(doc length), 32 = rank/(rank+1). */
-const DEFAULT_RANK_FLAGS = 1 | 32
-
-export interface QueryCompilerOptions {
-  registry: FieldRegistry
-  schema: string
-  index: string
-  /** Output of buildTsqueryExpression — already starts at placeholder 1. */
-  tsquery: { sql: string; params: string[] }
-  search: SearchOptions
-}
-
-export function compileSearch(opts: QueryCompilerOptions): CompiledSearch {
-  const { registry, schema, index, tsquery, search } = opts
-  const filterableSet = new Set(registry.filterable)
-  const sortableSet = new Set(registry.sortable)
-
-  const filter = compileFilter(search.filter, filterableSet, tsquery.params.length)
-  const params: unknown[] = [...tsquery.params, ...filter.params]
-
-  const whereParts: string[] = []
-  if (tsquery.sql) whereParts.push(`fts @@ q.query`)
-  if (filter.sql) whereParts.push(filter.sql)
-  const where = whereParts.length > 0 ? `WHERE ${whereParts.join(' AND ')}` : ''
-
-  const orderBy = compileOrder(search.sort, sortableSet, !tsquery.sql)
-
-  const perPage = Math.max(1, search.perPage ?? 20)
-  const page = Math.max(1, search.page ?? 1)
-  const offset = (page - 1) * perPage
-
-  const limitPh = `$${params.length + 1}`
-  const offsetPh = `$${params.length + 2}`
-  params.push(perPage, offset)
-
-  const wantedHighlights = pickHighlightFields(search.attributesToHighlight, registry)
-  const lang = `${quoteLiteral(registry.language)}::regconfig`
-
-  // The ranked CTE: filter + order + LIMIT, returns top-K rows + score only.
-  // ts_headline runs only on this top-K slice (huge perf win — ts_headline
-  // re-tokenizes raw text per row).
-  const cte = tsquery.sql
-    ? `WITH q AS (SELECT (${tsquery.sql}) AS query),
-           ranked AS (
-             SELECT id, doc, ts_rank_cd(fts, q.query, ${DEFAULT_RANK_FLAGS}) AS score
-               FROM ${indexTableName(schema, index)}, q
-               ${where}
-               ${orderBy}
-               LIMIT ${limitPh} OFFSET ${offsetPh}
-           )`
-    : `WITH ranked AS (
-             SELECT id, doc, 0::real AS score
-               FROM ${indexTableName(schema, index)}
-               ${where}
-               ${orderBy}
-               LIMIT ${limitPh} OFFSET ${offsetPh}
-           )`
-
-  const snippetCols = wantedHighlights.map(field => {
-    return `ts_headline(${lang}, coalesce(doc->>${quoteLiteral(field)}, ''), ` +
-      `${tsquery.sql ? '(SELECT query FROM q)' : 'plainto_tsquery(' + lang + ", '')"}, ` +
-      `${quoteLiteral(DEFAULT_HEADLINE_OPTIONS)}) AS ${quoteIdent(`__snip_${field}`)}`
-  })
-
-  const selectCols = ['id', 'doc', 'score', ...snippetCols]
-
-  // Re-emit ORDER BY in the outer SELECT — Postgres doesn't preserve row
-  // order across CTE boundaries.
-  const outerOrderBy = compileOuterOrder(search.sort, sortableSet, !tsquery.sql)
-  const sql = `${cte}
-    SELECT ${selectCols.join(', ')}
-    FROM ranked
-    ${outerOrderBy}`
-
-  // Count uses the MATCH + filter, but no rank/snippet/limit.
-  const countSql = tsquery.sql
-    ? `SELECT COUNT(*)::int AS n FROM ${indexTableName(schema, index)}, ` +
-        `(SELECT (${tsquery.sql}) AS query) q ${where}`
-    : `SELECT COUNT(*)::int AS n FROM ${indexTableName(schema, index)} ${where}`
-
-  const countParams = [...tsquery.params, ...filter.params]
-
-  return {
-    sql,
-    params,
-    countSql,
-    countParams,
-    snippetColumns: wantedHighlights,
-  }
-}
-
-function compileOrder(
-  sort: string[] | undefined,
-  sortableSet: ReadonlySet<string>,
-  matchAll: boolean
-): string {
-  if (sort && sort.length > 0) {
-    const parts: string[] = []
-    for (const spec of sort) {
-      const [field, dirRaw] = spec.split(':') as [string, string | undefined]
-      if (!field || !sortableSet.has(field)) {
-        throw new Error(
-          `Field "${field}" is not in sortableAttributes. Add it to the index settings before sorting on it.`
-        )
-      }
-      const dir = dirRaw?.toLowerCase() === 'desc' ? 'DESC' : 'ASC'
-      parts.push(`${quoteIdent(field)} ${dir}`)
-    }
-    return `ORDER BY ${parts.join(', ')}`
-  }
-  if (matchAll) return 'ORDER BY id ASC'
-  return 'ORDER BY score DESC'
-}
-
-/** ORDER BY for the outer SELECT — references columns visible on `ranked`. */
-function compileOuterOrder(
-  sort: string[] | undefined,
-  sortableSet: ReadonlySet<string>,
-  matchAll: boolean
-): string {
-  if (sort && sort.length > 0) {
-    // The CTE only exposes id, doc, score — sortable columns aren't in scope,
-    // so we sort by `doc->>'field'` lexically. Same lex semantics as the
-    // typed generated columns (which are TEXT) used inside the CTE.
-    const parts: string[] = []
-    for (const spec of sort) {
-      const [field, dirRaw] = spec.split(':') as [string, string | undefined]
-      if (!field || !sortableSet.has(field)) continue
-      const dir = dirRaw?.toLowerCase() === 'desc' ? 'DESC' : 'ASC'
-      parts.push(`(doc->>${quoteLiteral(field)}) ${dir}`)
-    }
-    return parts.length > 0 ? `ORDER BY ${parts.join(', ')}` : ''
-  }
-  if (matchAll) return 'ORDER BY id ASC'
-  return 'ORDER BY score DESC'
-}
-
-function pickHighlightFields(
-  requested: string[] | undefined,
-  registry: FieldRegistry
-): string[] {
-  if (registry.usesDefaultTextColumn) return []
-  if (!requested || requested.length === 0) return []
-  return requested.filter(f => registry.searchable.includes(f))
-}

package/src/drivers/postgres/engine/schema.ts

@@ -1,187 +0,0 @@
-import type { SQL } from 'bun'
-import { quoteIdent, quoteLiteral, indexTableName, termsTableName, metaTableName, bareIndexTable, bareTermsTable } from '../storage/identifiers.ts'
-import { MissingExtensionError } from '../errors.ts'
-import type { FieldRegistry } from './field_registry.ts'
-import type { ResolvedTypoTolerance } from '../types.ts'
-
-const SCHEMA_VERSION = 1
-
-/**
- * Idempotent: ensures the search schema, the shared `_meta` table, and the
- * required extensions exist. Called once per driver instantiation.
- */
-export async function ensureSchemaAndExtensions(
-  sql: SQL,
-  schema: string,
-  typo: ResolvedTypoTolerance
-): Promise<void> {
-  await sql.unsafe(`CREATE SCHEMA IF NOT EXISTS ${quoteIdent(schema)}`)
-
-  await sql.unsafe(`
-    CREATE TABLE IF NOT EXISTS ${metaTableName(schema)} (
-      index_name TEXT NOT NULL,
-      key        TEXT NOT NULL,
-      value      TEXT NOT NULL,
-      PRIMARY KEY (index_name, key)
-    )
-  `)
-
-  if (typo.enabled) {
-    try {
-      await sql.unsafe('CREATE EXTENSION IF NOT EXISTS pg_trgm')
-    } catch {
-      throw new MissingExtensionError('pg_trgm')
-    }
-    // fuzzystrmatch is optional — used to re-rank trigram candidates with a
-    // bounded Levenshtein. If absent we silently fall back to trigram-only.
-    try {
-      await sql.unsafe('CREATE EXTENSION IF NOT EXISTS fuzzystrmatch')
-    } catch {
-      // ignore
-    }
-  }
-}
-
-/**
- * Idempotent: create the per-index table, GIN index, terms_dict, and trigger.
- * Returns true if the table was newly created (caller may seed `_meta`).
- */
-export async function ensureIndexTable(
-  sql: SQL,
-  schema: string,
-  index: string,
-  registry: FieldRegistry,
-  ginFastUpdate: boolean
-): Promise<boolean> {
-  const exists = await tableExists(sql, schema, bareIndexTable(index))
-  if (exists) return false
-
-  const typedColsDdl = registry.typedColumns
-    .map(c => `, ${quoteIdent(c.name)} TEXT GENERATED ALWAYS AS (${c.expression}) STORED`)
-    .join('')
-
-  await sql.unsafe(`
-    CREATE TABLE ${indexTableName(schema, index)} (
-      id   TEXT PRIMARY KEY,
-      doc  JSONB NOT NULL,
-      fts  tsvector NOT NULL DEFAULT ''::tsvector${typedColsDdl}
-    )
-  `)
-
-  await sql.unsafe(
-    `CREATE INDEX ${quoteIdent(`${bareIndexTable(index)}_fts_gin`)} ` +
-      `ON ${indexTableName(schema, index)} USING gin(fts) ` +
-      `WITH (fastupdate = ${ginFastUpdate ? 'on' : 'off'})`
-  )
-
-  for (const col of registry.typedColumns) {
-    await sql.unsafe(
-      `CREATE INDEX ${quoteIdent(`${bareIndexTable(index)}_${col.name}_idx`)} ` +
-        `ON ${indexTableName(schema, index)}(${quoteIdent(col.name)})`
-    )
-  }
-
-  // Belt-and-suspenders: if anyone INSERTs without computing fts, recompute it
-  // from doc using the current language + weight scheme. The driver always
-  // sets fts itself; the trigger only fires when the caller didn't.
-  await ensureFtsTrigger(sql, schema, index, registry)
-
-  await ensureTermsDict(sql, schema, index)
-
-  await sql.unsafe(
-    `INSERT INTO ${metaTableName(schema)} (index_name, key, value) VALUES ` +
-      `($1, 'schema_version', $2), ($1, 'language', $3), ($1, 'searchable', $4), ` +
-      `($1, 'filterable', $5), ($1, 'sortable', $6) ` +
-      `ON CONFLICT (index_name, key) DO NOTHING`,
-    [
-      index,
-      String(SCHEMA_VERSION),
-      registry.language,
-      JSON.stringify(registry.searchable),
-      JSON.stringify(registry.filterable),
-      JSON.stringify(registry.sortable),
-    ]
-  )
-
-  return true
-}
-
-export async function ensureTermsDict(sql: SQL, schema: string, index: string): Promise<void> {
-  const exists = await tableExists(sql, schema, bareTermsTable(index))
-  if (exists) return
-
-  await sql.unsafe(`
-    CREATE TABLE ${termsTableName(schema, index)} (
-      term     TEXT PRIMARY KEY,
-      doc_freq INTEGER NOT NULL DEFAULT 0
-    )
-  `)
-  await sql.unsafe(
-    `CREATE INDEX ${quoteIdent(`${bareTermsTable(index)}_trgm`)} ` +
-      `ON ${termsTableName(schema, index)} USING gin (term gin_trgm_ops)`
-  )
-  await sql.unsafe(
-    `CREATE INDEX ${quoteIdent(`${bareTermsTable(index)}_len`)} ` +
-      `ON ${termsTableName(schema, index)} (length(term))`
-  )
-}
-
-async function ensureFtsTrigger(
-  sql: SQL,
-  schema: string,
-  index: string,
-  registry: FieldRegistry
-): Promise<void> {
-  const fnName = `${bareIndexTable(index)}_fts_trigger`
-  const lang = quoteLiteral(registry.language)
-  const segments = registry.usesDefaultTextColumn
-    ? `setweight(to_tsvector(${lang}::regconfig, ${defaultTextProjection()}), 'A')`
-    : registry.searchable
-        .map(attr => {
-          const weight = registry.weights.get(attr)!
-          return `setweight(to_tsvector(${lang}::regconfig, coalesce(NEW.doc->>${quoteLiteral(attr)}, '')), '${weight}')`
-        })
-        .join(' || ')
-
-  await sql.unsafe(`
-    CREATE OR REPLACE FUNCTION ${quoteIdent(schema)}.${quoteIdent(fnName)}() RETURNS trigger AS $$
-    BEGIN
-      IF NEW.fts IS NULL OR NEW.fts = ''::tsvector THEN
-        NEW.fts := ${segments};
-      END IF;
-      RETURN NEW;
-    END;
-    $$ LANGUAGE plpgsql
-  `)
-
-  await sql.unsafe(`
-    CREATE TRIGGER ${quoteIdent(`${bareIndexTable(index)}_fts_trg`)}
-    BEFORE INSERT OR UPDATE ON ${indexTableName(schema, index)}
-    FOR EACH ROW EXECUTE FUNCTION ${quoteIdent(schema)}.${quoteIdent(fnName)}()
-  `)
-}
-
-function defaultTextProjection(): string {
-  // For default mode (no searchableAttributes) the trigger fallback walks
-  // every JSONB string value — same shape as the field_registry default.
-  return `(SELECT coalesce(string_agg(value, ' '), '') FROM jsonb_each_text(NEW.doc))`
-}
-
-async function tableExists(sql: SQL, schema: string, table: string): Promise<boolean> {
-  const rows = (await sql.unsafe(
-    `SELECT 1 AS present FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace ` +
-      `WHERE n.nspname = $1 AND c.relname = $2 AND c.relkind = 'r' LIMIT 1`,
-    [schema, table]
-  )) as Array<Record<string, unknown>>
-  return rows.length > 0
-}
-
-/** Drop a single index's tables and trigger function. Idempotent. */
-export async function dropIndex(sql: SQL, schema: string, index: string): Promise<void> {
-  await sql.unsafe(`DROP TABLE IF EXISTS ${indexTableName(schema, index)} CASCADE`)
-  await sql.unsafe(`DROP TABLE IF EXISTS ${termsTableName(schema, index)} CASCADE`)
-  await sql.unsafe(
-    `DROP FUNCTION IF EXISTS ${quoteIdent(schema)}.${quoteIdent(`${bareIndexTable(index)}_fts_trigger`)}() CASCADE`
-  )
-  await sql.unsafe(`DELETE FROM ${metaTableName(schema)} WHERE index_name = $1`, [index])
-}

package/src/drivers/postgres/engine/snippet_formatter.ts

@@ -1,31 +0,0 @@
-/**
- * `ts_headline` returns text with literal `<mark>` / `</mark>` markers around
- * matched terms. The surrounding text comes from the source document — which
- * may itself contain HTML the caller didn't escape. We HTML-escape the
- * snippet, then restore the marker tags, mirroring what the embedded driver
- * does with sentinel markers.
- */
-const OPEN_TAG = '<mark>'
-const CLOSE_TAG = '</mark>'
-const OPEN_PLACEHOLDER = '
STRAV_OPEN
'
-const CLOSE_PLACEHOLDER = '
STRAV_CLOSE
'
-
-export function formatSnippet(snippet: string | null | undefined): string {
-  if (!snippet) return ''
-  // Replace ts_headline's literal tags with sentinel control bytes that
-  // can't appear in source text, escape, then swap back.
-  const swapped = snippet
-    .replaceAll(OPEN_TAG, OPEN_PLACEHOLDER)
-    .replaceAll(CLOSE_TAG, CLOSE_PLACEHOLDER)
-  const escaped = escapeHtml(swapped)
-  return escaped.replaceAll(OPEN_PLACEHOLDER, OPEN_TAG).replaceAll(CLOSE_PLACEHOLDER, CLOSE_TAG)
-}
-
-function escapeHtml(input: string): string {
-  return input
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#39;')
-}

package/src/drivers/postgres/engine/typo_expander.ts

@@ -1,131 +0,0 @@
-import type { SQL } from 'bun'
-import { termsTableName } from '../storage/identifiers.ts'
-import type { ResolvedTypoTolerance } from '../types.ts'
-
-/** Tokeniser used for terms-dict maintenance. Mirrors embedded driver. */
-export function tokenize(text: string): string[] {
-  if (!text) return []
-  const tokens: string[] = []
-  for (const raw of text.toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
-    if (raw.length >= 2) tokens.push(raw)
-  }
-  return tokens
-}
-
-/** Increment per-document term frequencies (counting unique tokens per doc). */
-export async function recordTerms(
-  sql: SQL,
-  schema: string,
-  index: string,
-  text: string
-): Promise<void> {
-  const unique = Array.from(new Set(tokenize(text)))
-  if (unique.length === 0) return
-
-  const placeholders = unique.map((_, i) => `($${i + 1})`).join(', ')
-  await sql.unsafe(
-    `INSERT INTO ${termsTableName(schema, index)} (term) VALUES ${placeholders} ` +
-      `ON CONFLICT (term) DO UPDATE SET doc_freq = ${termsTableName(schema, index)}.doc_freq + 1`,
-    unique
-  )
-}
-
-/** Decrement; purge rows that drop to zero. */
-export async function unrecordTerms(
-  sql: SQL,
-  schema: string,
-  index: string,
-  text: string
-): Promise<void> {
-  const unique = Array.from(new Set(tokenize(text)))
-  if (unique.length === 0) return
-
-  const placeholders = unique.map((_, i) => `$${i + 1}`).join(', ')
-  await sql.unsafe(
-    `UPDATE ${termsTableName(schema, index)} SET doc_freq = doc_freq - 1 WHERE term IN (${placeholders})`,
-    unique
-  )
-  await sql.unsafe(`DELETE FROM ${termsTableName(schema, index)} WHERE doc_freq <= 0`)
-}
-
-/**
- * Look up Levenshtein-near terms via pg_trgm prefilter. When fuzzystrmatch is
- * available we re-rank with bounded Levenshtein for precision (trigram on
- * short tokens is statistically noisy).
- */
-export async function expandTokens(
-  sql: SQL,
-  schema: string,
-  index: string,
-  tokens: string[],
-  settings: ResolvedTypoTolerance,
-  hasFuzzystrmatch: boolean,
-  maxCandidates = 8
-): Promise<Map<string, string[]>> {
-  const out = new Map<string, string[]>()
-  if (!settings.enabled || tokens.length === 0) return out
-
-  for (const token of tokens) {
-    if (token.length < settings.minTokenLength) continue
-
-    // pg_trgm uses a per-session similarity threshold. We set it transactionally
-    // via the WHERE clause comparison instead, so caller's session isn't touched.
-    const rows = (await sql.unsafe(
-      hasFuzzystrmatch
-        ? `WITH cands AS (
-             SELECT term FROM ${termsTableName(schema, index)}
-             WHERE similarity(term, $1) >= $2 AND term <> $1
-             ORDER BY similarity(term, $1) DESC
-             LIMIT 32
-           )
-           SELECT term FROM cands
-           WHERE levenshtein(term, $1) <= $3
-           LIMIT $4`
-        : `SELECT term FROM ${termsTableName(schema, index)}
-             WHERE similarity(term, $1) >= $2 AND term <> $1
-             ORDER BY similarity(term, $1) DESC
-             LIMIT $3`,
-      hasFuzzystrmatch
-        ? [token, settings.similarity, settings.maxDistance, maxCandidates]
-        : [token, settings.similarity, maxCandidates]
-    )) as Array<{ term: string }>
-
-    if (rows.length > 0) out.set(token, rows.map(r => r.term))
-  }
-
-  return out
-}
-
-/** Resolve user-provided typo tolerance settings into concrete numbers. */
-export function resolveTypoTolerance(
-  setting:
-    | 'off'
-    | 'auto'
-    | { minTokenLength?: number; maxDistance?: number; similarity?: number }
-    | undefined
-): ResolvedTypoTolerance {
-  if (setting === 'off') {
-    return { enabled: false, minTokenLength: 4, maxDistance: 1, similarity: 0.4 }
-  }
-  if (setting === undefined || setting === 'auto') {
-    return { enabled: true, minTokenLength: 4, maxDistance: 1, similarity: 0.4 }
-  }
-  return {
-    enabled: true,
-    minTokenLength: setting.minTokenLength ?? 4,
-    maxDistance: setting.maxDistance ?? 1,
-    similarity: setting.similarity ?? 0.4,
-  }
-}
-
-/** Detect whether fuzzystrmatch.levenshtein is available. */
-export async function hasFuzzystrmatch(sql: SQL): Promise<boolean> {
-  try {
-    const rows = (await sql.unsafe(
-      `SELECT 1 FROM pg_proc WHERE proname = 'levenshtein' LIMIT 1`
-    )) as Array<Record<string, unknown>>
-    return rows.length > 0
-  } catch {
-    return false
-  }
-}

package/src/drivers/postgres/errors.ts

@@ -1,33 +0,0 @@
-import { SearchError } from '../../errors.ts'
-
-export class PostgresFtsError extends SearchError {}
-
-export class MissingExtensionError extends PostgresFtsError {
-  constructor(extension: string) {
-    super(
-      `Postgres extension "${extension}" is required by the postgres-fts driver. ` +
-        `Run \`CREATE EXTENSION ${extension}\` as a superuser, or set typoTolerance: 'off' if you can't.`
-    )
-  }
-}
-
-export class RebuildRequiredError extends PostgresFtsError {
-  constructor(message: string) {
-    super(message)
-  }
-}
-
-export class UnsupportedFilterError extends PostgresFtsError {
-  constructor(message: string) {
-    super(`Postgres-fts driver filter is unsupported: ${message}`)
-  }
-}
-
-export class MissingConnectionError extends PostgresFtsError {
-  constructor() {
-    super(
-      'PostgresFtsDriver has no Postgres connection. ' +
-        'Pass `connection` in the driver config, or bootstrap @strav/database first so Database.raw is available.'
-    )
-  }
-}

package/src/drivers/postgres/filters/filter_compiler.ts

@@ -1,138 +0,0 @@
-import { UnsupportedFilterError } from '../errors.ts'
-import { quoteIdent } from '../storage/identifiers.ts'
-
-export interface CompiledFilter {
-  /** SQL fragment to splice into a WHERE clause (no leading 'WHERE'). Empty if no filter. */
-  sql: string
-  /** Bound parameters in the order their `$N` placeholders appear. */
-  params: unknown[]
-  /** Number of params already used (caller offsets later placeholders). */
-  paramCount: number
-}
-
-const OPERATORS = new Set(['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'nin'])
-
-/**
- * Compile a filter object into a parameterized SQL WHERE fragment.
- * Mirrors the embedded driver's contract — same operator set, same shape.
- *
- * Placeholder numbering starts at `startAt + 1` ($N+1, $N+2, ...) so callers
- * can compose with their own bindings.
- */
-export function compileFilter(
-  filter: Record<string, unknown> | string | undefined,
-  filterableAttributes: ReadonlySet<string>,
-  startAt = 0
-): CompiledFilter {
-  if (!filter) return { sql: '', params: [], paramCount: 0 }
-
-  if (typeof filter === 'string') {
-    throw new UnsupportedFilterError(
-      'Raw string filters are not supported by the postgres-fts driver. ' +
-        'Pass an object like `{ status: "published" }` instead.'
-    )
-  }
-
-  const clauses: string[] = []
-  const params: unknown[] = []
-  let cursor = startAt
-
-  const ph = () => `$${++cursor}`
-
-  for (const [key, value] of Object.entries(filter)) {
-    if (value === undefined) continue
-    if (!filterableAttributes.has(key)) {
-      throw new UnsupportedFilterError(
-        `Field "${key}" is not in filterableAttributes. Add it to the index settings before filtering on it.`
-      )
-    }
-
-    const col = quoteIdent(key)
-
-    if (value === null) {
-      clauses.push(`${col} IS NULL`)
-      continue
-    }
-
-    if (Array.isArray(value)) {
-      if (value.length === 0) {
-        clauses.push('1 = 0')
-      } else {
-        const placeholders = value.map(() => ph()).join(', ')
-        clauses.push(`${col} IN (${placeholders})`)
-        params.push(...value.map(coerce))
-      }
-      continue
-    }
-
-    if (isOperatorObject(value)) {
-      for (const [op, opValue] of Object.entries(value)) {
-        const compiled = compileOperator(col, op, opValue, ph)
-        clauses.push(compiled.sql)
-        params.push(...compiled.params)
-      }
-      continue
-    }
-
-    if (isPrimitive(value)) {
-      clauses.push(`${col} = ${ph()}`)
-      params.push(coerce(value))
-      continue
-    }
-
-    throw new UnsupportedFilterError(
-      `Unsupported filter value for key "${key}": ${JSON.stringify(value)}`
-    )
-  }
-
-  return { sql: clauses.join(' AND '), params, paramCount: cursor - startAt }
-}
-
-function compileOperator(
-  col: string,
-  op: string,
-  value: unknown,
-  ph: () => string
-): { sql: string; params: unknown[] } {
-  switch (op) {
-    case 'eq':
-      return { sql: `${col} = ${ph()}`, params: [coerce(value)] }
-    case 'neq':
-      return { sql: `${col} <> ${ph()}`, params: [coerce(value)] }
-    case 'gt':
-      return { sql: `${col} > ${ph()}`, params: [coerce(value)] }
-    case 'gte':
-      return { sql: `${col} >= ${ph()}`, params: [coerce(value)] }
-    case 'lt':
-      return { sql: `${col} < ${ph()}`, params: [coerce(value)] }
-    case 'lte':
-      return { sql: `${col} <= ${ph()}`, params: [coerce(value)] }
-    case 'in': {
-      if (!Array.isArray(value) || value.length === 0) return { sql: '1 = 0', params: [] }
-      const placeholders = value.map(() => ph()).join(', ')
-      return { sql: `${col} IN (${placeholders})`, params: value.map(coerce) }
-    }
-    case 'nin': {
-      if (!Array.isArray(value) || value.length === 0) return { sql: '1 = 1', params: [] }
-      const placeholders = value.map(() => ph()).join(', ')
-      return { sql: `${col} NOT IN (${placeholders})`, params: value.map(coerce) }
-    }
-    default:
-      throw new UnsupportedFilterError(`Unknown operator "${op}"`)
-  }
-}
-
-function isOperatorObject(value: unknown): value is Record<string, unknown> {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false
-  return Object.keys(value).every(k => OPERATORS.has(k))
-}
-
-function isPrimitive(value: unknown): boolean {
-  return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
-}
-
-function coerce(value: unknown): unknown {
-  if (value === null || value === undefined) return null
-  if (typeof value === 'boolean') return value ? 1 : 0
-  return value
-}