@strav/search 0.4.30 → 1.0.0-alpha.31

package/src/searchable.ts

@@ -1,211 +1,224 @@
-import type { BaseModel } from '@strav/database'
-import type { NormalizeConstructor } from '@strav/kernel'
-import { Emitter } from '@strav/kernel'
-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.
+ * `searchable(Repository)` — class mixin that bolts full-text
+ * search methods onto a Repository so apps can index a row and
+ * query its engine without juggling `SearchManager` calls by
+ * hand.
  *
- * @example
- * import { BaseModel } from '@strav/database'
- * import { searchable } from '@strav/search'
+ * ```ts
+ * export class ArticleRepository extends searchable(Repository<Article>) {
+ *   static override readonly schema = articleSchema
+ *   static override readonly model = Article
  *
- * class Article extends searchable(BaseModel) {
- *   declare id: number
- *   declare title: string
- *   declare body: string
+ *   constructor(options: RepositoryOptions, search: SearchManager) {
+ *     super(options)
+ *     this.search = search
+ *   }
  *
- *   static searchableAs() { return 'articles' }
+ *   protected override toSearchableDocument(a: Article) {
+ *     return { id: a.id, title: a.title, body: a.body, status: a.status }
+ *   }
  *
- *   toSearchableArray() {
- *     return { id: this.id, title: this.title, body: this.body }
+ *   protected static override searchableSettings() {
+ *     return {
+ *       searchableAttributes: ['title', 'body'],
+ *       filterableAttributes: ['status'],
+ *       sortableAttributes: ['created_at'],
+ *     }
  *   }
  * }
+ * ```
+ *
+ * Usage:
+ *
+ * ```ts
+ * await articles.createIndex()                      // first boot
+ * const a = await articles.create(...)
+ * await articles.index(a)                           // push to engine
+ *
+ * const r = await articles.search('hello', { perPage: 10 })
+ *
+ * await articles.delete(a)
+ * await articles.removeFromIndex(a)
+ * ```
+ *
+ * Why not auto-index on `create` / `update`?
+ *
+ *   V1 ships the explicit pattern (mirrors `@strav/rag`'s
+ *   `retrievable()`). An auto-hook would couple persistence to
+ *   the search engine's availability — a transient
+ *   Meilisearch outage would fail the create call. Apps that
+ *   want auto-index wire it themselves via
+ *   `events.on('article.created', m => articles.index(m))` so
+ *   they own the failure mode (fire-and-forget vs awaited vs
+ *   queued via `@strav/queue`).
+ *
+ * Extension points (all optional overrides):
+ *
+ *   - `indexName()` — defaults to the table name from the
+ *     schema. Override to point at a different index.
  *
- * // Composable with other mixins:
- * import { compose } from '@strav/kernel'
- * class Article extends compose(BaseModel, softDeletes, searchable) { }
+ *   - `toSearchableDocument(model)` — defaults to copying every
+ *     own non-underscore field on the model. The default works
+ *     for simple row shapes; apps with derived / nested fields
+ *     override.
  *
- * // Boot auto-indexing (in app bootstrap):
- * Article.bootSearch('article')
+ *   - `static searchableSettings()` — `IndexSettings` for
+ *     `createIndex()`. Defaults to `undefined` (engine
+ *     defaults).
  *
- * // Search:
- * const results = await Article.search('typescript')
+ *   - `shouldBeSearchable(model)` — gates indexing. Return
+ *     `false` for drafts / soft-deleted / private rows. The
+ *     default is `true`.
  */
-export function searchable<T extends NormalizeConstructor<typeof BaseModel>>(Base: T) {
-  return class Searchable extends Base {
-    private static _searchBooted = false
 
+import type { Repository } from '@strav/database'
+import type { SearchManager } from './search_manager.ts'
+import type { SearchOptions, SearchResult } from './types.ts'
+
+/** Minimal constructor type we can mix into. Wider than `typeof Repository` so subclasses with extra ctor args still type-check. */
+// biome-ignore lint/suspicious/noExplicitAny: mixin constructor signatures intentionally accept any[]; the user-side subclass narrows.
+type RepositoryConstructor<TModel extends object> = new (...args: any[]) => Repository<TModel>
+
+export function searchable<TModel extends object, TBase extends RepositoryConstructor<TModel>>(
+  Base: TBase,
+) {
+  abstract class SearchableRepository extends Base {
     /**
-     * The search index name for this model.
-     * Defaults to the table name. Override to customize.
+     * The framework's `SearchManager`. Assigned by the user-side
+     * subclass constructor. Public on purpose — apps that want to
+     * drop to the raw engine (`search.engine().…`) have a hook.
      */
-    static searchableAs(): string {
-      return (this as unknown as typeof BaseModel).tableName
-    }
+    search!: SearchManager
 
     /**
-     * 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 '_'.
+     * Index name for this repository's documents. Defaults to
+     * the schema name. Override to point at a different index or
+     * to compose per-env suffixes.
      */
-    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
+    protected indexName(): string {
+      const ctor = this.constructor as unknown as { schema: { name: string } }
+      return ctor.schema.name
     }
 
     /**
-     * Whether this model instance should be indexed.
-     * Override to conditionally exclude records (e.g. drafts).
+     * Build the document persisted to the engine. Default copies
+     * every non-underscore own property. Apps with structured
+     * content override.
      */
-    shouldBeSearchable(): boolean {
-      return true
+    protected toSearchableDocument(model: TModel): Record<string, unknown> {
+      const out: Record<string, unknown> = {}
+      for (const [key, value] of Object.entries(model as Record<string, unknown>)) {
+        if (key.startsWith('_')) continue
+        out[key] = value
+      }
+      return out
     }
 
     /**
-     * Index settings for this model (searchable/filterable/sortable attributes).
-     * Override to configure. Returns undefined by default (use engine defaults).
+     * Per-class index settings — `searchableAttributes`,
+     * `filterableAttributes`, etc. Returns `undefined` by
+     * default; engines fall back to their own defaults.
      */
-    static searchableSettings(): IndexSettings | undefined {
+    protected static searchableSettings(): import('./types.ts').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)
+    /** Whether `model` should currently be indexed. Override to skip drafts / soft-deleted. */
+    protected shouldBeSearchable(_model: TModel): boolean {
+      return true
     }
 
-    /** 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)
+    /** Resolve the fully-prefixed index name through the manager. */
+    private resolvedIndex(): string {
+      return this.search.indexName(this.indexName())
     }
 
-    // ── 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)
-    }
+    // ─── Per-row writes ───────────────────────────────────────────────────
 
     /**
-     * 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.
+     * Upsert one model into the engine. When
+     * `shouldBeSearchable(model)` returns `false`, the row is
+     * dropped from the index instead (so the "this just became
+     * private" path doesn't need a separate call).
      */
-    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>[]
+    async index(model: TModel): Promise<void> {
+      const id = modelId(model)
+      const indexName = this.resolvedIndex()
+      const engine = this.search.engine()
+      if (!this.shouldBeSearchable(model)) {
+        await engine.delete(indexName, id)
+        return
+      }
+      const document = this.toSearchableDocument(model)
+      await engine.upsert(indexName, id, document)
+    }
 
-        if (rows.length === 0) break
+    /** Drop one model from the engine. */
+    async removeFromIndex(model: TModel): Promise<void> {
+      const id = modelId(model)
+      await this.search.engine().delete(this.resolvedIndex(), id)
+    }
 
-        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
-      }
+    // ─── Reads ────────────────────────────────────────────────────────────
 
-      return imported
+    /** Full-text search this repository's index. */
+    async searchQuery(query: string, options?: SearchOptions): Promise<SearchResult> {
+      return this.search.engine().search(this.resolvedIndex(), query, options)
     }
 
-    /** 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)
+    // ─── Bulk operations ──────────────────────────────────────────────────
+
+    /**
+     * Create this repository's index with the static
+     * `searchableSettings()` payload. Idempotent on every
+     * driver. Call once at boot or as part of a deploy.
+     */
+    async createIndex(): Promise<void> {
+      const ctor = this.constructor as unknown as typeof SearchableRepository
+      const settings = ctor.searchableSettings()
+      await this.search.engine().createIndex(this.resolvedIndex(), settings)
     }
 
-    /** 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)
+    /** Drop every document in this repository's index (keeps the index itself). */
+    async flushIndex(): Promise<void> {
+      await this.search.engine().flush(this.resolvedIndex())
     }
 
     /**
-     * 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).
+     * Walk every row and upsert it into the engine. Useful for
+     * backfilling a new index or recovering after a schema
+     * change. Returns the total row count processed.
      */
-    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') {
-          try {
-            await (model as any).searchIndex()
-          } catch {
-            // Search indexing is secondary — failures should not break the event pipeline
-          }
-        }
-      }
-
-      const removeFn = async (model: unknown) => {
-        if (model && typeof (model as any).searchRemove === 'function') {
-          try {
-            await (model as any).searchRemove()
-          } catch {
-            // Search removal is secondary — failures should not break the event pipeline
-          }
-        }
+    async importAll(batchSize: number = 500): Promise<number> {
+      let processed = 0
+      let offset = 0
+      while (true) {
+        const rows = await this.query().orderBy('id', 'asc').limit(batchSize).offset(offset).get()
+        if (rows.length === 0) break
+        for (const row of rows) await this.index(row)
+        processed += rows.length
+        offset += rows.length
+        if (rows.length < batchSize) break
       }
-
-      Emitter.on(`${eventPrefix}.created`, indexFn)
-      Emitter.on(`${eventPrefix}.updated`, indexFn)
-      Emitter.on(`${eventPrefix}.synced`, indexFn)
-      Emitter.on(`${eventPrefix}.deleted`, removeFn)
+      return processed
     }
   }
+  return SearchableRepository
 }
 
-/** 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>
+/**
+ * Coerce a model's `id` to the form the engine accepts. Models
+ * use ULID / UUID / bigSerial — all three round-trip through
+ * `String(...)` cleanly. We pass numbers through verbatim so
+ * engines that key on numeric ids don't lose precision.
+ */
+function modelId(model: object): string | number {
+  const id = (model as { id?: unknown }).id
+  if (id === undefined || id === null) {
+    throw new Error(
+      `searchable: model has no \`id\`. The mixin only works on models with a single-column id.`,
+    )
+  }
+  if (typeof id === 'number') return id
+  return String(id)
+}

package/src/searchable_registry.ts

@@ -0,0 +1,61 @@
+/**
+ * `SearchableRegistry` — bag of named pointers to searchable
+ * repositories so the `search:import` and `search:flush`
+ * console commands can resolve them at runtime.
+ *
+ * The framework can't statically discover which repositories use
+ * the `searchable()` mixin — apps register them at boot:
+ *
+ *   const registry = app.resolve(SearchableRegistry)
+ *   registry.register('articles', ArticleRepository)
+ *
+ * Then:
+ *
+ *   bun strav search:import articles
+ *   bun strav search:import --all
+ *
+ * resolves the repository through the container and calls the
+ * mixin methods. The repo class must expose `importAll`,
+ * `flushIndex`, and `createIndex` — the `searchable()` mixin
+ * provides all three.
+ */
+
+import { inject } from '@strav/kernel'
+import { SearchError } from './search_error.ts'
+
+export interface SearchableTarget {
+  importAll(batchSize?: number): Promise<number>
+  flushIndex(): Promise<void>
+  createIndex(): Promise<void>
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: container-resolved constructor; the user-side class narrows.
+type SearchableConstructor = new (...args: any[]) => SearchableTarget
+
+@inject()
+export class SearchableRegistry {
+  private readonly targets = new Map<string, SearchableConstructor>()
+
+  /** Register a repository class under `name`. Resolved through the container at command time. */
+  register(name: string, ctor: SearchableConstructor): void {
+    this.targets.set(name, ctor)
+  }
+
+  /** List every registered name — used by `search:import --all`. */
+  names(): readonly string[] {
+    return [...this.targets.keys()]
+  }
+
+  /** Resolve the constructor for one name. Throws when unregistered. */
+  resolve(name: string): SearchableConstructor {
+    const ctor = this.targets.get(name)
+    if (ctor === undefined) {
+      throw new SearchError(`SearchableRegistry: no searchable registered under "${name}".`, {
+        code: 'search.registry.not_found',
+        status: 404,
+        context: { requested: name, available: this.names() },
+      })
+    }
+    return ctor
+  }
+}

package/src/types.ts

@@ -1,96 +1,106 @@
-// ── Documents ─────────────────────────────────────────────────────────────
-
-export interface SearchDocument {
-  id: string | number
-  [key: string]: unknown
-}
-
-// ── Multi-tenant scope ────────────────────────────────────────────────────
-
 /**
- * Per-tenant scope applied at index-name resolution. Drivers don't see
- * the scope directly — `SearchManager.indexName(name, scope)` rewrites
- * the index name to `${prefix}t${tenantId}_${name}` so two tenants on
- * the same shared engine read independent indexes.
+ * `@strav/search` types — the data shapes apps see when indexing
+ * and querying full-text search indexes.
+ *
+ * Three concept clusters:
  *
- * The tenantId must match `/^[a-zA-Z0-9_-]+$/`; anything else throws
- * (the value lands in URL paths and SQL identifiers downstream).
+ *   - **Documents** — the unit a search engine indexes. Every
+ *     document has an `id` (string or number) and an arbitrary
+ *     bag of fields. The mixin's `toSearchableDocument(model)`
+ *     produces these.
+ *
+ *   - **Queries + results** — `SearchOptions` carries filters,
+ *     sort, paging, and highlight hints; `SearchResult` carries
+ *     the matching hits, total count, and per-engine processing
+ *     time when available.
+ *
+ *   - **Configuration** — `SearchConfig` is `config.search`.
+ *     Apps declare drivers under `drivers`, pick one as
+ *     `default`, and optionally prefix index names with
+ *     `prefix` to namespace per-app or per-environment.
  */
-export interface SearchScope {
-  tenantId: string | number
+
+// ─── Documents ───────────────────────────────────────────────────────────
+
+export interface SearchDocument {
+  id: string | number
+  [field: string]: unknown
 }
 
-// ── Index settings ────────────────────────────────────────────────────────
+// ─── Index settings ──────────────────────────────────────────────────────
 
 export interface IndexSettings {
-  /** Fields to use for full-text search. */
+  /** Fields to use for full-text search. Order matters — earlier = higher BM25 weight on engines that honor it. */
   searchableAttributes?: string[]
-  /** Fields to return in results. */
+  /** Fields to return on each hit. Defaults to every field. */
   displayedAttributes?: string[]
-  /** Fields that can be used as filters. */
+  /** Fields that can be used in `SearchOptions.filter`. */
   filterableAttributes?: string[]
-  /** Fields that can be used for sorting. */
+  /** Fields that can be used in `SearchOptions.sort`. */
   sortableAttributes?: string[]
-  /** Primary key field name (defaults to 'id'). */
+  /** Primary key field name (defaults to `'id'`). */
   primaryKey?: string
 }
 
-// ── Search options & results ──────────────────────────────────────────────
+// ─── 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']. */
+  /**
+   * Filter on indexed fields. Object form is the portable shape:
+   * `{ status: 'published', kind: 'doc' }` — flat equality AND.
+   * Driver-specific filter strings are NOT accepted in V1 to keep
+   * cross-driver portability.
+   */
+  filter?: Record<string, unknown>
+  /** Sort directives, e.g. `['created_at:desc']`. Engine support varies. */
   sort?: string[]
-  /** Page number (1-based). */
+  /** Page number (1-based). Default `1`. */
   page?: number
-  /** Results per page. */
+  /** Hits per page. Default `20`. */
   perPage?: number
-  /** Fields to return in results. */
+  /** Restrict returned fields. */
   attributesToRetrieve?: string[]
-  /** Fields to highlight in results. */
+  /** Highlight these fields. Engines wrap matches with `<mark>` tags. */
   attributesToHighlight?: string[]
 }
 
 export interface SearchResult {
-  /** The matching documents. */
   hits: SearchHit[]
-  /** Total number of matching documents (estimated). */
+  /** Total matching documents (estimated on engines that don't compute the exact total). */
   totalHits: number
-  /** Current page. */
+  /** The page that was returned (1-based). */
   page: number
-  /** Results per page. */
+  /** The page size that was returned. */
   perPage: number
-  /** Processing time in milliseconds (if provided by the engine). */
+  /** Engine-side processing time when reported, in milliseconds. */
   processingTimeMs?: number
 }
 
 export interface SearchHit {
-  /** The document data. */
   document: Record<string, unknown>
-  /** Highlighted fields (if requested). */
+  /** Highlighted fields when `attributesToHighlight` was requested. */
   highlights?: Record<string, string>
 }
 
-// ── Configuration ─────────────────────────────────────────────────────────
+// ─── Configuration ───────────────────────────────────────────────────────
 
+/**
+ * `config.search` shape. Apps that don't configure search get a
+ * sensible default (the in-process `memory` driver) — see
+ * `SearchProvider.boot()`.
+ */
 export interface SearchConfig {
-  /** Default driver name. */
+  /** Default driver name — must be a key in `drivers`. */
   default: string
-  /** Index name prefix (e.g. 'myapp_'). */
-  prefix: string
+  /** Optional index-name prefix, applied via `SearchManager.indexName(name)`. */
+  prefix?: string
   /** Driver configurations keyed by name. */
   drivers: Record<string, DriverConfig>
 }
 
 export interface DriverConfig {
+  /** Driver kind — `'memory'`, `'meilisearch'`, `'typesense'`, `'postgres-fts'`, or a name registered via `manager.extend(...)`. */
   driver: string
-  host?: string
-  port?: number
-  apiKey?: string
-  /** Algolia application ID. */
-  appId?: string
-  /** Protocol — 'http' or 'https'. */
-  protocol?: string
+  /** Free-form driver-specific fields (host, apiKey, schema, …). */
   [key: string]: unknown
 }