@strav/search 0.4.31 → 1.0.0-alpha.31

package/src/drivers/typesense/typesense_driver.ts

@@ -0,0 +1,345 @@
+/**
+ * `TypesenseDriver` — REST client for [Typesense](https://typesense.org).
+ *
+ * Speaks the v0.x HTTP API via raw `fetch()` — no `typesense-js`
+ * SDK dependency. Typesense indexes are called "collections"
+ * upstream; we translate `index` → collection at the boundary so
+ * the `SearchEngine` contract stays uniform across drivers.
+ *
+ * Notable Typesense quirks the driver papers over:
+ *
+ *   - **Document IDs are strings.** We coerce numeric ids to
+ *     strings on write + leave them as strings on read.
+ *   - **Schema is required.** Typesense rejects upserts against
+ *     unknown collections; `createIndex(name, settings)` builds a
+ *     schema from `IndexSettings`. When settings are omitted we
+ *     fall back to an auto-schema (`fields: [{ name: '.*', type: 'auto' }]`).
+ *   - **No "delete all documents" endpoint.** `flush()` drops the
+ *     collection and recreates it with the original schema.
+ *   - **No async tasks.** Writes return synchronously, so reads
+ *     after writes are immediately consistent.
+ *
+ * Config (under `config.search.drivers.<name>`):
+ *
+ * ```ts
+ * typesense: {
+ *   driver: 'typesense',
+ *   host: 'http://localhost:8108',  // or split host/port/protocol
+ *   apiKey: env('TYPESENSE_KEY'),
+ * }
+ * ```
+ *
+ * Error mapping:
+ *
+ *   - `404` on writes / reads → `IndexNotFoundError`.
+ *   - All other non-2xx → `SearchQueryError` with the Typesense
+ *     payload on `cause`.
+ *
+ * @see https://typesense.org/docs/0.25.2/api/
+ */
+
+import { IndexNotFoundError, SearchQueryError } from '../../search_error.ts'
+import type { SearchEngine } from '../../search_engine.ts'
+import type {
+  DriverConfig,
+  IndexSettings,
+  SearchDocument,
+  SearchHit,
+  SearchOptions,
+  SearchResult,
+} from '../../types.ts'
+
+interface CollectionSchema {
+  name: string
+  fields: Array<Record<string, unknown>>
+  default_sorting_field?: string
+}
+
+export class TypesenseDriver implements SearchEngine {
+  readonly name = 'typesense'
+
+  private readonly baseUrl: string
+  private readonly apiKey: string
+  private readonly defaultQueryBy: string
+
+  constructor(config: DriverConfig) {
+    this.baseUrl = resolveBaseUrl(config)
+    this.apiKey = typeof config.apiKey === 'string' ? config.apiKey : ''
+    // Typesense ≥ 0.24 accepts `*` to query every string field;
+    // apps that want to scope can set `queryBy: 'title,body'`.
+    this.defaultQueryBy = typeof config.queryBy === 'string' ? config.queryBy : '*'
+  }
+
+  // ─── Index lifecycle ────────────────────────────────────────────────────
+
+  async createIndex(index: string, settings: IndexSettings = {}): Promise<void> {
+    // Idempotent — swallow the 409 Typesense returns for "already exists".
+    await this.request<CollectionSchema>('POST', '/collections', {
+      body: schemaFromSettings(index, settings),
+      acceptStatuses: [409],
+    })
+  }
+
+  async deleteIndex(index: string): Promise<void> {
+    await this.request('DELETE', `/collections/${encodeURIComponent(index)}`, {
+      acceptStatuses: [404],
+    })
+  }
+
+  async flush(index: string): Promise<void> {
+    // Typesense has no "delete all documents" endpoint; we drop +
+    // recreate using the live schema so the index identity stays
+    // stable for callers.
+    let schema: CollectionSchema | null
+    try {
+      schema = await this.request<CollectionSchema>(
+        'GET',
+        `/collections/${encodeURIComponent(index)}`,
+      )
+    } catch (err) {
+      if (err instanceof IndexNotFoundError) return
+      throw err
+    }
+    if (!schema) return
+    await this.request('DELETE', `/collections/${encodeURIComponent(index)}`)
+    await this.request('POST', '/collections', {
+      body: {
+        name: schema.name,
+        fields: schema.fields,
+        ...(schema.default_sorting_field
+          ? { default_sorting_field: schema.default_sorting_field }
+          : {}),
+      },
+    })
+  }
+
+  // ─── Writes ─────────────────────────────────────────────────────────────
+
+  async upsert(
+    index: string,
+    id: string | number,
+    document: Record<string, unknown>,
+  ): Promise<void> {
+    await this.request(
+      'POST',
+      `/collections/${encodeURIComponent(index)}/documents?action=upsert`,
+      { body: { ...document, id: String(id) } },
+    )
+  }
+
+  async upsertMany(index: string, documents: readonly SearchDocument[]): Promise<void> {
+    if (documents.length === 0) return
+    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))}`,
+      { acceptStatuses: [404] },
+    )
+  }
+
+  async deleteMany(index: string, ids: readonly (string | number)[]): Promise<void> {
+    if (ids.length === 0) return
+    const filter = `id:[${ids.map((id) => String(id)).join(',')}]`
+    await this.request(
+      'DELETE',
+      `/collections/${encodeURIComponent(index)}/documents?filter_by=${encodeURIComponent(filter)}`,
+      { acceptStatuses: [404] },
+    )
+  }
+
+  // ─── Reads ──────────────────────────────────────────────────────────────
+
+  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.length === 0 ? '*' : query,
+      query_by: this.defaultQueryBy,
+      per_page: String(perPage),
+      page: String(page),
+    })
+
+    if (options.filter !== undefined) {
+      if (typeof options.filter !== 'object' || options.filter === null || Array.isArray(options.filter)) {
+        throw new SearchQueryError(
+          'TypesenseDriver: `filter` must be a flat key/value object. Engine-native strings are not portable.',
+        )
+      }
+      params.set('filter_by', buildTypesenseFilter(options.filter))
+    }
+    if (options.sort) params.set('sort_by', options.sort.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<{
+      hits?: Array<{
+        document: Record<string, unknown>
+        highlights?: Array<{ field?: string; snippet?: string }>
+      }>
+      found?: number
+      search_time_ms?: number
+    }>(
+      'GET',
+      `/collections/${encodeURIComponent(index)}/documents/search?${params.toString()}`,
+    )
+
+    const hits: SearchHit[] = (data?.hits ?? []).map((hit) => {
+      const out: SearchHit = { document: hit.document }
+      if (hit.highlights && hit.highlights.length > 0) {
+        const highlights: Record<string, string> = {}
+        for (const h of hit.highlights) {
+          if (h.field && h.snippet) highlights[h.field] = h.snippet
+        }
+        if (Object.keys(highlights).length > 0) out.highlights = highlights
+      }
+      return out
+    })
+
+    return {
+      hits,
+      totalHits: data?.found ?? 0,
+      page,
+      perPage,
+      ...(typeof data?.search_time_ms === 'number'
+        ? { processingTimeMs: data.search_time_ms }
+        : {}),
+    }
+  }
+
+  // ─── HTTP ──────────────────────────────────────────────────────────────
+
+  private async request<T = unknown>(
+    method: string,
+    path: string,
+    options: { body?: unknown; acceptStatuses?: number[] } = {},
+  ): Promise<T | null> {
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: this.jsonHeaders(),
+      body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+    })
+    return this.readResponse<T>(response, method, path, options.acceptStatuses)
+  }
+
+  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,
+    })
+    await this.readResponse(response, method, path)
+  }
+
+  private async readResponse<T>(
+    response: Response,
+    method: string,
+    path: string,
+    acceptStatuses: number[] = [],
+  ): Promise<T | null> {
+    if (response.ok || acceptStatuses.includes(response.status)) {
+      if (response.status === 204 || response.headers.get('content-length') === '0') return null
+      const text = await response.text()
+      return text.length === 0 ? null : (JSON.parse(text) as T)
+    }
+
+    const text = await response.text()
+    const payload = safeJson(text)
+    if (response.status === 404) {
+      const index = extractIndexName(path)
+      throw new IndexNotFoundError(index ?? '<unknown>', this.name)
+    }
+    throw new SearchQueryError(
+      `TypesenseDriver: ${method} ${path} returned ${response.status}.`,
+      { context: { status: response.status, body: payload ?? text }, cause: payload ?? text },
+    )
+  }
+
+  private jsonHeaders(): Record<string, string> {
+    return {
+      'content-type': 'application/json',
+      'x-typesense-api-key': this.apiKey,
+    }
+  }
+}
+
+function resolveBaseUrl(config: DriverConfig): string {
+  const host = typeof config.host === 'string' ? config.host : 'localhost'
+  if (host.startsWith('http://') || host.startsWith('https://')) {
+    return host.replace(/\/+$/, '')
+  }
+  const protocol = typeof config.protocol === 'string' ? config.protocol : 'http'
+  const port = typeof config.port === 'number' ? config.port : 8108
+  return `${protocol}://${host}:${port}`
+}
+
+function schemaFromSettings(index: string, settings: IndexSettings): CollectionSchema {
+  const fields: Array<Record<string, unknown>> = []
+  const seen = new Set<string>()
+  const push = (field: Record<string, unknown>) => {
+    const name = field.name as string
+    if (seen.has(name)) return
+    seen.add(name)
+    fields.push(field)
+  }
+
+  for (const attr of settings.searchableAttributes ?? []) {
+    push({ name: attr, type: 'string' })
+  }
+  for (const attr of settings.filterableAttributes ?? []) {
+    push({ name: attr, type: 'string', facet: true })
+  }
+  for (const attr of settings.sortableAttributes ?? []) {
+    push({ name: attr, type: 'string', sort: true })
+  }
+  if (fields.length === 0) {
+    push({ name: '.*', type: 'auto' })
+  }
+
+  return { name: index, fields }
+}
+
+function buildTypesenseFilter(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}:=${JSON.stringify(value)}`
+    })
+    .join(' && ')
+}
+
+function extractIndexName(path: string): string | undefined {
+  const match = /\/collections\/([^/?]+)/.exec(path)
+  return match ? decodeURIComponent(match[1]!) : undefined
+}
+
+function safeJson(text: string): unknown {
+  if (text.length === 0) return undefined
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}

package/src/index.ts

@@ -1,48 +1,59 @@
-// Manager
-export { default, default as SearchManager } from './search_manager.ts'
+// Public API of `@strav/search`.
+//
+// Slice A (current):
+//   - SearchEngine interface + portable types.
+//   - SearchManager + SearchProvider service wiring.
+//   - MemoryDriver (in-process BM25 engine for tests / dev).
+//   - `searchable()` Repository mixin + SearchableRegistry.
+//
+// Subsequent slices add Meilisearch, Typesense, and Postgres FTS
+// drivers, plus the `search:import` / `search:flush` /
+// `search:reindex` console commands.
 
-// Provider
-export { default as SearchProvider } from './search_provider.ts'
-
-// Engine interface
+export {
+  SearchConsoleProvider,
+  SearchFlush,
+  SearchImport,
+  SearchList,
+  SearchReindex,
+} from './console/index.ts'
+export { MeilisearchDriver } from './drivers/meilisearch/meilisearch_driver.ts'
+export { MemoryDriver } from './drivers/memory/memory_driver.ts'
+export {
+  type ApplySearchMigrationOptions,
+  applySearchMigration,
+  DEFAULT_SEARCH_SCHEMA,
+} from './drivers/postgres/apply_search_migration.ts'
+export {
+  PostgresFtsDriver,
+  type PostgresFtsDriverOptions,
+} from './drivers/postgres/postgres_fts_driver.ts'
+export { TypesenseDriver } from './drivers/typesense/typesense_driver.ts'
 export type { SearchEngine } from './search_engine.ts'
-
-// Drivers
-export { MeilisearchDriver } from './drivers/meilisearch_driver.ts'
-export { TypesenseDriver } from './drivers/typesense_driver.ts'
-export { AlgoliaDriver } from './drivers/algolia_driver.ts'
-export { NullDriver } from './drivers/null_driver.ts'
-export { EmbeddedDriver } from './drivers/embedded/index.ts'
-export type {
-  EmbeddedConfig,
-  TypoToleranceMode,
-  TypoToleranceSettings,
-} from './drivers/embedded/index.ts'
-export { PostgresFtsDriver } from './drivers/postgres/index.ts'
-export type {
-  PostgresFtsConfig,
-  PgIndexSettings,
-} from './drivers/postgres/index.ts'
-
-// Mixin
+export {
+  IndexNotFoundError,
+  SearchConfigError,
+  SearchError,
+  SearchQueryError,
+} from './search_error.ts'
+export {
+  type EngineFactory,
+  SearchManager,
+  type SearchManagerOptions,
+  type SearchManagerResolver,
+} from './search_manager.ts'
+export { SearchProvider } from './search_provider.ts'
 export { searchable } from './searchable.ts'
-export type { SearchableInstance, SearchableModel } from './searchable.ts'
-
-// Helper
-export { search } from './helpers.ts'
-export type { ScopedSearch } from './helpers.ts'
-
-// Errors
-export { SearchError, IndexNotFoundError, SearchQueryError } from './errors.ts'
-
-// Types
+export {
+  SearchableRegistry,
+  type SearchableTarget,
+} from './searchable_registry.ts'
 export type {
-  SearchConfig,
   DriverConfig,
+  IndexSettings,
+  SearchConfig,
   SearchDocument,
+  SearchHit,
   SearchOptions,
   SearchResult,
-  SearchHit,
-  IndexSettings,
-  SearchScope,
 } from './types.ts'

package/src/search_engine.ts

@@ -1,36 +1,51 @@
-import type { SearchDocument, SearchOptions, SearchResult, IndexSettings } from './types.ts'
-
 /**
- * Contract that every search engine driver must implement.
+ * `SearchEngine` — the storage abstraction every search driver
+ * (`MemoryDriver`, `MeilisearchDriver`, `TypesenseDriver`,
+ * `PostgresFtsDriver`, custom drivers registered via
+ * `manager.extend(...)`) implements.
+ *
+ * Index lifecycle:
+ *
+ *   - `createIndex(name, settings?)` — idempotent. For
+ *     `MemoryDriver` this allocates the bucket; for
+ *     `MeilisearchDriver` / `TypesenseDriver` it creates the
+ *     remote index; for `PostgresFtsDriver` it provisions the
+ *     per-index table + GIN index.
+ *   - `deleteIndex(name)` — drops the index entirely.
+ *   - `flush(name)` — drops every document but keeps the index
+ *     itself. Faster than `deleteIndex` for "wipe + reimport".
+ *
+ * Writes:
+ *
+ *   - `upsert(index, id, doc)` / `upsertMany(index, docs)` —
+ *     insert or replace. Drivers MAY batch internally; callers
+ *     don't need to chunk for portability.
+ *   - `delete(index, id)` / `deleteMany(index, ids)` — remove.
  *
- * Drivers communicate with an external search service (Meilisearch,
- * Typesense, Algolia, etc.) via their REST API.
+ * Reads:
+ *
+ *   - `search(index, query, options?)` — full-text search. The
+ *     `SearchOptions` shape is portable across drivers; engines
+ *     ignore options they don't support rather than throwing.
  */
-export interface SearchEngine {
-  /** Driver name (e.g. 'meilisearch', 'typesense', 'algolia'). */
-  readonly name: string
-
-  /** Add or update a single document. */
-  upsert(index: string, id: string | number, document: Record<string, unknown>): Promise<void>
 
-  /** Add or update multiple documents at once. */
-  upsertMany(index: string, documents: SearchDocument[]): Promise<void>
+import type { IndexSettings, SearchDocument, SearchOptions, SearchResult } from './types.ts'
 
-  /** Remove a single document by ID. */
-  delete(index: string, id: string | number): Promise<void>
-
-  /** Remove multiple documents by ID. */
-  deleteMany(index: string, ids: Array<string | number>): Promise<void>
-
-  /** Remove all documents from an index (keep the index itself). */
-  flush(index: string): Promise<void>
+export interface SearchEngine {
+  /** Driver identifier — `'memory'`, `'meilisearch'`, `'typesense'`, `'postgres-fts'`, or the name passed to `manager.extend`. */
+  readonly name: string
 
-  /** Delete the entire index. */
+  // ─── Index lifecycle ───────────────────────────────────────────────────
+  createIndex(index: string, settings?: IndexSettings): Promise<void>
   deleteIndex(index: string): Promise<void>
+  flush(index: string): Promise<void>
 
-  /** Create an index with optional settings. */
-  createIndex(index: string, options?: IndexSettings): Promise<void>
+  // ─── Writes ────────────────────────────────────────────────────────────
+  upsert(index: string, id: string | number, document: Record<string, unknown>): Promise<void>
+  upsertMany(index: string, documents: readonly SearchDocument[]): Promise<void>
+  delete(index: string, id: string | number): Promise<void>
+  deleteMany(index: string, ids: readonly (string | number)[]): Promise<void>
 
-  /** Perform a full-text search. */
+  // ─── Reads ─────────────────────────────────────────────────────────────
   search(index: string, query: string, options?: SearchOptions): Promise<SearchResult>
 }

package/src/search_error.ts

@@ -0,0 +1,86 @@
+/**
+ * `SearchError` hierarchy — typed wrappers for failures in the
+ * search stack. Apps branch on the concrete subclass at the
+ * call site instead of parsing error messages.
+ *
+ * Three concrete subclasses ship in V1:
+ *
+ *   - `IndexNotFoundError` — a query / mutation referenced an
+ *     index that doesn't exist on the active engine. Apps create
+ *     the index via `manager.engine().createIndex(name, …)` (or
+ *     via the mixin's `Repository.createIndex()`) before the
+ *     first upsert.
+ *
+ *   - `SearchQueryError` — the underlying engine rejected the
+ *     query (bad filter shape, unknown attribute, malformed
+ *     sort directive, etc.). Cause carries the driver-native
+ *     error.
+ *
+ *   - `SearchConfigError` — surfaced from the manager when the
+ *     requested driver isn't configured or a custom factory
+ *     wasn't registered.
+ */
+
+import { StravError } from '@strav/kernel'
+
+export class SearchError extends StravError {
+  constructor(
+    message: string,
+    options: {
+      code?: string
+      status?: number
+      context?: Record<string, unknown>
+      cause?: unknown
+    } = {},
+  ) {
+    super(
+      message,
+      { code: options.code ?? 'search.error', status: options.status ?? 500 },
+      {
+        ...(options.context ? { context: options.context } : {}),
+        ...(options.cause !== undefined ? { cause: options.cause } : {}),
+      },
+    )
+  }
+}
+
+export class IndexNotFoundError extends SearchError {
+  constructor(index: string, engine: string) {
+    super(
+      `Search index "${index}" does not exist on engine "${engine}". Call \`engine.createIndex("${index}", …)\` before the first upsert.`,
+      {
+        code: 'search.index_not_found',
+        status: 404,
+        context: { index, engine },
+      },
+    )
+  }
+}
+
+export class SearchQueryError extends SearchError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
+    super(message, {
+      code: 'search.query',
+      status: 400,
+      ...(options.context ? { context: options.context } : {}),
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+  }
+}
+
+export class SearchConfigError extends SearchError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
+    super(message, {
+      code: 'search.config',
+      status: 500,
+      ...(options.context ? { context: options.context } : {}),
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+  }
+}