bekindprofanityfilter 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,1332 @@
+export { default as allLanguagesBadWords } from "./languages/english-primary-all-languages.js";
+/**
+ * Logger interface for BeKind library logging operations.
+ *
+ * @interface Logger
+ * @description Provides a contract for logging implementations used by the BeKind 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 BeKind({ logger: new CustomLogger() });
+ * ```
+ */
+export interface Logger {
+    /**
+     * Log informational messages about normal operations.
+     *
+     * @param message - The informational message to log
+     * @returns void
+     */
+    info(message: string): void;
+    /**
+     * 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 about failures or critical issues.
+     *
+     * @param message - The error message to log
+     * @returns void
+     */
+    error(message: string): void;
+}
+/**
+ * Configuration options for initializing an BeKind instance.
+ *
+ * @interface BeKindOptions
+ * @description Comprehensive configuration object for customizing profanity detection behavior,
+ * algorithm selection, performance optimizations, and logging.
+ *
+ * @example
+ * ```typescript
+ * const filter = new BeKind({
+ *   languages: ['english', 'french'],
+ *   enableLeetSpeak: true,
+ *   strictMode: true,
+ *   algorithm: {
+ *     matching: 'hybrid',
+ *     useBloomFilter: true
+ *   },
+ *   performance: {
+ *     enableCaching: true,
+ *     cacheSize: 500
+ *   }
+ * });
+ * ```
+ */
+export interface BeKindOptions {
+    /**
+     * 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;
+    /**
+     * Enable embedded profanity detection with certainty decay.
+     * When true, profane substrings inside larger words are detected (e.g., "bitch" in "lbitch")
+     * with decayed certainty based on extra characters and length ratio.
+     * Only reports matches where decayed certainty >= 2.
+     *
+     * Formula: decayed_c = base_c * (0.9 ^ extra_chars) * (profane_len / total_word_len)
+     *
+     * @default false
+     */
+    embeddedProfanityDetection?: boolean;
+    /**
+     * Allow the trie to skip over separator characters (spaces, @, ., -, _, *, etc.)
+     * during matching. Catches evasion patterns like "fu ck", "cun t", "fu@ck@cu@nt@bi@tch".
+     *
+     * When set to a number, specifies the max consecutive separators to skip per gap
+     * (e.g., 5 means "f     uck" is caught but "f      uck" with 6 spaces is not).
+     * When true, defaults to 5. When false, disabled.
+     *
+     * @default true (max 5 separators per gap)
+     */
+    separatorTolerance?: boolean | number;
+    /**
+     * 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;
+    /**
+     * Sensitive mode flags AMBIVALENT words as profanity too.
+     * When true, cross-language collisions that were dampened by innocence
+     * scoring (e.g. "bitte" = German "please" dampened from French "bite")
+     * still count as profanity in check()/detect().hasProfanity.
+     * When false (default), only PROFANE-scored words trigger hasProfanity —
+     * dampened words are ignored, reducing false positives.
+     *
+     * @default false
+     */
+    sensitiveMode?: 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;
+    };
+    /**
+     * 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 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 {
+    /** 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
+}
+/**
+ * Per-word severity classification for individual detected words.
+ *
+ * @enum {number}
+ */
+export declare enum WordSeverity {
+    /** Ambivalent: mild/contextual profanity that may be acceptable (damn, hell, crap, suck) */
+    AMBIVALENT = 1,
+    /** Profane: should be flagged — strong profanity, slurs, explicit content */
+    PROFANE = 2
+}
+/**
+ * A detected word with its individual severity classification.
+ */
+export interface ScoredWord {
+    /** The word as it appeared in the original text */
+    word: string;
+    /** Severity classification for this specific word */
+    severity: WordSeverity;
+}
+/**
+ * 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;
+        end: number;
+    }>;
+    /**
+     * Whether the text contains abhorrent language (hate speech, slurs, extremist terms)
+     * that should be flagged for manual review rather than auto-moderated.
+     *
+     * @type {boolean}
+     */
+    needsManualReview: boolean;
+    /**
+     * The specific abhorrent words that triggered the manual review flag.
+     * Empty array if needsManualReview is false.
+     *
+     * @type {string[]}
+     */
+    flaggedAbhorrentWords: string[];
+    /**
+     * Each detected word with its individual severity classification.
+     * Severity is assigned by the library: AMBIVALENT (1) or PROFANE (2).
+     * PROFANE words cross the flag threshold (s:5 any c, s:4+ c:2+, s:3 c:3+).
+     * AMBIVALENT words are below threshold — mild or contextually acceptable.
+     *
+     * @type {ScoredWord[]}
+     */
+    scoredWords: ScoredWord[];
+    /** Highest severity among all detected words. Null if no profanity detected. */
+    maxSeverity: WordSeverity | null;
+    /**
+     * Phrases that matched profanity across space boundaries during separator-tolerant
+     * detection. These are NOT flagged as profanity but are captured for review.
+     * Each entry includes the matched word, the surrounding context (±5 words),
+     * the base score, and the number of space boundaries crossed.
+     */
+    suspiciousPhrases: SuspiciousPhrase[];
+}
+/**
+ * A phrase that matched profanity across word boundaries (spaces).
+ * Not flagged as profanity — captured for manual review or secondary scoring.
+ */
+export interface SuspiciousPhrase {
+    /** The profanity dictionary word that was matched */
+    word: string;
+    /** The text as it appeared in the original input (with separators) */
+    originalText: string;
+    /** Surrounding context: ±5 words around the suspicious match */
+    context: string;
+    /** Start position of the match in the original text */
+    start: number;
+    /** End position of the match in the original text */
+    end: number;
+    /** Base severity/certainty score from the word list */
+    baseScore: {
+        severity: number;
+        certainty: number;
+    };
+    /** Number of space boundaries crossed to form this match */
+    spaceBoundaries: number;
+}
+/**
+ * BeKind - Professional-grade multilingual profanity detection and filtering library.
+ *
+ * @class BeKind
+ * @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 { BeKind, ProfanitySeverity } from 'allprofanity';
+ *
+ * const filter = new BeKind({
+ *   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 BeKind();
+ *
+ * // 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 BeKindOptions} for all configuration options
+ * @see {@link ProfanityDetectionResult} for detection result format
+ * @see {@link ProfanitySeverity} for severity levels
+ */
+export declare class BeKind {
+    private readonly profanityTrie;
+    private readonly whitelistSet;
+    private readonly loadedLanguages;
+    private readonly logger;
+    private defaultPlaceholder;
+    private enableLeetSpeak;
+    private caseSensitive;
+    private strictMode;
+    private detectPartialWords;
+    private embeddedProfanityDetection;
+    private separatorTolerance;
+    private sensitiveMode;
+    /**
+     * Temporary storage for suspicious matches found during separator-tolerant detection.
+     * Populated by findSeparatorTolerantMatches() and consumed by detect().
+     */
+    private _suspiciousMatches;
+    private readonly availableLanguages;
+    /**
+     * Word score lookup map. Maps lowercase words to their severity and certainty scores.
+     * Populated from the scored word list on construction.
+     */
+    private readonly wordScores;
+    /**
+     * Set of abhorrent words/phrases that trigger needsManualReview.
+     * Includes hate groups, slurs, extremist terminology, and Nazi references.
+     * Stored in lowercase for case-insensitive matching.
+     */
+    private readonly abhorrentWords;
+    private readonly leetMappings;
+    private readonly dynamicWords;
+    private ahoCorasickAutomaton;
+    private bloomFilter;
+    private contextAnalyzer;
+    private matchingAlgorithm;
+    private resultCache;
+    /**
+     * Creates a new BeKind instance with the specified configuration.
+     *
+     * @constructor
+     * @param {BeKindOptions} [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 BeKind();
+     *
+     * // Custom configuration
+     * const filter = new BeKind({
+     *   languages: ['english', 'french'],
+     *   strictMode: true,
+     *   defaultPlaceholder: '#',
+     *   algorithm: { matching: 'hybrid' }
+     * });
+     *
+     * // Silent mode (no logging)
+     * const filter = new BeKind({ silent: true });
+     * ```
+     *
+     * @see {@link BeKindOptions} for all available configuration options
+     */
+    constructor(options?: BeKindOptions);
+    /**
+     * Initialize advanced algorithms based on configuration
+     */
+    private initializeAdvancedAlgorithms;
+    /**
+     * Leet mappings where the source is a regular letter (e.g. z→s, v→u, j→y).
+     * These are ambiguous because they can destroy legitimate words during
+     * normalization (e.g. "nazi" → "nasi"). Separated so that layered
+     * normalization can try symbol-only mappings first.
+     */
+    private readonly letterToLetterLeetKeys;
+    /**
+     * Normalize leet speak to regular characters (full pass — all mappings).
+     * @param text - The input text.
+     * @returns Normalized text.
+     */
+    private normalizeLeetSpeak;
+    /**
+     * Conservative leet normalization — only replaces non-letter characters
+     * (digits, symbols, punctuation) with their letter equivalents.
+     * Letter-to-letter mappings (z→s, v→u, j→y, ph→f) are skipped so that
+     * real letters are preserved, avoiding collisions like "nazi" → "nasi".
+     */
+    private normalizeLeetSpeakSymbolsOnly;
+    /**
+     * Returns all unique leet-normalized variants of the text that differ
+     * from the base normalizedText. Runs two layers:
+     *   1. Symbol-only normalization (digits/special → letters, preserves real letters)
+     *   2. Full normalization (all mappings including letter→letter)
+     *
+     * This layered approach catches both "n4zi" (symbol-only → "nazi") and
+     * "a55" (full → "ass") without one breaking the other.
+     */
+    private getLeetVariants;
+    /**
+     * Non-space separator characters (evasion symbols like @, ., -, etc.)
+     * These are skipped freely with no certainty penalty.
+     */
+    private static readonly SYMBOL_SEPARATOR_SET;
+    /**
+     * Check if a character is a non-space separator (skipped freely).
+     */
+    private static isSymbolSeparator;
+    /**
+     * Check if a character is whitespace (skipped with certainty penalty).
+     */
+    private static isWhitespaceSeparator;
+    /**
+     * Check if a character is any kind of separator.
+     */
+    private static isSeparator;
+    /**
+     * Certainty penalty per space boundary crossed during separator-tolerant matching.
+     * Each distinct whitespace gap reduces the matched word's certainty by this amount.
+     * e.g., "fu ck" → fuck (c:5) → c:5-2 = c:3 → still flags at s:3
+     * e.g., "No m" → nom (c:3) → c:3-2 = c:1 → drops below threshold
+     */
+    private static readonly SPACE_CERTAINTY_PENALTY;
+    /**
+     * Extract surrounding context (±N words) around a match position in text.
+     */
+    private extractSurroundingContext;
+    /**
+     * Escape regex special characters in a string.
+     * @param str - The string to escape.
+     * @returns The escaped string.
+     */
+    private escapeRegex;
+    /**
+     * Check if a match is bounded by word boundaries (strict mode).
+     * @param text - The text.
+     * @param start - Start index.
+     * @param end - End index.
+     * @returns True if match is at word boundaries, false otherwise.
+     */
+    private hasWordBoundaries;
+    /**
+     * Determine if a match is a whole word.
+     * @param text - The text.
+     * @param start - Start index.
+     * @param end - End index.
+     * @returns True if whole word, false otherwise.
+     */
+    private static readonly CJK_RE;
+    private isWholeWord;
+    /**
+     * Returns the char-index bounds of the host word containing [start, end).
+     * Scans outward using the same Unicode-letter definition as isWholeWord.
+     */
+    private getHostWordBounds;
+    /**
+     * When a match is embedded (not a whole word), check whether the profane
+     * substring covers a large enough fraction of its host word to be flagged
+     * anyway. This catches deliberate obfuscation like "urASSHOLEbro" where
+     * "asshole" (7 chars) = 58 % of the 12-char host word.
+     *
+     * Guards (all must pass):
+     *   1. Match length ≥ 6 chars — short words (ass/shit/anal/semen) are too common.
+     *   2. Graduated coverage threshold — shorter matches need higher coverage:
+     *      - 6-char matches: ≥ 85% (only catches near-exact wraps like "ufucker")
+     *      - 7+ char matches: ≥ 55% (catches obfuscation like "urASSHOLEbro")
+     *   3. Language signal — scoreWord() on the host word must show signal for
+     *      the profane word's language. If the host word has no signal for that
+     *      language it's a cross-language collision (e.g. "singe" = French slur
+     *      inside "singer" which scores as English → skip).
+     *
+     * Examples:
+     *   "asshole" (7, en) in "urASSHOLEbro" (en signal) = 58 % → flagged ✓
+     *   "fucker"  (6, en) in "ufucker"      (en signal) = 86 % → flagged ✓
+     *   "raging"  (6, en) in "foraging"     = 75 % → below 85% for 6-char → safe ✓
+     *   "semen"   (5)     in "basement"              → too short → safe ✓
+     *   "anal"    (4)     in "canal"                  → too short → safe ✓
+     *   "singe"   (5, fr) in "singer"                → too short → safe ✓
+     *   "negro"   (5, en) in "negroni"               → too short → safe ✓
+     */
+    private static readonly HIGH_COVERAGE_THRESHOLD_SHORT;
+    private static readonly HIGH_COVERAGE_THRESHOLD_LONG;
+    private static readonly HIGH_COVERAGE_MIN_MATCH_LEN;
+    private static readonly HIGH_COVERAGE_LANG_SIGNAL_MIN;
+    private isHighCoverageEmbed;
+    /**
+     * Check if a match is whitelisted.
+     * @param word - Word from dictionary.
+     * @param matchedText - Actual matched text.
+     * @returns True if whitelisted, false otherwise.
+     */
+    private isWhitelistedMatch;
+    /**
+     * Remove overlapping matches, keeping only the longest at each start position.
+     * @param matches - Array of match results.
+     * @returns Deduplicated matches.
+     */
+    private deduplicateMatches;
+    /**
+     * Use Aho-Corasick algorithm for pattern matching
+     */
+    private findMatchesWithAhoCorasick;
+    /**
+     * Hybrid approach: Aho-Corasick for fast matching, Bloom Filter for validation
+     */
+    private findMatchesHybrid;
+    /**
+     * Apply context analysis to filter false positives
+     */
+    private applyContextAnalysis;
+    /**
+     * 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 BeKind();
+     * 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 BeKind({ 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;
+    /**
+     * Main matching function, with whole-word logic.
+     * @param searchText - The normalized text to search.
+     * @param originalText - The original text.
+     * @param matches - Array to collect matches.
+     */
+    private findMatches;
+    /**
+     * Walk the trie while tolerating separator characters between letters.
+     * Catches evasion patterns: "fu ck", "c.u.n.t", "fu@ck@cu@nt@bi@tch"
+     *
+     * Symbol separators (@, ., -, etc.) are skipped freely.
+     * Space separators reduce certainty by SPACE_CERTAINTY_PENALTY per gap.
+     * Matches that drop below the flagging threshold become "suspicious" instead.
+     */
+    private findSeparatorTolerantMatches;
+    /**
+     * Recursively walk the trie from a given node, skipping separator chars.
+     * Tracks space boundaries crossed (for certainty penalty) separately from
+     * symbol separators (which are free to skip).
+     */
+    private walkTrieWithSeparators;
+    /**
+     * Decay constant for embedded profanity detection.
+     * Each extra character beyond the profane root reduces certainty by this factor.
+     */
+    private static readonly EMBEDDED_DECAY_RATE;
+    /**
+     * Minimum decayed certainty to report an embedded match.
+     */
+    private static readonly EMBEDDED_MIN_CERTAINTY;
+    /**
+     * Find profane substrings embedded inside larger words with certainty decay.
+     *
+     * Formula: decayed_c = base_c * (DECAY_RATE ^ extra_chars) * (profane_len / host_word_len)
+     *
+     * Multi-profanity bonus: if a host word contains multiple profane substrings,
+     * certainty is boosted (sum of base severities used as multiplier, capped at c:5).
+     *
+     * Unusually long words (12+ chars) containing profanity get a certainty bonus
+     * since legitimate words rarely exceed this length.
+     */
+    private findEmbeddedMatches;
+    /**
+     * Deduplicate embedded finds: at overlapping positions, keep the longest match.
+     */
+    private deduplicateEmbeddedFinds;
+    /**
+     * Generate cleaned text by replacing profane words.
+     * @param originalText - The original text.
+     * @param matches - Array of matches.
+     * @returns Cleaned text.
+     */
+    private generateCleanedText;
+    /**
+     * 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 BeKind();
+     *
+     * 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;
+    /**
+     * 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 BeKind();
+     *
+     * // 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;
+    /**
+     * 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 BeKind();
+     *
+     * // 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;
+    /**
+     * 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 BeKind();
+     *
+     * // 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 BeKind();
+     * 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;
+    /**
+     * 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 BeKind();
+     *
+     * // 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 BeKind();
+     * 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;
+    /**
+     * Add words to the whitelist.
+     * @param words - Words to whitelist.
+     */
+    addToWhitelist(words: string[]): void;
+    /**
+     * Remove words from the whitelist.
+     * @param words - Words to remove from whitelist.
+     */
+    removeFromWhitelist(words: string[]): void;
+    /**
+     * Check if a word is whitelisted.
+     * @param word - The word to check.
+     * @returns True if whitelisted, false otherwise.
+     */
+    private isWhitelisted;
+    /**
+     * 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 BeKind();
+     *
+     * // 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 BeKind();
+     * 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;
+    /**
+     * Load multiple language dictionaries.
+     * @param languages - Array of languages to load.
+     * @returns Number of successfully loaded languages.
+     */
+    loadLanguages(languages: string[]): number;
+    /**
+     * Load all supported Indian languages.
+     * @returns Number of loaded Indian languages.
+     */
+    loadIndianLanguages(): number;
+    /**
+     * 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 BeKind();
+     *
+     * // 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 BeKind();
+     *
+     * 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;
+    /**
+     * Add a single word to the trie.
+     * @param word - The word to add.
+     * @returns True if added, false otherwise.
+     */
+    private addWordToTrie;
+    /**
+     * Calculate severity from matches.
+     * @param matches - Array of matches.
+     * @returns Severity level.
+     */
+    private calculateSeverity;
+    /**
+     * Get the severity (s) and certainty (c) scores for a word.
+     * Returns null if the word has no score entry.
+     *
+     * @param word - The word to look up
+     * @returns The score object or null
+     */
+    getWordScore(word: string): {
+        severity: number;
+        certainty: number;
+        language: string;
+    } | null;
+    /**
+     * Check whether a word should be flagged based on its severity/certainty scores.
+     *
+     * Threshold rules:
+     * - Flag if s:5 (any certainty)
+     * - Flag if s:4+ AND c:2+
+     * - Flag if s:3 AND c:3+
+     * - Allow everything else
+     *
+     * @param word - The word to check
+     * @returns true if the word should be flagged
+     */
+    /**
+     * Shared threshold logic: determines whether a severity/certainty pair
+     * crosses the flag threshold. Used by shouldFlag, shouldFlagWithContext,
+     * and inline threshold checks.
+     */
+    static shouldFlagWithCertainty(severity: number, certainty: number): boolean;
+    shouldFlag(word: string): boolean;
+    /**
+     * Context-aware shouldFlag: for words with certainty ≤ 3, applies
+     * certainty-delta adjustments from surrounding context before evaluating
+     * the shouldFlag threshold. Words with certainty > 3 skip context analysis.
+     */
+    private shouldFlagWithContext;
+    /**
+     * Clear all loaded dictionaries and dynamic words.
+     */
+    clearList(): void;
+    /**
+     * Set the placeholder character for filtered words.
+     * @param placeholder - The placeholder character.
+     */
+    setPlaceholder(placeholder: string): void;
+    /**
+     * Get the list of loaded languages.
+     * @returns Array of loaded language keys.
+     */
+    getLoadedLanguages(): string[];
+    /**
+     * Get the list of available built-in languages.
+     * @returns Array of available language keys.
+     */
+    getAvailableLanguages(): string[];
+    /**
+     * Get the current configuration of the profanity filter.
+     * @returns Partial configuration object.
+     */
+    getConfig(): Partial<BeKindOptions>;
+    /**
+     * Rebuild the profanity trie from loaded dictionaries and dynamic words.
+     */
+    private rebuildTrie;
+    /**
+     * Update configuration options for the profanity filter.
+     * @param options - Partial configuration object.
+     */
+    updateConfig(options: Partial<BeKindOptions>): void;
+    /**
+     * Create an BeKind instance from a configuration object.
+     * @param config - Configuration object
+     * @returns A new BeKind instance
+     */
+    static fromConfig(config: BeKindOptions | any): BeKind;
+}
+/**
+ * Singleton instance of BeKind with default configuration.
+ */
+declare const allProfanity: BeKind;
+export default allProfanity;