allprofanity 2.2.0 → 2.3.0

package/dist/index.d.ts

@@ -8,81 +8,398 @@ 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";
 /**
- * Logger interface for the library.
+ * Logger interface for AllProfanity library logging operations.
+ *
+ * @interface Logger
+ * @description Provides a contract for logging implementations used by the AllProfanity library.
+ * Implement this interface to provide custom logging behavior (e.g., logging to files, external services).
+ *
+ * @example
+ * ```typescript
+ * class CustomLogger implements Logger {
+ *   info(message: string): void {
+ *     // Custom info logging logic
+ *   }
+ *   warn(message: string): void {
+ *     // Custom warning logging logic
+ *   }
+ *   error(message: string): void {
+ *     // Custom error logging logic
+ *   }
+ * }
+ * const filter = new AllProfanity({ logger: new CustomLogger() });
+ * ```
  */
 export interface Logger {
     /**
-     * Log informational messages.
-     * @param message - The message to log.
+     * Log informational messages about normal operations.
+     *
+     * @param message - The informational message to log
+     * @returns void
      */
     info(message: string): void;
     /**
-     * Log warning messages.
-     * @param message - The message to log.
+     * Log warning messages about potential issues or deprecated usage.
+     *
+     * @param message - The warning message to log
+     * @returns void
      */
     warn(message: string): void;
     /**
-     * Log error messages.
-     * @param message - The message to log.
+     * Log error messages about failures or critical issues.
+     *
+     * @param message - The error message to log
+     * @returns void
      */
     error(message: string): void;
 }
 /**
- * Configuration options for AllProfanity.
+ * Configuration options for initializing an AllProfanity instance.
+ *
+ * @interface AllProfanityOptions
+ * @description Comprehensive configuration object for customizing profanity detection behavior,
+ * algorithm selection, performance optimizations, and logging.
+ *
+ * @example
+ * ```typescript
+ * const filter = new AllProfanity({
+ *   languages: ['english', 'french'],
+ *   enableLeetSpeak: true,
+ *   strictMode: true,
+ *   algorithm: {
+ *     matching: 'hybrid',
+ *     useBloomFilter: true
+ *   },
+ *   performance: {
+ *     enableCaching: true,
+ *     cacheSize: 500
+ *   }
+ * });
+ * ```
  */
 export interface AllProfanityOptions {
+    /**
+     * Array of language keys to load (e.g., 'english', 'hindi', 'french').
+     * Available languages: english, hindi, french, german, spanish, bengali, tamil, telugu, brazilian.
+     *
+     * @default ['english', 'hindi'] (loaded by default in constructor)
+     */
     languages?: string[];
+    /**
+     * Custom dictionaries to load in addition to built-in languages.
+     * Key is the dictionary name, value is an array of words.
+     *
+     * @example
+     * ```typescript
+     * customDictionaries: {
+     *   'gaming': ['noob', 'trash'],
+     *   'custom': ['word1', 'word2']
+     * }
+     * ```
+     */
     customDictionaries?: Record<string, string[]>;
+    /**
+     * Single character to use as replacement placeholder for profane characters.
+     *
+     * @default "*"
+     */
     defaultPlaceholder?: string;
+    /**
+     * Enable detection and normalization of leet speak variations (e.g., "h3ll0" -> "hello").
+     *
+     * @default true
+     */
     enableLeetSpeak?: boolean;
+    /**
+     * Enable case-sensitive matching. When false, all matching is done in lowercase.
+     *
+     * @default false
+     */
     caseSensitive?: boolean;
+    /**
+     * Array of words to whitelist (never flag as profanity even if in dictionaries).
+     *
+     * @example ['hello', 'class', 'assignment']
+     */
     whitelistWords?: string[];
+    /**
+     * Strict mode requires profanity to be surrounded by word boundaries (spaces, punctuation).
+     * When false, profanity embedded in other words may be detected.
+     *
+     * @default false
+     */
     strictMode?: boolean;
+    /**
+     * Allow detection of profanity as partial matches within larger words.
+     * When true, "badword" will be detected in "mybadwordhere".
+     *
+     * @default false
+     */
     detectPartialWords?: boolean;
+    /**
+     * Custom logger implementation for handling log messages.
+     * If not provided, defaults to ConsoleLogger unless silent mode is enabled.
+     */
     logger?: Logger;
+    /**
+     * Silent mode suppresses all logging output.
+     * When true, uses SilentLogger to discard all log messages.
+     *
+     * @default false
+     */
+    silent?: boolean;
+    /**
+     * Advanced algorithm configuration for pattern matching strategies.
+     */
     algorithm?: {
+        /**
+         * Primary matching algorithm to use.
+         * - 'trie': Fast prefix tree matching (default, best for most use cases)
+         * - 'aho-corasick': Multi-pattern matching (best for large dictionaries)
+         * - 'hybrid': Combines Aho-Corasick with Bloom Filter (best for extreme performance)
+         *
+         * @default "trie"
+         */
         matching?: "trie" | "aho-corasick" | "hybrid";
+        /**
+         * Enable Aho-Corasick automaton for multi-pattern matching.
+         * Automatically enabled when matching is set to 'aho-corasick' or 'hybrid'.
+         *
+         * @default false
+         */
         useAhoCorasick?: boolean;
+        /**
+         * Enable Bloom Filter for probabilistic quick rejection of non-profane text.
+         * Automatically enabled when matching is set to 'hybrid'.
+         *
+         * @default false
+         */
         useBloomFilter?: boolean;
+        /**
+         * Enable context analysis to reduce false positives based on surrounding words.
+         *
+         * @default false
+         */
         useContextAnalysis?: boolean;
     };
+    /**
+     * Bloom Filter configuration for probabilistic matching optimization.
+     */
     bloomFilter?: {
+        /**
+         * Enable Bloom Filter.
+         *
+         * @default false
+         */
         enabled?: boolean;
+        /**
+         * Expected number of items to be stored in the Bloom Filter.
+         * Higher values increase memory usage but reduce false positive rate.
+         *
+         * @default 10000
+         */
         expectedItems?: number;
+        /**
+         * Target false positive rate (probability of incorrectly identifying non-profanity as profanity).
+         * Lower values increase memory usage but improve accuracy.
+         *
+         * @default 0.01 (1%)
+         */
         falsePositiveRate?: number;
     };
+    /**
+     * Aho-Corasick automaton configuration for multi-pattern matching.
+     */
     ahoCorasick?: {
+        /**
+         * Enable Aho-Corasick automaton.
+         *
+         * @default false
+         */
         enabled?: boolean;
+        /**
+         * Pre-build the automaton during initialization.
+         * When false, automaton is built lazily on first use.
+         *
+         * @default false
+         */
         prebuild?: boolean;
     };
+    /**
+     * Context analysis configuration for reducing false positives.
+     */
     contextAnalysis?: {
+        /**
+         * Enable context-aware profanity detection.
+         *
+         * @default false
+         */
         enabled?: boolean;
+        /**
+         * Number of words before and after the detected word to analyze for context.
+         *
+         * @default 5
+         */
         contextWindow?: number;
+        /**
+         * Languages to use for context analysis (e.g., ['en', 'es']).
+         *
+         * @default ['en']
+         */
         languages?: string[];
+        /**
+         * Minimum confidence score (0-1) required to flag as profanity.
+         * Higher values reduce false positives but may miss some profanity.
+         *
+         * @default 0.5
+         */
         scoreThreshold?: number;
     };
+    /**
+     * Evasion-protection configuration. All passes are enabled by default and
+     * only run when their trigger characters are present in the text, so they
+     * add near-zero cost on ordinary input.
+     */
+    evasionProtection?: {
+        /**
+         * Fold unicode evasion: fullwidth forms (ｆｕｃｋ), Cyrillic/Greek
+         * homoglyphs (fυck), diacritics (fück) and invisible characters
+         * (zero-width spaces, soft hyphens) injected inside words.
+         *
+         * @default true
+         */
+        unicode?: boolean;
+        /**
+         * Collapse stretched characters ("fuuuuck" -> "fuck"). Only triggers when
+         * a run of 3+ identical characters exists.
+         *
+         * @default true
+         */
+        repeatedCharacters?: boolean;
+        /**
+         * Resolve masked characters as single-character wildcards ("f*ck",
+         * "f#ck", "f@ck"). A masked token only matches when the visible letters
+         * align exactly with a dictionary word.
+         *
+         * @default true
+         */
+        maskedCharacters?: boolean;
+        /**
+         * Detect words spelled out with uniform single separators
+         * ("f u c k", "f.u.c.k"). The joined letters must equal a dictionary
+         * word exactly, which keeps initialisms like "U S A" clean.
+         *
+         * @default true
+         */
+        separatedLetters?: boolean;
+        /**
+         * Detect unambiguous profanity stems embedded inside larger tokens
+         * ("sisfuck", "totalshitshow"). Applies only to a curated list of
+         * strong words that never occur in legitimate vocabulary, with built-in
+         * exceptions (Scunthorpe, mishit, snigger, ...), so "classic", "bass"
+         * and "Hitchcock" stay clean.
+         *
+         * @default true
+         */
+        embeddedWords?: boolean;
+    };
+    /**
+     * Performance optimization configuration.
+     */
     performance?: {
+        /**
+         * Maximum number of results to cache in LRU cache.
+         *
+         * @default 1000
+         */
         cacheSize?: number;
+        /**
+         * Enable result caching to speed up repeated queries.
+         * Stores detection results for previously seen text.
+         *
+         * @default false
+         */
         enableCaching?: boolean;
     };
 }
 /**
- * Severity levels for profanity detection.
+ * 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 declare enum ProfanitySeverity {
+    /** No profanity detected */
+    NONE = 0,
+    /** Mild profanity: 1 unique word or 1 total match */
     MILD = 1,
+    /** Moderate profanity: 2 unique words or 2 total matches */
     MODERATE = 2,
+    /** Severe profanity: 3 unique words or 3 total matches */
     SEVERE = 3,
+    /** Extreme profanity: 4+ unique words or 5+ total matches */
     EXTREME = 4
 }
 /**
- * Detection result for profanity detection.
+ * Result object returned from profanity detection operations.
+ *
+ * @interface ProfanityDetectionResult
+ * @description Contains comprehensive information about detected profanity including
+ * what was found, where it was found, how severe it is, and a cleaned version of the text.
+ *
+ * @example
+ * ```typescript
+ * const result = filter.detect("This is a bad word");
+ * console.log(result.hasProfanity); // true
+ * console.log(result.detectedWords); // ['bad word']
+ * console.log(result.cleanedText); // 'This is a *** ****'
+ * console.log(result.severity); // ProfanitySeverity.MILD
+ * console.log(result.positions); // [{ word: 'bad word', start: 10, end: 18 }]
+ * ```
  */
 export interface ProfanityDetectionResult {
+    /**
+     * Whether any profanity was detected in the text.
+     *
+     * @type {boolean}
+     */
     hasProfanity: boolean;
+    /**
+     * Array of detected profane words/phrases as they appeared in the original text.
+     * Includes case and formatting from the original text.
+     *
+     * @type {string[]}
+     */
     detectedWords: string[];
+    /**
+     * The text with all profanity replaced by placeholder characters.
+     * Each profane character is replaced with the configured placeholder (default: '*').
+     *
+     * @type {string}
+     */
     cleanedText: string;
+    /**
+     * Severity level of detected profanity.
+     *
+     * @type {ProfanitySeverity}
+     */
     severity: ProfanitySeverity;
+    /**
+     * Precise positions of each detected profane word in the original text.
+     * Useful for highlighting or further processing.
+     *
+     * @type {Array<{ word: string; start: number; end: number }>}
+     */
     positions: Array<{
         word: string;
         start: number;
@@ -90,7 +407,99 @@ export interface ProfanityDetectionResult {
     }>;
 }
 /**
- * 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 declare class AllProfanity {
     private readonly profanityTrie;
@@ -102,17 +511,60 @@ export declare class AllProfanity {
     private caseSensitive;
     private strictMode;
     private detectPartialWords;
+    private evasionUnicode;
+    private evasionRepeatedChars;
+    private evasionMaskedChars;
+    private evasionSeparatedLetters;
+    private evasionEmbeddedWords;
     private readonly availableLanguages;
     private readonly leetMappings;
     private readonly dynamicWords;
     private ahoCorasickAutomaton;
     private bloomFilter;
     private contextAnalyzer;
+    private contextScoreThreshold;
     private matchingAlgorithm;
     private resultCache;
+    private cacheMaxSize;
+    private leetTokensByFirstChar;
     /**
-     * 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?: AllProfanityOptions);
     /**
@@ -120,17 +572,56 @@ export declare class AllProfanity {
      */
     private initializeAdvancedAlgorithms;
     /**
-     * Normalize leet speak to regular characters.
-     * @param text - The input text.
-     * @returns Normalized text.
+     * Normalize leet speak to regular characters, keeping a map from each
+     * normalized character back to its source range in the input text.
+     *
+     * For normalized index i, starts[i]/ends[i] give the [start, end) range in
+     * the input that produced that character. A match [s, e) in the normalized
+     * string therefore spans [starts[s], ends[e - 1]) in the input. This is what
+     * keeps positions correct when length-changing mappings like "ph" -> "f"
+     * apply.
+     */
+    private normalizeLeetSpeakWithMap;
+    /**
+     * Fold unicode evasion tactics into ASCII with a position map: fullwidth
+     * forms, Cyrillic/Greek homoglyphs, Latin diacritics, and invisible
+     * characters injected inside words. Non-Latin scripts (Devanagari, Tamil,
+     * etc.) pass through untouched. Returns null when nothing changed.
+     */
+    private unicodeNormalizeWithMap;
+    /**
+     * Collapse runs of repeated characters ("fuuuuck" -> "fuck") with a
+     * position map. Only triggers when a run of 3+ identical characters
+     * exists, so ordinary doubled letters never pay for this pass.
+     * Returns null when not triggered.
      */
-    private normalizeLeetSpeak;
+    private collapseRepeatsWithMap;
     /**
-     * Escape regex special characters in a string.
-     * @param str - The string to escape.
-     * @returns The escaped string.
+     * Build the list of (text, position-map) variants to scan: the base text
+     * plus unicode-folded, leet-normalized and repeat-collapsed variants, each
+     * included only when its normalization actually changed something.
      */
-    private escapeRegex;
+    private buildScanPasses;
+    /**
+     * Find dictionary words hidden behind masked characters ("f*ck", "f#ck").
+     * Each mask matches exactly one character and the token's visible letters
+     * must align with a dictionary word, so "c#" or "5% off" never flag.
+     */
+    private findMaskedMatches;
+    /**
+     * Find words spelled out with a uniform single separator ("f u c k",
+     * "f.u.c.k"). The joined letters must equal a dictionary word exactly:
+     * runs like "U S A" or letters inside spelled-out sentences never flag.
+     */
+    private findSeparatedMatches;
+    /**
+     * Find unambiguous profanity stems embedded inside larger tokens
+     * ("sisfuck", "totalshitshow"). Only stems from EMBEDDED_STRONG_STEMS that
+     * are currently in the dictionary are considered, and tokens listed in
+     * EMBEDDED_SAFE_WORDS or the whitelist never flag. The whole containing
+     * token is reported so cleaning masks all of it.
+     */
+    private findEmbeddedMatches;
     /**
      * Check if a match is bounded by word boundaries (strict mode).
      * @param text - The text.
@@ -154,6 +645,11 @@ export declare class AllProfanity {
      * @returns True if whitelisted, false otherwise.
      */
     private isWhitelistedMatch;
+    /**
+     * In partial-word mode, check whether the word CONTAINING the match is
+     * whitelisted: with "classic" whitelisted, the embedded "ass" must not flag.
+     */
+    private isWhitelistedContainingWord;
     /**
      * Remove overlapping matches, keeping only the longest at each start position.
      * @param matches - Array of match results.
@@ -165,7 +661,13 @@ export declare class AllProfanity {
      */
     private findMatchesWithAhoCorasick;
     /**
-     * Hybrid approach: Aho-Corasick for fast matching, Bloom Filter for validation
+     * Check whether the Bloom Filter can quickly rule out any profanity in the
+     * text. Only safe for ASCII whole-word matching: partial matches and
+     * non-ASCII scripts can match inside tokens, so they bypass the prefilter.
+     */
+    private bloomQuickReject;
+    /**
+     * Hybrid approach: Bloom Filter for quick rejection, Aho-Corasick for matching
      */
     private findMatchesHybrid;
     /**
@@ -173,9 +675,61 @@ export declare class AllProfanity {
      */
     private applyContextAnalysis;
     /**
-     * Detect profanity in a given text.
-     * @param text - The text to check.
-     * @returns Profanity detection result.
+     * Drop all cached detection results. Must be called whenever the word lists
+     * or any option that affects detection output changes.
+     */
+    private invalidateCache;
+    /**
+     * 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: string): ProfanityDetectionResult;
     /**
@@ -193,33 +747,219 @@ export declare class AllProfanity {
      */
     private generateCleanedText;
     /**
-     * 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: string): boolean;
     /**
-     * Clean text with a custom placeholder.
-     * @param text - The text to clean.
-     * @param placeholder - The placeholder to use.
-     * @returns Cleaned text.
+     * Trie scan that stops at the first match surviving the whole-word,
+     * whitelist and boundary checks. Powers the fast path in check().
+     */
+    private hasMatchInPass;
+    /**
+     * 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: string, placeholder?: string): string;
     /**
-     * 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: string, placeholder?: string): string;
     /**
-     * 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: string | string[]): void;
     /**
-     * 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: string | string[]): void;
     /**
@@ -239,9 +979,60 @@ export declare class AllProfanity {
      */
     private isWhitelisted;
     /**
-     * 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: string): boolean;
     /**
@@ -256,9 +1047,64 @@ export declare class AllProfanity {
      */
     loadIndianLanguages(): number;
     /**
-     * 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: string, words: string[]): void;
     /**
@@ -298,9 +1144,10 @@ export declare class AllProfanity {
      */
     getConfig(): Partial<AllProfanityOptions>;
     /**
-     * Rebuild the profanity trie from loaded dictionaries and dynamic words.
+     * Rebuild all matching structures (trie, Aho-Corasick automaton, Bloom
+     * Filter) from loaded dictionaries and dynamic words.
      */
-    private rebuildTrie;
+    private rebuildIndexes;
     /**
      * Update configuration options for the profanity filter.
      * @param options - Partial configuration object.
@@ -315,6 +1162,7 @@ export declare class AllProfanity {
 }
 /**
  * Singleton instance of AllProfanity with default configuration.
+ * Silent so that importing the library never writes to the console.
  */
 declare const allProfanity: AllProfanity;
 export default allProfanity;