@mantiq/search 0.1.0

package/src/drivers/MeilisearchEngine.ts

@@ -0,0 +1,136 @@
+import type { SearchEngine, SearchResult } from '../contracts/SearchEngine.ts'
+import type { SearchBuilder } from '../SearchBuilder.ts'
+import { SearchError } from '../errors/SearchError.ts'
+
+/**
+ * Meilisearch engine driver using REST API.
+ */
+export class MeilisearchEngine implements SearchEngine {
+  constructor(
+    private readonly host: string,
+    private readonly apiKey: string,
+  ) {}
+
+  async update(models: any[]): Promise<void> {
+    if (models.length === 0) return
+    const indexName = this.resolveIndexName(models[0])
+    const documents = models.map((m) => ({
+      id: this.resolveKey(m),
+      ...this.resolveData(m),
+    }))
+    await this.request('POST', `/indexes/${encodeURIComponent(indexName)}/documents`, documents)
+  }
+
+  async delete(models: any[]): Promise<void> {
+    if (models.length === 0) return
+    const indexName = this.resolveIndexName(models[0])
+    const ids = models.map((m) => this.resolveKey(m))
+    await this.request('POST', `/indexes/${encodeURIComponent(indexName)}/documents/delete-batch`, ids)
+  }
+
+  async search(builder: SearchBuilder): Promise<SearchResult> {
+    const indexName = this.resolveModelIndexName(builder.model)
+    const body: Record<string, any> = { q: builder.query }
+
+    if (builder.getLimit() !== null) body.limit = builder.getLimit()
+    if (builder.getOffset() !== null) body.offset = builder.getOffset()
+
+    const filter = this.buildFilter(builder)
+    if (filter.length > 0) body.filter = filter
+
+    const sort = builder.orders.map((o) => `${o.column}:${o.direction}`)
+    if (sort.length > 0) body.sort = sort
+
+    const res = await this.request('POST', `/indexes/${encodeURIComponent(indexName)}/search`, body)
+
+    return {
+      raw: res,
+      keys: (res.hits ?? []).map((h: any) => h.id),
+      total: res.estimatedTotalHits ?? res.totalHits ?? 0,
+    }
+  }
+
+  async paginate(builder: SearchBuilder, perPage: number, page: number): Promise<SearchResult> {
+    const indexName = this.resolveModelIndexName(builder.model)
+    const body: Record<string, any> = {
+      q: builder.query,
+      hitsPerPage: perPage,
+      page,
+    }
+
+    const filter = this.buildFilter(builder)
+    if (filter.length > 0) body.filter = filter
+
+    const sort = builder.orders.map((o) => `${o.column}:${o.direction}`)
+    if (sort.length > 0) body.sort = sort
+
+    const res = await this.request('POST', `/indexes/${encodeURIComponent(indexName)}/search`, body)
+
+    return {
+      raw: res,
+      keys: (res.hits ?? []).map((h: any) => h.id),
+      total: res.totalHits ?? res.estimatedTotalHits ?? 0,
+    }
+  }
+
+  async flush(indexName: string): Promise<void> {
+    await this.request('DELETE', `/indexes/${encodeURIComponent(indexName)}/documents`)
+  }
+
+  async createIndex(name: string, options?: Record<string, any>): Promise<void> {
+    await this.request('POST', '/indexes', { uid: name, primaryKey: options?.primaryKey ?? 'id' })
+  }
+
+  async deleteIndex(name: string): Promise<void> {
+    await this.request('DELETE', `/indexes/${encodeURIComponent(name)}`)
+  }
+
+  private buildFilter(builder: SearchBuilder): string[] {
+    const filters: string[] = []
+    for (const { field, value } of builder.wheres) {
+      filters.push(`${field} = ${JSON.stringify(value)}`)
+    }
+    for (const { field, values } of builder.whereIns) {
+      const parts = values.map((v) => `${field} = ${JSON.stringify(v)}`)
+      filters.push(parts.join(' OR '))
+    }
+    return filters
+  }
+
+  private async request(method: string, path: string, body?: any): Promise<any> {
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' }
+    if (this.apiKey) headers['Authorization'] = `Bearer ${this.apiKey}`
+
+    const res = await fetch(`${this.host}${path}`, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    })
+
+    if (!res.ok) {
+      const text = await res.text()
+      throw new SearchError(`Meilisearch API error: ${res.status} ${text}`, { status: res.status })
+    }
+
+    const contentType = res.headers.get('content-type')
+    if (contentType?.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 }
+  }
+}

package/src/drivers/TypesenseEngine.ts

@@ -0,0 +1,181 @@
+import type { SearchEngine, SearchResult } from '../contracts/SearchEngine.ts'
+import type { SearchBuilder } from '../SearchBuilder.ts'
+import { SearchError } from '../errors/SearchError.ts'
+
+/**
+ * Typesense engine driver using REST API.
+ */
+export class TypesenseEngine implements SearchEngine {
+  private readonly baseUrl: string
+
+  constructor(
+    host: string,
+    port: number,
+    protocol: 'http' | 'https',
+    private readonly apiKey: string,
+  ) {
+    this.baseUrl = `${protocol}://${host}:${port}`
+  }
+
+  async update(models: any[]): Promise<void> {
+    if (models.length === 0) return
+    const collection = this.resolveIndexName(models[0])
+    const documents = models.map((m) => ({
+      ...this.resolveData(m),
+      id: String(this.resolveKey(m)),
+    }))
+
+    // JSONL import
+    const jsonl = documents.map((d) => JSON.stringify(d)).join('\n')
+    await this.request('POST', `/collections/${collection}/documents/import?action=upsert`, jsonl, 'text/plain')
+  }
+
+  async delete(models: any[]): Promise<void> {
+    if (models.length === 0) return
+    const collection = this.resolveIndexName(models[0])
+    const ids = models.map((m) => String(this.resolveKey(m)))
+
+    // Delete individually (Typesense doesn't have batch delete by ID)
+    for (const id of ids) {
+      try {
+        await this.request('DELETE', `/collections/${collection}/documents/${id}`)
+      } catch {
+        // Ignore 404s
+      }
+    }
+  }
+
+  async search(builder: SearchBuilder): Promise<SearchResult> {
+    const collection = this.resolveModelIndexName(builder.model)
+    const params = new URLSearchParams({
+      q: builder.query || '*',
+      query_by: this.resolveQueryBy(builder.model),
+    })
+
+    if (builder.getLimit() !== null) params.set('per_page', String(builder.getLimit()))
+    if (builder.getOffset() !== null) params.set('offset', String(builder.getOffset()))
+
+    const filter = this.buildFilter(builder)
+    if (filter) params.set('filter_by', filter)
+
+    const sort = builder.orders.map((o) => `${o.column}:${o.direction}`).join(',')
+    if (sort) params.set('sort_by', sort)
+
+    const res = await this.request('GET', `/collections/${collection}/documents/search?${params}`)
+
+    return {
+      raw: res,
+      keys: (res.hits ?? []).map((h: any) => h.document?.id),
+      total: res.found ?? 0,
+    }
+  }
+
+  async paginate(builder: SearchBuilder, perPage: number, page: number): Promise<SearchResult> {
+    const collection = this.resolveModelIndexName(builder.model)
+    const params = new URLSearchParams({
+      q: builder.query || '*',
+      query_by: this.resolveQueryBy(builder.model),
+      per_page: String(perPage),
+      page: String(page),
+    })
+
+    const filter = this.buildFilter(builder)
+    if (filter) params.set('filter_by', filter)
+
+    const sort = builder.orders.map((o) => `${o.column}:${o.direction}`).join(',')
+    if (sort) params.set('sort_by', sort)
+
+    const res = await this.request('GET', `/collections/${collection}/documents/search?${params}`)
+
+    return {
+      raw: res,
+      keys: (res.hits ?? []).map((h: any) => h.document?.id),
+      total: res.found ?? 0,
+    }
+  }
+
+  async flush(indexName: string): Promise<void> {
+    try {
+      await this.request('DELETE', `/collections/${indexName}`)
+    } catch {
+      // Collection may not exist
+    }
+  }
+
+  async createIndex(name: string, options?: Record<string, any>): Promise<void> {
+    const schema = {
+      name,
+      fields: options?.fields ?? [{ name: '.*', type: 'auto' }],
+      ...options,
+    }
+    await this.request('POST', '/collections', schema)
+  }
+
+  async deleteIndex(name: string): Promise<void> {
+    await this.request('DELETE', `/collections/${name}`)
+  }
+
+  private buildFilter(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) {
+      parts.push(`${field}:[${values.map((v) => JSON.stringify(v)).join(',')}]`)
+    }
+    return parts.join(' && ')
+  }
+
+  private resolveQueryBy(ModelClass: any): string {
+    if (typeof ModelClass.searchableColumns === 'function') {
+      return ModelClass.searchableColumns().join(',')
+    }
+    if (ModelClass.fillable && ModelClass.fillable.length > 0) {
+      return ModelClass.fillable.join(',')
+    }
+    return '*'
+  }
+
+  private async request(method: string, path: string, body?: any, contentType?: string): Promise<any> {
+    const headers: Record<string, string> = {
+      'X-TYPESENSE-API-KEY': this.apiKey,
+    }
+    if (contentType) {
+      headers['Content-Type'] = contentType
+    } else if (body && typeof body !== 'string') {
+      headers['Content-Type'] = 'application/json'
+    }
+
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      body: body ? (typeof body === 'string' ? body : JSON.stringify(body)) : undefined,
+    })
+
+    if (!res.ok) {
+      const text = await res.text()
+      throw new SearchError(`Typesense 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 }
+  }
+}

package/src/errors/SearchError.ts

@@ -0,0 +1,9 @@
+export class SearchError extends Error {
+  constructor(
+    message: string,
+    public readonly context?: Record<string, any>,
+  ) {
+    super(message)
+    this.name = 'SearchError'
+  }
+}

package/src/helpers/search.ts

@@ -0,0 +1,26 @@
+import type { SearchEngine } from '../contracts/SearchEngine.ts'
+import type { SearchManager } from '../SearchManager.ts'
+
+export const SEARCH_MANAGER = Symbol('SearchManager')
+
+let _manager: SearchManager | null = null
+
+export function setSearchManager(manager: SearchManager): void {
+  _manager = manager
+}
+
+export function getSearchManager(): SearchManager {
+  if (!_manager) {
+    throw new Error('SearchManager has not been initialized. Register SearchServiceProvider first.')
+  }
+  return _manager
+}
+
+/** Get the SearchManager or a specific engine. */
+export function search(): SearchManager
+export function search(engine: string): SearchEngine
+export function search(engine?: string): SearchManager | SearchEngine {
+  const manager = getSearchManager()
+  if (engine === undefined) return manager
+  return manager.driver(engine)
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+// @mantiq/search — public API exports
+
+// Contracts
+export type { SearchEngine, SearchResult } from './contracts/SearchEngine.ts'
+export type { SearchConfig, EngineConfig } from './contracts/SearchConfig.ts'
+export { DEFAULT_CONFIG } from './contracts/SearchConfig.ts'
+
+// Core
+export { SearchManager } from './SearchManager.ts'
+export { SearchBuilder, type PaginatedSearchResult, type WhereClause, type WhereInClause, type OrderClause } from './SearchBuilder.ts'
+export { SearchServiceProvider } from './SearchServiceProvider.ts'
+export { makeSearchable } from './Searchable.ts'
+export { SearchObserver } from './SearchObserver.ts'
+
+// Drivers
+export { CollectionEngine } from './drivers/CollectionEngine.ts'
+export { DatabaseEngine } from './drivers/DatabaseEngine.ts'
+export { AlgoliaEngine } from './drivers/AlgoliaEngine.ts'
+export { MeilisearchEngine } from './drivers/MeilisearchEngine.ts'
+export { TypesenseEngine } from './drivers/TypesenseEngine.ts'
+export { ElasticsearchEngine } from './drivers/ElasticsearchEngine.ts'
+
+// Commands
+export { SearchImportCommand } from './commands/SearchImportCommand.ts'
+export { SearchFlushCommand } from './commands/SearchFlushCommand.ts'
+export { SearchIndexCommand } from './commands/SearchIndexCommand.ts'
+export { SearchDeleteIndexCommand } from './commands/SearchDeleteIndexCommand.ts'
+
+// Jobs
+export { MakeSearchableJob } from './jobs/MakeSearchableJob.ts'
+
+// Helpers
+export { search, SEARCH_MANAGER, setSearchManager, getSearchManager } from './helpers/search.ts'
+
+// Testing
+export { SearchFake } from './testing/SearchFake.ts'
+
+// Errors
+export { SearchError } from './errors/SearchError.ts'

package/src/jobs/MakeSearchableJob.ts

@@ -0,0 +1,22 @@
+import { getSearchManager } from '../helpers/search.ts'
+
+export class MakeSearchableJob {
+  readonly jobName = 'MakeSearchableJob'
+  tries = 3
+  backoff = 10
+
+  constructor(
+    private readonly models: any[],
+    private readonly action: 'update' | 'delete',
+  ) {}
+
+  async handle(): Promise<void> {
+    const engine = getSearchManager().driver()
+
+    if (this.action === 'update') {
+      await engine.update(this.models)
+    } else {
+      await engine.delete(this.models)
+    }
+  }
+}

package/src/testing/SearchFake.ts

@@ -0,0 +1,136 @@
+import type { SearchEngine, SearchResult } from '../contracts/SearchEngine.ts'
+import type { SearchBuilder } from '../SearchBuilder.ts'
+
+/**
+ * Fake search engine for testing. Stores all indexed records in memory
+ * and provides assertion methods.
+ */
+export class SearchFake implements SearchEngine {
+  private indexed = new Map<string, Map<string | number, Record<string, any>>>()
+  private deleted = new Map<string, Set<string | number>>()
+  private flushed = new Set<string>()
+
+  async update(models: any[]): Promise<void> {
+    for (const model of models) {
+      const index = this.resolveIndexName(model)
+      if (!this.indexed.has(index)) this.indexed.set(index, new Map())
+      const key = this.resolveKey(model)
+      const data = typeof model.toSearchableArray === 'function'
+        ? model.toSearchableArray()
+        : { ...model.attributes }
+      this.indexed.get(index)!.set(key, data)
+    }
+  }
+
+  async delete(models: any[]): Promise<void> {
+    for (const model of models) {
+      const index = this.resolveIndexName(model)
+      if (!this.deleted.has(index)) this.deleted.set(index, new Set())
+      const key = this.resolveKey(model)
+      this.deleted.get(index)!.add(key)
+      this.indexed.get(index)?.delete(key)
+    }
+  }
+
+  async search(builder: SearchBuilder): Promise<SearchResult> {
+    const index = this.resolveModelIndexName(builder.model)
+    const records = this.indexed.get(index)
+    if (!records) return { raw: [], keys: [], total: 0 }
+
+    const keys = Array.from(records.keys())
+    return { raw: Array.from(records.values()), keys, total: keys.length }
+  }
+
+  async paginate(builder: SearchBuilder, perPage: number, page: number): Promise<SearchResult> {
+    const result = await this.search(builder)
+    const start = (page - 1) * perPage
+    const keys = result.keys.slice(start, start + perPage)
+    return { raw: result.raw.slice(start, start + perPage), keys, total: result.total }
+  }
+
+  async flush(indexName: string): Promise<void> {
+    this.indexed.delete(indexName)
+    this.flushed.add(indexName)
+  }
+
+  async createIndex(_name: string): Promise<void> {}
+  async deleteIndex(_name: string): Promise<void> {}
+
+  // ── Assertions ────────────────────────────────────────────────────
+
+  assertIndexed(modelClass: any, count?: number): void {
+    const index = this.resolveStaticIndexName(modelClass)
+    const records = this.indexed.get(index)
+    const actual = records?.size ?? 0
+    if (actual === 0) {
+      throw new Error(`Expected [${modelClass.name}] to be indexed, but it was not.`)
+    }
+    if (count !== undefined && actual !== count) {
+      throw new Error(`Expected [${modelClass.name}] to be indexed ${count} time(s), but was indexed ${actual} time(s).`)
+    }
+  }
+
+  assertNotIndexed(modelClass: any): void {
+    const index = this.resolveStaticIndexName(modelClass)
+    const records = this.indexed.get(index)
+    if (records && records.size > 0) {
+      throw new Error(`Expected [${modelClass.name}] to not be indexed, but ${records.size} record(s) found.`)
+    }
+  }
+
+  assertNothingIndexed(): void {
+    let total = 0
+    for (const records of this.indexed.values()) total += records.size
+    if (total > 0) {
+      throw new Error(`Expected nothing to be indexed, but ${total} record(s) found.`)
+    }
+  }
+
+  assertDeleted(modelClass: any, count?: number): void {
+    const index = this.resolveStaticIndexName(modelClass)
+    const deletedKeys = this.deleted.get(index)
+    const actual = deletedKeys?.size ?? 0
+    if (actual === 0) {
+      throw new Error(`Expected [${modelClass.name}] to have deletions, but none found.`)
+    }
+    if (count !== undefined && actual !== count) {
+      throw new Error(`Expected ${count} deletion(s) for [${modelClass.name}], but found ${actual}.`)
+    }
+  }
+
+  assertFlushed(modelClass: any): void {
+    const index = this.resolveStaticIndexName(modelClass)
+    if (!this.flushed.has(index)) {
+      throw new Error(`Expected [${modelClass.name}] index to be flushed, but it was not.`)
+    }
+  }
+
+  /** Get all indexed records for a model class. */
+  getIndexed(modelClass: any): Map<string | number, Record<string, any>> {
+    const index = this.resolveStaticIndexName(modelClass)
+    return this.indexed.get(index) ?? new Map()
+  }
+
+  reset(): void {
+    this.indexed.clear()
+    this.deleted.clear()
+    this.flushed.clear()
+  }
+
+  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 resolveStaticIndexName(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
+  }
+}