@strav/search 0.4.30 → 1.0.0-alpha.31

package/src/search_manager.ts

@@ -1,129 +1,147 @@
-import { inject, Configuration, ConfigurationError } from '@strav/kernel'
-import type { SearchEngine } from './search_engine.ts'
-import type { SearchConfig, DriverConfig, SearchScope } from './types.ts'
-import { MeilisearchDriver } from './drivers/meilisearch_driver.ts'
-import { TypesenseDriver } from './drivers/typesense_driver.ts'
-import { AlgoliaDriver } from './drivers/algolia_driver.ts'
-import { NullDriver } from './drivers/null_driver.ts'
-import { EmbeddedDriver } from './drivers/embedded/index.ts'
-import { PostgresFtsDriver } from './drivers/postgres/index.ts'
-
-@inject
-export default class SearchManager {
-  private static _config: SearchConfig
-  private static _engines = new Map<string, SearchEngine>()
-  private static _extensions = new Map<string, (config: DriverConfig) => SearchEngine>()
+/**
+ * `SearchManager` — the facade apps use to talk to the
+ * configured full-text search engine(s).
+ *
+ * Three concept clusters:
+ *
+ *   - **Engines.** Apps declare engines in `config.search.drivers`;
+ *     the manager constructs them lazily on first `engine(name)`
+ *     call. Custom drivers register via `manager.extend(name,
+ *     factory)`.
+ *
+ *   - **Index naming.** `manager.indexName(name)` prepends the
+ *     configured `prefix` so apps can namespace per-env or
+ *     per-app without rewriting their model code. The
+ *     `searchable()` mixin always resolves through this so apps
+ *     never embed raw index names in queries.
+ *
+ *   - **Test hooks.** `useEngine(name, engine)` swaps an engine
+ *     instance for the named slot — typically a `MemoryDriver`
+ *     in unit tests against code that resolves
+ *     `engine('meilisearch')`.
+ *
+ * Multitenancy: the V1 surface is single-tenant. The Postgres
+ * driver relies on `app.tenant_id` RLS (same hook
+ * `@strav/rag` / `@strav/database` use) for per-tenant
+ * isolation. Per-tenant index prefixing for Meili/Typesense
+ * lands in V1.1 if asked.
+ */
 
-  constructor(config: Configuration) {
-    SearchManager._config = {
-      default: config.get('search.default', 'null') as string,
-      prefix: config.get('search.prefix', '') as string,
-      drivers: config.get('search.drivers', {}) as Record<string, DriverConfig>,
-    }
-  }
+// biome-ignore lint/style/useImportType: PostgresDatabase value import for the container path that will wire PostgresFtsDriver.
+import { PostgresDatabase } from '@strav/database'
+// biome-ignore lint/style/useImportType: Application value import for the container handle.
+import { Application, inject } from '@strav/kernel'
+import { MeilisearchDriver } from './drivers/meilisearch/meilisearch_driver.ts'
+import { MemoryDriver } from './drivers/memory/memory_driver.ts'
+import { PostgresFtsDriver } from './drivers/postgres/postgres_fts_driver.ts'
+import { TypesenseDriver } from './drivers/typesense/typesense_driver.ts'
+import { SearchConfigError } from './search_error.ts'
+import type { SearchEngine } from './search_engine.ts'
+import type { DriverConfig, SearchConfig } from './types.ts'
 
-  static get config(): SearchConfig {
-    if (!SearchManager._config) {
-      throw new ConfigurationError(
-        'SearchManager not configured. Resolve it through the container first.'
-      )
-    }
-    return SearchManager._config
-  }
+export interface SearchManagerOptions {
+  config: SearchConfig
+  /** Optional — required only if a `postgres-fts` driver is configured. */
+  db?: PostgresDatabase
+}
 
-  /** Get an engine by name, or the default engine. Engines are lazily created. */
-  static engine(name?: string): SearchEngine {
-    const key = name ?? SearchManager.config.default
+/** Factory for custom drivers — apps register via `manager.extend(name, factory)`. */
+export type EngineFactory = (config: DriverConfig) => SearchEngine
 
-    let engine = SearchManager._engines.get(key)
-    if (engine) return engine
+@inject()
+export class SearchManager {
+  readonly config: SearchConfig
+  private readonly db: PostgresDatabase | undefined
+  private readonly engines = new Map<string, SearchEngine>()
+  private readonly extensions = new Map<string, EngineFactory>()
 
-    const driverConfig = SearchManager.config.drivers[key]
-    if (!driverConfig) {
-      throw new ConfigurationError(`Search driver "${key}" is not configured.`)
+  constructor(options: SearchManagerOptions) {
+    if (!options.config.drivers[options.config.default]) {
+      throw new SearchConfigError(
+        `SearchManager: default driver "${options.config.default}" is not configured.`,
+        {
+          context: {
+            default: options.config.default,
+            available: Object.keys(options.config.drivers),
+          },
+        },
+      )
     }
-
-    engine = SearchManager.createEngine(key, driverConfig)
-    SearchManager._engines.set(key, engine)
-    return engine
+    this.config = options.config
+    this.db = options.db
   }
 
-  /** The index name prefix from configuration. */
-  static get prefix(): string {
-    return SearchManager._config?.prefix ?? ''
-  }
+  // ─── Engine management ────────────────────────────────────────────────
 
   /**
-   * Resolve a full index name by applying the configured prefix and
-   * optional per-tenant scope. Per-tenant scoping namespaces the index
-   * as `${prefix}t${tenantId}_${name}` so two tenants on the same
-   * shared engine cannot read or overwrite each other's documents.
-   *
-   * Apps that don't need multi-tenant isolation can omit the scope.
-   * The driver layer is unchanged — namespacing happens here at the
-   * manager boundary.
+   * Resolve an engine by name (or the default when omitted).
+   * Engines are constructed lazily on first use + memoized.
    */
-  static indexName(name: string, scope?: SearchScope | null): string {
-    const base = SearchManager.prefix ? `${SearchManager.prefix}${name}` : name
-    if (!scope || scope.tenantId === undefined || scope.tenantId === null) return base
-    // Validate tenant identifier — anything that ends up in an index
-    // name lands in URL paths / SQL identifiers downstream, so refuse
-    // values that could escape the namespace. Letters, digits, dashes,
-    // underscores only.
-    const tenantId = String(scope.tenantId)
-    if (!/^[a-zA-Z0-9_-]+$/.test(tenantId)) {
-      throw new ConfigurationError(
-        `SearchManager.indexName: invalid tenantId ${JSON.stringify(tenantId)} — ` +
-          `must match /^[a-zA-Z0-9_-]+$/.`
-      )
+  engine(name?: string): SearchEngine {
+    const key = name ?? this.config.default
+    const cached = this.engines.get(key)
+    if (cached) return cached
+    const cfg = this.config.drivers[key]
+    if (!cfg) {
+      throw new SearchConfigError(`SearchManager: driver "${key}" is not configured.`, {
+        context: { requested: key, available: Object.keys(this.config.drivers) },
+      })
     }
-    if (SearchManager.prefix) {
-      return `${SearchManager.prefix}t${tenantId}_${name}`
-    }
-    return `t${tenantId}_${name}`
+    const engine = this.createEngine(key, cfg)
+    this.engines.set(key, engine)
+    return engine
   }
 
-  /** Register a custom driver factory. */
-  static extend(name: string, factory: (config: DriverConfig) => SearchEngine): void {
-    SearchManager._extensions.set(name, factory)
+  /** Register a custom driver. Subsequent `engine(name)` calls resolving to a `driver: <name>` will use it. */
+  extend(name: string, factory: EngineFactory): void {
+    this.extensions.set(name, factory)
   }
 
-  /** Replace an engine at runtime (e.g. for testing). */
-  static useEngine(engine: SearchEngine): void {
-    SearchManager._engines.set(engine.name, engine)
+  /** Hand-wire an engine instance under a name (tests / one-off drivers). */
+  useEngine(name: string, engine: SearchEngine): void {
+    this.engines.set(name, engine)
   }
 
-  /** Reset all state. Intended for test teardown. */
-  static reset(): void {
-    SearchManager._engines.clear()
-    SearchManager._extensions.clear()
-    SearchManager._config = undefined as any
+  /**
+   * Compose the configured prefix with `name`. The `searchable()`
+   * mixin always routes through this so apps that toggle the
+   * prefix in config don't have to rewrite calls.
+   */
+  indexName(name: string): string {
+    return this.config.prefix ? `${this.config.prefix}${name}` : name
   }
 
-  private static createEngine(name: string, config: DriverConfig): SearchEngine {
+  // ─── Internals ────────────────────────────────────────────────────────
+
+  private createEngine(name: string, config: DriverConfig): SearchEngine {
     const driverName = config.driver ?? name
 
-    const extension = SearchManager._extensions.get(driverName)
+    const extension = this.extensions.get(driverName)
     if (extension) return extension(config)
 
     switch (driverName) {
+      case 'memory':
+        return new MemoryDriver()
       case 'meilisearch':
         return new MeilisearchDriver(config)
       case 'typesense':
         return new TypesenseDriver(config)
-      case 'algolia':
-        return new AlgoliaDriver(config)
-      case 'embedded':
-        return new EmbeddedDriver(config)
-      case 'postgres-fts':
       case 'postgres':
-        return new PostgresFtsDriver(config)
-      case 'null':
-        return new NullDriver()
+      case 'postgres-fts':
+        if (!this.db) {
+          throw new SearchConfigError(
+            'SearchManager: postgres-fts driver requires PostgresDatabase. Register DatabaseProvider before SearchProvider.',
+          )
+        }
+        return PostgresFtsDriver.fromConfig(this.db, config)
       default:
-        throw new ConfigurationError(
-          `Unknown search driver "${driverName}". Register it with SearchManager.extend().`
+        throw new SearchConfigError(
+          `SearchManager: unknown driver "${driverName}". Register it via \`manager.extend("${driverName}", factory)\`.`,
+          { context: { driver: driverName, name } },
         )
     }
   }
 }
+
+/** Public alias for the container-resolution helper apps occasionally pass around. */
+export type SearchManagerResolver = (app: Application) => SearchManager

package/src/search_provider.ts

@@ -1,16 +1,78 @@
-import { ServiceProvider } from '@strav/kernel'
-import type { Application } from '@strav/kernel'
-import SearchManager from './search_manager.ts'
+/**
+ * `SearchProvider` — `ServiceProvider` that wires `SearchManager`
+ * into the container from `config.search`.
+ *
+ * Eager construction at boot — a malformed config or a missing
+ * postgres dependency should fail before the first call hits.
+ * Apps register `DatabaseProvider` before this one when any
+ * `postgres-fts` driver is configured; the `dependencies` array
+ * declares the order.
+ *
+ * Config defaults: when `config.search` is absent entirely, the
+ * provider boots with the in-process `memory` driver as the
+ * default so apps can call `search.engine().createIndex(...)` /
+ * `engine().search(...)` in dev without configuration.
+ * Production apps override via a real `config/search.ts`.
+ */
 
-export default class SearchProvider extends ServiceProvider {
-  readonly name = 'search'
+// biome-ignore lint/style/useImportType: PostgresDatabase value import — required when any postgres-fts driver is configured. Loaded conditionally below.
+import { PostgresDatabase } from '@strav/database'
+import { type Application, ConfigError, ConfigRepository, ServiceProvider } from '@strav/kernel'
+import { SearchManager, type SearchManagerOptions } from './search_manager.ts'
+import { SearchableRegistry } from './searchable_registry.ts'
+import type { SearchConfig } from './types.ts'
+
+export class SearchProvider extends ServiceProvider {
+  override readonly name = 'search'
   override readonly dependencies = ['config']
 
   override register(app: Application): void {
-    app.singleton(SearchManager)
+    app.singleton(SearchableRegistry, () => new SearchableRegistry())
+    app.singleton(SearchManager, (c) => {
+      const raw = c.resolve(ConfigRepository).get('search') as Partial<SearchConfig> | undefined
+      const config = applyDefaults(raw)
+
+      const opts: SearchManagerOptions = { config }
+
+      const needsDb = Object.values(config.drivers).some(
+        (d) => d.driver === 'postgres-fts' || d.driver === 'postgres',
+      )
+      if (needsDb) {
+        try {
+          opts.db = c.resolve(PostgresDatabase)
+        } catch (cause) {
+          throw new ConfigError(
+            'SearchProvider: at least one driver uses `driver: "postgres-fts"` but PostgresDatabase is not registered. Register DatabaseProvider before SearchProvider.',
+            { cause },
+          )
+        }
+      }
+      return new SearchManager(opts)
+    })
   }
 
   override boot(app: Application): void {
+    // Force-resolve so config errors surface at boot, not on first call.
     app.resolve(SearchManager)
   }
 }
+
+/**
+ * Fill in defaults for omitted config fields. Apps with no
+ * `config/search.ts` at all get a working in-memory setup.
+ */
+function applyDefaults(raw: Partial<SearchConfig> | undefined): SearchConfig {
+  const config: Partial<SearchConfig> = raw ?? {}
+  const drivers = config.drivers ?? { memory: { driver: 'memory' } }
+  const def = config.default ?? Object.keys(drivers)[0] ?? 'memory'
+  if (!drivers[def]) {
+    throw new ConfigError(
+      `SearchProvider: default driver "${def}" is not declared in config.search.drivers.`,
+    )
+  }
+  return {
+    default: def,
+    ...(config.prefix !== undefined ? { prefix: config.prefix } : {}),
+    drivers,
+  }
+}