@basaltkit/search 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Machize Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# @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…).
+
+## What this module solves
+
+Searching well is more than a `WHERE ... LIKE '%text%'`: you need **relevance** (the best results first), **prefix** matching, and **tenant isolation** (customer A never sees customer B's data). This module gives you that with:
+
+- **Typed indexes** — declare once which fields are searchable and filterable.
+- **Guaranteed tenant isolation** — every search is scoped to `tenantId`; a result never "leaks" between tenants.
+- **Interchangeable driver** — `MemorySearchDriver` (no services, for dev/test) and `MeilisearchDriver` (production). Your code doesn't change when you switch.
+- **Automatic indexing** — hooks into domain events (created/updated/deleted) and the index keeps itself up to date.
+
+## Installation
+
+```bash
+pnpm add @basaltkit/search
+```
+
+Depends only on `@basaltkit/core`. `MemorySearchDriver` works with nothing installed; for production, point `MeilisearchDriver` at a Meilisearch server.
+
+## Get started in 5 minutes
+
+```ts
+import { createApp } from '@basaltkit/core'
+import { searchPlugin, SEARCH, defineIndex } from '@basaltkit/search'
+
+const app = await createApp({
+  plugins: [
+    searchPlugin({
+      indexes: [defineIndex({ name: 'notes', fields: ['title', 'body'], filterable: ['folder'] })],
+    }),
+  ],
+}).boot()
+
+const search = app.container.get(SEARCH)
+
+// index (the document carries the tenantId)
+await search.index('notes', { id: '1', tenantId: 'acme', title: 'Hello world', body: 'first note', folder: 'inbox' })
+
+// search (the tenant comes from the request context, or you pass it explicitly)
+const result = await search.search('notes', 'hello', { tenantId: 'acme', filters: { folder: 'inbox' } })
+console.log(result.hits) // [{ id: '1', score, document }]
+console.log(result.total)
+```
+
+## Automatic indexing (hooks → index)
+
+Instead of indexing by hand everywhere, wire domain events to the index — and it keeps itself up to date:
+
+```ts
+import { searchPlugin, defineIndex, syncRule } from '@basaltkit/search'
+
+searchPlugin({
+  indexes: [defineIndex({ name: 'notes', fields: ['title', 'body'] })],
+  sync: [
+    syncRule({
+      hook: 'note:created', // or note:updated
+      index: 'notes',
+      document: (p) => ({ id: p.note.id, tenantId: p.tenantId, title: p.note.title, body: p.note.body }),
+    }),
+    syncRule({
+      hook: 'note:deleted',
+      index: 'notes',
+      remove: (p) => ({ tenantId: p.tenantId, id: p.noteId }),
+    }),
+  ],
+})
+```
+
+`syncRule` type-checks against the hook's payload. Return `null` from `document`/`remove` to skip an event.
+
+## How relevance works (in-memory driver)
+
+`MemorySearchDriver` tokenizes the searchable fields and scores by **term frequency** with **prefix** matching (`qui` matches `quick`). It requires **all** query terms to be present (AND semantics), sorts by score, and only searches the fields declared in `fields`. It's deterministic and good enough for development; in production Meilisearch provides real relevance (typo-tolerance, stemming, etc.).
+
+## Production with Meilisearch
+
+```ts
+import { searchPlugin, MeilisearchDriver, defineIndex } from '@basaltkit/search'
+
+searchPlugin({
+  driver: new MeilisearchDriver({ host: 'http://localhost:7700', apiKey: process.env.MEILI_KEY }),
+  indexes: [defineIndex({ name: 'notes', fields: ['title', 'body'], filterable: ['folder'] })],
+})
+```
+
+The driver talks directly to Meilisearch's REST API (no SDK). Each document gets a composite primary key (`_pk`), so ids never collide across tenants; and **every search is filtered by `tenantId`**, guaranteeing isolation. `defineIndex(...).filterable` is automatically declared as a filterable attribute in Meilisearch.
+
+## API reference
+
+### `searchPlugin(options?)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `driver` | `SearchDriver` | `MemorySearchDriver` | Search backend. |
+| `indexes` | `IndexDefinition[]` | `[]` | Indexes to register on startup. |
+| `sync` | `SyncRule[]` | `[]` | Hook → index rules (use `syncRule(...)`). |
+
+Registers the `SEARCH` token (`Search`).
+
+### `class Search`
+
+| Method | Description |
+|---|---|
+| `index(indexName, document)` | Indexes/updates a document (carries `id` and `tenantId`). |
+| `bulk(indexName, documents)` | Indexes several. |
+| `remove(indexName, id, tenantId?)` | Removes a document (tenant from context if omitted). |
+| `search(indexName, q, options?)` | Searches. `options`: `tenantId?`, `filters?`, `limit?`, `offset?`. |
+
+Without an explicit `tenantId`, `search`/`remove` use `ctx().tenant.id`; if there's no tenant, they throw `TenantRequiredError`.
+
+### `defineIndex({ name, fields, filterable? })`
+
+Declares an index: `fields` are searchable (full-text), `filterable` are usable in `filters` (`tenantId` is always filterable).
+
+### Drivers
+
+- `MemorySearchDriver` — in-process, dev/test.
+- `MeilisearchDriver({ host, apiKey?, fetch? })` — production; `fetch` is injectable for tests.
+
+## How it connects to other modules
+
+- **`@basaltkit/core`** — `createApp`, tokens, hooks (which automatic sync consumes), and the context `tenantId` comes from.
+- **`@basaltkit/tenancy`** — places `tenant` in the context; with it active, `search.search('notes', q)` already knows the tenant.
+- **`@basaltkit/events`** — emits the domain events that feed `sync`.

package/dist/index.d.ts

@@ -0,0 +1,162 @@
+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);
+}
+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[];
+}
+declare function searchPlugin(options?: SearchPluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
+
+export { type IndexDefinition, MeilisearchDriver, type MeilisearchDriverOptions, MeilisearchError, MemorySearchDriver, SEARCH, Search, type SearchDocument, type SearchDriver, type SearchHit, type SearchOptions, type SearchPluginOptions, type SearchQuery, type SearchResult, type SyncRule, TenantRequiredError, defineIndex, searchPlugin, syncRule };

package/dist/index.js

@@ -0,0 +1,250 @@
+// 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 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 ?? {})) {
+      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 ?? []) await driver.register(index);
+      }
+      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,
+  TenantRequiredError,
+  defineIndex,
+  searchPlugin,
+  syncRule
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@basaltkit/search",
+  "version": "1.0.0",
+  "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",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@basaltkit/core": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0",
+    "@basaltkit/tsconfig": "^0.24.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "directory": "packages/search"
+  },
+  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/search#readme",
+  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "keywords": [
+    "basalt",
+    "typescript",
+    "saas",
+    "search",
+    "full-text",
+    "meilisearch"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}