@basaltkit/search 1.2.0 → 1.3.1

package/README.md

@@ -1,3 +1,9 @@
+<p align="center">
+  <a href="https://basaltkit-docs.pages.dev">
+    <img src="https://basaltkit-docs.pages.dev/social-card.png" alt="Basalt" width="440">
+  </a>
+</p>
+
 # @basaltkit/search
 
 Full-text search for Basalt: indexes and searches documents **per tenant**, with a typed API and an interchangeable driver — **in-memory** for development/testing and **Meilisearch** for production. You need this module when you want to give users a fast, relevant search box over their data (notes, projects, customers…).

package/dist/drivers/meilisearch.d.ts

@@ -0,0 +1,36 @@
+import { BasaltError } from '@basaltkit/core';
+import type { IndexDefinition, SearchDocument, SearchDriver, SearchQuery, SearchResult } from '../types.js';
+export declare class MeilisearchError extends BasaltError {
+    readonly httpStatus: number;
+    constructor(httpStatus: number, message: string);
+}
+export declare class SearchFilterFieldError extends BasaltError {
+    constructor(field: string);
+}
+export declare class SearchIndexNameError extends BasaltError {
+    constructor(name: string);
+}
+export interface MeilisearchDriverOptions {
+    host: string;
+    apiKey?: string;
+    /** Injected fetch (tests). Default: global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Meilisearch driver targeting the REST API directly (no SDK). Documents get a
+ * compound `_pk` so ids never collide across tenants, and every search is
+ * constrained with a `tenantId` filter so results never leak between tenants.
+ */
+export declare class MeilisearchDriver implements SearchDriver {
+    private readonly options;
+    private readonly fetch;
+    constructor(options: MeilisearchDriverOptions);
+    register(index: IndexDefinition): Promise<void>;
+    index(indexName: string, document: SearchDocument): Promise<void>;
+    bulk(indexName: string, documents: SearchDocument[]): Promise<void>;
+    remove(indexName: string, tenantId: string, id: string): Promise<void>;
+    clear(indexName: string): Promise<void>;
+    search(indexName: string, query: SearchQuery): Promise<SearchResult>;
+    private buildFilter;
+    private request;
+}

package/dist/drivers/meilisearch.js

@@ -0,0 +1,127 @@
+import { BasaltError } from '@basaltkit/core';
+export class MeilisearchError extends BasaltError {
+    httpStatus;
+    constructor(httpStatus, message) {
+        super('SEARCH_ENGINE_ERROR', `Meilisearch request failed (${httpStatus}): ${message}`);
+        this.httpStatus = httpStatus;
+    }
+}
+export class SearchFilterFieldError extends BasaltError {
+    constructor(field) {
+        super('SEARCH_INVALID_FILTER_FIELD', `Invalid filter field name: ${JSON.stringify(field)}.`);
+    }
+}
+export class SearchIndexNameError extends BasaltError {
+    constructor(name) {
+        super('SEARCH_INVALID_INDEX_NAME', `Invalid index name: ${JSON.stringify(name)}.`);
+    }
+}
+// The index name is interpolated into Meilisearch REST URL paths
+// (`/indexes/${name}/...`). Meilisearch index uids only allow letters, digits,
+// hyphens and underscores, so anything else is both invalid upstream and a way
+// to break out of the path — reject it at the boundary. Config-time identifier,
+// not request input, but validated defensively.
+const SAFE_INDEX_NAME = /^[A-Za-z0-9_-]+$/;
+/** Throw on an index name that isn't a safe Meilisearch uid / path segment. */
+const assertValidIndexName = (name) => {
+    if (!SAFE_INDEX_NAME.test(name))
+        throw new SearchIndexNameError(name);
+    return name;
+};
+// A filter field is interpolated into Meilisearch's filter DSL, so it must be a
+// bare identifier (optionally dotted). Rejecting anything else stops a crafted
+// field name from injecting operators (` OR `, `=`, quotes) to escape the
+// mandatory `tenantId` scope and read another tenant's documents.
+const SAFE_FILTER_FIELD = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+/** Stable Meilisearch primary key from (tenant, id) — always a valid doc id. */
+const primaryKey = (tenantId, id) => Buffer.from(`${tenantId}::${id}`).toString('base64url');
+const quote = (value) => JSON.stringify(value);
+/**
+ * Meilisearch driver targeting the REST API directly (no SDK). Documents get a
+ * compound `_pk` so ids never collide across tenants, and every search is
+ * constrained with a `tenantId` filter so results never leak between tenants.
+ */
+export class MeilisearchDriver {
+    options;
+    fetch;
+    constructor(options) {
+        this.options = options;
+        this.fetch = options.fetch ?? globalThis.fetch;
+    }
+    async register(index) {
+        assertValidIndexName(index.name);
+        // Create the index (ignore "already exists"), then declare attributes.
+        try {
+            await this.request('POST', '/indexes', { uid: index.name, primaryKey: '_pk' });
+        }
+        catch {
+            // index_already_exists and similar are fine to ignore on register.
+        }
+        await this.request('PATCH', `/indexes/${index.name}/settings`, {
+            searchableAttributes: index.fields,
+            filterableAttributes: ['tenantId', ...(index.filterable ?? [])],
+        });
+    }
+    async index(indexName, document) {
+        await this.bulk(indexName, [document]);
+    }
+    async bulk(indexName, documents) {
+        assertValidIndexName(indexName);
+        const withPk = documents.map((d) => ({ ...d, _pk: primaryKey(d.tenantId, d.id) }));
+        await this.request('PUT', `/indexes/${indexName}/documents`, withPk);
+    }
+    async remove(indexName, tenantId, id) {
+        assertValidIndexName(indexName);
+        await this.request('DELETE', `/indexes/${indexName}/documents/${primaryKey(tenantId, id)}`);
+    }
+    async clear(indexName) {
+        assertValidIndexName(indexName);
+        await this.request('DELETE', `/indexes/${indexName}/documents`);
+    }
+    async search(indexName, query) {
+        assertValidIndexName(indexName);
+        const result = (await this.request('POST', `/indexes/${indexName}/search`, {
+            q: query.q,
+            filter: this.buildFilter(query.tenantId, query.filters),
+            limit: query.limit ?? 20,
+            offset: query.offset ?? 0,
+            showRankingScore: true,
+        }));
+        const hits = (result.hits ?? []).map((hit) => {
+            const { _pk, _rankingScore, ...document } = hit;
+            void _pk;
+            return {
+                id: String(document['id']),
+                score: typeof _rankingScore === 'number' ? _rankingScore : 0,
+                document: document,
+            };
+        });
+        return { hits, total: result.estimatedTotalHits ?? hits.length };
+    }
+    buildFilter(tenantId, filters) {
+        const parts = [`tenantId = ${quote(tenantId)}`];
+        for (const [field, value] of Object.entries(filters ?? {})) {
+            if (!SAFE_FILTER_FIELD.test(field))
+                throw new SearchFilterFieldError(field);
+            parts.push(Array.isArray(value) ? `${field} IN [${value.map(quote).join(', ')}]` : `${field} = ${quote(value)}`);
+        }
+        return parts.join(' AND ');
+    }
+    async request(method, path, body) {
+        const response = await this.fetch(`${this.options.host}${path}`, {
+            method,
+            headers: {
+                'content-type': 'application/json',
+                ...(this.options.apiKey ? { authorization: `Bearer ${this.options.apiKey}` } : {}),
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        const text = await response.text();
+        const json = text ? JSON.parse(text) : {};
+        if (!response.ok) {
+            const message = json.message ?? text ?? 'unknown error';
+            throw new MeilisearchError(response.status, message);
+        }
+        return json;
+    }
+}

package/dist/index.d.ts

@@ -1,172 +1,5 @@
-import * as _basaltkit_core from '@basaltkit/core';
-import { BasaltError, BasaltHooks } from '@basaltkit/core';
-
-/** A document to index. Always carries an `id` and the owning `tenantId`. */
-interface SearchDocument {
-    id: string;
-    tenantId: string;
-    [field: string]: unknown;
-}
-/** Declares an index: which fields are searchable (full-text) and filterable. */
-interface IndexDefinition {
-    name: string;
-    /** Text fields matched by the query. */
-    fields: string[];
-    /** Fields usable in `filters` (exact match). `tenantId` is always filterable. */
-    filterable?: string[];
-}
-declare function defineIndex(definition: IndexDefinition): IndexDefinition;
-interface SearchQuery {
-    tenantId: string;
-    q: string;
-    /** Exact-match filters. A value array means "any of". */
-    filters?: Record<string, unknown>;
-    limit?: number;
-    offset?: number;
-}
-interface SearchHit {
-    id: string;
-    score: number;
-    document: SearchDocument;
-}
-interface SearchResult {
-    hits: SearchHit[];
-    /** Total matches (before limit/offset). */
-    total: number;
-}
-/**
- * Search backend contract. The core talks to this; drivers talk to the engine.
- * Every operation is tenant-scoped: `search` must only ever return documents
- * whose `tenantId` matches the query.
- */
-interface SearchDriver {
-    /** Optional: called once per index at boot with its config. */
-    register?(index: IndexDefinition): Promise<void>;
-    index(indexName: string, document: SearchDocument): Promise<void>;
-    bulk(indexName: string, documents: SearchDocument[]): Promise<void>;
-    remove(indexName: string, tenantId: string, id: string): Promise<void>;
-    search(indexName: string, query: SearchQuery): Promise<SearchResult>;
-    /** Drops every document in the index (used by tests). */
-    clear(indexName: string): Promise<void>;
-}
-
-/**
- * In-process full-text driver for dev and tests — no external engine. Scores by
- * term frequency with prefix matching, requires every query term to match (AND
- * semantics), scopes results to the query's tenant, and supports exact-match
- * filters. Good enough for development; swap in {@link MeilisearchDriver} for
- * production-scale relevance.
- */
-declare class MemorySearchDriver implements SearchDriver {
-    private readonly documents;
-    private readonly configs;
-    register(index: IndexDefinition): Promise<void>;
-    index(indexName: string, document: SearchDocument): Promise<void>;
-    bulk(indexName: string, documents: SearchDocument[]): Promise<void>;
-    remove(indexName: string, tenantId: string, id: string): Promise<void>;
-    clear(indexName: string): Promise<void>;
-    search(indexName: string, query: SearchQuery): Promise<SearchResult>;
-    private score;
-    private passesFilters;
-    private searchableFields;
-    private store;
-}
-
-/** Search was asked for a tenant it couldn't determine. */
-declare class TenantRequiredError extends BasaltError {
-    readonly status = 400;
-    constructor();
-}
-interface SearchOptions {
-    /** Defaults to the current tenant (`ctx().tenant.id`). */
-    tenantId?: string;
-    filters?: Record<string, unknown>;
-    limit?: number;
-    offset?: number;
-}
-/**
- * Tenant-scoped full-text search. Indexing takes the tenant from the document;
- * querying takes it from `options.tenantId` or the current request context.
- */
-declare class Search {
-    private readonly driver;
-    constructor(options?: {
-        driver?: SearchDriver;
-    });
-    index(indexName: string, document: SearchDocument): Promise<void>;
-    bulk(indexName: string, documents: SearchDocument[]): Promise<void>;
-    remove(indexName: string, id: string, tenantId?: string): Promise<void>;
-    search(indexName: string, q: string, options?: SearchOptions): Promise<SearchResult>;
-}
-
-declare class MeilisearchError extends BasaltError {
-    readonly httpStatus: number;
-    constructor(httpStatus: number, message: string);
-}
-declare class SearchFilterFieldError extends BasaltError {
-    constructor(field: string);
-}
-interface MeilisearchDriverOptions {
-    host: string;
-    apiKey?: string;
-    /** Injected fetch (tests). Default: global fetch. */
-    fetch?: typeof fetch;
-}
-/**
- * Meilisearch driver targeting the REST API directly (no SDK). Documents get a
- * compound `_pk` so ids never collide across tenants, and every search is
- * constrained with a `tenantId` filter so results never leak between tenants.
- */
-declare class MeilisearchDriver implements SearchDriver {
-    private readonly options;
-    private readonly fetch;
-    constructor(options: MeilisearchDriverOptions);
-    register(index: IndexDefinition): Promise<void>;
-    index(indexName: string, document: SearchDocument): Promise<void>;
-    bulk(indexName: string, documents: SearchDocument[]): Promise<void>;
-    remove(indexName: string, tenantId: string, id: string): Promise<void>;
-    clear(indexName: string): Promise<void>;
-    search(indexName: string, query: SearchQuery): Promise<SearchResult>;
-    private buildFilter;
-    private request;
-}
-
-declare const SEARCH: _basaltkit_core.Token<Search>;
-/**
- * Keeps an index in sync with domain events: on the given hook, either upsert a
- * document or remove one. Wire it once and your search index maintains itself.
- *
- *   syncRule({ hook: 'note:created', index: 'notes', document: (p) => ({
- *     id: p.note.id, tenantId: p.tenantId, title: p.note.title, body: p.note.body,
- *   })})
- */
-interface SyncRule<K extends keyof BasaltHooks & string = keyof BasaltHooks & string> {
-    hook: K;
-    index: string;
-    /** Build the document to upsert. Return null to skip. */
-    document?: (payload: BasaltHooks[K]) => SearchDocument | null;
-    /** Or the identifiers to remove. Return null to skip. */
-    remove?: (payload: BasaltHooks[K]) => {
-        tenantId: string;
-        id: string;
-    } | null;
-}
-/** Type-checks a sync rule against its hook, then erases the generic. */
-declare function syncRule<K extends keyof BasaltHooks & string>(rule: SyncRule<K>): SyncRule;
-interface SearchPluginOptions {
-    driver?: SearchDriver;
-    /** Indexes to register with the driver at boot. */
-    indexes?: IndexDefinition[];
-    /** Rules keeping indexes in sync with domain hooks. */
-    sync?: SyncRule[];
-    /**
-     * Throw if an index fails to register at boot. Default `false`: a search
-     * backend that's down or misconfigured logs a warning and the app boots
-     * anyway (search stays degraded until the backend is reachable), so an outage
-     * never blocks unrelated work — including CLI commands that don't use search.
-     */
-    failOnRegisterError?: boolean;
-}
-declare function searchPlugin(options?: SearchPluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
-
-export { type IndexDefinition, MeilisearchDriver, type MeilisearchDriverOptions, MeilisearchError, MemorySearchDriver, SEARCH, Search, type SearchDocument, type SearchDriver, SearchFilterFieldError, type SearchHit, type SearchOptions, type SearchPluginOptions, type SearchQuery, type SearchResult, type SyncRule, TenantRequiredError, defineIndex, searchPlugin, syncRule };
+export { defineIndex, type SearchDocument, type IndexDefinition, type SearchQuery, type SearchHit, type SearchResult, type SearchDriver, } from './types.js';
+export { MemorySearchDriver } from './memory.js';
+export { Search, TenantRequiredError, type SearchOptions } from './search.js';
+export { MeilisearchDriver, MeilisearchError, SearchFilterFieldError, SearchIndexNameError, type MeilisearchDriverOptions, } from './drivers/meilisearch.js';
+export { searchPlugin, syncRule, SEARCH, type SearchPluginOptions, type SyncRule, } from './plugin.js';

package/dist/index.js

@@ -1,269 +1,5 @@
-// src/types.ts
-function defineIndex(definition) {
-  return definition;
-}
-
-// src/memory.ts
-var tokenize = (text) => text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
-var docKey = (tenantId, id) => `${tenantId}\0${id}`;
-var MemorySearchDriver = class {
-  documents = /* @__PURE__ */ new Map();
-  configs = /* @__PURE__ */ new Map();
-  async register(index) {
-    this.configs.set(index.name, index);
-    if (!this.documents.has(index.name)) this.documents.set(index.name, /* @__PURE__ */ new Map());
-  }
-  async index(indexName, document) {
-    this.store(indexName).set(docKey(document.tenantId, document.id), document);
-  }
-  async bulk(indexName, documents) {
-    for (const document of documents) await this.index(indexName, document);
-  }
-  async remove(indexName, tenantId, id) {
-    this.store(indexName).delete(docKey(tenantId, id));
-  }
-  async clear(indexName) {
-    this.documents.set(indexName, /* @__PURE__ */ new Map());
-  }
-  async search(indexName, query) {
-    const fields = this.searchableFields(indexName);
-    const terms = tokenize(query.q);
-    const scored = [];
-    for (const document of this.store(indexName).values()) {
-      if (document.tenantId !== query.tenantId) continue;
-      if (!this.passesFilters(document, query.filters)) continue;
-      const score = this.score(document, fields, terms);
-      if (score < 0) continue;
-      scored.push({ id: document.id, score, document });
-    }
-    scored.sort((a, b) => b.score - a.score);
-    const offset = query.offset ?? 0;
-    const limit = query.limit ?? 20;
-    return { hits: scored.slice(offset, offset + limit), total: scored.length };
-  }
-  score(document, fields, terms) {
-    if (terms.length === 0) return 0;
-    const tokens = tokenize(fields.map((field) => String(document[field] ?? "")).join(" "));
-    let total = 0;
-    for (const term of terms) {
-      let termScore = 0;
-      for (const token of tokens) {
-        if (token === term) termScore += 2;
-        else if (token.startsWith(term)) termScore += 1;
-      }
-      if (termScore === 0) return -1;
-      total += termScore;
-    }
-    return total;
-  }
-  passesFilters(document, filters) {
-    if (!filters) return true;
-    for (const [field, value] of Object.entries(filters)) {
-      const actual = document[field];
-      if (Array.isArray(value) ? !value.includes(actual) : actual !== value) return false;
-    }
-    return true;
-  }
-  searchableFields(indexName) {
-    const config = this.configs.get(indexName);
-    if (config) return config.fields;
-    const sample = this.store(indexName).values().next().value;
-    if (!sample) return [];
-    return Object.keys(sample).filter((k) => k !== "id" && k !== "tenantId" && typeof sample[k] === "string");
-  }
-  store(indexName) {
-    let store = this.documents.get(indexName);
-    if (!store) {
-      store = /* @__PURE__ */ new Map();
-      this.documents.set(indexName, store);
-    }
-    return store;
-  }
-};
-
-// src/search.ts
-import { BasaltError, tryCtx } from "@basaltkit/core";
-var TenantRequiredError = class extends BasaltError {
-  status = 400;
-  constructor() {
-    super("SEARCH_TENANT_REQUIRED", "A tenant is required \u2014 pass tenantId or run inside a tenant context.");
-  }
-};
-var currentTenant = (explicit) => {
-  const id = explicit ?? tryCtx()?.["tenant"]?.id;
-  if (!id) throw new TenantRequiredError();
-  return id;
-};
-var Search = class {
-  driver;
-  constructor(options = {}) {
-    this.driver = options.driver ?? new MemorySearchDriver();
-  }
-  index(indexName, document) {
-    return this.driver.index(indexName, document);
-  }
-  bulk(indexName, documents) {
-    return this.driver.bulk(indexName, documents);
-  }
-  async remove(indexName, id, tenantId) {
-    return this.driver.remove(indexName, currentTenant(tenantId), id);
-  }
-  async search(indexName, q, options = {}) {
-    return this.driver.search(indexName, {
-      tenantId: currentTenant(options.tenantId),
-      q,
-      ...options.filters ? { filters: options.filters } : {},
-      ...options.limit !== void 0 ? { limit: options.limit } : {},
-      ...options.offset !== void 0 ? { offset: options.offset } : {}
-    });
-  }
-};
-
-// src/drivers/meilisearch.ts
-import { BasaltError as BasaltError2 } from "@basaltkit/core";
-var MeilisearchError = class extends BasaltError2 {
-  constructor(httpStatus, message) {
-    super("SEARCH_ENGINE_ERROR", `Meilisearch request failed (${httpStatus}): ${message}`);
-    this.httpStatus = httpStatus;
-  }
-  httpStatus;
-};
-var SearchFilterFieldError = class extends BasaltError2 {
-  constructor(field) {
-    super("SEARCH_INVALID_FILTER_FIELD", `Invalid filter field name: ${JSON.stringify(field)}.`);
-  }
-};
-var SAFE_FILTER_FIELD = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
-var primaryKey = (tenantId, id) => Buffer.from(`${tenantId}::${id}`).toString("base64url");
-var quote = (value) => JSON.stringify(value);
-var MeilisearchDriver = class {
-  constructor(options) {
-    this.options = options;
-    this.fetch = options.fetch ?? globalThis.fetch;
-  }
-  options;
-  fetch;
-  async register(index) {
-    try {
-      await this.request("POST", "/indexes", { uid: index.name, primaryKey: "_pk" });
-    } catch {
-    }
-    await this.request("PATCH", `/indexes/${index.name}/settings`, {
-      searchableAttributes: index.fields,
-      filterableAttributes: ["tenantId", ...index.filterable ?? []]
-    });
-  }
-  async index(indexName, document) {
-    await this.bulk(indexName, [document]);
-  }
-  async bulk(indexName, documents) {
-    const withPk = documents.map((d) => ({ ...d, _pk: primaryKey(d.tenantId, d.id) }));
-    await this.request("PUT", `/indexes/${indexName}/documents`, withPk);
-  }
-  async remove(indexName, tenantId, id) {
-    await this.request("DELETE", `/indexes/${indexName}/documents/${primaryKey(tenantId, id)}`);
-  }
-  async clear(indexName) {
-    await this.request("DELETE", `/indexes/${indexName}/documents`);
-  }
-  async search(indexName, query) {
-    const result = await this.request("POST", `/indexes/${indexName}/search`, {
-      q: query.q,
-      filter: this.buildFilter(query.tenantId, query.filters),
-      limit: query.limit ?? 20,
-      offset: query.offset ?? 0,
-      showRankingScore: true
-    });
-    const hits = (result.hits ?? []).map((hit) => {
-      const { _pk, _rankingScore, ...document } = hit;
-      void _pk;
-      return {
-        id: String(document["id"]),
-        score: typeof _rankingScore === "number" ? _rankingScore : 0,
-        document
-      };
-    });
-    return { hits, total: result.estimatedTotalHits ?? hits.length };
-  }
-  buildFilter(tenantId, filters) {
-    const parts = [`tenantId = ${quote(tenantId)}`];
-    for (const [field, value] of Object.entries(filters ?? {})) {
-      if (!SAFE_FILTER_FIELD.test(field)) throw new SearchFilterFieldError(field);
-      parts.push(Array.isArray(value) ? `${field} IN [${value.map(quote).join(", ")}]` : `${field} = ${quote(value)}`);
-    }
-    return parts.join(" AND ");
-  }
-  async request(method, path, body) {
-    const response = await this.fetch(`${this.options.host}${path}`, {
-      method,
-      headers: {
-        "content-type": "application/json",
-        ...this.options.apiKey ? { authorization: `Bearer ${this.options.apiKey}` } : {}
-      },
-      ...body !== void 0 ? { body: JSON.stringify(body) } : {}
-    });
-    const text = await response.text();
-    const json = text ? JSON.parse(text) : {};
-    if (!response.ok) {
-      const message = json.message ?? text ?? "unknown error";
-      throw new MeilisearchError(response.status, message);
-    }
-    return json;
-  }
-};
-
-// src/plugin.ts
-import { createToken, definePlugin } from "@basaltkit/core";
-var SEARCH = createToken("search");
-function syncRule(rule) {
-  return rule;
-}
-function searchPlugin(options = {}) {
-  const driver = options.driver ?? new MemorySearchDriver();
-  return definePlugin({
-    name: "basalt:search",
-    register({ container }) {
-      container.singleton(SEARCH, () => new Search({ driver }));
-    },
-    async boot({ container, hooks }) {
-      const search = container.get(SEARCH);
-      if (driver.register) {
-        for (const index of options.indexes ?? []) {
-          try {
-            await driver.register(index);
-          } catch (error) {
-            if (options.failOnRegisterError) throw error;
-            console.warn(
-              `[basalt:search] could not register index "${index.name}": ${String(
-                error?.message ?? error
-              )} \u2014 search is degraded until the backend is reachable.`
-            );
-          }
-        }
-      }
-      for (const rule of options.sync ?? []) {
-        hooks.on(rule.hook, async (payload) => {
-          if (rule.document) {
-            const document = rule.document(payload);
-            if (document) await search.index(rule.index, document);
-          } else if (rule.remove) {
-            const target = rule.remove(payload);
-            if (target) await search.remove(rule.index, target.id, target.tenantId);
-          }
-        });
-      }
-    }
-  });
-}
-export {
-  MeilisearchDriver,
-  MeilisearchError,
-  MemorySearchDriver,
-  SEARCH,
-  Search,
-  SearchFilterFieldError,
-  TenantRequiredError,
-  defineIndex,
-  searchPlugin,
-  syncRule
-};
+export { defineIndex, } from './types.js';
+export { MemorySearchDriver } from './memory.js';
+export { Search, TenantRequiredError } from './search.js';
+export { MeilisearchDriver, MeilisearchError, SearchFilterFieldError, SearchIndexNameError, } from './drivers/meilisearch.js';
+export { searchPlugin, syncRule, SEARCH, } from './plugin.js';

package/dist/memory.d.ts

@@ -0,0 +1,22 @@
+import type { IndexDefinition, SearchDocument, SearchDriver, SearchQuery, SearchResult } from './types.js';
+/**
+ * In-process full-text driver for dev and tests — no external engine. Scores by
+ * term frequency with prefix matching, requires every query term to match (AND
+ * semantics), scopes results to the query's tenant, and supports exact-match
+ * filters. Good enough for development; swap in {@link MeilisearchDriver} for
+ * production-scale relevance.
+ */
+export declare class MemorySearchDriver implements SearchDriver {
+    private readonly documents;
+    private readonly configs;
+    register(index: IndexDefinition): Promise<void>;
+    index(indexName: string, document: SearchDocument): Promise<void>;
+    bulk(indexName: string, documents: SearchDocument[]): Promise<void>;
+    remove(indexName: string, tenantId: string, id: string): Promise<void>;
+    clear(indexName: string): Promise<void>;
+    search(indexName: string, query: SearchQuery): Promise<SearchResult>;
+    private score;
+    private passesFilters;
+    private searchableFields;
+    private store;
+}

package/dist/plugin.d.ts

@@ -0,0 +1,40 @@
+import type { BasaltHooks } from '@basaltkit/core';
+import { Search } from './search.js';
+import type { IndexDefinition, SearchDocument, SearchDriver } from './types.js';
+export declare const SEARCH: import("@basaltkit/core").Token<Search>;
+/**
+ * Keeps an index in sync with domain events: on the given hook, either upsert a
+ * document or remove one. Wire it once and your search index maintains itself.
+ *
+ *   syncRule({ hook: 'note:created', index: 'notes', document: (p) => ({
+ *     id: p.note.id, tenantId: p.tenantId, title: p.note.title, body: p.note.body,
+ *   })})
+ */
+export interface SyncRule<K extends keyof BasaltHooks & string = keyof BasaltHooks & string> {
+    hook: K;
+    index: string;
+    /** Build the document to upsert. Return null to skip. */
+    document?: (payload: BasaltHooks[K]) => SearchDocument | null;
+    /** Or the identifiers to remove. Return null to skip. */
+    remove?: (payload: BasaltHooks[K]) => {
+        tenantId: string;
+        id: string;
+    } | null;
+}
+/** Type-checks a sync rule against its hook, then erases the generic. */
+export declare function syncRule<K extends keyof BasaltHooks & string>(rule: SyncRule<K>): SyncRule;
+export interface SearchPluginOptions {
+    driver?: SearchDriver;
+    /** Indexes to register with the driver at boot. */
+    indexes?: IndexDefinition[];
+    /** Rules keeping indexes in sync with domain hooks. */
+    sync?: SyncRule[];
+    /**
+     * Throw if an index fails to register at boot. Default `false`: a search
+     * backend that's down or misconfigured logs a warning and the app boots
+     * anyway (search stays degraded until the backend is reachable), so an outage
+     * never blocks unrelated work — including CLI commands that don't use search.
+     */
+    failOnRegisterError?: boolean;
+}
+export declare function searchPlugin(options?: SearchPluginOptions): import("@basaltkit/core").BasaltPlugin<unknown>;

package/dist/plugin.js

@@ -0,0 +1,48 @@
+import { createToken, definePlugin } from '@basaltkit/core';
+import { MemorySearchDriver } from './memory.js';
+import { Search } from './search.js';
+export const SEARCH = createToken('search');
+/** Type-checks a sync rule against its hook, then erases the generic. */
+export function syncRule(rule) {
+    return rule;
+}
+export function searchPlugin(options = {}) {
+    const driver = options.driver ?? new MemorySearchDriver();
+    return definePlugin({
+        name: 'basalt:search',
+        register({ container }) {
+            container.singleton(SEARCH, () => new Search({ driver }));
+        },
+        async boot({ container, hooks }) {
+            const search = container.get(SEARCH);
+            if (driver.register) {
+                for (const index of options.indexes ?? []) {
+                    try {
+                        await driver.register(index);
+                    }
+                    catch (error) {
+                        if (options.failOnRegisterError)
+                            throw error;
+                        // Non-fatal by default: a search backend that's down/misconfigured
+                        // shouldn't stop the app booting or block unrelated CLI commands.
+                        console.warn(`[basalt:search] could not register index "${index.name}": ${String(error?.message ?? error)} — search is degraded until the backend is reachable.`);
+                    }
+                }
+            }
+            for (const rule of options.sync ?? []) {
+                hooks.on(rule.hook, async (payload) => {
+                    if (rule.document) {
+                        const document = rule.document(payload);
+                        if (document)
+                            await search.index(rule.index, document);
+                    }
+                    else if (rule.remove) {
+                        const target = rule.remove(payload);
+                        if (target)
+                            await search.remove(rule.index, target.id, target.tenantId);
+                    }
+                });
+            }
+        },
+    });
+}

package/dist/search.d.ts

@@ -0,0 +1,28 @@
+import { BasaltError } from '@basaltkit/core';
+import type { SearchDocument, SearchDriver, SearchResult } from './types.js';
+/** Search was asked for a tenant it couldn't determine. */
+export declare class TenantRequiredError extends BasaltError {
+    readonly status = 400;
+    constructor();
+}
+export interface SearchOptions {
+    /** Defaults to the current tenant (`ctx().tenant.id`). */
+    tenantId?: string;
+    filters?: Record<string, unknown>;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Tenant-scoped full-text search. Indexing takes the tenant from the document;
+ * querying takes it from `options.tenantId` or the current request context.
+ */
+export declare class Search {
+    private readonly driver;
+    constructor(options?: {
+        driver?: SearchDriver;
+    });
+    index(indexName: string, document: SearchDocument): Promise<void>;
+    bulk(indexName: string, documents: SearchDocument[]): Promise<void>;
+    remove(indexName: string, id: string, tenantId?: string): Promise<void>;
+    search(indexName: string, q: string, options?: SearchOptions): Promise<SearchResult>;
+}

package/dist/search.js

@@ -0,0 +1,43 @@
+import { BasaltError, tryCtx } from '@basaltkit/core';
+import { MemorySearchDriver } from './memory.js';
+/** Search was asked for a tenant it couldn't determine. */
+export class TenantRequiredError extends BasaltError {
+    status = 400;
+    constructor() {
+        super('SEARCH_TENANT_REQUIRED', 'A tenant is required — pass tenantId or run inside a tenant context.');
+    }
+}
+const currentTenant = (explicit) => {
+    const id = explicit ?? tryCtx()?.['tenant']?.id;
+    if (!id)
+        throw new TenantRequiredError();
+    return id;
+};
+/**
+ * Tenant-scoped full-text search. Indexing takes the tenant from the document;
+ * querying takes it from `options.tenantId` or the current request context.
+ */
+export class Search {
+    driver;
+    constructor(options = {}) {
+        this.driver = options.driver ?? new MemorySearchDriver();
+    }
+    index(indexName, document) {
+        return this.driver.index(indexName, document);
+    }
+    bulk(indexName, documents) {
+        return this.driver.bulk(indexName, documents);
+    }
+    async remove(indexName, id, tenantId) {
+        return this.driver.remove(indexName, currentTenant(tenantId), id);
+    }
+    async search(indexName, q, options = {}) {
+        return this.driver.search(indexName, {
+            tenantId: currentTenant(options.tenantId),
+            q,
+            ...(options.filters ? { filters: options.filters } : {}),
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+            ...(options.offset !== undefined ? { offset: options.offset } : {}),
+        });
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+/** A document to index. Always carries an `id` and the owning `tenantId`. */
+export interface SearchDocument {
+    id: string;
+    tenantId: string;
+    [field: string]: unknown;
+}
+/** Declares an index: which fields are searchable (full-text) and filterable. */
+export interface IndexDefinition {
+    name: string;
+    /** Text fields matched by the query. */
+    fields: string[];
+    /** Fields usable in `filters` (exact match). `tenantId` is always filterable. */
+    filterable?: string[];
+}
+export declare function defineIndex(definition: IndexDefinition): IndexDefinition;
+export interface SearchQuery {
+    tenantId: string;
+    q: string;
+    /** Exact-match filters. A value array means "any of". */
+    filters?: Record<string, unknown>;
+    limit?: number;
+    offset?: number;
+}
+export interface SearchHit {
+    id: string;
+    score: number;
+    document: SearchDocument;
+}
+export interface SearchResult {
+    hits: SearchHit[];
+    /** Total matches (before limit/offset). */
+    total: number;
+}
+/**
+ * Search backend contract. The core talks to this; drivers talk to the engine.
+ * Every operation is tenant-scoped: `search` must only ever return documents
+ * whose `tenantId` matches the query.
+ */
+export interface SearchDriver {
+    /** Optional: called once per index at boot with its config. */
+    register?(index: IndexDefinition): Promise<void>;
+    index(indexName: string, document: SearchDocument): Promise<void>;
+    bulk(indexName: string, documents: SearchDocument[]): Promise<void>;
+    remove(indexName: string, tenantId: string, id: string): Promise<void>;
+    search(indexName: string, query: SearchQuery): Promise<SearchResult>;
+    /** Drops every document in the index (used by tests). */
+    clear(indexName: string): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+export function defineIndex(definition) {
+    return definition;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/search",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Full-text search for Basalt: tenant-scoped indexing and querying with a pluggable driver (in-memory for dev/test, Meilisearch for production) and automatic sync from domain events.",
   "license": "MIT",
   "type": "module",
@@ -14,13 +14,12 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/core": "^1.0.0"
+    "@basaltkit/core": "^1.1.2"
   },
   "devDependencies": {
-    "@types/node": "^22.15.0",
-    "tsup": "^8.4.0",
-    "typescript": "^5.8.0",
-    "vitest": "^3.1.0",
+    "@types/node": "^26.3.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {
@@ -28,11 +27,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "url": "git+https://github.com/basaltkit/basalt.git",
     "directory": "packages/search"
   },
-  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/search#readme",
-  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "homepage": "https://github.com/basaltkit/basalt/tree/main/packages/search#readme",
+  "bugs": "https://github.com/basaltkit/basalt/issues",
   "keywords": [
     "basalt",
     "typescript",
@@ -42,7 +41,7 @@
     "meilisearch"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }