@mantiq/search 0.1.0

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@mantiq/search",
+  "version": "0.1.0",
+  "description": "Full-text search abstraction — Algolia, Meilisearch, Typesense, Elasticsearch, database, and collection drivers",
+  "type": "module",
+  "license": "MIT",
+  "author": "Abdullah Khan",
+  "homepage": "https://github.com/mantiqjs/mantiq/tree/main/packages/search",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mantiqjs/mantiq.git",
+    "directory": "packages/search"
+  },
+  "bugs": {
+    "url": "https://github.com/mantiqjs/mantiq/issues"
+  },
+  "keywords": [
+    "mantiq",
+    "mantiqjs",
+    "search",
+    "algolia",
+    "meilisearch",
+    "typesense",
+    "elasticsearch",
+    "full-text-search"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun --packages=external",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "@mantiq/core": "^0.1.0",
+    "@mantiq/database": "^0.1.0"
+  },
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "^5.7.0",
+    "@mantiq/core": "workspace:*",
+    "@mantiq/database": "workspace:*"
+  }
+}

package/src/SearchBuilder.ts

@@ -0,0 +1,149 @@
+import type { SearchEngine, SearchResult } from './contracts/SearchEngine.ts'
+
+export interface WhereClause {
+  field: string
+  value: any
+}
+
+export interface WhereInClause {
+  field: string
+  values: any[]
+}
+
+export interface OrderClause {
+  column: string
+  direction: 'asc' | 'desc'
+}
+
+export interface PaginatedSearchResult<T = any> {
+  data: T[]
+  total: number
+  perPage: number
+  currentPage: number
+  lastPage: number
+  hasMorePages: boolean
+}
+
+export class SearchBuilder {
+  readonly model: any
+  readonly query: string
+  readonly wheres: WhereClause[] = []
+  readonly whereIns: WhereInClause[] = []
+  readonly orders: OrderClause[] = []
+
+  private _limit: number | null = null
+  private _offset: number | null = null
+  private _callback: ((engine: SearchEngine, query: string, builder: SearchBuilder) => any) | null = null
+  private _engine: SearchEngine
+
+  constructor(model: any, query: string, engine: SearchEngine, callback?: (engine: SearchEngine, query: string, builder: SearchBuilder) => any) {
+    this.model = model
+    this.query = query
+    this._engine = engine
+    this._callback = callback ?? null
+  }
+
+  where(field: string, value: any): this {
+    this.wheres.push({ field, value })
+    return this
+  }
+
+  whereIn(field: string, values: any[]): this {
+    this.whereIns.push({ field, values })
+    return this
+  }
+
+  orderBy(column: string, direction: 'asc' | 'desc' = 'asc'): this {
+    this.orders.push({ column, direction })
+    return this
+  }
+
+  take(count: number): this {
+    this._limit = count
+    return this
+  }
+
+  limit(count: number): this {
+    return this.take(count)
+  }
+
+  skip(count: number): this {
+    this._offset = count
+    return this
+  }
+
+  offset(count: number): this {
+    return this.skip(count)
+  }
+
+  getLimit(): number | null {
+    return this._limit
+  }
+
+  getOffset(): number | null {
+    return this._offset
+  }
+
+  /** Execute the search and return hydrated models. */
+  async get(): Promise<any[]> {
+    const results = await this.raw()
+    if (results.keys.length === 0) return []
+    return this.hydrateModels(results)
+  }
+
+  /** Execute a paginated search and return hydrated models with pagination info. */
+  async paginate(perPage = 15, page = 1): Promise<PaginatedSearchResult> {
+    const results = await this._engine.paginate(this, perPage, page)
+    const data = results.keys.length > 0 ? await this.hydrateModels(results) : []
+    const lastPage = Math.max(1, Math.ceil(results.total / perPage))
+
+    return {
+      data,
+      total: results.total,
+      perPage,
+      currentPage: page,
+      lastPage,
+      hasMorePages: page < lastPage,
+    }
+  }
+
+  /** Get raw engine results without hydrating models. */
+  async raw(): Promise<SearchResult> {
+    if (this._callback) {
+      return this._callback(this._engine, this.query, this)
+    }
+    return this._engine.search(this)
+  }
+
+  /** Get just the matching model keys/IDs. */
+  async keys(): Promise<(string | number)[]> {
+    const results = await this.raw()
+    return results.keys
+  }
+
+  /** Get the total count of matching records. */
+  async count(): Promise<number> {
+    const results = await this.raw()
+    return results.total
+  }
+
+  /** Hydrate model instances from the database using the search result keys. */
+  private async hydrateModels(results: SearchResult): Promise<any[]> {
+    if (results.keys.length === 0) return []
+
+    const ModelClass = this.model
+    const pk = ModelClass.primaryKey ?? 'id'
+
+    const models = await ModelClass.query().whereIn(pk, results.keys).get()
+
+    // Preserve search result ordering
+    const modelMap = new Map<string | number, any>()
+    for (const m of models) {
+      modelMap.set(m.getAttribute(pk), m)
+    }
+
+    return results.keys
+      .map((key) => modelMap.get(key))
+      .filter(Boolean)
+  }
+}

package/src/SearchManager.ts

@@ -0,0 +1,95 @@
+import type { SearchEngine } from './contracts/SearchEngine.ts'
+import type { SearchConfig, EngineConfig } from './contracts/SearchConfig.ts'
+import { SearchError } from './errors/SearchError.ts'
+
+type EngineFactory = (config: EngineConfig) => SearchEngine
+
+export class SearchManager {
+  private readonly engines = new Map<string, SearchEngine>()
+  private readonly customEngines = new Map<string, EngineFactory>()
+
+  constructor(
+    private readonly config: SearchConfig,
+    private readonly builtInEngines: Map<string, EngineFactory> = new Map(),
+  ) {}
+
+  /** Get an engine instance by name, lazy-loaded and cached. */
+  driver(name?: string): SearchEngine {
+    const engineName = name ?? this.config.default
+    if (this.engines.has(engineName)) return this.engines.get(engineName)!
+
+    const engineConfig = this.config.engines[engineName]
+    if (!engineConfig) {
+      throw new SearchError(`Search engine "${engineName}" is not configured`, { engine: engineName })
+    }
+
+    const engine = this.createEngine(engineConfig)
+    this.engines.set(engineName, engine)
+    return engine
+  }
+
+  /** Register a custom engine driver. */
+  extend(name: string, factory: EngineFactory): void {
+    this.customEngines.set(name, factory)
+  }
+
+  /** Get the default driver name. */
+  getDefaultDriver(): string {
+    return this.config.default
+  }
+
+  /** Get the search config. */
+  getConfig(): SearchConfig {
+    return this.config
+  }
+
+  /** Get the index prefix. */
+  getPrefix(): string {
+    return this.config.prefix
+  }
+
+  /** Forget a cached engine instance. */
+  forget(name: string): void {
+    this.engines.delete(name)
+  }
+
+  // ── Delegation to default engine ──────────────────────────────────
+
+  async update(models: any[]): Promise<void> {
+    return this.driver().update(models)
+  }
+
+  async delete(models: any[]): Promise<void> {
+    return this.driver().delete(models)
+  }
+
+  async flush(indexName: string): Promise<void> {
+    return this.driver().flush(indexName)
+  }
+
+  async createIndex(name: string, options?: Record<string, any>): Promise<void> {
+    return this.driver().createIndex(name, options)
+  }
+
+  async deleteIndex(name: string): Promise<void> {
+    return this.driver().deleteIndex(name)
+  }
+
+  // ── Private ───────────────────────────────────────────────────────
+
+  private createEngine(config: EngineConfig): SearchEngine {
+    const driverName = config.driver
+
+    // Custom engines first
+    if (this.customEngines.has(driverName)) {
+      return this.customEngines.get(driverName)!(config)
+    }
+
+    // Built-in engines
+    if (this.builtInEngines.has(driverName)) {
+      return this.builtInEngines.get(driverName)!(config)
+    }
+
+    throw new SearchError(`Unsupported search driver "${driverName}"`, { driver: driverName })
+  }
+}

package/src/SearchObserver.ts

@@ -0,0 +1,62 @@
+import { getSearchManager } from './helpers/search.ts'
+
+/**
+ * Model observer that automatically syncs models with the search index.
+ * Registered by makeSearchable() on each searchable model class.
+ */
+export class SearchObserver {
+  async saved(model: any): Promise<void> {
+    if (typeof model.shouldBeSearchable === 'function' && !model.shouldBeSearchable()) {
+      await this.tryDelete(model)
+      return
+    }
+    await this.tryUpdate(model)
+  }
+
+  async deleted(model: any): Promise<void> {
+    await this.tryDelete(model)
+  }
+
+  async forceDeleted(model: any): Promise<void> {
+    await this.tryDelete(model)
+  }
+
+  async restored(model: any): Promise<void> {
+    await this.tryUpdate(model)
+  }
+
+  private async tryUpdate(model: any): Promise<void> {
+    try {
+      const manager = getSearchManager()
+      const config = manager.getConfig()
+
+      if (config.queue) {
+        // Dispatch to queue if configured
+        try {
+          const { dispatch } = await import('@mantiq/queue')
+          const { MakeSearchableJob } = await import('./jobs/MakeSearchableJob.ts')
+          const job = new MakeSearchableJob([model], 'update')
+          const queueName = typeof config.queue === 'string' ? config.queue : undefined
+          const pending = dispatch(job)
+          if (queueName) pending.onQueue(queueName)
+        } catch {
+          // Queue not available, fall back to sync
+          await manager.driver().update([model])
+        }
+      } else {
+        await manager.driver().update([model])
+      }
+    } catch {
+      // Silently fail — search indexing should not break model operations
+    }
+  }
+
+  private async tryDelete(model: any): Promise<void> {
+    try {
+      const manager = getSearchManager()
+      await manager.driver().delete([model])
+    } catch {
+      // Silently fail
+    }
+  }
+}

package/src/SearchServiceProvider.ts

@@ -0,0 +1,59 @@
+import { SearchManager } from './SearchManager.ts'
+import { setSearchManager, SEARCH_MANAGER } from './helpers/search.ts'
+import type { SearchConfig } from './contracts/SearchConfig.ts'
+import { DEFAULT_CONFIG } from './contracts/SearchConfig.ts'
+import type { SearchEngine } from './contracts/SearchEngine.ts'
+
+export class SearchServiceProvider {
+  constructor(private readonly app: any) {}
+
+  register(): void {
+    this.app.singleton(SearchManager, () => {
+      const configRepo = this.app.make?.('ConfigRepository') ?? this.app.config?.()
+      const config: SearchConfig = configRepo?.get?.('search') ?? DEFAULT_CONFIG
+
+      const builtInEngines = new Map<string, (cfg: any) => SearchEngine>()
+
+      builtInEngines.set('collection', () => {
+        const { CollectionEngine } = require('./drivers/CollectionEngine.ts')
+        return new CollectionEngine()
+      })
+
+      builtInEngines.set('database', (cfg) => {
+        const { DatabaseEngine } = require('./drivers/DatabaseEngine.ts')
+        return new DatabaseEngine(cfg.connection)
+      })
+
+      builtInEngines.set('algolia', (cfg) => {
+        const { AlgoliaEngine } = require('./drivers/AlgoliaEngine.ts')
+        return new AlgoliaEngine(cfg.applicationId, cfg.apiKey, cfg.indexSettings)
+      })
+
+      builtInEngines.set('meilisearch', (cfg) => {
+        const { MeilisearchEngine } = require('./drivers/MeilisearchEngine.ts')
+        return new MeilisearchEngine(cfg.host, cfg.apiKey)
+      })
+
+      builtInEngines.set('typesense', (cfg) => {
+        const { TypesenseEngine } = require('./drivers/TypesenseEngine.ts')
+        return new TypesenseEngine(cfg.host, cfg.port, cfg.protocol, cfg.apiKey)
+      })
+
+      builtInEngines.set('elasticsearch', (cfg) => {
+        const { ElasticsearchEngine } = require('./drivers/ElasticsearchEngine.ts')
+        return new ElasticsearchEngine(cfg.hosts, cfg.apiKey, cfg.username, cfg.password)
+      })
+
+      const manager = new SearchManager(config, builtInEngines)
+      setSearchManager(manager)
+      return manager
+    })
+
+    this.app.alias?.(SearchManager, SEARCH_MANAGER)
+  }
+
+  boot(): void {
+    // Service provider boot — nothing needed here.
+    // Models opt in to search via makeSearchable() in their booted().
+  }
+}

package/src/Searchable.ts

@@ -0,0 +1,89 @@
+import { SearchBuilder } from './SearchBuilder.ts'
+import { SearchObserver } from './SearchObserver.ts'
+import { getSearchManager } from './helpers/search.ts'
+
+/**
+ * Makes a Model class searchable. Call in static booted().
+ *
+ * Adds: Model.search(query), Model.makeAllSearchable(), Model.removeAllFromSearch(),
+ *       instance.toSearchableArray(), instance.searchableKey(), instance.shouldBeSearchable()
+ */
+export function makeSearchable(ModelClass: any): void {
+  // ── Static methods ──────────────────────────────────────────────
+
+  /** Start a search query against the model's search index. */
+  ModelClass.search = function (query: string, callback?: any): SearchBuilder {
+    const manager = getSearchManager()
+    return new SearchBuilder(this, query, manager.driver(), callback)
+  }
+
+  /** Get the search index name for this model. */
+  if (!ModelClass.searchableAs) {
+    ModelClass.searchableAs = function (): string {
+      const prefix = getSearchManager().getPrefix()
+      return prefix + (this.table ?? this.name.toLowerCase() + 's')
+    }
+  }
+
+  /** Import all model records into the search index. */
+  ModelClass.makeAllSearchable = async function (chunkSize = 500): Promise<void> {
+    const manager = getSearchManager()
+    const engine = manager.driver()
+    let offset = 0
+
+    while (true) {
+      const models = await this.query().limit(chunkSize).offset(offset).get()
+      if (models.length === 0) break
+
+      const searchable = models.filter((m: any) =>
+        typeof m.shouldBeSearchable === 'function' ? m.shouldBeSearchable() : true,
+      )
+
+      if (searchable.length > 0) {
+        await engine.update(searchable)
+      }
+
+      if (models.length < chunkSize) break
+      offset += chunkSize
+    }
+  }
+
+  /** Remove all model records from the search index. */
+  ModelClass.removeAllFromSearch = async function (): Promise<void> {
+    const manager = getSearchManager()
+    const indexName = this.searchableAs()
+    await manager.driver().flush(indexName)
+  }
+
+  // ── Instance methods (defaults, overridable by the model) ───────
+
+  if (!ModelClass.prototype.toSearchableArray) {
+    ModelClass.prototype.toSearchableArray = function (): Record<string, any> {
+      return this.toObject ? this.toObject() : { ...this.attributes }
+    }
+  }
+
+  if (!ModelClass.prototype.searchableKey) {
+    ModelClass.prototype.searchableKey = function (): string | number {
+      const pk = (this.constructor as any).primaryKey ?? 'id'
+      return this.getAttribute(pk)
+    }
+  }
+
+  if (!ModelClass.prototype.shouldBeSearchable) {
+    ModelClass.prototype.shouldBeSearchable = function (): boolean {
+      return true
+    }
+  }
+
+  // ── Register observer for auto-indexing ─────────────────────────
+
+  try {
+    const observer = new SearchObserver()
+    if (typeof ModelClass.observe === 'function') {
+      ModelClass.observe(observer)
+    }
+  } catch {
+    // Events package may not be available — manual indexing only
+  }
+}

package/src/commands/SearchDeleteIndexCommand.ts

@@ -0,0 +1,22 @@
+import { getSearchManager } from '../helpers/search.ts'
+
+export class SearchDeleteIndexCommand {
+  readonly name = 'search:delete-index'
+  readonly description = 'Delete a search index'
+  readonly usage = 'search:delete-index <name>'
+
+  async handle(args: { positionals: string[] }, io: any): Promise<void> {
+    const name = args.positionals[0]
+    if (!name) {
+      io.error('Please provide an index name: search:delete-index <name>')
+      return
+    }
+
+    try {
+      await getSearchManager().deleteIndex(name)
+      io.success(`Index "${name}" deleted.`)
+    } catch (err) {
+      io.error(`Failed to delete index: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+}

package/src/commands/SearchFlushCommand.ts

@@ -0,0 +1,44 @@
+import { getSearchManager } from '../helpers/search.ts'
+
+export class SearchFlushCommand {
+  readonly name = 'search:flush'
+  readonly description = 'Remove all records for a model from the search index'
+  readonly usage = 'search:flush <model>'
+
+  async handle(args: { positionals: string[] }, io: any): Promise<void> {
+    const modelName = args.positionals[0]
+    if (!modelName) {
+      io.error('Please provide a model name: search:flush <model>')
+      return
+    }
+
+    io.info(`Flushing ${modelName} from search index...`)
+
+    try {
+      const ModelClass = await this.resolveModel(modelName)
+      if (typeof ModelClass.removeAllFromSearch === 'function') {
+        await ModelClass.removeAllFromSearch()
+        io.success(`All ${modelName} records have been removed from the search index.`)
+      } else {
+        io.error(`${modelName} is not searchable. Call makeSearchable() in its booted() method.`)
+      }
+    } catch (err) {
+      io.error(`Failed to flush: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
+  private async resolveModel(name: string): Promise<any> {
+    const paths = [
+      `../../app/Models/${name}.ts`,
+      `../../Models/${name}.ts`,
+      `../../app/Models/${name}`,
+    ]
+    for (const p of paths) {
+      try {
+        const mod = await import(p)
+        return mod[name] ?? mod.default
+      } catch { /* try next */ }
+    }
+    throw new Error(`Could not resolve model "${name}".`)
+  }
+}

package/src/commands/SearchImportCommand.ts

@@ -0,0 +1,45 @@
+import { getSearchManager } from '../helpers/search.ts'
+
+export class SearchImportCommand {
+  readonly name = 'search:import'
+  readonly description = 'Import all records for a model into the search index'
+  readonly usage = 'search:import <model>'
+
+  async handle(args: { positionals: string[] }, io: any): Promise<void> {
+    const modelName = args.positionals[0]
+    if (!modelName) {
+      io.error('Please provide a model name: search:import <model>')
+      return
+    }
+
+    io.info(`Importing ${modelName}...`)
+
+    try {
+      const ModelClass = await this.resolveModel(modelName)
+      if (typeof ModelClass.makeAllSearchable === 'function') {
+        await ModelClass.makeAllSearchable()
+        io.success(`All ${modelName} records have been imported.`)
+      } else {
+        io.error(`${modelName} is not searchable. Call makeSearchable() in its booted() method.`)
+      }
+    } catch (err) {
+      io.error(`Failed to import: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
+  private async resolveModel(name: string): Promise<any> {
+    // Try common model paths
+    const paths = [
+      `../../app/Models/${name}.ts`,
+      `../../Models/${name}.ts`,
+      `../../app/Models/${name}`,
+    ]
+    for (const p of paths) {
+      try {
+        const mod = await import(p)
+        return mod[name] ?? mod.default
+      } catch { /* try next */ }
+    }
+    throw new Error(`Could not resolve model "${name}". Ensure it exists in app/Models/.`)
+  }
+}

package/src/commands/SearchIndexCommand.ts

@@ -0,0 +1,22 @@
+import { getSearchManager } from '../helpers/search.ts'
+
+export class SearchIndexCommand {
+  readonly name = 'search:index'
+  readonly description = 'Create a search index'
+  readonly usage = 'search:index <name>'
+
+  async handle(args: { positionals: string[] }, io: any): Promise<void> {
+    const name = args.positionals[0]
+    if (!name) {
+      io.error('Please provide an index name: search:index <name>')
+      return
+    }
+
+    try {
+      await getSearchManager().createIndex(name)
+      io.success(`Index "${name}" created.`)
+    } catch (err) {
+      io.error(`Failed to create index: ${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+}

package/src/contracts/SearchConfig.ts

@@ -0,0 +1,30 @@
+export type EngineConfig =
+  | { driver: 'collection' }
+  | { driver: 'database'; connection?: string }
+  | { driver: 'algolia'; applicationId: string; apiKey: string; indexSettings?: Record<string, any> }
+  | { driver: 'meilisearch'; host: string; apiKey: string }
+  | { driver: 'typesense'; host: string; port: number; protocol: 'http' | 'https'; apiKey: string }
+  | { driver: 'elasticsearch'; hosts: string[]; apiKey?: string; username?: string; password?: string }
+
+export interface SearchConfig {
+  /** Default engine name */
+  default: string
+  /** Index name prefix (e.g., 'prod_') */
+  prefix: string
+  /** false = sync, true = default queue, string = named queue */
+  queue: boolean | string
+  /** Include __soft_deleted field in indexed data */
+  softDelete: boolean
+  /** Engine configurations keyed by name */
+  engines: Record<string, EngineConfig>
+}
+
+export const DEFAULT_CONFIG: SearchConfig = {
+  default: 'collection',
+  prefix: '',
+  queue: false,
+  softDelete: false,
+  engines: {
+    collection: { driver: 'collection' },
+  },
+}