@mantiq/search 0.1.0

package/src/contracts/SearchEngine.ts

@@ -0,0 +1,33 @@
+import type { SearchBuilder } from '../SearchBuilder.ts'
+
+export interface SearchResult {
+  /** Raw results from the engine (format varies by driver) */
+  raw: any
+  /** Mapped model keys from the results */
+  keys: (string | number)[]
+  /** Total number of matching records (for pagination) */
+  total: number
+}
+
+export interface SearchEngine {
+  /** Upsert models into the search index */
+  update(models: any[]): Promise<void>
+
+  /** Remove models from the search index */
+  delete(models: any[]): Promise<void>
+
+  /** Perform a search query */
+  search(builder: SearchBuilder): Promise<SearchResult>
+
+  /** Perform a paginated search query */
+  paginate(builder: SearchBuilder, perPage: number, page: number): Promise<SearchResult>
+
+  /** Remove all records for a model from its index */
+  flush(indexName: string): Promise<void>
+
+  /** Create a search index */
+  createIndex(name: string, options?: Record<string, any>): Promise<void>
+
+  /** Delete a search index */
+  deleteIndex(name: string): Promise<void>
+}

package/src/drivers/AlgoliaEngine.ts

@@ -0,0 +1,145 @@
+import type { SearchEngine, SearchResult } from '../contracts/SearchEngine.ts'
+import type { SearchBuilder } from '../SearchBuilder.ts'
+import { SearchError } from '../errors/SearchError.ts'
+
+/**
+ * Algolia search engine driver using REST API (no SDK).
+ */
+export class AlgoliaEngine implements SearchEngine {
+  private readonly baseUrl: string
+
+  constructor(
+    private readonly applicationId: string,
+    private readonly apiKey: string,
+    private readonly indexSettings?: Record<string, any>,
+  ) {
+    this.baseUrl = `https://${applicationId}-dsn.algolia.net`
+  }
+
+  async update(models: any[]): Promise<void> {
+    if (models.length === 0) return
+
+    const indexName = this.resolveIndexName(models[0])
+    const objects = models.map((m) => ({
+      objectID: String(this.resolveKey(m)),
+      ...this.resolveData(m),
+    }))
+
+    await this.request('POST', `/1/indexes/${encodeURIComponent(indexName)}/batch`, {
+      requests: objects.map((obj) => ({ action: 'updateObject', body: obj })),
+    })
+  }
+
+  async delete(models: any[]): Promise<void> {
+    if (models.length === 0) return
+
+    const indexName = this.resolveIndexName(models[0])
+    const objectIDs = models.map((m) => String(this.resolveKey(m)))
+
+    await this.request('POST', `/1/indexes/${encodeURIComponent(indexName)}/batch`, {
+      requests: objectIDs.map((id) => ({ action: 'deleteObject', body: { objectID: id } })),
+    })
+  }
+
+  async search(builder: SearchBuilder): Promise<SearchResult> {
+    const indexName = this.resolveModelIndexName(builder.model)
+
+    const params: Record<string, any> = { query: builder.query }
+    if (builder.getLimit() !== null) params.hitsPerPage = builder.getLimit()
+
+    const filters = this.buildFilters(builder)
+    if (filters) params.filters = filters
+
+    const res = await this.request('POST', `/1/indexes/${encodeURIComponent(indexName)}/query`, params)
+
+    return {
+      raw: res,
+      keys: (res.hits ?? []).map((h: any) => h.objectID),
+      total: res.nbHits ?? 0,
+    }
+  }
+
+  async paginate(builder: SearchBuilder, perPage: number, page: number): Promise<SearchResult> {
+    const indexName = this.resolveModelIndexName(builder.model)
+
+    const params: Record<string, any> = {
+      query: builder.query,
+      hitsPerPage: perPage,
+      page: page - 1, // Algolia is 0-indexed
+    }
+
+    const filters = this.buildFilters(builder)
+    if (filters) params.filters = filters
+
+    const res = await this.request('POST', `/1/indexes/${encodeURIComponent(indexName)}/query`, params)
+
+    return {
+      raw: res,
+      keys: (res.hits ?? []).map((h: any) => h.objectID),
+      total: res.nbHits ?? 0,
+    }
+  }
+
+  async flush(indexName: string): Promise<void> {
+    await this.request('POST', `/1/indexes/${encodeURIComponent(indexName)}/clear`, {})
+  }
+
+  async createIndex(name: string, options?: Record<string, any>): Promise<void> {
+    const settings = { ...this.indexSettings, ...options }
+    if (Object.keys(settings).length > 0) {
+      await this.request('PUT', `/1/indexes/${encodeURIComponent(name)}/settings`, settings)
+    }
+  }
+
+  async deleteIndex(name: string): Promise<void> {
+    await this.request('DELETE', `/1/indexes/${encodeURIComponent(name)}`)
+  }
+
+  private buildFilters(builder: SearchBuilder): string {
+    const parts: string[] = []
+    for (const { field, value } of builder.wheres) {
+      parts.push(`${field}:${JSON.stringify(value)}`)
+    }
+    for (const { field, values } of builder.whereIns) {
+      const orParts = values.map((v) => `${field}:${JSON.stringify(v)}`)
+      parts.push(`(${orParts.join(' OR ')})`)
+    }
+    return parts.join(' AND ')
+  }
+
+  private async request(method: string, path: string, body?: any): Promise<any> {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Algolia-Application-Id': this.applicationId,
+        'X-Algolia-API-Key': this.apiKey,
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    })
+
+    if (!res.ok) {
+      const text = await res.text()
+      throw new SearchError(`Algolia API error: ${res.status} ${text}`, { status: res.status })
+    }
+
+    return res.json()
+  }
+
+  private resolveIndexName(model: any): string {
+    const MC = model.constructor
+    return typeof MC.searchableAs === 'function' ? MC.searchableAs() : MC.table ?? MC.name.toLowerCase() + 's'
+  }
+
+  private resolveModelIndexName(MC: any): string {
+    return typeof MC.searchableAs === 'function' ? MC.searchableAs() : MC.table ?? MC.name.toLowerCase() + 's'
+  }
+
+  private resolveKey(model: any): string | number {
+    return typeof model.searchableKey === 'function' ? model.searchableKey() : model.getAttribute?.('id') ?? model.id
+  }
+
+  private resolveData(model: any): Record<string, any> {
+    return typeof model.toSearchableArray === 'function' ? model.toSearchableArray() : { ...model.attributes }
+  }
+}

package/src/drivers/CollectionEngine.ts

@@ -0,0 +1,176 @@
+import type { SearchEngine, SearchResult } from '../contracts/SearchEngine.ts'
+import type { SearchBuilder } from '../SearchBuilder.ts'
+
+/**
+ * In-memory search engine for development and testing.
+ * Stores indexed records in a Map and searches with string matching.
+ */
+export class CollectionEngine implements SearchEngine {
+  private readonly store = new Map<string, Map<string | number, Record<string, any>>>()
+
+  async update(models: any[]): Promise<void> {
+    for (const model of models) {
+      const indexName = this.resolveIndexName(model)
+      if (!this.store.has(indexName)) this.store.set(indexName, new Map())
+      const index = this.store.get(indexName)!
+
+      const key = this.resolveKey(model)
+      const data = typeof model.toSearchableArray === 'function'
+        ? model.toSearchableArray()
+        : { ...model.attributes }
+
+      index.set(key, data)
+    }
+  }
+
+  async delete(models: any[]): Promise<void> {
+    for (const model of models) {
+      const indexName = this.resolveIndexName(model)
+      const index = this.store.get(indexName)
+      if (!index) continue
+      index.delete(this.resolveKey(model))
+    }
+  }
+
+  async search(builder: SearchBuilder): Promise<SearchResult> {
+    const indexName = this.resolveModelIndexName(builder.model)
+    const index = this.store.get(indexName)
+
+    if (!index) return { raw: [], keys: [], total: 0 }
+
+    let records = Array.from(index.entries()).map(([key, data]) => ({ key, data }))
+
+    // Full-text filter
+    if (builder.query) {
+      const q = builder.query.toLowerCase()
+      records = records.filter(({ data }) =>
+        Object.values(data).some((v) =>
+          v !== null && v !== undefined && String(v).toLowerCase().includes(q),
+        ),
+      )
+    }
+
+    // Where clauses
+    for (const { field, value } of builder.wheres) {
+      records = records.filter(({ data }) => data[field] === value)
+    }
+
+    // WhereIn clauses
+    for (const { field, values } of builder.whereIns) {
+      records = records.filter(({ data }) => values.includes(data[field]))
+    }
+
+    const total = records.length
+
+    // Order
+    for (const { column, direction } of [...builder.orders].reverse()) {
+      records.sort((a, b) => {
+        const av = a.data[column]
+        const bv = b.data[column]
+        if (av < bv) return direction === 'asc' ? -1 : 1
+        if (av > bv) return direction === 'asc' ? 1 : -1
+        return 0
+      })
+    }
+
+    // Offset
+    const offset = builder.getOffset()
+    if (offset !== null && offset > 0) {
+      records = records.slice(offset)
+    }
+
+    // Limit
+    const limit = builder.getLimit()
+    if (limit !== null) {
+      records = records.slice(0, limit)
+    }
+
+    return {
+      raw: records.map((r) => r.data),
+      keys: records.map((r) => r.key),
+      total,
+    }
+  }
+
+  async paginate(builder: SearchBuilder, perPage: number, page: number): Promise<SearchResult> {
+    const indexName = this.resolveModelIndexName(builder.model)
+    const index = this.store.get(indexName)
+
+    if (!index) return { raw: [], keys: [], total: 0 }
+
+    let records = Array.from(index.entries()).map(([key, data]) => ({ key, data }))
+
+    // Apply filters (same as search)
+    if (builder.query) {
+      const q = builder.query.toLowerCase()
+      records = records.filter(({ data }) =>
+        Object.values(data).some((v) =>
+          v !== null && v !== undefined && String(v).toLowerCase().includes(q),
+        ),
+      )
+    }
+    for (const { field, value } of builder.wheres) {
+      records = records.filter(({ data }) => data[field] === value)
+    }
+    for (const { field, values } of builder.whereIns) {
+      records = records.filter(({ data }) => values.includes(data[field]))
+    }
+
+    const total = records.length
+
+    for (const { column, direction } of [...builder.orders].reverse()) {
+      records.sort((a, b) => {
+        const av = a.data[column]
+        const bv = b.data[column]
+        if (av < bv) return direction === 'asc' ? -1 : 1
+        if (av > bv) return direction === 'asc' ? 1 : -1
+        return 0
+      })
+    }
+
+    const start = (page - 1) * perPage
+    records = records.slice(start, start + perPage)
+
+    return {
+      raw: records.map((r) => r.data),
+      keys: records.map((r) => r.key),
+      total,
+    }
+  }
+
+  async flush(indexName: string): Promise<void> {
+    this.store.delete(indexName)
+  }
+
+  async createIndex(name: string): Promise<void> {
+    if (!this.store.has(name)) this.store.set(name, new Map())
+  }
+
+  async deleteIndex(name: string): Promise<void> {
+    this.store.delete(name)
+  }
+
+  /** Get the raw store for testing/debugging. */
+  getStore(): Map<string, Map<string | number, Record<string, any>>> {
+    return this.store
+  }
+
+  private resolveIndexName(model: any): string {
+    const ModelClass = model.constructor
+    return typeof ModelClass.searchableAs === 'function'
+      ? ModelClass.searchableAs()
+      : ModelClass.table ?? ModelClass.name.toLowerCase() + 's'
+  }
+
+  private resolveModelIndexName(ModelClass: any): string {
+    return typeof ModelClass.searchableAs === 'function'
+      ? ModelClass.searchableAs()
+      : ModelClass.table ?? ModelClass.name.toLowerCase() + 's'
+  }
+
+  private resolveKey(model: any): string | number {
+    return typeof model.searchableKey === 'function'
+      ? model.searchableKey()
+      : model.getAttribute?.('id') ?? model.id
+  }
+}

package/src/drivers/DatabaseEngine.ts

@@ -0,0 +1,139 @@
+import type { SearchEngine, SearchResult } from '../contracts/SearchEngine.ts'
+import type { SearchBuilder } from '../SearchBuilder.ts'
+
+/**
+ * Database-backed search engine using SQL full-text capabilities.
+ * - SQLite: LIKE '%query%' across searchable columns
+ * - PostgreSQL: to_tsvector() @@ plainto_tsquery()
+ * - MySQL: MATCH ... AGAINST (if FULLTEXT index exists, falls back to LIKE)
+ */
+export class DatabaseEngine implements SearchEngine {
+  constructor(private readonly connectionName?: string) {}
+
+  async update(_models: any[]): Promise<void> {
+    // No-op: data lives in the database already.
+  }
+
+  async delete(_models: any[]): Promise<void> {
+    // No-op: data lives in the database already.
+  }
+
+  async search(builder: SearchBuilder): Promise<SearchResult> {
+    const ModelClass = builder.model
+    let query = ModelClass.query()
+
+    if (this.connectionName) {
+      query = query.connection(this.connectionName)
+    }
+
+    // Apply full-text search
+    if (builder.query) {
+      query = this.applySearchQuery(query, builder)
+    }
+
+    // Apply where clauses
+    for (const { field, value } of builder.wheres) {
+      query = query.where(field, value)
+    }
+    for (const { field, values } of builder.whereIns) {
+      query = query.whereIn(field, values)
+    }
+
+    // Apply ordering
+    for (const { column, direction } of builder.orders) {
+      query = query.orderBy(column, direction)
+    }
+
+    // Apply offset
+    const offset = builder.getOffset()
+    if (offset !== null && offset > 0) {
+      query = query.offset(offset)
+    }
+
+    // Apply limit
+    const limit = builder.getLimit()
+    if (limit !== null) {
+      query = query.limit(limit)
+    }
+
+    const models = await query.get()
+    const pk = ModelClass.primaryKey ?? 'id'
+    const keys = models.map((m: any) => m.getAttribute(pk))
+
+    return { raw: models, keys, total: keys.length }
+  }
+
+  async paginate(builder: SearchBuilder, perPage: number, page: number): Promise<SearchResult> {
+    const ModelClass = builder.model
+    let query = ModelClass.query()
+
+    if (this.connectionName) {
+      query = query.connection(this.connectionName)
+    }
+
+    if (builder.query) {
+      query = this.applySearchQuery(query, builder)
+    }
+
+    for (const { field, value } of builder.wheres) {
+      query = query.where(field, value)
+    }
+    for (const { field, values } of builder.whereIns) {
+      query = query.whereIn(field, values)
+    }
+
+    for (const { column, direction } of builder.orders) {
+      query = query.orderBy(column, direction)
+    }
+
+    // Get total count
+    const countQuery = ModelClass.query()
+    if (builder.query) this.applySearchQuery(countQuery, builder)
+    for (const { field, value } of builder.wheres) countQuery.where(field, value)
+    for (const { field, values } of builder.whereIns) countQuery.whereIn(field, values)
+    const total = await countQuery.count()
+
+    // Paginate
+    const models = await query.limit(perPage).offset((page - 1) * perPage).get()
+    const pk = ModelClass.primaryKey ?? 'id'
+    const keys = models.map((m: any) => m.getAttribute(pk))
+
+    return { raw: models, keys, total }
+  }
+
+  async flush(_indexName: string): Promise<void> {
+    // No-op: we don't manage a separate index.
+  }
+
+  async createIndex(_name: string): Promise<void> {
+    // No-op: database tables are the index.
+  }
+
+  async deleteIndex(_name: string): Promise<void> {
+    // No-op
+  }
+
+  private applySearchQuery(query: any, builder: SearchBuilder): any {
+    const searchTerm = builder.query
+    const ModelClass = builder.model
+
+    // Get searchable columns from the model, or fall back to fillable
+    const columns: string[] = typeof ModelClass.searchableColumns === 'function'
+      ? ModelClass.searchableColumns()
+      : ModelClass.fillable ?? []
+
+    if (columns.length === 0) return query
+
+    // Use LIKE for broad compatibility (works on SQLite, Postgres, MySQL)
+    return query.where((q: any) => {
+      for (let i = 0; i < columns.length; i++) {
+        const col = columns[i]!
+        if (i === 0) {
+          q.where(col, 'LIKE', `%${searchTerm}%`)
+        } else {
+          q.orWhere(col, 'LIKE', `%${searchTerm}%`)
+        }
+      }
+    })
+  }
+}

package/src/drivers/ElasticsearchEngine.ts

@@ -0,0 +1,188 @@
+import type { SearchEngine, SearchResult } from '../contracts/SearchEngine.ts'
+import type { SearchBuilder } from '../SearchBuilder.ts'
+import { SearchError } from '../errors/SearchError.ts'
+
+/**
+ * Elasticsearch engine driver using REST API.
+ */
+export class ElasticsearchEngine implements SearchEngine {
+  private readonly host: string
+
+  constructor(
+    hosts: string[],
+    private readonly apiKey?: string,
+    private readonly username?: string,
+    private readonly password?: string,
+  ) {
+    this.host = hosts[0] ?? 'http://127.0.0.1:9200'
+  }
+
+  async update(models: any[]): Promise<void> {
+    if (models.length === 0) return
+    const indexName = this.resolveIndexName(models[0])
+
+    // Bulk API
+    const lines: string[] = []
+    for (const model of models) {
+      const id = String(this.resolveKey(model))
+      lines.push(JSON.stringify({ index: { _index: indexName, _id: id } }))
+      lines.push(JSON.stringify(this.resolveData(model)))
+    }
+
+    await this.request('POST', '/_bulk', lines.join('\n') + '\n', 'application/x-ndjson')
+  }
+
+  async delete(models: any[]): Promise<void> {
+    if (models.length === 0) return
+    const indexName = this.resolveIndexName(models[0])
+
+    const lines: string[] = []
+    for (const model of models) {
+      const id = String(this.resolveKey(model))
+      lines.push(JSON.stringify({ delete: { _index: indexName, _id: id } }))
+    }
+
+    await this.request('POST', '/_bulk', lines.join('\n') + '\n', 'application/x-ndjson')
+  }
+
+  async search(builder: SearchBuilder): Promise<SearchResult> {
+    const indexName = this.resolveModelIndexName(builder.model)
+    const body = this.buildSearchBody(builder)
+
+    const res = await this.request('POST', `/${indexName}/_search`, body)
+    const hits = res.hits?.hits ?? []
+
+    return {
+      raw: res,
+      keys: hits.map((h: any) => h._id),
+      total: res.hits?.total?.value ?? res.hits?.total ?? 0,
+    }
+  }
+
+  async paginate(builder: SearchBuilder, perPage: number, page: number): Promise<SearchResult> {
+    const indexName = this.resolveModelIndexName(builder.model)
+    const body = this.buildSearchBody(builder)
+    body.size = perPage
+    body.from = (page - 1) * perPage
+
+    const res = await this.request('POST', `/${indexName}/_search`, body)
+    const hits = res.hits?.hits ?? []
+
+    return {
+      raw: res,
+      keys: hits.map((h: any) => h._id),
+      total: res.hits?.total?.value ?? res.hits?.total ?? 0,
+    }
+  }
+
+  async flush(indexName: string): Promise<void> {
+    try {
+      await this.request('POST', `/${indexName}/_delete_by_query`, {
+        query: { match_all: {} },
+      })
+    } catch {
+      // Index may not exist
+    }
+  }
+
+  async createIndex(name: string, options?: Record<string, any>): Promise<void> {
+    const body = options ? { settings: options.settings, mappings: options.mappings } : {}
+    await this.request('PUT', `/${name}`, body)
+  }
+
+  async deleteIndex(name: string): Promise<void> {
+    try {
+      await this.request('DELETE', `/${name}`)
+    } catch {
+      // Index may not exist
+    }
+  }
+
+  private buildSearchBody(builder: SearchBuilder): Record<string, any> {
+    const body: Record<string, any> = {}
+    const must: any[] = []
+    const filter: any[] = []
+
+    // Full-text query
+    if (builder.query) {
+      must.push({ multi_match: { query: builder.query, type: 'best_fields', fuzziness: 'AUTO' } })
+    }
+
+    // Where clauses as term filters
+    for (const { field, value } of builder.wheres) {
+      filter.push({ term: { [field]: value } })
+    }
+    for (const { field, values } of builder.whereIns) {
+      filter.push({ terms: { [field]: values } })
+    }
+
+    if (must.length > 0 || filter.length > 0) {
+      body.query = { bool: {} }
+      if (must.length > 0) body.query.bool.must = must
+      if (filter.length > 0) body.query.bool.filter = filter
+    } else {
+      body.query = { match_all: {} }
+    }
+
+    // Sorting
+    if (builder.orders.length > 0) {
+      body.sort = builder.orders.map((o) => ({ [o.column]: { order: o.direction } }))
+    }
+
+    // Limit / offset
+    const limit = builder.getLimit()
+    if (limit !== null) body.size = limit
+    const offset = builder.getOffset()
+    if (offset !== null) body.from = offset
+
+    return body
+  }
+
+  private async request(method: string, path: string, body?: any, contentType?: string): Promise<any> {
+    const headers: Record<string, string> = {}
+
+    if (contentType) {
+      headers['Content-Type'] = contentType
+    } else if (body) {
+      headers['Content-Type'] = 'application/json'
+    }
+
+    if (this.apiKey) {
+      headers['Authorization'] = `ApiKey ${this.apiKey}`
+    } else if (this.username && this.password) {
+      headers['Authorization'] = `Basic ${btoa(`${this.username}:${this.password}`)}`
+    }
+
+    const res = await fetch(`${this.host}${path}`, {
+      method,
+      headers,
+      body: body ? (typeof body === 'string' ? body : JSON.stringify(body)) : undefined,
+    })
+
+    if (!res.ok) {
+      const text = await res.text()
+      throw new SearchError(`Elasticsearch API error: ${res.status} ${text}`, { status: res.status })
+    }
+
+    const ct = res.headers.get('content-type')
+    if (ct?.includes('application/json')) return res.json()
+    return {}
+  }
+
+  private resolveIndexName(model: any): string {
+    const MC = model.constructor
+    return typeof MC.searchableAs === 'function' ? MC.searchableAs() : MC.table ?? MC.name.toLowerCase() + 's'
+  }
+
+  private resolveModelIndexName(MC: any): string {
+    return typeof MC.searchableAs === 'function' ? MC.searchableAs() : MC.table ?? MC.name.toLowerCase() + 's'
+  }
+
+  private resolveKey(model: any): string | number {
+    return typeof model.searchableKey === 'function' ? model.searchableKey() : model.getAttribute?.('id') ?? model.id
+  }
+
+  private resolveData(model: any): Record<string, any> {
+    return typeof model.toSearchableArray === 'function' ? model.toSearchableArray() : { ...model.attributes }
+  }
+}