@nebutra/search 0.1.0 → 0.1.1

package/dist/providers/typesense.js

@@ -0,0 +1,352 @@
+import { logger } from "@nebutra/logger";
+import Typesense from "typesense";
+// =============================================================================
+// Typesense Provider — Optimised for geo search and instant faceting
+// =============================================================================
+export class TypesenseProvider {
+    name = "typesense";
+    client;
+    constructor(config) {
+        const url = config?.url ?? process.env.TYPESENSE_URL ?? "http://localhost:8108";
+        const apiKey = config?.apiKey ?? process.env.TYPESENSE_API_KEY ?? "xyz";
+        const timeout = config?.timeout ?? 30000;
+        logger.info("[search:typesense] Initializing", { url });
+        this.client = new Typesense.Client({
+            nodes: [
+                {
+                    host: this._parseHostFromUrl(url),
+                    port: this._parsePortFromUrl(url),
+                    protocol: this._parseProtocolFromUrl(url),
+                },
+            ],
+            apiKey,
+            connectionTimeoutSeconds: timeout / 1000,
+        });
+    }
+    async indexDocument(index, doc) {
+        try {
+            const collectionName = this._getCollectionName(index, doc.tenantId);
+            const document = this._prepareDocument(doc);
+            await this.client.collections(collectionName).documents().create(document);
+            logger.debug("[search:typesense] Indexed document", {
+                collection: collectionName,
+                docId: doc.id,
+            });
+        }
+        catch (error) {
+            logger.error("[search:typesense] Failed to index document", {
+                index,
+                docId: doc.id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    async indexDocuments(index, docs) {
+        if (docs.length === 0)
+            return;
+        try {
+            // Group documents by tenant
+            const byTenant = new Map();
+            for (const doc of docs) {
+                const tenant = doc.tenantId;
+                if (!byTenant.has(tenant)) {
+                    byTenant.set(tenant, []);
+                }
+                byTenant.get(tenant)?.push(doc);
+            }
+            // Index each tenant's documents
+            for (const [tenantId, tenantDocs] of byTenant.entries()) {
+                const collectionName = this._getCollectionName(index, tenantId);
+                const documents = tenantDocs.map((doc) => this._prepareDocument(doc));
+                for (const doc of documents) {
+                    await this.client.collections(collectionName).documents().create(doc);
+                }
+                logger.debug("[search:typesense] Indexed batch", {
+                    collection: collectionName,
+                    count: tenantDocs.length,
+                });
+            }
+        }
+        catch (error) {
+            logger.error("[search:typesense] Failed to index batch", {
+                index,
+                count: docs.length,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    async search(index, query) {
+        try {
+            const collectionName = this._getCollectionName(index, query.tenantId);
+            const page = query.page ?? 1;
+            const hitsPerPage = Math.min(query.hitsPerPage ?? 20, 100);
+            // Build filter conditions
+            let filterBy;
+            if (query.filters || query.tenantId) {
+                const filterParts = [];
+                if (query.tenantId) {
+                    filterParts.push(`tenantId:=${query.tenantId}`);
+                }
+                if (query.filters) {
+                    for (const [key, value] of Object.entries(query.filters)) {
+                        if (typeof value === "string") {
+                            filterParts.push(`${key}:=${value}`);
+                        }
+                        else if (typeof value === "number") {
+                            filterParts.push(`${key}:=${value}`);
+                        }
+                        else if (typeof value === "boolean") {
+                            filterParts.push(`${key}:=${value ? 1 : 0}`);
+                        }
+                    }
+                }
+                if (filterParts.length > 0) {
+                    filterBy = filterParts.join(" && ");
+                }
+            }
+            const startMs = performance.now();
+            const searchParams = {
+                q: query.query,
+                query_by: this._getQueryByFields(),
+                page,
+                per_page: hitsPerPage,
+                typo_tokens_threshold: query.typoTolerance !== false ? 1 : 0,
+            };
+            if (filterBy) {
+                searchParams.filter_by = filterBy;
+            }
+            if (query.facets) {
+                searchParams.facet_by = query.facets.join(",");
+            }
+            if (query.sort) {
+                searchParams.sort_by = query.sort.join(",");
+            }
+            if (query.highlightFields) {
+                searchParams.highlight_fields = query.highlightFields.join(",");
+                searchParams.highlight_affix_num_tokens = 5;
+            }
+            const result = await this.client
+                .collections(collectionName)
+                .documents()
+                .search(searchParams);
+            const processingTimeMs = performance.now() - startMs;
+            const hits = (result?.hits || []).map((hit) => ({
+                doc: hit.document,
+                score: hit.text_match_info?.score ?? 1,
+                highlights: hit.highlight ?? undefined,
+            }));
+            const totalHits = result?.found ?? 0;
+            const totalPages = Math.ceil(totalHits / hitsPerPage);
+            const facetDistribution = {};
+            const resultAny = result;
+            if (resultAny?.facet_counts) {
+                for (const facet of resultAny.facet_counts) {
+                    facetDistribution[facet.field_name] = {};
+                    for (const count of facet.counts) {
+                        if (count.value !== undefined && count.count !== undefined) {
+                            const field = facetDistribution[facet.field_name];
+                            if (field) {
+                                field[count.value] = count.count;
+                            }
+                        }
+                    }
+                }
+            }
+            logger.debug("[search:typesense] Search completed", {
+                collection: collectionName,
+                query: query.query,
+                hits: hits.length,
+                totalHits,
+                processingTimeMs,
+            });
+            return {
+                hits,
+                totalHits,
+                processingTimeMs,
+                facetDistribution: (Object.keys(facetDistribution).length > 0 ? facetDistribution : undefined) ?? {},
+                page,
+                hitsPerPage,
+                totalPages,
+            };
+        }
+        catch (error) {
+            logger.error("[search:typesense] Search failed", {
+                index,
+                query: query.query,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    async deleteDocument(index, docId, tenantId) {
+        try {
+            const collectionName = this._getCollectionName(index, tenantId);
+            await this.client.collections(collectionName).documents(docId).delete();
+            logger.debug("[search:typesense] Deleted document", {
+                collection: collectionName,
+                docId,
+            });
+        }
+        catch (error) {
+            logger.error("[search:typesense] Failed to delete document", {
+                index,
+                docId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    async deleteByFilter(index, filters) {
+        try {
+            // Build filter string
+            const filterParts = [];
+            for (const [key, value] of Object.entries(filters)) {
+                if (typeof value === "string") {
+                    filterParts.push(`${key}:=${value}`);
+                }
+                else if (typeof value === "number") {
+                    filterParts.push(`${key}:=${value}`);
+                }
+                else if (typeof value === "boolean") {
+                    filterParts.push(`${key}:=${value ? 1 : 0}`);
+                }
+            }
+            const filterBy = filterParts.join(" && ");
+            // Search for matching documents
+            const result = await this.client
+                .collections(index)
+                .documents()
+                .search({ q: "*", filter_by: filterBy, limit: 10000 });
+            if (result?.hits && result.hits.length > 0) {
+                for (const hit of result.hits) {
+                    await this.client.collections(index).documents(hit.document.id).delete();
+                }
+                logger.debug("[search:typesense] Deleted documents by filter", {
+                    collection: index,
+                    filters,
+                    deletedCount: result.hits.length,
+                });
+            }
+        }
+        catch (error) {
+            logger.error("[search:typesense] Failed to delete by filter", {
+                index,
+                filters,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    async createIndex(index, settings) {
+        try {
+            // Typesense requires explicit schema definition
+            const schema = this._buildSchema(index, settings);
+            await this.client.collections().create(schema);
+            logger.info("[search:typesense] Collection created", { collection: index });
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes("Already exists")) {
+                logger.debug("[search:typesense] Collection already exists", { collection: index });
+                return;
+            }
+            logger.error("[search:typesense] Failed to create collection", {
+                index,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    async updateSettings(index, _settings) {
+        try {
+            // Typesense doesn't support updating schema after creation
+            // Log a warning and skip
+            logger.warn("[search:typesense] Schema updates not supported after creation", {
+                index,
+            });
+        }
+        catch (error) {
+            logger.error("[search:typesense] Failed to update settings", {
+                index,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    async close() {
+        logger.info("[search:typesense] Closing connection");
+        // Typesense doesn't require explicit connection cleanup
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    _getCollectionName(baseIndex, tenantId) {
+        if (tenantId) {
+            return `${baseIndex}__${tenantId}`;
+        }
+        return baseIndex;
+    }
+    _prepareDocument(doc) {
+        return { ...doc };
+    }
+    _buildSchema(collectionName, settings) {
+        const fields = [
+            { name: "id", type: "string" },
+            { name: "tenantId", type: "string", optional: true },
+        ];
+        // Add searchable fields
+        if (settings.searchableAttributes) {
+            for (const attr of settings.searchableAttributes) {
+                if (!["id", "tenantId"].includes(attr)) {
+                    fields.push({ name: attr, type: "string" });
+                }
+            }
+        }
+        // Add facetable fields
+        if (settings.facetableAttributes) {
+            for (const attr of settings.facetableAttributes) {
+                if (!fields.some((f) => f.name === attr)) {
+                    fields.push({ name: attr, type: "string", facet: true });
+                }
+            }
+        }
+        return {
+            name: collectionName,
+            fields,
+            default_sorting_field: "id",
+        };
+    }
+    _getQueryByFields() {
+        // Default searchable fields
+        return "id,tenantId";
+    }
+    _parseHostFromUrl(url) {
+        try {
+            const urlObj = new URL(url);
+            return urlObj.hostname;
+        }
+        catch {
+            return "localhost";
+        }
+    }
+    _parsePortFromUrl(url) {
+        try {
+            const urlObj = new URL(url);
+            if (urlObj.port) {
+                return parseInt(urlObj.port, 10);
+            }
+            return urlObj.protocol === "https:" ? 443 : 80;
+        }
+        catch {
+            return 8108;
+        }
+    }
+    _parseProtocolFromUrl(url) {
+        try {
+            const urlObj = new URL(url);
+            return urlObj.protocol.replace(":", "");
+        }
+        catch {
+            return "http";
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,163 @@
+import { z } from "zod";
+/**
+ * Supported search backend providers.
+ *
+ * - `meilisearch` — Self-hosted, developer-friendly, typo-tolerant
+ * - `typesense`   — Self-hosted, optimised for geo search and faceting
+ * - `algolia`     — Managed SaaS, zero-ops, global CDN
+ * - `pgvector`    — Postgres + pgvector extension; BM25 keyword + vector
+ *                   cosine search. Choose this when AI/RAG over your own
+ *                   Postgres is the primary use case (no external search
+ *                   infra to operate).
+ */
+export type SearchProviderType = "meilisearch" | "typesense" | "algolia" | "pgvector";
+/**
+ * A document that can be indexed by the search provider.
+ * All documents must have an id; tenantId is optional for multi-tenancy.
+ * Additional fields are arbitrary and searchable.
+ */
+export declare const SearchDocumentSchema: z.ZodObject<{
+    id: z.ZodString;
+    tenantId: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type SearchDocument = z.infer<typeof SearchDocumentSchema>;
+export declare const SearchQuerySchema: z.ZodObject<{
+    query: z.ZodString;
+    tenantId: z.ZodOptional<z.ZodString>;
+    filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    facets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sort: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    page: z.ZodOptional<z.ZodNumber>;
+    hitsPerPage: z.ZodOptional<z.ZodNumber>;
+    highlightFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    typoTolerance: z.ZodOptional<z.ZodBoolean>;
+    minScore: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type SearchQuery = z.infer<typeof SearchQuerySchema>;
+export interface SearchHit<T extends SearchDocument = SearchDocument> {
+    /** The matched document */
+    doc: T;
+    /** Score (0-1) — higher is more relevant */
+    score: number;
+    /** Field highlights (HTML-safe snippets with <mark> tags) */
+    highlights?: Record<string, string>;
+}
+export interface SearchResult<T extends SearchDocument = SearchDocument> {
+    /** Matching documents with relevance scores */
+    hits: SearchHit<T>[];
+    /** Total number of matches (before pagination) */
+    totalHits: number;
+    /** Time taken by the provider (in milliseconds) */
+    processingTimeMs: number;
+    /** Facet distribution for filter UI (if requested) */
+    facetDistribution?: Record<string, Record<string, number>>;
+    /** Current page number (1-indexed) */
+    page: number;
+    /** Hits per page */
+    hitsPerPage: number;
+    /** Total pages (calculated from totalHits / hitsPerPage) */
+    totalPages: number;
+}
+/**
+ * Every search backend must implement this interface.
+ * The factory function (`createSearch`) returns a `SearchProvider`.
+ */
+export interface SearchProvider {
+    readonly name: SearchProviderType;
+    /**
+     * Index a single document.
+     * If the document already exists, it is updated (upsert semantics).
+     */
+    indexDocument<T extends SearchDocument>(index: string, doc: T): Promise<void>;
+    /**
+     * Index multiple documents in a batch operation.
+     * More efficient than sequential indexDocument() calls.
+     */
+    indexDocuments<T extends SearchDocument>(index: string, docs: T[]): Promise<void>;
+    /**
+     * Search for documents matching a query.
+     */
+    search<T extends SearchDocument = SearchDocument>(index: string, query: SearchQuery): Promise<SearchResult<T>>;
+    /**
+     * Delete a single document from an index.
+     */
+    deleteDocument(index: string, docId: string, tenantId?: string): Promise<void>;
+    /**
+     * Delete multiple documents matching a filter.
+     * Typically used for tenant cleanup: deleteByFilter(index, { tenantId: "org_123" })
+     */
+    deleteByFilter(index: string, filters: Record<string, string | number | boolean>): Promise<void>;
+    /**
+     * Create or update an index with optional settings.
+     * Called during app initialization to set up searchable fields.
+     */
+    createIndex(index: string, settings: IndexSettings): Promise<void>;
+    /**
+     * Update index settings (e.g., searchable attributes, ranking rules).
+     */
+    updateSettings(index: string, settings: IndexSettings): Promise<void>;
+    /**
+     * Graceful shutdown — close connections, flush in-flight operations.
+     */
+    close(): Promise<void>;
+}
+export interface IndexSettings {
+    /** Attributes that should be searchable (default: all) */
+    searchableAttributes?: string[];
+    /** Attributes used for filtering */
+    filterableAttributes?: string[];
+    /** Attributes to use for faceting */
+    facetableAttributes?: string[];
+    /** Attributes used for sorting */
+    sortableAttributes?: string[];
+    /** Primary key / unique field (default: "id") */
+    primaryKey?: string;
+    /** Custom ranking rules (provider-specific) */
+    rankingRules?: string[];
+    /** Synonyms for the index (e.g., { "dashboard": ["overview", "analytics"] }) */
+    synonyms?: Record<string, string[]>;
+}
+export interface MeilisearchConfig {
+    provider: "meilisearch";
+    /** Meilisearch server URL (defaults to `process.env.MEILISEARCH_URL`) */
+    url?: string;
+    /** API key with at least search + indexing permissions (defaults to `process.env.MEILISEARCH_API_KEY`) */
+    apiKey?: string;
+    /** Default timeout for requests (in milliseconds, default: 30000) */
+    timeout?: number;
+}
+export interface TypesenseConfig {
+    provider: "typesense";
+    /** Typesense server URL (defaults to `process.env.TYPESENSE_URL`) */
+    url?: string;
+    /** API key for authentication (defaults to `process.env.TYPESENSE_API_KEY`) */
+    apiKey?: string;
+    /** Default timeout for requests (in milliseconds, default: 30000) */
+    timeout?: number;
+}
+export interface AlgoliaConfig {
+    provider: "algolia";
+    /** Algolia app ID (defaults to `process.env.ALGOLIA_APP_ID`) */
+    appId?: string;
+    /** Algolia search API key (defaults to `process.env.ALGOLIA_SEARCH_KEY`) */
+    searchKey?: string;
+    /** Algolia admin API key for indexing (defaults to `process.env.ALGOLIA_ADMIN_KEY`) */
+    adminKey?: string;
+}
+export interface PgvectorConfig {
+    provider: "pgvector";
+    /** Postgres connection string (defaults to `process.env.DATABASE_URL`) */
+    connectionString?: string;
+    /**
+     * Embedding vector dimension. All documents indexed under this provider
+     * must use the same dimension. Defaults to 1536 (OpenAI text-embedding-3-small).
+     */
+    embeddingDim?: number;
+    /**
+     * Optional table-name prefix. Each index becomes a table named
+     * `<prefix>_<index>`. Defaults to `nebutra_search`.
+     */
+    tablePrefix?: string;
+}
+export type SearchConfig = MeilisearchConfig | TypesenseConfig | AlgoliaConfig | PgvectorConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+// ── Search Document ────────────────────────────────────────────────────────
+/**
+ * A document that can be indexed by the search provider.
+ * All documents must have an id; tenantId is optional for multi-tenancy.
+ * Additional fields are arbitrary and searchable.
+ */
+export const SearchDocumentSchema = z
+    .object({
+    /** Globally unique document ID within the index */
+    id: z.string(),
+    /** Optional tenant/workspace ID for multi-tenant filtering */
+    tenantId: z.string().optional(),
+    /** Arbitrary searchable fields — flattened at index time */
+})
+    .passthrough();
+// ── Search Query ──────────────────────────────────────────────────────────
+export const SearchQuerySchema = z.object({
+    /** Full-text search query string (e.g., "analytics dashboard") */
+    query: z.string(),
+    /** Tenant ID for filtering results to a specific tenant */
+    tenantId: z.string().optional(),
+    /** Filters to apply (provider-agnostic key-value pairs) */
+    filters: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+    /** Facet fields to include in results (for filtering UI) */
+    facets: z.array(z.string()).optional(),
+    /** Sort order (e.g., ["createdAt:desc", "relevance:asc"]) */
+    sort: z.array(z.string()).optional(),
+    /** Page number (1-indexed, default: 1) */
+    page: z.number().int().min(1).optional(),
+    /** Hits per page (default: 20, max: 100) */
+    hitsPerPage: z.number().int().min(1).max(100).optional(),
+    /** Fields to return highlights for (where supported) */
+    highlightFields: z.array(z.string()).optional(),
+    /** Enable typo tolerance (default: true) */
+    typoTolerance: z.boolean().optional(),
+    /** Minimum score threshold (0-1, provider-dependent interpretation) */
+    minScore: z.number().min(0).max(1).optional(),
+});

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@nebutra/search",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
-  "license": "AGPL-3.0",
+  "license": "MIT",
   "type": "module",
   "nebutra": {
     "status": "foundation",
@@ -52,7 +52,7 @@
     "algoliasearch": "^5.20.0",
     "pg": "^8.13.1",
     "zod": "^4.3.6",
-    "@nebutra/logger": "0.1.0"
+    "@nebutra/logger": "0.1.1"
   },
   "devDependencies": {
     "@types/pg": "^8.11.10",