@strav/search 0.3.32 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/search",
-  "version": "0.3.32",
+  "version": "0.4.0",
   "type": "module",
   "description": "Full-text search for the Strav framework",
   "license": "MIT",
@@ -18,9 +18,9 @@
     "tsconfig.json"
   ],
   "peerDependencies": {
-    "@strav/kernel": "0.3.32",
-    "@strav/database": "0.3.32",
-    "@strav/cli": "0.3.32"
+    "@strav/kernel": "0.4.0",
+    "@strav/database": "0.4.0",
+    "@strav/cli": "0.4.0"
   },
   "scripts": {
     "test": "bun test tests/",

package/src/helpers.ts

@@ -6,6 +6,7 @@ import type {
   SearchResult,
   IndexSettings,
   DriverConfig,
+  SearchScope,
 } from './types.ts'
 
 /**
@@ -67,4 +68,53 @@ export const search = {
   deleteIndex(index: string): Promise<void> {
     return SearchManager.engine().deleteIndex(SearchManager.indexName(index))
   },
+
+  /**
+   * Return a tenant-scoped wrapper of this helper. All index names
+   * resolved through it are namespaced as `${prefix}t${tenantId}_${name}`,
+   * giving two tenants on the same shared engine independent indexes.
+   *
+   * @example
+   * await search.for({ tenantId: 42 }).upsert('articles', 1, { … })
+   * await search.for({ tenantId: 42 }).query('articles', 'lookup')
+   *
+   * Apps that don't need multi-tenant isolation skip `.for()` and call
+   * the top-level helpers directly.
+   */
+  for(scope: SearchScope): ScopedSearch {
+    return makeScoped(scope)
+  },
+}
+
+// ── Scoped helper ────────────────────────────────────────────────────────
+
+export interface ScopedSearch {
+  query(index: string, query: string, options?: SearchOptions): Promise<SearchResult>
+  upsert(index: string, id: string | number, document: Record<string, unknown>): Promise<void>
+  upsertMany(index: string, documents: SearchDocument[]): Promise<void>
+  delete(index: string, id: string | number): Promise<void>
+  deleteMany(index: string, ids: Array<string | number>): Promise<void>
+  flush(index: string): Promise<void>
+  createIndex(index: string, options?: IndexSettings): Promise<void>
+  deleteIndex(index: string): Promise<void>
+}
+
+function makeScoped(scope: SearchScope): ScopedSearch {
+  return {
+    query: (index, query, options) =>
+      SearchManager.engine().search(SearchManager.indexName(index, scope), query, options),
+    upsert: (index, id, document) =>
+      SearchManager.engine().upsert(SearchManager.indexName(index, scope), id, document),
+    upsertMany: (index, documents) =>
+      SearchManager.engine().upsertMany(SearchManager.indexName(index, scope), documents),
+    delete: (index, id) =>
+      SearchManager.engine().delete(SearchManager.indexName(index, scope), id),
+    deleteMany: (index, ids) =>
+      SearchManager.engine().deleteMany(SearchManager.indexName(index, scope), ids),
+    flush: index => SearchManager.engine().flush(SearchManager.indexName(index, scope)),
+    createIndex: (index, options) =>
+      SearchManager.engine().createIndex(SearchManager.indexName(index, scope), options),
+    deleteIndex: index =>
+      SearchManager.engine().deleteIndex(SearchManager.indexName(index, scope)),
+  }
 }

package/src/index.ts

@@ -30,6 +30,7 @@ export type { SearchableInstance, SearchableModel } from './searchable.ts'
 
 // Helper
 export { search } from './helpers.ts'
+export type { ScopedSearch } from './helpers.ts'
 
 // Errors
 export { SearchError, IndexNotFoundError, SearchQueryError } from './errors.ts'
@@ -43,4 +44,5 @@ export type {
   SearchResult,
   SearchHit,
   IndexSettings,
+  SearchScope,
 } from './types.ts'

package/src/search_manager.ts

@@ -1,6 +1,6 @@
 import { inject, Configuration, ConfigurationError } from '@strav/kernel'
 import type { SearchEngine } from './search_engine.ts'
-import type { SearchConfig, DriverConfig } from './types.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'
@@ -53,9 +53,34 @@ export default class SearchManager {
     return SearchManager._config?.prefix ?? ''
   }
 
-  /** Resolve a full index name by applying the configured prefix. */
-  static indexName(name: string): string {
-    return SearchManager.prefix ? `${SearchManager.prefix}${name}` : name
+  /**
+   * 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.
+   */
+  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_-]+$/.`
+      )
+    }
+    if (SearchManager.prefix) {
+      return `${SearchManager.prefix}t${tenantId}_${name}`
+    }
+    return `t${tenantId}_${name}`
   }
 
   /** Register a custom driver factory. */

package/src/types.ts

@@ -5,6 +5,21 @@ export interface SearchDocument {
   [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.
+ *
+ * The tenantId must match `/^[a-zA-Z0-9_-]+$/`; anything else throws
+ * (the value lands in URL paths and SQL identifiers downstream).
+ */
+export interface SearchScope {
+  tenantId: string | number
+}
+
 // ── Index settings ────────────────────────────────────────────────────────
 
 export interface IndexSettings {