@strav/search 0.1.0

package/src/drivers/typesense_driver.ts

@@ -0,0 +1,229 @@
+import { ExternalServiceError } from '@stravigor/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

@@ -0,0 +1,18 @@
+import { StravError } from '@stravigor/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

@@ -0,0 +1,70 @@
+import SearchManager from './search_manager.ts'
+import type { SearchEngine } from './search_engine.ts'
+import type {
+  SearchDocument,
+  SearchOptions,
+  SearchResult,
+  IndexSettings,
+  DriverConfig,
+} from './types.ts'
+
+/**
+ * Search helper — the primary convenience API.
+ *
+ * @example
+ * import { search } from '@stravigor/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))
+  },
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+// Manager
+export { default, default as SearchManager } from './search_manager.ts'
+
+// Provider
+export { default as SearchProvider } from './search_provider.ts'
+
+// Engine interface
+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'
+
+// Mixin
+export { searchable } from './searchable.ts'
+export type { SearchableInstance, SearchableModel } from './searchable.ts'
+
+// Helper
+export { search } from './helpers.ts'
+
+// Errors
+export { SearchError, IndexNotFoundError, SearchQueryError } from './errors.ts'
+
+// Types
+export type {
+  SearchConfig,
+  DriverConfig,
+  SearchDocument,
+  SearchOptions,
+  SearchResult,
+  SearchHit,
+  IndexSettings,
+} from './types.ts'

package/src/search_engine.ts

@@ -0,0 +1,36 @@
+import type { SearchDocument, SearchOptions, SearchResult, IndexSettings } from './types.ts'
+
+/**
+ * Contract that every search engine driver must implement.
+ *
+ * Drivers communicate with an external search service (Meilisearch,
+ * Typesense, Algolia, etc.) via their REST API.
+ */
+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>
+
+  /** 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>
+
+  /** Delete the entire index. */
+  deleteIndex(index: string): Promise<void>
+
+  /** Create an index with optional settings. */
+  createIndex(index: string, options?: IndexSettings): Promise<void>
+
+  /** Perform a full-text search. */
+  search(index: string, query: string, options?: SearchOptions): Promise<SearchResult>
+}

package/src/search_manager.ts

@@ -0,0 +1,97 @@
+import { inject, Configuration, ConfigurationError } from '@stravigor/kernel'
+import type { SearchEngine } from './search_engine.ts'
+import type { SearchConfig, DriverConfig } from './types.ts'
+import { MeilisearchDriver } from './drivers/meilisearch_driver.ts'
+import { TypesenseDriver } from './drivers/typesense_driver.ts'
+import { AlgoliaDriver } from './drivers/algolia_driver.ts'
+import { NullDriver } from './drivers/null_driver.ts'
+
+@inject
+export default class SearchManager {
+  private static _config: SearchConfig
+  private static _engines = new Map<string, SearchEngine>()
+  private static _extensions = new Map<string, (config: DriverConfig) => SearchEngine>()
+
+  constructor(config: Configuration) {
+    SearchManager._config = {
+      default: config.get('search.default', 'null') as string,
+      prefix: config.get('search.prefix', '') as string,
+      drivers: config.get('search.drivers', {}) as Record<string, DriverConfig>,
+    }
+  }
+
+  static get config(): SearchConfig {
+    if (!SearchManager._config) {
+      throw new ConfigurationError(
+        'SearchManager not configured. Resolve it through the container first.'
+      )
+    }
+    return SearchManager._config
+  }
+
+  /** Get an engine by name, or the default engine. Engines are lazily created. */
+  static engine(name?: string): SearchEngine {
+    const key = name ?? SearchManager.config.default
+
+    let engine = SearchManager._engines.get(key)
+    if (engine) return engine
+
+    const driverConfig = SearchManager.config.drivers[key]
+    if (!driverConfig) {
+      throw new ConfigurationError(`Search driver "${key}" is not configured.`)
+    }
+
+    engine = SearchManager.createEngine(key, driverConfig)
+    SearchManager._engines.set(key, engine)
+    return engine
+  }
+
+  /** The index name prefix from configuration. */
+  static get prefix(): string {
+    return SearchManager._config?.prefix ?? ''
+  }
+
+  /** Resolve a full index name by applying the configured prefix. */
+  static indexName(name: string): string {
+    return SearchManager.prefix ? `${SearchManager.prefix}${name}` : name
+  }
+
+  /** Register a custom driver factory. */
+  static extend(name: string, factory: (config: DriverConfig) => SearchEngine): void {
+    SearchManager._extensions.set(name, factory)
+  }
+
+  /** Replace an engine at runtime (e.g. for testing). */
+  static useEngine(engine: SearchEngine): void {
+    SearchManager._engines.set(engine.name, engine)
+  }
+
+  /** Reset all state. Intended for test teardown. */
+  static reset(): void {
+    SearchManager._engines.clear()
+    SearchManager._extensions.clear()
+    SearchManager._config = undefined as any
+  }
+
+  private static createEngine(name: string, config: DriverConfig): SearchEngine {
+    const driverName = config.driver ?? name
+
+    const extension = SearchManager._extensions.get(driverName)
+    if (extension) return extension(config)
+
+    switch (driverName) {
+      case 'meilisearch':
+        return new MeilisearchDriver(config)
+      case 'typesense':
+        return new TypesenseDriver(config)
+      case 'algolia':
+        return new AlgoliaDriver(config)
+      case 'null':
+        return new NullDriver()
+      default:
+        throw new ConfigurationError(
+          `Unknown search driver "${driverName}". Register it with SearchManager.extend().`
+        )
+    }
+  }
+}

package/src/search_provider.ts

@@ -0,0 +1,16 @@
+import { ServiceProvider } from '@stravigor/kernel'
+import type { Application } from '@stravigor/kernel'
+import SearchManager from './search_manager.ts'
+
+export default class SearchProvider extends ServiceProvider {
+  readonly name = 'search'
+  override readonly dependencies = ['config']
+
+  override register(app: Application): void {
+    app.singleton(SearchManager)
+  }
+
+  override boot(app: Application): void {
+    app.resolve(SearchManager)
+  }
+}