allprofanity 2.1.1 → 2.2.1

package/dist/index.js

@@ -7,6 +7,11 @@ import spanishBadWords from "./languages/spanish-words.js";
 import bengaliBadWords from "./languages/bengali-words.js";
 import tamilBadWords from "./languages/tamil-words.js";
 import teluguBadWords from "./languages/telugu-words.js";
+import brazilianBadWords from "./languages/brazilian-words.js";
+// Advanced algorithm imports
+import { AhoCorasick } from "./algos/aho-corasick.js";
+import { BloomFilter } from "./algos/bloom-filter.js";
+import { ContextAnalyzer } from "./algos/context-patterns.js";
 // Export language dictionaries for direct access
 export { default as englishBadWords } from "./languages/english-words.js";
 export { default as hindiBadWords } from "./languages/hindi-words.js";
@@ -16,36 +21,128 @@ export { default as spanishBadWords } from "./languages/spanish-words.js";
 export { default as bengaliBadWords } from "./languages/bengali-words.js";
 export { default as tamilBadWords } from "./languages/tamil-words.js";
 export { default as teluguBadWords } from "./languages/telugu-words.js";
+export { default as brazilianBadWords } from "./languages/brazilian-words.js";
 /**
- * Default console logger implementation.
+ * Default console logger implementation for AllProfanity.
+ *
+ * @class ConsoleLogger
+ * @implements {Logger}
+ * @description Logs messages to the browser or Node.js console with an "[AllProfanity]" prefix.
+ * This is the default logger used when no custom logger is provided.
+ *
+ * @internal
  */
 class ConsoleLogger {
+    /**
+     * Log informational messages to console.log with [AllProfanity] prefix.
+     *
+     * @param message - The message to log
+     * @returns void
+     */
     info(message) {
         console.log(`[AllProfanity] ${message}`);
     }
+    /**
+     * Log warning messages to console.warn with [AllProfanity] prefix.
+     *
+     * @param message - The warning message to log
+     * @returns void
+     */
     warn(message) {
         console.warn(`[AllProfanity] ${message}`);
     }
+    /**
+     * Log error messages to console.error with [AllProfanity] prefix.
+     *
+     * @param message - The error message to log
+     * @returns void
+     */
     error(message) {
         console.error(`[AllProfanity] ${message}`);
     }
 }
 /**
- * Severity levels for profanity detection.
+ * Silent logger implementation that suppresses all log output.
+ *
+ * @class SilentLogger
+ * @implements {Logger}
+ * @description A no-op logger that discards all log messages. Used when `silent: true` is set
+ * in AllProfanityOptions, or when you want to completely disable logging.
+ *
+ * @internal
+ */
+class SilentLogger {
+    /**
+     * No-op implementation - messages are discarded.
+     *
+     * @param _message - The message (unused)
+     * @returns void
+     */
+    info(_message) {
+        // Silent mode - no logging
+    }
+    /**
+     * No-op implementation - warnings are discarded.
+     *
+     * @param _message - The warning message (unused)
+     * @returns void
+     */
+    warn(_message) {
+        // Silent mode - no logging
+    }
+    /**
+     * No-op implementation - errors are discarded.
+     *
+     * @param _message - The error message (unused)
+     * @returns void
+     */
+    error(_message) {
+        // Silent mode - no logging
+    }
+}
+/**
+ * Severity levels for profanity detection results.
+ *
+ * @enum {number}
+ * @description Categorizes the severity of detected profanity based on the number
+ * of unique words and total matches found in the text.
+ *
+ * @readonly
+ * @example
+ * ```typescript
+ * const result = filter.detect("some text");
+ * if (result.severity === ProfanitySeverity.EXTREME) {
+ *   // Handle extreme profanity
+ * }
+ * ```
  */
 export var ProfanitySeverity;
 (function (ProfanitySeverity) {
+    /** Mild profanity: 1 unique word or 1 total match */
     ProfanitySeverity[ProfanitySeverity["MILD"] = 1] = "MILD";
+    /** Moderate profanity: 2 unique words or 2 total matches */
     ProfanitySeverity[ProfanitySeverity["MODERATE"] = 2] = "MODERATE";
+    /** Severe profanity: 3 unique words or 3 total matches */
     ProfanitySeverity[ProfanitySeverity["SEVERE"] = 3] = "SEVERE";
+    /** Extreme profanity: 4+ unique words or 5+ total matches */
     ProfanitySeverity[ProfanitySeverity["EXTREME"] = 4] = "EXTREME";
 })(ProfanitySeverity = ProfanitySeverity || (ProfanitySeverity = {}));
 /**
- * Validate a string parameter.
- * @param input - The input to validate.
- * @param paramName - The name of the parameter.
- * @returns The validated string.
- * @throws {TypeError} If input is not a string.
+ * Validates that an input is a non-empty string.
+ *
+ * @function validateString
+ * @param {unknown} input - The value to validate
+ * @param {string} paramName - Name of the parameter being validated (used in error messages)
+ * @returns {string} The validated string
+ * @throws {TypeError} If input is not a string
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * const text = validateString(userInput, 'text');
+ * // Returns userInput if it's a string, throws TypeError otherwise
+ * ```
  */
 function validateString(input, paramName) {
     if (typeof input !== "string") {
@@ -54,11 +151,22 @@ function validateString(input, paramName) {
     return input;
 }
 /**
- * Validate a string array parameter.
- * @param input - The input to validate.
- * @param paramName - The name of the parameter.
- * @returns The validated string array.
- * @throws {TypeError} If input is not an array.
+ * Validates and filters a string array, removing non-string and empty items.
+ *
+ * @function validateStringArray
+ * @param {unknown} input - The value to validate (expected to be an array)
+ * @param {string} paramName - Name of the parameter being validated (used in error/warning messages)
+ * @returns {string[]} Array of valid, non-empty strings
+ * @throws {TypeError} If input is not an array
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * const words = validateStringArray(['word1', '', 123, 'word2'], 'words');
+ * // Returns: ['word1', 'word2']
+ * // Logs warning: "Skipping non-string item in words: 123"
+ * ```
  */
 function validateStringArray(input, paramName) {
     if (!Array.isArray(input)) {
@@ -73,17 +181,50 @@ function validateStringArray(input, paramName) {
     });
 }
 /**
- * Trie node for efficient string matching.
+ * Trie (prefix tree) node for efficient pattern matching and word storage.
+ *
+ * @class TrieNode
+ * @description Implements a trie data structure for O(m) time complexity word matching,
+ * where m is the length of the word being searched. Each node represents a character
+ * in the word, and paths from root to nodes with isEndOfWord=true represent complete words.
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * const trie = new TrieNode();
+ * trie.addWord('bad');
+ * trie.addWord('badword');
+ * const matches = trie.findMatches('badwords here', 0, false);
+ * // Returns matches for 'bad' and 'badword'
+ * ```
  */
 class TrieNode {
     constructor() {
+        /** Map of characters to child nodes for fast lookups */
         this.children = new Map();
+        /** Flag indicating if this node represents the end of a complete word */
         this.isEndOfWord = false;
+        /** The complete word ending at this node (only set when isEndOfWord is true) */
         this.word = "";
     }
     /**
-     * Add a word to the trie.
-     * @param word - The word to add.
+     * Adds a word to the trie structure.
+     *
+     * @param {string} word - The word to add to the trie
+     * @returns {void}
+     *
+     * @remarks
+     * - Time Complexity: O(m) where m is the length of the word
+     * - Space Complexity: O(m) in worst case when all characters are new
+     * - Supports any Unicode characters
+     *
+     * @example
+     * ```typescript
+     * const trie = new TrieNode();
+     * trie.addWord('hello');
+     * trie.addWord('world');
+     * ```
      */
     addWord(word) {
         let current = this;
@@ -100,13 +241,36 @@ class TrieNode {
         current.word = word;
     }
     /**
-     * Remove a word from the trie.
-     * @param word - The word to remove.
-     * @returns True if the word was removed, false otherwise.
+     * Removes a word from the trie structure.
+     *
+     * @param {string} word - The word to remove from the trie
+     * @returns {boolean} True if the word existed and was removed, false if word was not found
+     *
+     * @remarks
+     * - Time Complexity: O(m) where m is the length of the word
+     * - Also removes unnecessary nodes to keep the trie optimized
+     * - Only removes the word marking; shared prefixes with other words are preserved
+     *
+     * @example
+     * ```typescript
+     * const trie = new TrieNode();
+     * trie.addWord('hello');
+     * trie.removeWord('hello'); // Returns: true
+     * trie.removeWord('world'); // Returns: false (word not in trie)
+     * ```
      */
     removeWord(word) {
         return this.removeHelper(word, 0);
     }
+    /**
+     * Recursive helper method for removing a word from the trie.
+     *
+     * @param {string} word - The word being removed
+     * @param {number} index - Current character index in the word
+     * @returns {boolean} True if this node should be deleted (has no children and is not end of another word)
+     *
+     * @internal
+     */
     removeHelper(word, index) {
         if (index === word.length) {
             if (!this.isEndOfWord)
@@ -126,11 +290,25 @@ class TrieNode {
         return false;
     }
     /**
-     * Find all matches starting at a given position.
-     * @param text - The text to search.
-     * @param startPos - The start position.
-     * @param allowPartial - Whether to allow partial word matches.
-     * @returns Array of matches.
+     * Finds all word matches in text starting at a specific position.
+     *
+     * @param {string} text - The text to search for profanity
+     * @param {number} startPos - The starting position (0-based index) in the text
+     * @param {boolean} allowPartial - If true, finds partial matches within larger words
+     * @returns {Array<{ word: string; start: number; end: number }>} Array of match objects with word and position info
+     *
+     * @remarks
+     * - Time Complexity: O(k) where k is the length of the longest match from startPos
+     * - Returns all valid words that can be formed starting from startPos
+     * - When allowPartial is false, respects word boundaries
+     *
+     * @example
+     * ```typescript
+     * const trie = new TrieNode();
+     * trie.addWord('bad');
+     * const matches = trie.findMatches('badword', 0, false);
+     * // Returns: [{ word: 'bad', start: 0, end: 3 }]
+     * ```
      */
     findMatches(text, startPos, allowPartial) {
         const matches = [];
@@ -164,7 +342,22 @@ class TrieNode {
         return matches;
     }
     /**
-     * Clear all words from the trie.
+     * Clears all words from the trie, resetting it to empty state.
+     *
+     * @returns {void}
+     *
+     * @remarks
+     * - Time Complexity: O(1) - clears the root node only (JavaScript GC handles children)
+     * - Removes all stored words and resets the trie to initial state
+     *
+     * @example
+     * ```typescript
+     * const trie = new TrieNode();
+     * trie.addWord('hello');
+     * trie.addWord('world');
+     * trie.clear();
+     * // Trie is now empty
+     * ```
      */
     clear() {
         this.children.clear();
@@ -173,12 +366,139 @@ class TrieNode {
     }
 }
 /**
- * Main class for profanity detection and filtering.
+ * AllProfanity - Professional-grade multilingual profanity detection and filtering library.
+ *
+ * @class AllProfanity
+ * @description A comprehensive, high-performance profanity filtering system supporting 9+ languages
+ * with advanced features including leet speak detection, context analysis, multiple matching algorithms,
+ * and customizable filtering options.
+ *
+ * @remarks
+ * ### Features:
+ * - **Multi-language Support**: English, Hindi, French, German, Spanish, Bengali, Tamil, Telugu, Brazilian Portuguese
+ * - **Advanced Algorithms**: Trie, Aho-Corasick, Bloom Filter, and hybrid approaches
+ * - **Leet Speak Detection**: Automatically normalizes and detects variations like "h3ll0"
+ * - **Context Analysis**: Reduces false positives using surrounding word context
+ * - **Performance**: Built-in caching and optimized data structures
+ * - **Flexible**: Custom dictionaries, whitelisting, severity levels
+ *
+ * ### Default Behavior:
+ * - Loads English and Hindi dictionaries by default
+ * - Case-insensitive matching
+ * - Leet speak detection enabled
+ * - Uses Trie algorithm (fastest for most cases)
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with default instance
+ * import allProfanity from 'allprofanity';
+ *
+ * const result = allProfanity.detect("This is some bad text");
+ * console.log(result.hasProfanity); // true
+ * console.log(result.cleanedText); // "This is some *** text"
+ * console.log(result.severity); // ProfanitySeverity.MILD
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Advanced usage with custom configuration
+ * import { AllProfanity, ProfanitySeverity } from 'allprofanity';
+ *
+ * const filter = new AllProfanity({
+ *   languages: ['english', 'french', 'spanish'],
+ *   enableLeetSpeak: true,
+ *   strictMode: true,
+ *   algorithm: {
+ *     matching: 'hybrid',
+ *     useBloomFilter: true
+ *   },
+ *   performance: {
+ *     enableCaching: true,
+ *     cacheSize: 500
+ *   },
+ *   whitelistWords: ['class', 'assignment']
+ * });
+ *
+ * const text = "This text has some b@d w0rds";
+ * const result = filter.detect(text);
+ *
+ * if (result.hasProfanity) {
+ *   console.log(`Found ${result.detectedWords.length} profane words`);
+ *   console.log(`Severity: ${ProfanitySeverity[result.severity]}`);
+ *   console.log(`Cleaned: ${result.cleanedText}`);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using individual methods
+ * const filter = new AllProfanity();
+ *
+ * // Simple check
+ * if (filter.check("some text")) {
+ *   console.log("Contains profanity!");
+ * }
+ *
+ * // Clean with custom placeholder
+ * const cleaned = filter.clean("bad words here", "#");
+ *
+ * // Load additional languages
+ * filter.loadLanguage('german');
+ * filter.loadIndianLanguages(); // Loads hindi, bengali, tamil, telugu
+ *
+ * // Add custom words
+ * filter.add(['customword1', 'customword2']);
+ *
+ * // Remove words
+ * filter.remove(['someword']);
+ *
+ * // Whitelist words
+ * filter.addToWhitelist(['class', 'assignment']);
+ * ```
+ *
+ * @see {@link AllProfanityOptions} for all configuration options
+ * @see {@link ProfanityDetectionResult} for detection result format
+ * @see {@link ProfanitySeverity} for severity levels
  */
 export class AllProfanity {
     /**
-     * Create an AllProfanity instance.
-     * @param options - Profanity filter configuration options.
+     * Creates a new AllProfanity instance with the specified configuration.
+     *
+     * @constructor
+     * @param {AllProfanityOptions} [options] - Configuration options for profanity detection behavior
+     *
+     * @remarks
+     * ### Default Initialization:
+     * - Loads English and Hindi dictionaries automatically
+     * - Enables leet speak detection
+     * - Case-insensitive matching
+     * - Uses Trie algorithm for pattern matching
+     *
+     * ### Performance Considerations:
+     * - Initial load time depends on number of languages loaded
+     * - Aho-Corasick automaton (if enabled) is built during construction
+     * - Bloom Filter (if enabled) is populated during construction
+     *
+     * @throws {TypeError} If invalid options are provided
+     *
+     * @example
+     * ```typescript
+     * // Default instance
+     * const filter = new AllProfanity();
+     *
+     * // Custom configuration
+     * const filter = new AllProfanity({
+     *   languages: ['english', 'french'],
+     *   strictMode: true,
+     *   defaultPlaceholder: '#',
+     *   algorithm: { matching: 'hybrid' }
+     * });
+     *
+     * // Silent mode (no logging)
+     * const filter = new AllProfanity({ silent: true });
+     * ```
+     *
+     * @see {@link AllProfanityOptions} for all available configuration options
      */
     constructor(options) {
         var _a, _b, _c, _d, _e;
@@ -199,6 +519,7 @@ export class AllProfanity {
             bengali: bengaliBadWords || [],
             tamil: tamilBadWords || [],
             telugu: teluguBadWords || [],
+            brazilian: brazilianBadWords || [],
         };
         this.leetMappings = new Map([
             ["@", "a"],
@@ -259,7 +580,14 @@ export class AllProfanity {
             ["7_", "z"],
         ]);
         this.dynamicWords = new Set();
-        this.logger = (options === null || options === void 0 ? void 0 : options.logger) || new ConsoleLogger();
+        // Advanced algorithms
+        this.ahoCorasickAutomaton = null;
+        this.bloomFilter = null;
+        this.contextAnalyzer = null;
+        this.matchingAlgorithm = "trie";
+        this.resultCache = null;
+        // Use silent logger if silent mode is enabled, otherwise use provided logger or console logger
+        this.logger = (options === null || options === void 0 ? void 0 : options.logger) || ((options === null || options === void 0 ? void 0 : options.silent) ? new SilentLogger() : new ConsoleLogger());
         if ((options === null || options === void 0 ? void 0 : options.defaultPlaceholder) !== undefined) {
             this.setPlaceholder(options.defaultPlaceholder);
         }
@@ -270,6 +598,9 @@ export class AllProfanity {
         if (options === null || options === void 0 ? void 0 : options.whitelistWords) {
             this.addToWhitelist(options.whitelistWords);
         }
+        // Initialize advanced algorithms BEFORE loading dictionaries
+        // so that words can be added to all data structures
+        this.initializeAdvancedAlgorithms(options);
         this.loadLanguage("english");
         this.loadLanguage("hindi");
         if ((_e = options === null || options === void 0 ? void 0 : options.languages) === null || _e === void 0 ? void 0 : _e.length) {
@@ -281,6 +612,52 @@ export class AllProfanity {
             });
         }
     }
+    /**
+     * Initialize advanced algorithms based on configuration
+     */
+    initializeAdvancedAlgorithms(options) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+        // Set matching algorithm
+        if ((_a = options === null || options === void 0 ? void 0 : options.algorithm) === null || _a === void 0 ? void 0 : _a.matching) {
+            this.matchingAlgorithm = options.algorithm.matching;
+        }
+        // Initialize Bloom Filter if enabled
+        const bloomEnabled = ((_b = options === null || options === void 0 ? void 0 : options.algorithm) === null || _b === void 0 ? void 0 : _b.useBloomFilter) ||
+            ((_c = options === null || options === void 0 ? void 0 : options.bloomFilter) === null || _c === void 0 ? void 0 : _c.enabled) ||
+            this.matchingAlgorithm === "hybrid";
+        if (bloomEnabled) {
+            const expectedItems = ((_d = options === null || options === void 0 ? void 0 : options.bloomFilter) === null || _d === void 0 ? void 0 : _d.expectedItems) || 10000;
+            const falsePositiveRate = ((_e = options === null || options === void 0 ? void 0 : options.bloomFilter) === null || _e === void 0 ? void 0 : _e.falsePositiveRate) || 0.01;
+            this.bloomFilter = new BloomFilter(expectedItems, falsePositiveRate);
+            this.logger.info(`Bloom Filter initialized with ${expectedItems} expected items and ${(falsePositiveRate * 100).toFixed(2)}% false positive rate`);
+        }
+        // Initialize Aho-Corasick if enabled
+        const ahoEnabled = ((_f = options === null || options === void 0 ? void 0 : options.algorithm) === null || _f === void 0 ? void 0 : _f.useAhoCorasick) ||
+            ((_g = options === null || options === void 0 ? void 0 : options.ahoCorasick) === null || _g === void 0 ? void 0 : _g.enabled) ||
+            this.matchingAlgorithm === "aho-corasick" ||
+            this.matchingAlgorithm === "hybrid";
+        if (ahoEnabled) {
+            this.ahoCorasickAutomaton = new AhoCorasick([]);
+            this.logger.info("Aho-Corasick automaton initialized");
+        }
+        // Initialize Context Analyzer if enabled
+        const contextEnabled = ((_h = options === null || options === void 0 ? void 0 : options.algorithm) === null || _h === void 0 ? void 0 : _h.useContextAnalysis) ||
+            ((_j = options === null || options === void 0 ? void 0 : options.contextAnalysis) === null || _j === void 0 ? void 0 : _j.enabled);
+        if (contextEnabled) {
+            const contextLanguages = ((_k = options === null || options === void 0 ? void 0 : options.contextAnalysis) === null || _k === void 0 ? void 0 : _k.languages) || ["en"];
+            this.contextAnalyzer = new ContextAnalyzer(contextLanguages);
+            if ((_l = options === null || options === void 0 ? void 0 : options.contextAnalysis) === null || _l === void 0 ? void 0 : _l.contextWindow) {
+                this.contextAnalyzer.setContextWindow(options.contextAnalysis.contextWindow);
+            }
+            this.logger.info(`Context Analyzer initialized for languages: ${contextLanguages.join(", ")}`);
+        }
+        // Initialize result cache if enabled
+        if ((_m = options === null || options === void 0 ? void 0 : options.performance) === null || _m === void 0 ? void 0 : _m.enableCaching) {
+            const cacheSize = options.performance.cacheSize || 1000;
+            this.resultCache = new Map();
+            this.logger.info(`Result caching enabled with size limit: ${cacheSize}`);
+        }
+    }
     /**
      * Normalize leet speak to regular characters.
      * @param text - The input text.
@@ -371,11 +748,123 @@ export class AllProfanity {
         return result;
     }
     /**
-     * Detect profanity in a given text.
-     * @param text - The text to check.
-     * @returns Profanity detection result.
+     * Use Aho-Corasick algorithm for pattern matching
+     */
+    findMatchesWithAhoCorasick(searchText, originalText) {
+        if (!this.ahoCorasickAutomaton) {
+            return [];
+        }
+        const ahoMatches = this.ahoCorasickAutomaton.findAll(searchText);
+        const results = [];
+        for (const match of ahoMatches) {
+            if (!this.detectPartialWords &&
+                !this.isWholeWord(originalText, match.start, match.end)) {
+                continue;
+            }
+            const matchedText = originalText.substring(match.start, match.end);
+            if (this.isWhitelistedMatch(match.pattern, matchedText)) {
+                continue;
+            }
+            if (this.hasWordBoundaries(originalText, match.start, match.end)) {
+                results.push({
+                    word: match.pattern,
+                    start: match.start,
+                    end: match.end,
+                    originalWord: matchedText,
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Hybrid approach: Aho-Corasick for fast matching, Bloom Filter for validation
+     */
+    findMatchesHybrid(searchText, originalText) {
+        // Use Aho-Corasick for primary matching if available
+        if (this.ahoCorasickAutomaton) {
+            const matches = this.findMatchesWithAhoCorasick(searchText, originalText);
+            // If Bloom Filter is enabled, validate matches
+            if (this.bloomFilter) {
+                return matches.filter((match) => this.bloomFilter.mightContain(match.word));
+            }
+            return matches;
+        }
+        // Fallback to Trie if Aho-Corasick not available
+        const matches = [];
+        this.findMatches(searchText, originalText, matches);
+        // Validate with Bloom Filter if enabled
+        if (this.bloomFilter) {
+            return matches.filter((match) => this.bloomFilter.mightContain(match.word));
+        }
+        return matches;
+    }
+    /**
+     * Apply context analysis to filter false positives
+     */
+    applyContextAnalysis(text, matches, scoreThreshold = 0.5) {
+        if (!this.contextAnalyzer) {
+            return matches;
+        }
+        return matches.filter((match) => {
+            const analysis = this.contextAnalyzer.analyzeContext(text, match.start, match.end, match.word);
+            // If score is above threshold, it's likely profanity
+            return analysis.score >= scoreThreshold;
+        });
+    }
+    /**
+     * Detects profanity in the provided text and returns comprehensive analysis.
+     *
+     * @param {string} text - The text to analyze for profanity
+     * @returns {ProfanityDetectionResult} Detailed detection result including matches, positions, severity, and cleaned text
+     *
+     * @throws {TypeError} If text is not a string
+     *
+     * @remarks
+     * ### Performance:
+     * - Time Complexity: O(n*m) where n is text length, m is average word length in dictionary
+     * - With Bloom Filter: O(n) average case (faster early rejection)
+     * - With Caching: O(1) for repeated identical text
+     *
+     * ### Features:
+     * - Detects leet speak variations (if enabled): "h3ll0" → "hello"
+     * - Respects word boundaries (strict mode) or detects partial matches
+     * - Returns exact positions for highlighting/masking
+     * - Calculates severity based on match count and uniqueness
+     *
+     * ### Caching:
+     * - Results are cached if `performance.enableCaching` is true
+     * - Cache uses LRU eviction when size limit is reached
+     *
+     * @example
+     * ```typescript
+     * const filter = new AllProfanity();
+     * const result = filter.detect("This has bad words");
+     *
+     * console.log(result.hasProfanity); // true
+     * console.log(result.detectedWords); // ['bad']
+     * console.log(result.cleanedText); // 'This has *** words'
+     * console.log(result.severity); // ProfanitySeverity.MILD
+     * console.log(result.positions); // [{ word: 'bad', start: 9, end: 12 }]
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With leet speak detection
+     * const filter = new AllProfanity({ enableLeetSpeak: true });
+     * const result = filter.detect("st0p b3ing b@d");
+     *
+     * if (result.hasProfanity) {
+     *   result.positions.forEach(pos => {
+     *     console.log(`Found "${pos.word}" at position ${pos.start}-${pos.end}`);
+     *   });
+     * }
+     * ```
+     *
+     * @see {@link ProfanityDetectionResult} for result structure
+     * @see {@link ProfanitySeverity} for severity levels
      */
     detect(text) {
+        var _a;
         const validatedText = validateString(text, "text");
         if (validatedText.length === 0) {
             return {
@@ -386,22 +875,56 @@ export class AllProfanity {
                 positions: [],
             };
         }
-        const matches = [];
+        // Check cache first if enabled
+        if ((_a = this.resultCache) === null || _a === void 0 ? void 0 : _a.has(validatedText)) {
+            return this.resultCache.get(validatedText);
+        }
+        let matches = [];
         const normalizedText = this.caseSensitive
             ? validatedText
             : validatedText.toLowerCase();
-        this.findMatches(normalizedText, validatedText, matches);
-        if (this.enableLeetSpeak) {
-            const leetNormalized = this.normalizeLeetSpeak(normalizedText);
-            if (leetNormalized !== normalizedText) {
-                this.findMatches(leetNormalized, validatedText, matches);
-            }
+        // Choose matching algorithm based on configuration
+        switch (this.matchingAlgorithm) {
+            case "aho-corasick":
+                matches = this.findMatchesWithAhoCorasick(normalizedText, validatedText);
+                if (this.enableLeetSpeak) {
+                    const leetNormalized = this.normalizeLeetSpeak(normalizedText);
+                    if (leetNormalized !== normalizedText) {
+                        const leetMatches = this.findMatchesWithAhoCorasick(leetNormalized, validatedText);
+                        matches.push(...leetMatches);
+                    }
+                }
+                break;
+            case "hybrid":
+                matches = this.findMatchesHybrid(normalizedText, validatedText);
+                if (this.enableLeetSpeak) {
+                    const leetNormalized = this.normalizeLeetSpeak(normalizedText);
+                    if (leetNormalized !== normalizedText) {
+                        const leetMatches = this.findMatchesHybrid(leetNormalized, validatedText);
+                        matches.push(...leetMatches);
+                    }
+                }
+                break;
+            case "trie":
+            default:
+                this.findMatches(normalizedText, validatedText, matches);
+                if (this.enableLeetSpeak) {
+                    const leetNormalized = this.normalizeLeetSpeak(normalizedText);
+                    if (leetNormalized !== normalizedText) {
+                        this.findMatches(leetNormalized, validatedText, matches);
+                    }
+                }
+                break;
+        }
+        // Apply context analysis if enabled
+        if (this.contextAnalyzer) {
+            matches = this.applyContextAnalysis(validatedText, matches);
         }
         const uniqueMatches = this.deduplicateMatches(matches);
         const detectedWords = uniqueMatches.map((m) => m.originalWord);
         const severity = this.calculateSeverity(uniqueMatches);
         const cleanedText = this.generateCleanedText(validatedText, uniqueMatches);
-        return {
+        const result = {
             hasProfanity: uniqueMatches.length > 0,
             detectedWords,
             cleanedText,
@@ -412,6 +935,18 @@ export class AllProfanity {
                 end: m.end,
             })),
         };
+        // Cache result if caching is enabled
+        if (this.resultCache) {
+            this.resultCache.set(validatedText, result);
+            // Implement simple LRU by clearing cache when it gets too large
+            if (this.resultCache.size > 1000) {
+                const firstKey = this.resultCache.keys().next().value;
+                if (firstKey !== undefined) {
+                    this.resultCache.delete(firstKey);
+                }
+            }
+        }
+        return result;
     }
     /**
      * Main matching function, with whole-word logic.
@@ -465,18 +1000,78 @@ export class AllProfanity {
         return result;
     }
     /**
-     * Check if a string contains profanity.
-     * @param text - The text to check.
-     * @returns True if profanity is found, false otherwise.
+     * Quick boolean check for profanity presence in text.
+     *
+     * @param {string} text - The text to check for profanity
+     * @returns {boolean} True if profanity is detected, false otherwise
+     *
+     * @throws {TypeError} If text is not a string
+     *
+     * @remarks
+     * - Convenience method that internally calls `detect()` and returns only the boolean result
+     * - For detailed information about matches, use `detect()` instead
+     * - Results are cached if caching is enabled (same cache as `detect()`)
+     *
+     * @example
+     * ```typescript
+     * const filter = new AllProfanity();
+     *
+     * if (filter.check("This has bad words")) {
+     *   console.log("Profanity detected!");
+     * }
+     *
+     * // Quick validation
+     * const isClean = !filter.check(userInput);
+     * ```
+     *
+     * @see {@link detect} for detailed profanity analysis
      */
     check(text) {
         return this.detect(text).hasProfanity;
     }
     /**
-     * Clean text with a custom placeholder.
-     * @param text - The text to clean.
-     * @param placeholder - The placeholder to use.
-     * @returns Cleaned text.
+     * Cleans text by replacing profanity with a placeholder character.
+     *
+     * @param {string} text - The text to clean
+     * @param {string} [placeholder] - Optional custom placeholder character (uses default if not provided)
+     * @returns {string} The cleaned text with profanity replaced
+     *
+     * @throws {TypeError} If text is not a string
+     *
+     * @remarks
+     * ### Character-level Replacement:
+     * - Each profane character is replaced individually
+     * - "bad" with placeholder "*" becomes "***"
+     * - Preserves text length and structure
+     *
+     * ### Placeholder Behavior:
+     * - If no placeholder provided, uses the instance's default placeholder
+     * - If placeholder provided, uses only the first character
+     * - Empty placeholder throws error
+     *
+     * @example
+     * ```typescript
+     * const filter = new AllProfanity();
+     *
+     * // Using default placeholder (*)
+     * const cleaned = filter.clean("This has bad words");
+     * console.log(cleaned); // "This has *** *****"
+     *
+     * // Using custom placeholder
+     * const cleaned = filter.clean("This has bad words", "#");
+     * console.log(cleaned); // "This has ### #####"
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Clean user-generated content for display
+     * const userComment = "Some inappropriate words here";
+     * const safeComment = filter.clean(userComment);
+     * displayComment(safeComment);
+     * ```
+     *
+     * @see {@link cleanWithPlaceholder} for word-level replacement
+     * @see {@link setPlaceholder} to change default placeholder
      */
     clean(text, placeholder) {
         const detection = this.detect(text);
@@ -503,10 +1098,46 @@ export class AllProfanity {
         return result;
     }
     /**
-     * Clean text by replacing each profane word with a single placeholder (word-level).
-     * @param text - The text to clean.
-     * @param placeholder - The placeholder to use.
-     * @returns Word-level cleaned text.
+     * Cleans text by replacing each profane word with a single placeholder string (word-level replacement).
+     *
+     * @param {string} text - The text to clean
+     * @param {string} [placeholder="***"] - The placeholder string to use for each profane word
+     * @returns {string} The cleaned text with each profane word replaced by the placeholder
+     *
+     * @throws {TypeError} If text is not a string
+     *
+     * @remarks
+     * ### Word-level Replacement:
+     * - Each profane word is replaced with the entire placeholder string (not character-by-character)
+     * - "bad words" with placeholder "***" becomes "*** ***"
+     * - Does NOT preserve original text length
+     *
+     * ### Difference from `clean()`:
+     * - `clean()`: Character-level replacement - "bad" becomes "***" (preserves length)
+     * - `cleanWithPlaceholder()`: Word-level replacement - "bad" becomes "***" (fixed placeholder)
+     *
+     * @example
+     * ```typescript
+     * const filter = new AllProfanity();
+     *
+     * // Default placeholder (***) const text = "This has bad words";
+     * const cleaned = filter.cleanWithPlaceholder(text);
+     * console.log(cleaned); // "This has *** ***"
+     *
+     * // Custom placeholder
+     * const cleaned2 = filter.cleanWithPlaceholder(text, "[CENSORED]");
+     * console.log(cleaned2); // "This has [CENSORED] [CENSORED]"
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Censoring chat messages
+     * const message = "You are a badword and stupid";
+     * const censored = filter.cleanWithPlaceholder(message, "[***]");
+     * // Result: "You are a [***] and [***]"
+     * ```
+     *
+     * @see {@link clean} for character-level replacement
      */
     cleanWithPlaceholder(text, placeholder = "***") {
         const detection = this.detect(text);
@@ -532,8 +1163,51 @@ export class AllProfanity {
         return result;
     }
     /**
-     * Add word(s) to the profanity filter.
-     * @param word - Word or array of words to add.
+     * Dynamically adds one or more words to the profanity filter at runtime.
+     *
+     * @param {string | string[]} word - A single word or array of words to add to the filter
+     * @returns {void}
+     *
+     * @remarks
+     * ### Behavior:
+     * - Words are added to all active data structures (Trie, Aho-Corasick, Bloom Filter)
+     * - Automatically normalizes words based on caseSensitive setting
+     * - Skips whitelisted words
+     * - Validates and filters out non-string or empty values
+     * - Changes take effect immediately for subsequent detect/check/clean calls
+     *
+     * ### Use Cases:
+     * - Adding context-specific profanity
+     * - Building dynamic word lists from user reports
+     * - Customizing filters for specific communities/applications
+     *
+     * @example
+     * ```typescript
+     * const filter = new AllProfanity();
+     *
+     * // Add single word
+     * filter.add('newbadword');
+     *
+     * // Add multiple words
+     * filter.add(['word1', 'word2', 'word3']);
+     *
+     * // Now these words will be detected
+     * filter.check('newbadword'); // true
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Add game-specific slang dynamically
+     * const filter = new AllProfanity();
+     * const gamingSlang = ['noob', 'trash', 'tryhard'];
+     * filter.add(gamingSlang);
+     *
+     * const message = "You're such a noob";
+     * console.log(filter.check(message)); // true
+     * ```
+     *
+     * @see {@link remove} to remove words
+     * @see {@link loadCustomDictionary} for loading named dictionaries
      */
     add(word) {
         const words = Array.isArray(word) ? word : [word];
@@ -544,8 +1218,50 @@ export class AllProfanity {
         }
     }
     /**
-     * Remove word(s) from the profanity filter.
-     * @param word - Word or array of words to remove.
+     * Dynamically removes one or more words from the profanity filter at runtime.
+     *
+     * @param {string | string[]} word - A single word or array of words to remove from the filter
+     * @returns {void}
+     *
+     * @remarks
+     * ### Behavior:
+     * - Removes words from all active data structures (Trie, dynamic words set)
+     * - Normalizes words based on caseSensitive setting before removal
+     * - Only removes dynamically added words, not words from loaded language dictionaries
+     * - Changes take effect immediately for subsequent detect/check/clean calls
+     *
+     * ### Important Notes:
+     * - Cannot remove words from built-in language dictionaries
+     * - To exclude dictionary words, use `addToWhitelist()` instead
+     * - Validates and filters out non-string or empty values
+     *
+     * @example
+     * ```typescript
+     * const filter = new AllProfanity();
+     *
+     * // Add then remove a word
+     * filter.add('tempword');
+     * filter.check('tempword'); // true
+     *
+     * filter.remove('tempword');
+     * filter.check('tempword'); // false
+     *
+     * // Remove multiple words
+     * filter.remove(['word1', 'word2']);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Managing custom word list
+     * const filter = new AllProfanity();
+     * filter.add(['custom1', 'custom2', 'custom3']);
+     *
+     * // Later, remove one that's no longer needed
+     * filter.remove('custom2');
+     * ```
+     *
+     * @see {@link add} to add words
+     * @see {@link addToWhitelist} to exclude dictionary words without removing them
      */
     remove(word) {
         const words = Array.isArray(word) ? word : [word];
@@ -588,9 +1304,60 @@ export class AllProfanity {
         return this.whitelistSet.has(normalizedWord);
     }
     /**
-     * Load a built-in language dictionary.
-     * @param language - The language key.
-     * @returns True if loaded, false otherwise.
+     * Loads a built-in language dictionary into the profanity filter.
+     *
+     * @param {string} language - The language key to load (case-insensitive)
+     * @returns {boolean} True if language was loaded successfully, false if not found or already loaded
+     *
+     * @remarks
+     * ### Available Languages:
+     * - `'english'` - English profanity words
+     * - `'hindi'` - Hindi profanity words
+     * - `'french'` - French profanity words
+     * - `'german'` - German profanity words
+     * - `'spanish'` - Spanish profanity words
+     * - `'bengali'` - Bengali profanity words
+     * - `'tamil'` - Tamil profanity words
+     * - `'telugu'` - Telugu profanity words
+     * - `'brazilian'` - Brazilian Portuguese profanity words
+     *
+     * ### Behavior:
+     * - Language keys are case-insensitive
+     * - Loading is idempotent - calling multiple times for same language is safe
+     * - Returns true if language loaded successfully or was already loaded
+     * - Returns false if language not found
+     * - Logs success/failure messages (unless silent mode enabled)
+     * - Words are added to all active data structures
+     *
+     * ### Default Languages:
+     * English and Hindi are loaded automatically in the constructor
+     *
+     * @example
+     * ```typescript
+     * const filter = new AllProfanity();
+     *
+     * // Load additional languages
+     * filter.loadLanguage('french');
+     * filter.loadLanguage('spanish');
+     *
+     * // Case-insensitive
+     * filter.loadLanguage('GERMAN'); // Works
+     *
+     * // Check if loaded
+     * console.log(filter.getLoadedLanguages()); // ['english', 'hindi', 'french', 'spanish', 'german']
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Load all Indian languages at once
+     * const filter = new AllProfanity();
+     * filter.loadIndianLanguages();
+     * ```
+     *
+     * @see {@link loadLanguages} to load multiple languages at once
+     * @see {@link loadIndianLanguages} for convenience method
+     * @see {@link getAvailableLanguages} to see all available languages
+     * @see {@link getLoadedLanguages} to see currently loaded languages
      */
     loadLanguage(language) {
         if (!language || typeof language !== "string") {
@@ -642,9 +1409,64 @@ export class AllProfanity {
         return this.loadLanguages(indianLanguages);
     }
     /**
-     * Load a custom dictionary.
-     * @param name - Name of the dictionary.
-     * @param words - Words to add.
+     * Loads a custom dictionary of profane words with a specific name.
+     *
+     * @param {string} name - Unique name/identifier for this custom dictionary
+     * @param {string[]} words - Array of profane words to add to the dictionary
+     * @returns {void}
+     *
+     * @throws {TypeError} If name is not a string or words is not an array
+     *
+     * @remarks
+     * ### Behavior:
+     * - Creates a new named dictionary or overwrites existing one with same name
+     * - Validates and filters out non-string and empty values from words array
+     * - Words are added to all active data structures (Trie, Aho-Corasick, Bloom Filter)
+     * - Dictionary name is converted to lowercase for storage
+     * - Logs count of loaded words (unless silent mode enabled)
+     *
+     * ### Use Cases:
+     * - Domain-specific profanity (gaming, medical, legal, etc.)
+     * - Organization-specific word lists
+     * - Temporary or context-dependent filters
+     * - Testing and development
+     *
+     * @example
+     * ```typescript
+     * const filter = new AllProfanity();
+     *
+     * // Load gaming-specific slang
+     * filter.loadCustomDictionary('gaming', [
+     *   'noob',
+     *   'scrub',
+     *   'tryhard',
+     *   'trash'
+     * ]);
+     *
+     * // Load company-specific terms
+     * filter.loadCustomDictionary('company', [
+     *   'competitor1',
+     *   'bannedTerm1',
+     *   'inappropriateJargon'
+     * ]);
+     *
+     * console.log(filter.check('You are such a noob')); // true
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Load from external source
+     * const filter = new AllProfanity();
+     *
+     * async function loadExternalDictionary() {
+     *   const response = await fetch('https://example.com/custom-words.json');
+     *   const customWords = await response.json();
+     *   filter.loadCustomDictionary('external', customWords);
+     * }
+     * ```
+     *
+     * @see {@link add} for adding individual words dynamically
+     * @see {@link loadLanguage} for loading built-in language dictionaries
      */
     loadCustomDictionary(name, words) {
         validateString(name, "dictionary name");
@@ -683,7 +1505,16 @@ export class AllProfanity {
         if (this.isWhitelisted(normalizedWord)) {
             return false;
         }
+        // Add to Trie (always used as fallback)
         this.profanityTrie.addWord(normalizedWord);
+        // Add to Bloom Filter if enabled
+        if (this.bloomFilter) {
+            this.bloomFilter.add(normalizedWord);
+        }
+        // Add to Aho-Corasick automaton if enabled
+        if (this.ahoCorasickAutomaton) {
+            this.ahoCorasickAutomaton.addPattern(normalizedWord);
+        }
         return true;
     }
     /**
@@ -797,6 +1628,50 @@ export class AllProfanity {
             this.rebuildTrie();
         }
     }
+    /**
+     * Create an AllProfanity instance from a configuration object.
+     * @param config - Configuration object
+     * @returns A new AllProfanity instance
+     */
+    static fromConfig(config) {
+        const options = {};
+        if (config.algorithm)
+            options.algorithm = config.algorithm;
+        if (config.bloomFilter)
+            options.bloomFilter = config.bloomFilter;
+        if (config.ahoCorasick)
+            options.ahoCorasick = config.ahoCorasick;
+        if (config.contextAnalysis)
+            options.contextAnalysis = config.contextAnalysis;
+        if (config.performance)
+            options.performance = config.performance;
+        if (config.profanityDetection) {
+            options.enableLeetSpeak = config.profanityDetection.enableLeetSpeak;
+            options.caseSensitive = config.profanityDetection.caseSensitive;
+            options.strictMode = config.profanityDetection.strictMode;
+            options.detectPartialWords = config.profanityDetection.detectPartialWords;
+            options.defaultPlaceholder = config.profanityDetection.defaultPlaceholder;
+        }
+        if (config.enableLeetSpeak !== undefined)
+            options.enableLeetSpeak = config.enableLeetSpeak;
+        if (config.caseSensitive !== undefined)
+            options.caseSensitive = config.caseSensitive;
+        if (config.strictMode !== undefined)
+            options.strictMode = config.strictMode;
+        if (config.detectPartialWords !== undefined)
+            options.detectPartialWords = config.detectPartialWords;
+        if (config.defaultPlaceholder !== undefined)
+            options.defaultPlaceholder = config.defaultPlaceholder;
+        if (config.languages)
+            options.languages = config.languages;
+        if (config.whitelistWords)
+            options.whitelistWords = config.whitelistWords;
+        if (config.customDictionaries)
+            options.customDictionaries = config.customDictionaries;
+        if (config.logger)
+            options.logger = config.logger;
+        return new AllProfanity(options);
+    }
 }
 /**
  * Singleton instance of AllProfanity with default configuration.