@strav/search 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# @stravigor/search
+
+Full-text search for the [Strav](https://www.npmjs.com/package/@stravigor/core) framework. Unified API for Meilisearch, Typesense, and Algolia with automatic indexing via model events.
+
+## Install
+
+```bash
+bun add @stravigor/search
+bun strav install search
+```
+
+Requires `@stravigor/core` as a peer dependency.
+
+## Setup
+
+```ts
+import { SearchProvider } from '@stravigor/search'
+
+app.use(new SearchProvider())
+```
+
+## Searchable Models
+
+```ts
+import { searchable } from '@stravigor/search'
+
+class Post extends searchable(BaseModel) {
+  static searchableAs = 'posts'
+
+  toSearchableDocument() {
+    return { id: this.id, title: this.title, body: this.body }
+  }
+}
+```
+
+## Usage
+
+```ts
+import { search } from '@stravigor/search'
+
+// Search
+const results = await search.query('posts', 'hello world', {
+  filters: 'status = published',
+  limit: 20,
+})
+
+// Manual indexing
+await search.index('posts', [{ id: 1, title: 'Hello' }])
+await search.delete('posts', ['1'])
+```
+
+## Drivers
+
+- **Meilisearch** — fast, typo-tolerant, self-hosted
+- **Typesense** — open-source, instant search
+- **Algolia** — hosted search-as-a-service
+- **Null** — no-op driver for testing
+
+## CLI
+
+```bash
+bun strav search:import    # Import all searchable models
+bun strav search:flush     # Flush all indexes
+```
+
+## Documentation
+
+See the full [Search guide](../../guides/search.md).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@strav/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": {
+    "@strav/kernel": "0.1.0",
+    "@strav/database": "0.1.0",
+    "@strav/cli": "0.1.0"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "commander": "^14.0.3"
+  }
+}

package/src/commands/search_flush.ts

@@ -0,0 +1,41 @@
+import type { Command } from 'commander'
+import chalk from 'chalk'
+import { bootstrap, shutdown } from '@stravigor/cli'
+import { BaseModel } from '@stravigor/database'
+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/cli'
+import { BaseModel } from '@stravigor/database'
+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: { chunk: 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?.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/kernel'
+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/kernel'
+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 }
+  }
+}