@stravigor/search 0.1.0

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@stravigor/search",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Full-text search for the Strav framework",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "strav": {
+    "commands": "src/commands"
+  },
+  "files": ["src/", "stubs/", "package.json", "tsconfig.json"],
+  "peerDependencies": {
+    "@stravigor/core": "0.2.5"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/commands/search_flush.ts

@@ -0,0 +1,41 @@
+import type { Command } from 'commander'
+import chalk from 'chalk'
+import { bootstrap, shutdown } from '@stravigor/core/cli/bootstrap'
+import BaseModel from '@stravigor/core/orm/base_model'
+import SearchManager from '../search_manager.ts'
+
+export function register(program: Command): void {
+  program
+    .command('search:flush <model>')
+    .description("Flush all documents from a model's search index")
+    .action(async (modelPath: string) => {
+      let db
+      try {
+        const { db: database, config } = await bootstrap()
+        db = database
+
+        new BaseModel(db)
+        new SearchManager(config)
+
+        const resolved = require.resolve(`${process.cwd()}/${modelPath}`)
+        const module = await import(resolved)
+        const ModelClass = module.default ?? (Object.values(module)[0] as any)
+
+        if (typeof ModelClass?.flushIndex !== 'function') {
+          console.error(chalk.red(`Model "${modelPath}" does not use the searchable() mixin.`))
+          process.exit(1)
+        }
+
+        const indexName = ModelClass.searchableAs()
+        console.log(chalk.dim(`Flushing "${indexName}"...`))
+
+        await ModelClass.flushIndex()
+        console.log(chalk.green(`Flushed all documents from "${indexName}".`))
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      } finally {
+        if (db) await shutdown(db)
+      }
+    })
+}

package/src/commands/search_import.ts

@@ -0,0 +1,43 @@
+import type { Command } from 'commander'
+import chalk from 'chalk'
+import { bootstrap, shutdown } from '@stravigor/core/cli/bootstrap'
+import BaseModel from '@stravigor/core/orm/base_model'
+import SearchManager from '../search_manager.ts'
+
+export function register(program: Command): void {
+  program
+    .command('search:import <model>')
+    .description('Import all records for a model into the search index')
+    .option('--chunk <size>', 'Records per batch', '500')
+    .action(async (modelPath: string, options) => {
+      let db
+      try {
+        const { db: database, config } = await bootstrap()
+        db = database
+
+        new BaseModel(db)
+        new SearchManager(config)
+
+        const resolved = require.resolve(`${process.cwd()}/${modelPath}`)
+        const module = await import(resolved)
+        const ModelClass = module.default ?? (Object.values(module)[0] as any)
+
+        if (typeof ModelClass?.importAll !== 'function') {
+          console.error(chalk.red(`Model "${modelPath}" does not use the searchable() mixin.`))
+          process.exit(1)
+        }
+
+        const chunkSize = parseInt(options.chunk, 10)
+        const indexName = ModelClass.searchableAs()
+        console.log(chalk.dim(`Importing ${ModelClass.name} into "${indexName}"...`))
+
+        const count = await ModelClass.importAll(chunkSize)
+        console.log(chalk.green(`Imported ${count} record(s) into "${indexName}".`))
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      } finally {
+        if (db) await shutdown(db)
+      }
+    })
+}

package/src/drivers/algolia_driver.ts

@@ -0,0 +1,170 @@
+import { ExternalServiceError } from '@stravigor/core/exceptions/errors'
+import type { SearchEngine } from '../search_engine.ts'
+import type {
+  SearchDocument,
+  SearchOptions,
+  SearchResult,
+  SearchHit,
+  IndexSettings,
+  DriverConfig,
+} from '../types.ts'
+
+/**
+ * Algolia driver — communicates with the Algolia REST API via raw `fetch()`.
+ *
+ * @see https://www.algolia.com/doc/rest-api/search/
+ */
+export class AlgoliaDriver implements SearchEngine {
+  readonly name = 'algolia'
+  private appId: string
+  private apiKey: string
+  private baseUrl: string
+
+  constructor(config: DriverConfig) {
+    this.appId = (config.appId as string) ?? ''
+    this.apiKey = (config.apiKey as string) ?? ''
+    this.baseUrl = `https://${this.appId}.algolia.net`
+  }
+
+  // ── Interface ────────────────────────────────────────────────────────────
+
+  async upsert(
+    index: string,
+    id: string | number,
+    document: Record<string, unknown>
+  ): Promise<void> {
+    await this.request(
+      'PUT',
+      `/1/indexes/${encodeURIComponent(index)}/${encodeURIComponent(String(id))}`,
+      document
+    )
+  }
+
+  async upsertMany(index: string, documents: SearchDocument[]): Promise<void> {
+    const requests = documents.map(doc => ({
+      action: 'updateObject',
+      body: { objectID: String(doc.id), ...doc },
+    }))
+    await this.request('POST', `/1/indexes/${encodeURIComponent(index)}/batch`, { requests })
+  }
+
+  async delete(index: string, id: string | number): Promise<void> {
+    await this.request(
+      'DELETE',
+      `/1/indexes/${encodeURIComponent(index)}/${encodeURIComponent(String(id))}`
+    )
+  }
+
+  async deleteMany(index: string, ids: Array<string | number>): Promise<void> {
+    const requests = ids.map(id => ({
+      action: 'deleteObject',
+      body: { objectID: String(id) },
+    }))
+    await this.request('POST', `/1/indexes/${encodeURIComponent(index)}/batch`, { requests })
+  }
+
+  async flush(index: string): Promise<void> {
+    await this.request('POST', `/1/indexes/${encodeURIComponent(index)}/clear`)
+  }
+
+  async deleteIndex(index: string): Promise<void> {
+    await this.request('DELETE', `/1/indexes/${encodeURIComponent(index)}`)
+  }
+
+  async createIndex(index: string, options?: IndexSettings): Promise<void> {
+    // Algolia creates indexes implicitly on first write.
+    // If settings are provided, configure them.
+    if (options) {
+      const settings: Record<string, unknown> = {}
+      if (options.searchableAttributes) settings.searchableAttributes = options.searchableAttributes
+      if (options.displayedAttributes) settings.attributesToRetrieve = options.displayedAttributes
+      if (options.filterableAttributes) {
+        settings.attributesForFaceting = options.filterableAttributes.map(
+          attr => `filterOnly(${attr})`
+        )
+      }
+      if (options.sortableAttributes) settings.ranking = options.sortableAttributes
+
+      if (Object.keys(settings).length > 0) {
+        await this.request('PUT', `/1/indexes/${encodeURIComponent(index)}/settings`, settings)
+      }
+    }
+  }
+
+  async search(index: string, query: string, options?: SearchOptions): Promise<SearchResult> {
+    const perPage = options?.perPage ?? 20
+    const page = options?.page ?? 1
+
+    const body: Record<string, unknown> = {
+      query,
+      hitsPerPage: perPage,
+      page: page - 1, // Algolia uses 0-based pages
+    }
+
+    if (options?.filter) {
+      body.filters =
+        typeof options.filter === 'string' ? options.filter : this.buildFilter(options.filter)
+    }
+    if (options?.attributesToRetrieve) body.attributesToRetrieve = options.attributesToRetrieve
+    if (options?.attributesToHighlight) body.attributesToHighlight = options.attributesToHighlight
+
+    const data = await this.request('POST', `/1/indexes/${encodeURIComponent(index)}/query`, body)
+
+    return {
+      hits: (data.hits ?? []).map(
+        (hit: any): SearchHit => ({
+          document: hit,
+          highlights: hit._highlightResult
+            ? Object.fromEntries(
+                Object.entries(hit._highlightResult).map(([key, val]: [string, any]) => [
+                  key,
+                  val.value ?? '',
+                ])
+              )
+            : undefined,
+        })
+      ),
+      totalHits: data.nbHits ?? 0,
+      page,
+      perPage,
+      processingTimeMs: data.processingTimeMS,
+    }
+  }
+
+  // ── Private ──────────────────────────────────────────────────────────────
+
+  private headers(): Record<string, string> {
+    return {
+      'content-type': 'application/json',
+      'x-algolia-application-id': this.appId,
+      'x-algolia-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('Algolia', response.status, text)
+    }
+
+    if (response.status === 204 || response.headers.get('content-length') === '0') return null
+    return response.json()
+  }
+
+  private buildFilter(filter: Record<string, unknown>): string {
+    return Object.entries(filter)
+      .map(([key, value]) => {
+        if (Array.isArray(value)) {
+          return value.map(v => `${key}:${JSON.stringify(v)}`).join(' OR ')
+        }
+        return `${key}:${JSON.stringify(value)}`
+      })
+      .join(' AND ')
+  }
+}

package/src/drivers/meilisearch_driver.ts

@@ -0,0 +1,150 @@
+import { ExternalServiceError } from '@stravigor/core/exceptions/errors'
+import type { SearchEngine } from '../search_engine.ts'
+import type {
+  SearchDocument,
+  SearchOptions,
+  SearchResult,
+  SearchHit,
+  IndexSettings,
+  DriverConfig,
+} from '../types.ts'
+
+/**
+ * Meilisearch driver — communicates with the Meilisearch REST API via raw `fetch()`.
+ *
+ * @see https://www.meilisearch.com/docs/reference/api/overview
+ */
+export class MeilisearchDriver implements SearchEngine {
+  readonly name = 'meilisearch'
+  private baseUrl: string
+  private apiKey: string
+
+  constructor(config: DriverConfig) {
+    const protocol = config.protocol ?? 'http'
+    const host = config.host ?? 'localhost'
+    const port = config.port ?? 7700
+    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', `/indexes/${encodeURIComponent(index)}/documents`, [
+      { id, ...document },
+    ])
+  }
+
+  async upsertMany(index: string, documents: SearchDocument[]): Promise<void> {
+    await this.request('POST', `/indexes/${encodeURIComponent(index)}/documents`, documents)
+  }
+
+  async delete(index: string, id: string | number): Promise<void> {
+    await this.request(
+      'DELETE',
+      `/indexes/${encodeURIComponent(index)}/documents/${encodeURIComponent(String(id))}`
+    )
+  }
+
+  async deleteMany(index: string, ids: Array<string | number>): Promise<void> {
+    await this.request('POST', `/indexes/${encodeURIComponent(index)}/documents/delete-batch`, ids)
+  }
+
+  async flush(index: string): Promise<void> {
+    await this.request('DELETE', `/indexes/${encodeURIComponent(index)}/documents`)
+  }
+
+  async deleteIndex(index: string): Promise<void> {
+    await this.request('DELETE', `/indexes/${encodeURIComponent(index)}`)
+  }
+
+  async createIndex(index: string, options?: IndexSettings): Promise<void> {
+    await this.request('POST', '/indexes', {
+      uid: index,
+      primaryKey: options?.primaryKey ?? 'id',
+    })
+
+    if (options) {
+      const settings: Record<string, unknown> = {}
+      if (options.searchableAttributes) settings.searchableAttributes = options.searchableAttributes
+      if (options.displayedAttributes) settings.displayedAttributes = options.displayedAttributes
+      if (options.filterableAttributes) settings.filterableAttributes = options.filterableAttributes
+      if (options.sortableAttributes) settings.sortableAttributes = options.sortableAttributes
+
+      if (Object.keys(settings).length > 0) {
+        await this.request('PATCH', `/indexes/${encodeURIComponent(index)}/settings`, settings)
+      }
+    }
+  }
+
+  async search(index: string, query: string, options?: SearchOptions): Promise<SearchResult> {
+    const perPage = options?.perPage ?? 20
+    const page = options?.page ?? 1
+
+    const body: Record<string, unknown> = { q: query, limit: perPage, offset: (page - 1) * perPage }
+
+    if (options?.filter) {
+      body.filter =
+        typeof options.filter === 'string' ? options.filter : this.buildFilter(options.filter)
+    }
+    if (options?.sort) body.sort = options.sort
+    if (options?.attributesToRetrieve) body.attributesToRetrieve = options.attributesToRetrieve
+    if (options?.attributesToHighlight) {
+      body.attributesToHighlight = options.attributesToHighlight
+    }
+
+    const data = await this.request('POST', `/indexes/${encodeURIComponent(index)}/search`, body)
+
+    return {
+      hits: (data.hits ?? []).map(
+        (hit: any): SearchHit => ({
+          document: hit,
+          highlights: hit._formatted,
+        })
+      ),
+      totalHits: data.estimatedTotalHits ?? data.totalHits ?? 0,
+      page,
+      perPage,
+      processingTimeMs: data.processingTimeMs,
+    }
+  }
+
+  // ── Private ──────────────────────────────────────────────────────────────
+
+  private headers(): Record<string, string> {
+    const h: Record<string, string> = { 'content-type': 'application/json' }
+    if (this.apiKey) h['authorization'] = `Bearer ${this.apiKey}`
+    return h
+  }
+
+  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('Meilisearch', response.status, text)
+    }
+
+    if (response.status === 204 || response.headers.get('content-length') === '0') return null
+    return response.json()
+  }
+
+  private buildFilter(filter: Record<string, unknown>): string {
+    return Object.entries(filter)
+      .map(([key, value]) => {
+        if (Array.isArray(value)) {
+          return `${key} IN [${value.map(v => JSON.stringify(v)).join(', ')}]`
+        }
+        return `${key} = ${JSON.stringify(value)}`
+      })
+      .join(' AND ')
+  }
+}

package/src/drivers/null_driver.ts

@@ -0,0 +1,27 @@
+import type { SearchEngine } from '../search_engine.ts'
+import type { SearchDocument, SearchOptions, SearchResult, IndexSettings } from '../types.ts'
+
+/**
+ * No-op search driver — silently discards all writes and returns empty results.
+ *
+ * Useful when search is disabled or during testing.
+ */
+export class NullDriver implements SearchEngine {
+  readonly name = 'null'
+
+  async upsert(
+    _index: string,
+    _id: string | number,
+    _document: Record<string, unknown>
+  ): Promise<void> {}
+  async upsertMany(_index: string, _documents: SearchDocument[]): Promise<void> {}
+  async delete(_index: string, _id: string | number): Promise<void> {}
+  async deleteMany(_index: string, _ids: Array<string | number>): Promise<void> {}
+  async flush(_index: string): Promise<void> {}
+  async deleteIndex(_index: string): Promise<void> {}
+  async createIndex(_index: string, _options?: IndexSettings): Promise<void> {}
+
+  async search(_index: string, _query: string, options?: SearchOptions): Promise<SearchResult> {
+    return { hits: [], totalHits: 0, page: options?.page ?? 1, perPage: options?.perPage ?? 20 }
+  }
+}

package/src/drivers/typesense_driver.ts

@@ -0,0 +1,227 @@
+import { ExternalServiceError } from '@stravigor/core/exceptions/errors'
+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.
+    try {
+      const schema = await this.request('GET', `/collections/${encodeURIComponent(index)}`)
+      await this.request('DELETE', `/collections/${encodeURIComponent(index)}`)
+      await this.request('POST', '/collections', {
+        name: schema.name,
+        fields: schema.fields,
+      })
+    } catch {
+      // If the collection doesn't exist, that's fine
+    }
+  }
+
+  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/core/exceptions/strav_error'
+
+/** 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,32 @@
+// Manager
+export { default, default as SearchManager } from './search_manager.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,99 @@
+import { inject } from '@stravigor/core/core'
+import type Configuration from '@stravigor/core/config/configuration'
+import { ConfigurationError } from '@stravigor/core/exceptions/errors'
+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/searchable.ts

@@ -0,0 +1,203 @@
+import type BaseModel from '@stravigor/core/orm/base_model'
+import type { NormalizeConstructor } from '@stravigor/core/helpers'
+import Emitter from '@stravigor/core/events/emitter'
+import SearchManager from './search_manager.ts'
+import type { SearchOptions, SearchResult, SearchDocument, IndexSettings } from './types.ts'
+
+/**
+ * Mixin that adds full-text search capabilities to a BaseModel subclass.
+ *
+ * @example
+ * import { BaseModel } from '@stravigor/core/orm'
+ * import { searchable } from '@stravigor/search'
+ *
+ * class Article extends searchable(BaseModel) {
+ *   declare id: number
+ *   declare title: string
+ *   declare body: string
+ *
+ *   static searchableAs() { return 'articles' }
+ *
+ *   toSearchableArray() {
+ *     return { id: this.id, title: this.title, body: this.body }
+ *   }
+ * }
+ *
+ * // Composable with other mixins:
+ * import { compose } from '@stravigor/core/helpers'
+ * class Article extends compose(BaseModel, softDeletes, searchable) { }
+ *
+ * // Boot auto-indexing (in app bootstrap):
+ * Article.bootSearch('article')
+ *
+ * // Search:
+ * const results = await Article.search('typescript')
+ */
+export function searchable<T extends NormalizeConstructor<typeof BaseModel>>(Base: T) {
+  return class Searchable extends Base {
+    private static _searchBooted = false
+
+    /**
+     * The search index name for this model.
+     * Defaults to the table name. Override to customize.
+     */
+    static searchableAs(): string {
+      return (this as unknown as typeof BaseModel).tableName
+    }
+
+    /**
+     * Convert this model instance to a document for the search index.
+     * Override in subclass to control which fields are indexed.
+     *
+     * Default: returns all own properties that don't start with '_'.
+     */
+    toSearchableArray(): Record<string, unknown> {
+      const data: Record<string, unknown> = {}
+      for (const key of Object.keys(this)) {
+        if (key.startsWith('_')) continue
+        data[key] = (this as any)[key]
+      }
+      return data
+    }
+
+    /**
+     * Whether this model instance should be indexed.
+     * Override to conditionally exclude records (e.g. drafts).
+     */
+    shouldBeSearchable(): boolean {
+      return true
+    }
+
+    /**
+     * Index settings for this model (searchable/filterable/sortable attributes).
+     * Override to configure. Returns undefined by default (use engine defaults).
+     */
+    static searchableSettings(): IndexSettings | undefined {
+      return undefined
+    }
+
+    // ── Instance methods ─────────────────────────────────────────────────
+
+    /** Index (upsert) this model instance in the search engine. */
+    async searchIndex(): Promise<void> {
+      if (!this.shouldBeSearchable()) return
+      const ctor = this.constructor as typeof Searchable
+      const index = SearchManager.indexName(ctor.searchableAs())
+      const pkProp = (ctor as unknown as typeof BaseModel).primaryKeyProperty
+      const id = (this as any)[pkProp]
+      const document = this.toSearchableArray()
+      await SearchManager.engine().upsert(index, id, document)
+    }
+
+    /** Remove this model instance from the search index. */
+    async searchRemove(): Promise<void> {
+      const ctor = this.constructor as typeof Searchable
+      const index = SearchManager.indexName(ctor.searchableAs())
+      const pkProp = (ctor as unknown as typeof BaseModel).primaryKeyProperty
+      const id = (this as any)[pkProp]
+      await SearchManager.engine().delete(index, id)
+    }
+
+    // ── Static methods ───────────────────────────────────────────────────
+
+    /** Perform a full-text search on this model's index. */
+    static async search(query: string, options?: SearchOptions): Promise<SearchResult> {
+      const index = SearchManager.indexName(this.searchableAs())
+      return SearchManager.engine().search(index, query, options)
+    }
+
+    /**
+     * Import all records into the search index. Fetches from DB in chunks.
+     * @param chunkSize Number of records per batch.
+     * @returns The number of documents indexed.
+     */
+    static async importAll(chunkSize: number = 500): Promise<number> {
+      const ModelCtor = this as unknown as typeof BaseModel & typeof Searchable
+      const index = SearchManager.indexName(this.searchableAs())
+      const db = ModelCtor.db
+      const table = ModelCtor.tableName
+      const pkCol = ModelCtor.primaryKeyColumn
+
+      let imported = 0
+      let offset = 0
+
+      while (true) {
+        const rows = (await db.sql.unsafe(
+          `SELECT * FROM "${table}" ORDER BY "${pkCol}" LIMIT $1 OFFSET $2`,
+          [chunkSize, offset]
+        )) as Record<string, unknown>[]
+
+        if (rows.length === 0) break
+
+        const documents: SearchDocument[] = []
+        for (const row of rows) {
+          const instance = ModelCtor.hydrate(row) as InstanceType<typeof Searchable>
+          if (instance.shouldBeSearchable()) {
+            const doc = instance.toSearchableArray()
+            const pkProp = ModelCtor.primaryKeyProperty
+            documents.push({ id: (instance as any)[pkProp], ...doc })
+          }
+        }
+
+        if (documents.length > 0) {
+          await SearchManager.engine().upsertMany(index, documents)
+          imported += documents.length
+        }
+
+        offset += chunkSize
+        if (rows.length < chunkSize) break
+      }
+
+      return imported
+    }
+
+    /** Flush all documents from this model's search index. */
+    static async flushIndex(): Promise<void> {
+      const index = SearchManager.indexName(this.searchableAs())
+      await SearchManager.engine().flush(index)
+    }
+
+    /** Create this model's search index with configured settings. */
+    static async createSearchIndex(): Promise<void> {
+      const index = SearchManager.indexName(this.searchableAs())
+      const settings = this.searchableSettings()
+      await SearchManager.engine().createIndex(index, settings)
+    }
+
+    /**
+     * Register Emitter listeners for auto-indexing on model events.
+     *
+     * Hooks into `<prefix>.created`, `<prefix>.updated`, `<prefix>.synced`,
+     * and `<prefix>.deleted` events emitted by generated services.
+     *
+     * @param eventPrefix The event prefix (e.g. 'article' for ArticleEvents).
+     */
+    static bootSearch(eventPrefix: string): void {
+      if (this._searchBooted) return
+      this._searchBooted = true
+
+      const indexFn = async (model: unknown) => {
+        if (model && typeof (model as any).searchIndex === 'function') {
+          await (model as any).searchIndex()
+        }
+      }
+
+      const removeFn = async (model: unknown) => {
+        if (model && typeof (model as any).searchRemove === 'function') {
+          await (model as any).searchRemove()
+        }
+      }
+
+      Emitter.on(`${eventPrefix}.created`, indexFn)
+      Emitter.on(`${eventPrefix}.updated`, indexFn)
+      Emitter.on(`${eventPrefix}.synced`, indexFn)
+      Emitter.on(`${eventPrefix}.deleted`, removeFn)
+    }
+  }
+}
+
+/** The instance type of any searchable model. */
+export type SearchableInstance = InstanceType<ReturnType<typeof searchable>>
+
+/** The static type of any searchable model class. */
+export type SearchableModel = ReturnType<typeof searchable>

package/src/types.ts

@@ -0,0 +1,81 @@
+// ── Documents ─────────────────────────────────────────────────────────────
+
+export interface SearchDocument {
+  id: string | number
+  [key: string]: unknown
+}
+
+// ── Index settings ────────────────────────────────────────────────────────
+
+export interface IndexSettings {
+  /** Fields to use for full-text search. */
+  searchableAttributes?: string[]
+  /** Fields to return in results. */
+  displayedAttributes?: string[]
+  /** Fields that can be used as filters. */
+  filterableAttributes?: string[]
+  /** Fields that can be used for sorting. */
+  sortableAttributes?: string[]
+  /** Primary key field name (defaults to 'id'). */
+  primaryKey?: string
+}
+
+// ── Search options & results ──────────────────────────────────────────────
+
+export interface SearchOptions {
+  /** Filters — key-value pairs or engine-native filter string. */
+  filter?: Record<string, unknown> | string
+  /** Sort by field(s), e.g. ['created_at:desc']. */
+  sort?: string[]
+  /** Page number (1-based). */
+  page?: number
+  /** Results per page. */
+  perPage?: number
+  /** Fields to return in results. */
+  attributesToRetrieve?: string[]
+  /** Fields to highlight in results. */
+  attributesToHighlight?: string[]
+}
+
+export interface SearchResult {
+  /** The matching documents. */
+  hits: SearchHit[]
+  /** Total number of matching documents (estimated). */
+  totalHits: number
+  /** Current page. */
+  page: number
+  /** Results per page. */
+  perPage: number
+  /** Processing time in milliseconds (if provided by the engine). */
+  processingTimeMs?: number
+}
+
+export interface SearchHit {
+  /** The document data. */
+  document: Record<string, unknown>
+  /** Highlighted fields (if requested). */
+  highlights?: Record<string, string>
+}
+
+// ── Configuration ─────────────────────────────────────────────────────────
+
+export interface SearchConfig {
+  /** Default driver name. */
+  default: string
+  /** Index name prefix (e.g. 'myapp_'). */
+  prefix: string
+  /** Driver configurations keyed by name. */
+  drivers: Record<string, DriverConfig>
+}
+
+export interface DriverConfig {
+  driver: string
+  host?: string
+  port?: number
+  apiKey?: string
+  /** Algolia application ID. */
+  appId?: string
+  /** Protocol — 'http' or 'https'. */
+  protocol?: string
+  [key: string]: unknown
+}

package/stubs/config/search.ts

@@ -0,0 +1,32 @@
+import { env } from '@stravigor/core/helpers'
+
+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', ''),
+    },
+  },
+}

package/tsconfig.json

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