@basaltkit/search 1.3.1 → 1.4.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { defineIndex, type SearchDocument, type IndexDefinition, type SearchQuery, type SearchHit, type SearchResult, type SearchDriver, } from './types.js';
+export { defineIndex, type SearchDocument, type SearchInput, 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 { Search, SINGLE_TENANT_SCOPE, 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,5 +1,5 @@
 export { defineIndex, } from './types.js';
 export { MemorySearchDriver } from './memory.js';
-export { Search, TenantRequiredError } from './search.js';
+export { Search, SINGLE_TENANT_SCOPE, TenantRequiredError } from './search.js';
 export { MeilisearchDriver, MeilisearchError, SearchFilterFieldError, SearchIndexNameError, } from './drivers/meilisearch.js';
 export { searchPlugin, syncRule, SEARCH, } from './plugin.js';

package/dist/plugin.d.ts

@@ -1,6 +1,6 @@
 import type { BasaltHooks } from '@basaltkit/core';
 import { Search } from './search.js';
-import type { IndexDefinition, SearchDocument, SearchDriver } from './types.js';
+import type { IndexDefinition, SearchDriver, SearchInput } 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
@@ -14,10 +14,10 @@ export interface SyncRule<K extends keyof BasaltHooks & string = keyof BasaltHoo
     hook: K;
     index: string;
     /** Build the document to upsert. Return null to skip. */
-    document?: (payload: BasaltHooks[K]) => SearchDocument | null;
+    document?: (payload: BasaltHooks[K]) => SearchInput | null;
     /** Or the identifiers to remove. Return null to skip. */
     remove?: (payload: BasaltHooks[K]) => {
-        tenantId: string;
+        tenantId?: string;
         id: string;
     } | null;
 }

package/dist/plugin.js

@@ -1,4 +1,4 @@
-import { createToken, definePlugin } from '@basaltkit/core';
+import { createToken, definePlugin, ensureMetadata } from '@basaltkit/core';
 import { MemorySearchDriver } from './memory.js';
 import { Search } from './search.js';
 export const SEARCH = createToken('search');
@@ -11,7 +11,10 @@ export function searchPlugin(options = {}) {
     return definePlugin({
         name: 'basalt:search',
         register({ container }) {
-            container.singleton(SEARCH, () => new Search({ driver }));
+            // 'tenancy:active' is tenancyPlugin's marker: how a generic package
+            // learns the app is multi-tenant without importing @basaltkit/tenancy.
+            const metadata = ensureMetadata(container);
+            container.singleton(SEARCH, () => new Search({ driver }, () => metadata.get('tenancy:active').length > 0));
         },
         async boot({ container, hooks }) {
             const search = container.get(SEARCH);

package/dist/search.d.ts

@@ -1,10 +1,16 @@
 import { BasaltError } from '@basaltkit/core';
-import type { SearchDocument, SearchDriver, SearchResult } from './types.js';
+import type { SearchDriver, SearchInput, SearchResult } from './types.js';
 /** Search was asked for a tenant it couldn't determine. */
 export declare class TenantRequiredError extends BasaltError {
     readonly status = 400;
     constructor();
 }
+/**
+ * The scope every document lands in when the app has no tenancy at all. The
+ * driver contract is tenant-keyed, so a single-tenant app still needs one
+ * stable key — it just shouldn't have to invent (and remember) it.
+ */
+export declare const SINGLE_TENANT_SCOPE = "default";
 export interface SearchOptions {
     /** Defaults to the current tenant (`ctx().tenant.id`). */
     tenantId?: string;
@@ -17,12 +23,37 @@ export interface SearchOptions {
  * querying takes it from `options.tenantId` or the current request context.
  */
 export declare class Search {
+    /**
+     * Whether the host app registered `@basaltkit/tenancy`. `searchPlugin`
+     * wires this to the container's `'tenancy:active'` metadata marker — a
+     * signal, not an import, so this generic package never depends on the
+     * opt-in SaaS layer. Defaults to `false` (single-tenant).
+     */
+    private readonly tenancyActive;
     private readonly driver;
     constructor(options?: {
         driver?: SearchDriver;
-    });
-    index(indexName: string, document: SearchDocument): Promise<void>;
-    bulk(indexName: string, documents: SearchDocument[]): Promise<void>;
+    }, 
+    /**
+     * Whether the host app registered `@basaltkit/tenancy`. `searchPlugin`
+     * wires this to the container's `'tenancy:active'` metadata marker — a
+     * signal, not an import, so this generic package never depends on the
+     * opt-in SaaS layer. Defaults to `false` (single-tenant).
+     */
+    tenancyActive?: () => boolean);
+    index(indexName: string, document: SearchInput): Promise<void>;
+    bulk(indexName: string, documents: SearchInput[]): Promise<void>;
     remove(indexName: string, id: string, tenantId?: string): Promise<void>;
     search(indexName: string, q: string, options?: SearchOptions): Promise<SearchResult>;
+    /**
+     * The tenant a call is scoped to.
+     *
+     * With `@basaltkit/tenancy` registered an unresolvable tenant is an error:
+     * indexing or querying unscoped would cross tenants. Without it there is no
+     * tenant dimension, so every document shares {@link SINGLE_TENANT_SCOPE} and
+     * index/query always agree.
+     */
+    private tenant;
+    /** Fills in the document's tenant with the same rule the read path uses. */
+    private resolveDocument;
 }

package/dist/search.js

@@ -7,37 +7,66 @@ export class TenantRequiredError extends BasaltError {
         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;
-};
+/**
+ * The scope every document lands in when the app has no tenancy at all. The
+ * driver contract is tenant-keyed, so a single-tenant app still needs one
+ * stable key — it just shouldn't have to invent (and remember) it.
+ */
+export const SINGLE_TENANT_SCOPE = 'default';
 /**
  * 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 {
+    tenancyActive;
     driver;
-    constructor(options = {}) {
+    constructor(options = {}, 
+    /**
+     * Whether the host app registered `@basaltkit/tenancy`. `searchPlugin`
+     * wires this to the container's `'tenancy:active'` metadata marker — a
+     * signal, not an import, so this generic package never depends on the
+     * opt-in SaaS layer. Defaults to `false` (single-tenant).
+     */
+    tenancyActive = () => false) {
+        this.tenancyActive = tenancyActive;
         this.driver = options.driver ?? new MemorySearchDriver();
     }
     index(indexName, document) {
-        return this.driver.index(indexName, document);
+        return this.driver.index(indexName, this.resolveDocument(document));
     }
     bulk(indexName, documents) {
-        return this.driver.bulk(indexName, documents);
+        return this.driver.bulk(indexName, documents.map((document) => this.resolveDocument(document)));
     }
     async remove(indexName, id, tenantId) {
-        return this.driver.remove(indexName, currentTenant(tenantId), id);
+        return this.driver.remove(indexName, this.tenant(tenantId), id);
     }
     async search(indexName, q, options = {}) {
         return this.driver.search(indexName, {
-            tenantId: currentTenant(options.tenantId),
+            tenantId: this.tenant(options.tenantId),
             q,
             ...(options.filters ? { filters: options.filters } : {}),
             ...(options.limit !== undefined ? { limit: options.limit } : {}),
             ...(options.offset !== undefined ? { offset: options.offset } : {}),
         });
     }
+    /**
+     * The tenant a call is scoped to.
+     *
+     * With `@basaltkit/tenancy` registered an unresolvable tenant is an error:
+     * indexing or querying unscoped would cross tenants. Without it there is no
+     * tenant dimension, so every document shares {@link SINGLE_TENANT_SCOPE} and
+     * index/query always agree.
+     */
+    tenant(explicit) {
+        const id = explicit ?? tryCtx()?.['tenant']?.id;
+        if (id)
+            return id;
+        if (this.tenancyActive())
+            throw new TenantRequiredError();
+        return SINGLE_TENANT_SCOPE;
+    }
+    /** Fills in the document's tenant with the same rule the read path uses. */
+    resolveDocument(document) {
+        return { ...document, tenantId: this.tenant(document.tenantId) };
+    }
 }

package/dist/types.d.ts

@@ -1,9 +1,23 @@
-/** A document to index. Always carries an `id` and the owning `tenantId`. */
+/**
+ * A document as the driver sees it: `tenantId` is always resolved by the time
+ * it reaches the driver. Callers pass a {@link SearchInput}.
+ */
 export interface SearchDocument {
     id: string;
     tenantId: string;
     [field: string]: unknown;
 }
+/**
+ * A document as callers provide it. `tenantId` is optional: `Search` resolves
+ * it from the ambient tenant, and in an app with no `tenancyPlugin` falls back
+ * to {@link SINGLE_TENANT_SCOPE} — so a non-SaaS app indexes and queries the
+ * same scope without inventing a tenant id.
+ */
+export interface SearchInput {
+    id: string;
+    tenantId?: string;
+    [field: string]: unknown;
+}
 /** Declares an index: which fields are searchable (full-text) and filterable. */
 export interface IndexDefinition {
     name: string;

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@basaltkit/search",
-  "version": "1.3.1",
+  "version": "1.4.0",
+  "engines": {
+    "node": ">=22.5.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",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -14,7 +18,7 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/core": "^1.1.2"
+    "@basaltkit/core": "^1.3.1"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",