@strav/search 0.4.31 → 1.0.0-alpha.31

package/src/drivers/postgres/index.ts

@@ -1,14 +0,0 @@
-export { PostgresFtsDriver } from './postgres_fts_driver.ts'
-export type {
-  PostgresFtsConfig,
-  TypoToleranceMode,
-  TypoToleranceSettings,
-  PgIndexSettings,
-} from './types.ts'
-export {
-  PostgresFtsError,
-  MissingExtensionError,
-  RebuildRequiredError,
-  UnsupportedFilterError,
-  MissingConnectionError,
-} from './errors.ts'

package/src/drivers/postgres/rebuild/rebuild_inplace.ts

@@ -1,113 +0,0 @@
-import type { SQL } from 'bun'
-import type { FieldRegistry } from '../engine/field_registry.ts'
-import { indexTableName, quoteLiteral, quoteIdent } from '../storage/identifiers.ts'
-import { RebuildRequiredError } from '../errors.ts'
-
-/** Tier boundaries for rebuild strategy selection. */
-const TIER1_MAX = 100_000
-const TIER2_MAX = 10_000_000
-
-/** Batch size for tier-2 batched UPDATE. */
-const BATCH_SIZE = 5_000
-
-export interface RebuildOptions {
-  /** If true, run REINDEX on the GIN index after the rebuild. Default true. */
-  reindex?: boolean
-  /** Per-batch sleep in milliseconds (tier 2 only). Default 50. */
-  pauseMs?: number
-  /** Optional progress callback fired after each batch. */
-  onProgress?: (done: number, total: number) => void
-}
-
-/**
- * Rebuild an index's `fts` column in place using the current registry's
- * language + weight scheme. Picks tier by row count:
- * - < 100k → single UPDATE
- * - 100k-10M → batched UPDATE with pauses
- * - > 10M → RebuildRequiredError (defer to v1.1 swap strategy)
- */
-export async function rebuildInPlace(
-  sql: SQL,
-  schema: string,
-  index: string,
-  registry: FieldRegistry,
-  options: RebuildOptions = {}
-): Promise<{ tier: 1 | 2; rows: number; elapsedMs: number }> {
-  const reindex = options.reindex ?? true
-  const pauseMs = options.pauseMs ?? 50
-  const table = indexTableName(schema, index)
-  const start = performance.now()
-
-  const countRows = (await sql.unsafe(
-    `SELECT COUNT(*)::bigint AS n FROM ${table}`
-  )) as Array<{ n: string | number }>
-  const total = Number(countRows[0]?.n ?? 0)
-
-  if (total > TIER2_MAX) {
-    throw new RebuildRequiredError(
-      `Index "${index}" has ${total} rows (>${TIER2_MAX}). ` +
-        `In-place / batched rebuild is unsafe at this scale. ` +
-        `Use the v1.1 dual-table swap strategy (not yet shipped).`
-    )
-  }
-
-  const ftsExpr = buildSetFtsExpression(registry)
-
-  if (total <= TIER1_MAX) {
-    await sql.unsafe(`UPDATE ${table} SET fts = ${ftsExpr}`)
-    if (reindex) await reindexGin(sql, schema, index)
-    return { tier: 1, rows: total, elapsedMs: Math.round(performance.now() - start) }
-  }
-
-  // Tier 2: batched update keyed by id, with pauses for autovacuum.
-  let cursor: string | null = null
-  let done = 0
-
-  while (true) {
-    const where = cursor === null ? '' : `WHERE id > $1`
-    const params = cursor === null ? [] : [cursor]
-    const batch = (await sql.unsafe(
-      `SELECT id FROM ${table} ${where} ORDER BY id LIMIT ${BATCH_SIZE}`,
-      params
-    )) as Array<{ id: string }>
-    if (batch.length === 0) break
-
-    const ids = batch.map(r => r.id)
-    const placeholders = ids.map((_, i) => `$${i + 1}`).join(', ')
-    await sql.unsafe(
-      `UPDATE ${table} SET fts = ${ftsExpr} WHERE id IN (${placeholders})`,
-      ids
-    )
-
-    done += batch.length
-    cursor = ids[ids.length - 1]!
-    options.onProgress?.(done, total)
-    if (pauseMs > 0) await new Promise(r => setTimeout(r, pauseMs))
-  }
-
-  if (reindex) await reindexGin(sql, schema, index)
-  return { tier: 2, rows: total, elapsedMs: Math.round(performance.now() - start) }
-}
-
-function buildSetFtsExpression(registry: FieldRegistry): string {
-  const lang = `${quoteLiteral(registry.language)}::regconfig`
-  if (registry.usesDefaultTextColumn) {
-    return (
-      `setweight(to_tsvector(${lang}, ` +
-      `(SELECT coalesce(string_agg(value, ' '), '') FROM jsonb_each_text(doc))), 'A')`
-    )
-  }
-  return registry.searchable
-    .map(attr => {
-      const weight = registry.weights.get(attr)!
-      return (
-        `setweight(to_tsvector(${lang}, coalesce(doc->>${quoteLiteral(attr)}, '')), '${weight}')`
-      )
-    })
-    .join(' || ')
-}
-
-async function reindexGin(sql: SQL, schema: string, index: string): Promise<void> {
-  const ginName = `${quoteIdent(schema)}.${quoteIdent(`search_${index}_fts_gin`)}`
-  await sql.unsafe(`REINDEX INDEX ${ginName}`)
-}

package/src/drivers/postgres/storage/identifiers.ts

@@ -1,46 +0,0 @@
-import { PostgresFtsError } from '../errors.ts'
-
-const PG_IDENT_MAX = 63
-
-/**
- * Quote a Postgres identifier (schema, table, column). Throws on identifiers
- * containing NUL or exceeding the 63-byte name limit.
- */
-export function quoteIdent(name: string): string {
-  if (name.includes('\0')) throw new PostgresFtsError(`Invalid identifier: contains NUL byte.`)
-  if (Buffer.byteLength(name, 'utf8') > PG_IDENT_MAX) {
-    throw new PostgresFtsError(
-      `Identifier "${name}" exceeds Postgres' ${PG_IDENT_MAX}-byte limit.`
-    )
-  }
-  return `"${name.replace(/"/g, '""')}"`
-}
-
-/** Quote a single-quoted SQL string literal (used inside DDL options). */
-export function quoteLiteral(value: string): string {
-  return `'${value.replace(/'/g, "''")}'`
-}
-
-/** Build the schema-qualified table name for a search index. */
-export function indexTableName(schema: string, index: string): string {
-  return `${quoteIdent(schema)}.${quoteIdent(`search_${index}`)}`
-}
-
-/** Terms-dictionary table name for a given index. */
-export function termsTableName(schema: string, index: string): string {
-  return `${quoteIdent(schema)}.${quoteIdent(`search_${index}_terms`)}`
-}
-
-/** Meta table — single shared table; rows keyed by (index_name, key). */
-export function metaTableName(schema: string): string {
-  return `${quoteIdent(schema)}.${quoteIdent('_meta')}`
-}
-
-/** Bare (unquoted) tablename — useful for pg_class lookups. */
-export function bareIndexTable(index: string): string {
-  return `search_${index}`
-}
-
-export function bareTermsTable(index: string): string {
-  return `search_${index}_terms`
-}

package/src/drivers/postgres/types.ts

@@ -1,53 +0,0 @@
-import type { SQL } from 'bun'
-import type { DriverConfig, IndexSettings } from '../../types.ts'
-
-export type TypoToleranceMode = 'off' | 'auto'
-
-export interface TypoToleranceSettings {
-  /** Minimum token length to consider for fuzzy expansion (default 4). */
-  minTokenLength?: number
-  /** Maximum Levenshtein distance to tolerate (default 1; 2 is supported but slower). */
-  maxDistance?: number
-  /** pg_trgm similarity threshold (default 0.4). Higher = stricter. */
-  similarity?: number
-}
-
-export interface PostgresFtsConfig extends DriverConfig {
-  driver: string
-  /**
-   * Bun SQL connection. If omitted, the driver falls back to
-   * `Database.raw` from `@strav/database` (must be bootstrapped first).
-   */
-  connection?: SQL
-  /** Postgres schema for index tables. Default 'strav_search'. */
-  schema?: string
-  /** Default text-search configuration ('english', 'french', ...). */
-  language?: string
-  /** Typo tolerance: 'off' disables; 'auto' uses defaults; object for fine-grained control. */
-  typoTolerance?: TypoToleranceMode | TypoToleranceSettings
-  /** GIN index tuning. */
-  gin?: {
-    /** Default false — better tail latency for read-heavy search. */
-    fastupdate?: boolean
-  }
-  /** Per-search-transaction work_mem hint, e.g. '64MB'. Set to null/empty to skip. */
-  workMem?: string | null
-}
-
-/** Resolved typo tolerance settings (after defaults applied). */
-export interface ResolvedTypoTolerance {
-  enabled: boolean
-  minTokenLength: number
-  maxDistance: number
-  similarity: number
-}
-
-/** Per-index extra settings stored in `_meta`. */
-export interface PgIndexSettings extends IndexSettings {
-  language?: string
-  /**
-   * Per-attribute weight tier override. Keys must appear in `searchableAttributes`.
-   * Values: 'A' | 'B' | 'C' | 'D'. Default = positional (1st=A, 2nd=B, ...).
-   */
-  weights?: Record<string, 'A' | 'B' | 'C' | 'D'>
-}

package/src/drivers/typesense_driver.ts

@@ -1,229 +0,0 @@
-import { ExternalServiceError } from '@strav/kernel'
-import type { SearchEngine } from '../search_engine.ts'
-import type {
-  SearchDocument,
-  SearchOptions,
-  SearchResult,
-  SearchHit,
-  IndexSettings,
-  DriverConfig,
-} from '../types.ts'
-
-/**
- * Typesense driver — communicates with the Typesense REST API via raw `fetch()`.
- *
- * @see https://typesense.org/docs/api/
- */
-export class TypesenseDriver implements SearchEngine {
-  readonly name = 'typesense'
-  private baseUrl: string
-  private apiKey: string
-
-  constructor(config: DriverConfig) {
-    const protocol = config.protocol ?? 'http'
-    const host = config.host ?? 'localhost'
-    const port = config.port ?? 8108
-    this.baseUrl = `${protocol}://${host}:${port}`
-    this.apiKey = (config.apiKey as string) ?? ''
-  }
-
-  // ── Interface ────────────────────────────────────────────────────────────
-
-  async upsert(
-    index: string,
-    id: string | number,
-    document: Record<string, unknown>
-  ): Promise<void> {
-    await this.request(
-      'POST',
-      `/collections/${encodeURIComponent(index)}/documents?action=upsert`,
-      { id: String(id), ...document }
-    )
-  }
-
-  async upsertMany(index: string, documents: SearchDocument[]): Promise<void> {
-    const jsonl = documents.map(doc => JSON.stringify({ ...doc, id: String(doc.id) })).join('\n')
-    await this.rawRequest(
-      'POST',
-      `/collections/${encodeURIComponent(index)}/documents/import?action=upsert`,
-      jsonl,
-      'text/plain'
-    )
-  }
-
-  async delete(index: string, id: string | number): Promise<void> {
-    await this.request(
-      'DELETE',
-      `/collections/${encodeURIComponent(index)}/documents/${encodeURIComponent(String(id))}`
-    )
-  }
-
-  async deleteMany(index: string, ids: Array<string | number>): Promise<void> {
-    const filter = `id:[${ids.map(id => String(id)).join(',')}]`
-    await this.request(
-      'DELETE',
-      `/collections/${encodeURIComponent(index)}/documents?filter_by=${encodeURIComponent(filter)}`
-    )
-  }
-
-  async flush(index: string): Promise<void> {
-    // Typesense has no "delete all documents" endpoint — delete the collection and recreate it.
-    // We fetch the current schema first so we can recreate it.
-    let schema: any
-    try {
-      schema = await this.request('GET', `/collections/${encodeURIComponent(index)}`)
-    } catch {
-      // Collection doesn't exist — nothing to flush
-      return
-    }
-    await this.request('DELETE', `/collections/${encodeURIComponent(index)}`)
-    await this.request('POST', '/collections', {
-      name: schema.name,
-      fields: schema.fields,
-    })
-  }
-
-  async deleteIndex(index: string): Promise<void> {
-    await this.request('DELETE', `/collections/${encodeURIComponent(index)}`)
-  }
-
-  async createIndex(index: string, options?: IndexSettings): Promise<void> {
-    const fields: Record<string, unknown>[] = []
-
-    if (options?.searchableAttributes) {
-      for (const attr of options.searchableAttributes) {
-        fields.push({ name: attr, type: 'string', facet: false })
-      }
-    }
-    if (options?.filterableAttributes) {
-      for (const attr of options.filterableAttributes) {
-        if (!fields.some(f => f.name === attr)) {
-          fields.push({ name: attr, type: 'string', facet: true })
-        }
-      }
-    }
-    if (options?.sortableAttributes) {
-      for (const attr of options.sortableAttributes) {
-        if (!fields.some(f => f.name === attr)) {
-          fields.push({ name: attr, type: 'string', sort: true })
-        }
-      }
-    }
-
-    // Always include a wildcard field so untyped fields are auto-detected
-    if (fields.length === 0) {
-      fields.push({ name: '.*', type: 'auto' })
-    }
-
-    await this.request('POST', '/collections', {
-      name: index,
-      fields,
-    })
-  }
-
-  async search(index: string, query: string, options?: SearchOptions): Promise<SearchResult> {
-    const perPage = options?.perPage ?? 20
-    const page = options?.page ?? 1
-
-    const params = new URLSearchParams({
-      q: query,
-      query_by: '*',
-      per_page: String(perPage),
-      page: String(page),
-    })
-
-    if (options?.filter) {
-      params.set(
-        'filter_by',
-        typeof options.filter === 'string' ? options.filter : this.buildFilter(options.filter)
-      )
-    }
-    if (options?.sort) {
-      params.set('sort_by', options.sort.map(s => s.replace(':', ':')).join(','))
-    }
-    if (options?.attributesToRetrieve) {
-      params.set('include_fields', options.attributesToRetrieve.join(','))
-    }
-    if (options?.attributesToHighlight) {
-      params.set('highlight_fields', options.attributesToHighlight.join(','))
-    }
-
-    const data = await this.request(
-      'GET',
-      `/collections/${encodeURIComponent(index)}/documents/search?${params.toString()}`
-    )
-
-    return {
-      hits: (data.hits ?? []).map(
-        (hit: any): SearchHit => ({
-          document: hit.document,
-          highlights: hit.highlights?.reduce(
-            (acc: Record<string, string>, h: any) => {
-              if (h.field && h.snippet) acc[h.field] = h.snippet
-              return acc
-            },
-            {} as Record<string, string>
-          ),
-        })
-      ),
-      totalHits: data.found ?? 0,
-      page,
-      perPage,
-      processingTimeMs: data.search_time_ms,
-    }
-  }
-
-  // ── Private ──────────────────────────────────────────────────────────────
-
-  private headers(): Record<string, string> {
-    return {
-      'content-type': 'application/json',
-      'x-typesense-api-key': this.apiKey,
-    }
-  }
-
-  private async request(method: string, path: string, body?: unknown): Promise<any> {
-    const response = await fetch(`${this.baseUrl}${path}`, {
-      method,
-      headers: this.headers(),
-      body: body !== undefined ? JSON.stringify(body) : undefined,
-    })
-
-    if (!response.ok) {
-      const text = await response.text()
-      throw new ExternalServiceError('Typesense', response.status, text)
-    }
-
-    if (response.status === 204 || response.headers.get('content-length') === '0') return null
-    return response.json()
-  }
-
-  private async rawRequest(
-    method: string,
-    path: string,
-    body: string,
-    contentType: string
-  ): Promise<void> {
-    const response = await fetch(`${this.baseUrl}${path}`, {
-      method,
-      headers: { 'content-type': contentType, 'x-typesense-api-key': this.apiKey },
-      body,
-    })
-
-    if (!response.ok) {
-      const text = await response.text()
-      throw new ExternalServiceError('Typesense', response.status, text)
-    }
-  }
-
-  private buildFilter(filter: Record<string, unknown>): string {
-    return Object.entries(filter)
-      .map(([key, value]) => {
-        if (Array.isArray(value)) {
-          return `${key}:[${value.map(v => String(v)).join(',')}]`
-        }
-        return `${key}:=${value}`
-      })
-      .join(' && ')
-  }
-}

package/src/errors.ts

@@ -1,18 +0,0 @@
-import { StravError } from '@strav/kernel'
-
-/** Base error class for all search errors. */
-export class SearchError extends StravError {}
-
-/** Thrown when a search index is not found. */
-export class IndexNotFoundError extends SearchError {
-  constructor(index: string) {
-    super(`Search index "${index}" not found.`)
-  }
-}
-
-/** Thrown when a search query fails. */
-export class SearchQueryError extends SearchError {
-  constructor(index: string, cause?: string) {
-    super(`Search query on "${index}" failed${cause ? `: ${cause}` : ''}.`)
-  }
-}

package/src/helpers.ts

@@ -1,120 +0,0 @@
-import SearchManager from './search_manager.ts'
-import type { SearchEngine } from './search_engine.ts'
-import type {
-  SearchDocument,
-  SearchOptions,
-  SearchResult,
-  IndexSettings,
-  DriverConfig,
-  SearchScope,
-} from './types.ts'
-
-/**
- * Search helper — the primary convenience API.
- *
- * @example
- * import { search } from '@strav/search'
- *
- * const results = await search.query('articles', 'typescript generics')
- * await search.upsert('articles', 1, { title: 'Guide', body: '...' })
- */
-export const search = {
-  /** Get the underlying engine instance (default or named). */
-  engine(name?: string): SearchEngine {
-    return SearchManager.engine(name)
-  },
-
-  /** Register a custom search driver factory. */
-  extend(name: string, factory: (config: DriverConfig) => SearchEngine): void {
-    SearchManager.extend(name, factory)
-  },
-
-  /** Perform a full-text search query. */
-  query(index: string, query: string, options?: SearchOptions): Promise<SearchResult> {
-    return SearchManager.engine().search(SearchManager.indexName(index), query, options)
-  },
-
-  /** Add or update a single document. */
-  upsert(index: string, id: string | number, document: Record<string, unknown>): Promise<void> {
-    return SearchManager.engine().upsert(SearchManager.indexName(index), id, document)
-  },
-
-  /** Add or update multiple documents. */
-  upsertMany(index: string, documents: SearchDocument[]): Promise<void> {
-    return SearchManager.engine().upsertMany(SearchManager.indexName(index), documents)
-  },
-
-  /** Remove a document from the index. */
-  delete(index: string, id: string | number): Promise<void> {
-    return SearchManager.engine().delete(SearchManager.indexName(index), id)
-  },
-
-  /** Remove multiple documents from the index. */
-  deleteMany(index: string, ids: Array<string | number>): Promise<void> {
-    return SearchManager.engine().deleteMany(SearchManager.indexName(index), ids)
-  },
-
-  /** Remove all documents from an index. */
-  flush(index: string): Promise<void> {
-    return SearchManager.engine().flush(SearchManager.indexName(index))
-  },
-
-  /** Create an index with optional settings. */
-  createIndex(index: string, options?: IndexSettings): Promise<void> {
-    return SearchManager.engine().createIndex(SearchManager.indexName(index), options)
-  },
-
-  /** Delete an entire index. */
-  deleteIndex(index: string): Promise<void> {
-    return SearchManager.engine().deleteIndex(SearchManager.indexName(index))
-  },
-
-  /**
-   * Return a tenant-scoped wrapper of this helper. All index names
-   * resolved through it are namespaced as `${prefix}t${tenantId}_${name}`,
-   * giving two tenants on the same shared engine independent indexes.
-   *
-   * @example
-   * await search.for({ tenantId: 42 }).upsert('articles', 1, { … })
-   * await search.for({ tenantId: 42 }).query('articles', 'lookup')
-   *
-   * Apps that don't need multi-tenant isolation skip `.for()` and call
-   * the top-level helpers directly.
-   */
-  for(scope: SearchScope): ScopedSearch {
-    return makeScoped(scope)
-  },
-}
-
-// ── Scoped helper ────────────────────────────────────────────────────────
-
-export interface ScopedSearch {
-  query(index: string, query: string, options?: SearchOptions): Promise<SearchResult>
-  upsert(index: string, id: string | number, document: Record<string, unknown>): Promise<void>
-  upsertMany(index: string, documents: SearchDocument[]): Promise<void>
-  delete(index: string, id: string | number): Promise<void>
-  deleteMany(index: string, ids: Array<string | number>): Promise<void>
-  flush(index: string): Promise<void>
-  createIndex(index: string, options?: IndexSettings): Promise<void>
-  deleteIndex(index: string): Promise<void>
-}
-
-function makeScoped(scope: SearchScope): ScopedSearch {
-  return {
-    query: (index, query, options) =>
-      SearchManager.engine().search(SearchManager.indexName(index, scope), query, options),
-    upsert: (index, id, document) =>
-      SearchManager.engine().upsert(SearchManager.indexName(index, scope), id, document),
-    upsertMany: (index, documents) =>
-      SearchManager.engine().upsertMany(SearchManager.indexName(index, scope), documents),
-    delete: (index, id) =>
-      SearchManager.engine().delete(SearchManager.indexName(index, scope), id),
-    deleteMany: (index, ids) =>
-      SearchManager.engine().deleteMany(SearchManager.indexName(index, scope), ids),
-    flush: index => SearchManager.engine().flush(SearchManager.indexName(index, scope)),
-    createIndex: (index, options) =>
-      SearchManager.engine().createIndex(SearchManager.indexName(index, scope), options),
-    deleteIndex: index =>
-      SearchManager.engine().deleteIndex(SearchManager.indexName(index, scope)),
-  }
-}

package/stubs/config/search.ts

@@ -1,57 +0,0 @@
-import { env } from '@strav/kernel'
-
-export default {
-  /** The default search driver to use. */
-  default: env('SEARCH_DRIVER', 'meilisearch'),
-
-  /** Index name prefix (useful for multi-tenant or multi-environment). */
-  prefix: env('SEARCH_PREFIX', ''),
-
-  drivers: {
-    meilisearch: {
-      driver: 'meilisearch',
-      host: env('MEILISEARCH_HOST', 'localhost'),
-      port: env('MEILISEARCH_PORT', '7700').int(),
-      apiKey: env('MEILISEARCH_KEY', ''),
-    },
-
-    typesense: {
-      driver: 'typesense',
-      host: env('TYPESENSE_HOST', 'localhost'),
-      port: env('TYPESENSE_PORT', '8108').int(),
-      apiKey: env('TYPESENSE_KEY', ''),
-      protocol: 'http',
-    },
-
-    algolia: {
-      driver: 'algolia',
-      appId: env('ALGOLIA_APP_ID', ''),
-      apiKey: env('ALGOLIA_SECRET', ''),
-    },
-
-    embedded: {
-      driver: 'embedded',
-      /** Directory holding per-index `.sqlite` files. Use ':memory:' for tests. */
-      path: env('SEARCH_PATH', './storage/search'),
-      /** SQLite synchronous pragma. NORMAL is crash-safe with sub-second-of-writes loss. */
-      synchronous: env('SEARCH_SYNCHRONOUS', 'NORMAL'),
-      /** Typo tolerance: 'off' to disable, 'auto' for defaults, or { minTokenLength, maxDistance }. */
-      typoTolerance: env('SEARCH_TYPO_TOLERANCE', 'auto'),
-    },
-
-    postgres: {
-      driver: 'postgres-fts',
-      /** Postgres schema for index tables. */
-      schema: env('SEARCH_PG_SCHEMA', 'strav_search'),
-      /** Default text-search configuration ('english', 'french', ...). */
-      language: env('SEARCH_PG_LANGUAGE', 'english'),
-      /** Typo tolerance: 'off' to disable, 'auto' for defaults, or { minTokenLength, maxDistance, similarity }. */
-      typoTolerance: env('SEARCH_TYPO_TOLERANCE', 'auto'),
-      /** Per-search work_mem hint. Set to null/empty to skip. */
-      workMem: env('SEARCH_PG_WORK_MEM', '64MB'),
-      /** GIN index tuning — fastupdate=off improves read tail latency. */
-      gin: { fastupdate: false },
-      // `connection` (Bun SQL instance) is resolved from @strav/database at runtime.
-    },
-  },
-}

package/tsconfig.json

@@ -1,5 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "include": ["src/**/*.ts"],
-  "exclude": ["node_modules", "tests"]
-}