@danielsimonjr/memoryjs 1.0.0

package/dist/search/BM25Search.js

@@ -0,0 +1,340 @@
+/**
+ * BM25 Search
+ *
+ * BM25 (Best Matching 25) relevance scoring algorithm for lexical search.
+ * Provides improved ranking over TF-IDF by incorporating document length normalization.
+ *
+ * Phase 12 Sprint 3: Search Algorithm Optimization
+ *
+ * @module search/BM25Search
+ */
+import { SEARCH_LIMITS } from '../utils/constants.js';
+/**
+ * Common English stopwords to filter from queries and documents.
+ * These words are too common to provide meaningful ranking signal.
+ */
+export const STOPWORDS = new Set([
+    'a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'for', 'from',
+    'has', 'he', 'in', 'is', 'it', 'its', 'of', 'on', 'or', 'that',
+    'the', 'to', 'was', 'were', 'will', 'with', 'you', 'your',
+    'this', 'but', 'they', 'have', 'had', 'what', 'when', 'where',
+    'who', 'which', 'why', 'how', 'all', 'each', 'every', 'both',
+    'few', 'more', 'most', 'other', 'some', 'such', 'no', 'not',
+    'only', 'own', 'same', 'so', 'than', 'too', 'very', 'can',
+    'just', 'should', 'now', 'also', 'being', 'been', 'would',
+    'could', 'into', 'over', 'after', 'before', 'between', 'under',
+    'again', 'then', 'once', 'here', 'there', 'any', 'about',
+]);
+/**
+ * Default BM25 parameters based on research recommendations.
+ */
+export const DEFAULT_BM25_CONFIG = {
+    k1: 1.2,
+    b: 0.75,
+};
+/**
+ * BM25 Search implementation.
+ *
+ * BM25 improves over TF-IDF by:
+ * 1. Saturating term frequency - prevents long documents from dominating
+ * 2. Document length normalization - accounts for varying document sizes
+ *
+ * Formula:
+ * score(D,Q) = sum_i( IDF(qi) * (f(qi,D) * (k1 + 1)) / (f(qi,D) + k1 * (1 - b + b * |D|/avgdl)) )
+ *
+ * Where:
+ * - f(qi,D) is the term frequency of qi in document D
+ * - |D| is the length of document D
+ * - avgdl is the average document length
+ * - k1 and b are free parameters
+ *
+ * @example
+ * ```typescript
+ * const bm25 = new BM25Search(storage);
+ * await bm25.buildIndex();
+ * const results = await bm25.search('machine learning');
+ * ```
+ */
+export class BM25Search {
+    storage;
+    index = null;
+    config;
+    constructor(storage, config = {}) {
+        this.storage = storage;
+        this.config = { ...DEFAULT_BM25_CONFIG, ...config };
+    }
+    /**
+     * Get the current configuration.
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update configuration parameters.
+     *
+     * @param config - New configuration values
+     */
+    setConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Tokenize text into lowercase terms with stopword filtering.
+     *
+     * @param text - Text to tokenize
+     * @param filterStopwords - Whether to filter stopwords (default: true)
+     * @returns Array of lowercase tokens
+     */
+    tokenize(text, filterStopwords = true) {
+        const tokens = text
+            .toLowerCase()
+            .replace(/[^\w\s]/g, ' ')
+            .split(/\s+/)
+            .filter(token => token.length > 0);
+        if (filterStopwords) {
+            return tokens.filter(token => !STOPWORDS.has(token));
+        }
+        return tokens;
+    }
+    /**
+     * Build the BM25 index from the current graph.
+     *
+     * Should be called after significant graph changes.
+     */
+    async buildIndex() {
+        const graph = await this.storage.loadGraph();
+        const documents = new Map();
+        const documentFrequency = new Map();
+        const termsSeen = new Set();
+        let totalDocLength = 0;
+        // First pass: tokenize all documents and count term frequencies
+        for (const entity of graph.entities) {
+            const text = this.entityToText(entity);
+            const tokens = this.tokenize(text);
+            const termFreqs = new Map();
+            // Count term frequencies for this document
+            for (const token of tokens) {
+                termFreqs.set(token, (termFreqs.get(token) || 0) + 1);
+            }
+            // Track which terms appear in this document (for IDF calculation)
+            termsSeen.clear();
+            for (const token of tokens) {
+                if (!termsSeen.has(token)) {
+                    termsSeen.add(token);
+                    documentFrequency.set(token, (documentFrequency.get(token) || 0) + 1);
+                }
+            }
+            const entry = {
+                entityName: entity.name,
+                termFreqs,
+                docLength: tokens.length,
+            };
+            documents.set(entity.name, entry);
+            totalDocLength += tokens.length;
+        }
+        const totalDocs = documents.size;
+        const avgDocLength = totalDocs > 0 ? totalDocLength / totalDocs : 0;
+        this.index = {
+            documents,
+            documentFrequency,
+            avgDocLength,
+            totalDocs,
+        };
+    }
+    /**
+     * Search using the BM25 algorithm.
+     *
+     * @param query - Search query
+     * @param limit - Maximum results to return
+     * @returns Array of search results sorted by BM25 score
+     */
+    async search(query, limit = SEARCH_LIMITS.DEFAULT) {
+        const effectiveLimit = Math.min(limit, SEARCH_LIMITS.MAX);
+        // Ensure index is built
+        if (!this.index) {
+            await this.buildIndex();
+        }
+        if (!this.index || this.index.documents.size === 0) {
+            return [];
+        }
+        const graph = await this.storage.loadGraph();
+        const entityMap = new Map(graph.entities.map(e => [e.name, e]));
+        // Tokenize query
+        const queryTerms = this.tokenize(query);
+        if (queryTerms.length === 0) {
+            return [];
+        }
+        const { k1, b } = this.config;
+        const { documents, documentFrequency, avgDocLength, totalDocs } = this.index;
+        const results = [];
+        // Calculate BM25 score for each document
+        for (const [entityName, docEntry] of documents) {
+            const entity = entityMap.get(entityName);
+            if (!entity)
+                continue;
+            let score = 0;
+            const matchedFields = {};
+            for (const term of queryTerms) {
+                const tf = docEntry.termFreqs.get(term) || 0;
+                if (tf === 0)
+                    continue;
+                // Calculate IDF
+                const df = documentFrequency.get(term) || 0;
+                const idf = df > 0 ? Math.log((totalDocs - df + 0.5) / (df + 0.5) + 1) : 0;
+                // Calculate BM25 score component
+                const numerator = tf * (k1 + 1);
+                const denominator = tf + k1 * (1 - b + b * (docEntry.docLength / avgDocLength));
+                const termScore = idf * (numerator / denominator);
+                score += termScore;
+                // Track which fields matched
+                if (entity.name.toLowerCase().includes(term)) {
+                    matchedFields.name = true;
+                }
+                if (entity.entityType.toLowerCase().includes(term)) {
+                    matchedFields.entityType = true;
+                }
+                const matchedObs = entity.observations.filter(o => o.toLowerCase().includes(term));
+                if (matchedObs.length > 0) {
+                    matchedFields.observations = matchedObs;
+                }
+            }
+            if (score > 0) {
+                results.push({
+                    entity,
+                    score,
+                    matchedFields,
+                });
+            }
+        }
+        // Sort by score descending and limit
+        return results
+            .sort((a, b) => b.score - a.score)
+            .slice(0, effectiveLimit);
+    }
+    /**
+     * Update the index for changed entities.
+     *
+     * @param changedEntityNames - Names of entities that changed
+     */
+    async update(changedEntityNames) {
+        if (!this.index) {
+            await this.buildIndex();
+            return;
+        }
+        const graph = await this.storage.loadGraph();
+        const entityMap = new Map(graph.entities.map(e => [e.name, e]));
+        // Process each changed entity
+        for (const entityName of changedEntityNames) {
+            const entity = entityMap.get(entityName);
+            const existingEntry = this.index.documents.get(entityName);
+            if (existingEntry) {
+                // Remove old term frequencies from document frequency counts
+                for (const [term] of existingEntry.termFreqs) {
+                    const df = this.index.documentFrequency.get(term) || 0;
+                    if (df <= 1) {
+                        this.index.documentFrequency.delete(term);
+                    }
+                    else {
+                        this.index.documentFrequency.set(term, df - 1);
+                    }
+                }
+                this.index.documents.delete(entityName);
+            }
+            if (entity) {
+                // Add new entry
+                const text = this.entityToText(entity);
+                const tokens = this.tokenize(text);
+                const termFreqs = new Map();
+                const termsSeen = new Set();
+                for (const token of tokens) {
+                    termFreqs.set(token, (termFreqs.get(token) || 0) + 1);
+                    if (!termsSeen.has(token)) {
+                        termsSeen.add(token);
+                        this.index.documentFrequency.set(token, (this.index.documentFrequency.get(token) || 0) + 1);
+                    }
+                }
+                const entry = {
+                    entityName: entity.name,
+                    termFreqs,
+                    docLength: tokens.length,
+                };
+                this.index.documents.set(entityName, entry);
+            }
+        }
+        // Recalculate average document length
+        this.index.totalDocs = this.index.documents.size;
+        let totalLength = 0;
+        for (const doc of this.index.documents.values()) {
+            totalLength += doc.docLength;
+        }
+        this.index.avgDocLength = this.index.totalDocs > 0
+            ? totalLength / this.index.totalDocs
+            : 0;
+    }
+    /**
+     * Remove an entity from the index.
+     *
+     * @param entityName - Name of entity to remove
+     */
+    remove(entityName) {
+        if (!this.index) {
+            return false;
+        }
+        const entry = this.index.documents.get(entityName);
+        if (!entry) {
+            return false;
+        }
+        // Update document frequency counts
+        for (const [term] of entry.termFreqs) {
+            const df = this.index.documentFrequency.get(term) || 0;
+            if (df <= 1) {
+                this.index.documentFrequency.delete(term);
+            }
+            else {
+                this.index.documentFrequency.set(term, df - 1);
+            }
+        }
+        this.index.documents.delete(entityName);
+        // Update totals
+        this.index.totalDocs = this.index.documents.size;
+        let totalLength = 0;
+        for (const doc of this.index.documents.values()) {
+            totalLength += doc.docLength;
+        }
+        this.index.avgDocLength = this.index.totalDocs > 0
+            ? totalLength / this.index.totalDocs
+            : 0;
+        return true;
+    }
+    /**
+     * Clear the index.
+     */
+    clearIndex() {
+        this.index = null;
+    }
+    /**
+     * Check if the index is built.
+     */
+    isIndexed() {
+        return this.index !== null;
+    }
+    /**
+     * Get index statistics.
+     */
+    getIndexStats() {
+        if (!this.index) {
+            return null;
+        }
+        return {
+            documents: this.index.documents.size,
+            terms: this.index.documentFrequency.size,
+            avgDocLength: this.index.avgDocLength,
+        };
+    }
+    /**
+     * Convert an entity to searchable text.
+     */
+    entityToText(entity) {
+        return [entity.name, entity.entityType, ...entity.observations].join(' ');
+    }
+}
+//# sourceMappingURL=BM25Search.js.map

package/dist/search/BM25Search.js.map

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

package/dist/search/BasicSearch.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Basic Search
+ *
+ * Simple text-based search with tag, importance, and date filters with result caching.
+ *
+ * @module search/BasicSearch
+ */
+import type { KnowledgeGraph } from '../types/index.js';
+import type { GraphStorage } from '../core/GraphStorage.js';
+/**
+ * Performs basic text search with optional filters and caching.
+ */
+export declare class BasicSearch {
+    private storage;
+    private enableCache;
+    constructor(storage: GraphStorage, enableCache?: boolean);
+    /**
+     * Search nodes by text query with optional filters and pagination.
+     *
+     * Searches across entity names, types, and observations.
+     *
+     * @param query - Text to search for (case-insensitive)
+     * @param tags - Optional tags to filter by
+     * @param minImportance - Optional minimum importance (0-10)
+     * @param maxImportance - Optional maximum importance (0-10)
+     * @param offset - Number of results to skip (default: 0)
+     * @param limit - Maximum number of results (default: 50, max: 200)
+     * @returns Filtered knowledge graph with pagination applied
+     */
+    searchNodes(query: string, tags?: string[], minImportance?: number, maxImportance?: number, offset?: number, limit?: number): Promise<KnowledgeGraph>;
+    /**
+     * Open specific nodes by name.
+     *
+     * @param names - Array of entity names to retrieve
+     * @returns Knowledge graph with specified entities and their relations
+     */
+    openNodes(names: string[]): Promise<KnowledgeGraph>;
+    /**
+     * Search by date range with optional filters and pagination.
+     *
+     * @param startDate - Optional start date (ISO 8601)
+     * @param endDate - Optional end date (ISO 8601)
+     * @param entityType - Optional entity type filter
+     * @param tags - Optional tags filter
+     * @param offset - Number of results to skip (default: 0)
+     * @param limit - Maximum number of results (default: 50, max: 200)
+     * @returns Filtered knowledge graph with pagination applied
+     */
+    searchByDateRange(startDate?: string, endDate?: string, entityType?: string, tags?: string[], offset?: number, limit?: number): Promise<KnowledgeGraph>;
+}
+//# sourceMappingURL=BasicSearch.d.ts.map

package/dist/search/BasicSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BasicSearch.d.ts","sourceRoot":"","sources":["../../src/search/BasicSearch.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAI5D;;GAEG;AACH,qBAAa,WAAW;IAEpB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,WAAW;gBADX,OAAO,EAAE,YAAY,EACrB,WAAW,GAAE,OAAc;IAGrC;;;;;;;;;;;;OAYG;IACG,WAAW,CACf,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,MAAM,EAAE,EACf,aAAa,CAAC,EAAE,MAAM,EACtB,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,GAAE,MAAU,EAClB,KAAK,GAAE,MAA8B,GACpC,OAAO,CAAC,cAAc,CAAC;IAwD1B;;;;;OAKG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC;IAYzD;;;;;;;;;;OAUG;IACG,iBAAiB,CACrB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,MAAM,EAAE,EACf,MAAM,GAAE,MAAU,EAClB,KAAK,GAAE,MAA8B,GACpC,OAAO,CAAC,cAAc,CAAC;CAiD3B"}

package/dist/search/BasicSearch.js

@@ -0,0 +1,138 @@
+/**
+ * Basic Search
+ *
+ * Simple text-based search with tag, importance, and date filters with result caching.
+ *
+ * @module search/BasicSearch
+ */
+import { isWithinDateRange, SEARCH_LIMITS, searchCaches } from '../utils/index.js';
+import { SearchFilterChain } from './SearchFilterChain.js';
+/**
+ * Performs basic text search with optional filters and caching.
+ */
+export class BasicSearch {
+    storage;
+    enableCache;
+    constructor(storage, enableCache = true) {
+        this.storage = storage;
+        this.enableCache = enableCache;
+    }
+    /**
+     * Search nodes by text query with optional filters and pagination.
+     *
+     * Searches across entity names, types, and observations.
+     *
+     * @param query - Text to search for (case-insensitive)
+     * @param tags - Optional tags to filter by
+     * @param minImportance - Optional minimum importance (0-10)
+     * @param maxImportance - Optional maximum importance (0-10)
+     * @param offset - Number of results to skip (default: 0)
+     * @param limit - Maximum number of results (default: 50, max: 200)
+     * @returns Filtered knowledge graph with pagination applied
+     */
+    async searchNodes(query, tags, minImportance, maxImportance, offset = 0, limit = SEARCH_LIMITS.DEFAULT) {
+        // Check cache first
+        if (this.enableCache) {
+            const cacheKey = { query, tags, minImportance, maxImportance, offset, limit };
+            const cached = searchCaches.basic.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+        }
+        const graph = await this.storage.loadGraph();
+        const queryLower = query.toLowerCase();
+        // First filter by text match (search-specific)
+        // OPTIMIZED: Uses pre-computed lowercase cache to avoid repeated toLowerCase() calls
+        const textMatched = graph.entities.filter(e => {
+            const lowercased = this.storage.getLowercased(e.name);
+            if (lowercased) {
+                return (lowercased.name.includes(queryLower) ||
+                    lowercased.entityType.includes(queryLower) ||
+                    lowercased.observations.some(o => o.includes(queryLower)));
+            }
+            // Fallback for entities not in cache (shouldn't happen in normal use)
+            return (e.name.toLowerCase().includes(queryLower) ||
+                e.entityType.toLowerCase().includes(queryLower) ||
+                e.observations.some(o => o.toLowerCase().includes(queryLower)));
+        });
+        // Apply tag and importance filters using SearchFilterChain
+        const filters = { tags, minImportance, maxImportance };
+        const filteredEntities = SearchFilterChain.applyFilters(textMatched, filters);
+        // Apply pagination using SearchFilterChain
+        const pagination = SearchFilterChain.validatePagination(offset, limit);
+        const paginatedEntities = SearchFilterChain.paginate(filteredEntities, pagination);
+        const filteredEntityNames = new Set(paginatedEntities.map(e => e.name));
+        const filteredRelations = graph.relations.filter(r => filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to));
+        const result = { entities: paginatedEntities, relations: filteredRelations };
+        // Cache the result
+        if (this.enableCache) {
+            const cacheKey = { query, tags, minImportance, maxImportance, offset, limit };
+            searchCaches.basic.set(cacheKey, result);
+        }
+        return result;
+    }
+    /**
+     * Open specific nodes by name.
+     *
+     * @param names - Array of entity names to retrieve
+     * @returns Knowledge graph with specified entities and their relations
+     */
+    async openNodes(names) {
+        const graph = await this.storage.loadGraph();
+        const filteredEntities = graph.entities.filter(e => names.includes(e.name));
+        const filteredEntityNames = new Set(filteredEntities.map(e => e.name));
+        const filteredRelations = graph.relations.filter(r => filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to));
+        return { entities: filteredEntities, relations: filteredRelations };
+    }
+    /**
+     * Search by date range with optional filters and pagination.
+     *
+     * @param startDate - Optional start date (ISO 8601)
+     * @param endDate - Optional end date (ISO 8601)
+     * @param entityType - Optional entity type filter
+     * @param tags - Optional tags filter
+     * @param offset - Number of results to skip (default: 0)
+     * @param limit - Maximum number of results (default: 50, max: 200)
+     * @returns Filtered knowledge graph with pagination applied
+     */
+    async searchByDateRange(startDate, endDate, entityType, tags, offset = 0, limit = SEARCH_LIMITS.DEFAULT) {
+        // Check cache first
+        if (this.enableCache) {
+            const cacheKey = { method: 'dateRange', startDate, endDate, entityType, tags, offset, limit };
+            const cached = searchCaches.basic.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+        }
+        const graph = await this.storage.loadGraph();
+        // First filter by date range (search-specific - uses createdAt OR lastModified)
+        const dateFiltered = graph.entities.filter(e => {
+            const dateToCheck = e.createdAt || e.lastModified;
+            if (dateToCheck && !isWithinDateRange(dateToCheck, startDate, endDate)) {
+                return false;
+            }
+            return true;
+        });
+        // Apply entity type and tag filters using SearchFilterChain
+        const filters = { tags, entityType };
+        const filteredEntities = SearchFilterChain.applyFilters(dateFiltered, filters);
+        // Apply pagination using SearchFilterChain
+        const pagination = SearchFilterChain.validatePagination(offset, limit);
+        const paginatedEntities = SearchFilterChain.paginate(filteredEntities, pagination);
+        const filteredEntityNames = new Set(paginatedEntities.map(e => e.name));
+        const filteredRelations = graph.relations.filter(r => {
+            const dateToCheck = r.createdAt || r.lastModified;
+            const inDateRange = !dateToCheck || isWithinDateRange(dateToCheck, startDate, endDate);
+            const involvesFilteredEntities = filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to);
+            return inDateRange && involvesFilteredEntities;
+        });
+        const result = { entities: paginatedEntities, relations: filteredRelations };
+        // Cache the result
+        if (this.enableCache) {
+            const cacheKey = { method: 'dateRange', startDate, endDate, entityType, tags, offset, limit };
+            searchCaches.basic.set(cacheKey, result);
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=BasicSearch.js.map

package/dist/search/BasicSearch.js.map

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

package/dist/search/BooleanSearch.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Boolean Search
+ *
+ * Advanced search with boolean operators (AND, OR, NOT) and field-specific queries.
+ *
+ * @module search/BooleanSearch
+ */
+import type { KnowledgeGraph } from '../types/index.js';
+import type { GraphStorage } from '../core/GraphStorage.js';
+/**
+ * Performs boolean search with query parsing and AST evaluation.
+ */
+export declare class BooleanSearch {
+    private storage;
+    /**
+     * Phase 4 Sprint 4: AST cache to avoid re-parsing queries.
+     * Maps query string -> parsed AST.
+     */
+    private astCache;
+    /**
+     * Phase 4 Sprint 4: Result cache for boolean search.
+     * Maps cache key -> cached results.
+     */
+    private resultCache;
+    constructor(storage: GraphStorage);
+    /**
+     * Phase 4 Sprint 4: Generate cache key for boolean search.
+     */
+    private generateCacheKey;
+    /**
+     * Phase 4 Sprint 4: Clear all caches.
+     */
+    clearCache(): void;
+    /**
+     * Phase 4 Sprint 4: Cleanup old cache entries.
+     */
+    private cleanupResultCache;
+    /**
+     * Phase 4 Sprint 4: Get or parse AST for a query.
+     */
+    private getOrParseAST;
+    /**
+     * Boolean search with support for AND, OR, NOT operators, field-specific queries, and pagination.
+     *
+     * Phase 4 Sprint 4: Implements AST caching and result caching for repeated queries.
+     *
+     * Query syntax examples:
+     * - "alice AND programming" - Both terms must match
+     * - "type:person OR type:organization" - Either type matches
+     * - "NOT archived" - Exclude archived items
+     * - "name:alice AND (observation:coding OR observation:teaching)"
+     *
+     * @param query - Boolean query string
+     * @param tags - Optional tags filter
+     * @param minImportance - Optional minimum importance
+     * @param maxImportance - Optional maximum importance
+     * @param offset - Number of results to skip (default: 0)
+     * @param limit - Maximum number of results (default: 50, max: 200)
+     * @returns Filtered knowledge graph matching the boolean query with pagination applied
+     */
+    booleanSearch(query: string, tags?: string[], minImportance?: number, maxImportance?: number, offset?: number, limit?: number): Promise<KnowledgeGraph>;
+    /**
+     * Tokenize a boolean query into tokens.
+     *
+     * Handles quoted strings, parentheses, and operators.
+     */
+    private tokenizeBooleanQuery;
+    /**
+     * Parse a boolean search query into an AST.
+     *
+     * Supports: AND, OR, NOT, parentheses, field-specific queries (field:value)
+     */
+    private parseBooleanQuery;
+    /**
+     * Evaluate a boolean query AST against an entity.
+     */
+    private evaluateBooleanQuery;
+    /**
+     * Check if a search term is simple (no regex or wildcards).
+     * Simple terms can use the O(1) observation index.
+     */
+    private isSimpleTerm;
+    /**
+     * Check if entity matches a search term in any text field.
+     * OPTIMIZED: Uses pre-computed lowercase data when available.
+     */
+    private entityMatchesTerm;
+    /**
+     * Validate query complexity to prevent resource exhaustion.
+     * Checks nesting depth, term count, and operator count against configured limits.
+     */
+    private validateQueryComplexity;
+    /**
+     * Calculate query complexity metrics.
+     */
+    private calculateQueryComplexity;
+}
+//# sourceMappingURL=BooleanSearch.d.ts.map

package/dist/search/BooleanSearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BooleanSearch.d.ts","sourceRoot":"","sources":["../../src/search/BooleanSearch.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAA4B,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAClF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAkC5D;;GAEG;AACH,qBAAa,aAAa;IAaZ,OAAO,CAAC,OAAO;IAZ3B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAA4C;IAE5D;;;OAGG;IACH,OAAO,CAAC,WAAW,CAA6C;gBAE5C,OAAO,EAAE,YAAY;IAEzC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAkBxB;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAwB1B;;OAEG;IACH,OAAO,CAAC,aAAa;IAqBrB;;;;;;;;;;;;;;;;;;OAkBG;IACG,aAAa,CACjB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,MAAM,EAAE,EACf,aAAa,CAAC,EAAE,MAAM,EACtB,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,GAAE,MAAU,EAClB,KAAK,GAAE,MAA8B,GACpC,OAAO,CAAC,cAAc,CAAC;IA2E1B;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IA+C5B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAuFzB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA2D5B;;;OAGG;IACH,OAAO,CAAC,YAAY;IAKpB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAoBzB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IA2B/B;;OAEG;IACH,OAAO,CAAC,wBAAwB;CA8BjC"}