glin-profanity 2.3.8 → 3.0.1

package/dist/types-BgQe4FSE.d.cts

@@ -0,0 +1,350 @@
+/**
+ * Type definitions for glin-profanity JavaScript/TypeScript package.
+ * Unified API that mirrors the Python package structure.
+ */
+/** Severity levels for profanity matches - unified with Python */
+declare enum SeverityLevel {
+    EXACT = 1,
+    FUZZY = 2
+}
+/** Supported languages - unified list with Python */
+type Language = 'arabic' | 'chinese' | 'czech' | 'danish' | 'dutch' | 'english' | 'esperanto' | 'finnish' | 'french' | 'german' | 'hindi' | 'hungarian' | 'italian' | 'japanese' | 'korean' | 'norwegian' | 'persian' | 'polish' | 'portuguese' | 'russian' | 'spanish' | 'swedish' | 'thai' | 'turkish';
+/** Represents a profanity match in text - unified with Python */
+interface Match {
+    word: string;
+    index: number;
+    severity: SeverityLevel;
+    contextScore?: number;
+    reason?: string;
+    isWhitelisted?: boolean;
+}
+/** Result of profanity check operation - unified field names */
+interface CheckProfanityResult {
+    containsProfanity: boolean;
+    profaneWords: string[];
+    processedText?: string;
+    severityMap?: Record<string, SeverityLevel>;
+    matches?: Match[];
+    contextScore?: number;
+    reason?: string;
+}
+/** Configuration for context-aware filtering - unified with Python */
+interface ContextAwareConfig {
+    enableContextAware?: boolean;
+    contextWindow?: number;
+    confidenceThreshold?: number;
+    domainWhitelists?: Record<string, string[]>;
+}
+/** Leetspeak detection intensity levels */
+type LeetspeakLevel = 'basic' | 'moderate' | 'aggressive';
+/** Main filter configuration options - unified with Python */
+interface FilterConfig extends ContextAwareConfig {
+    languages?: Language[];
+    allLanguages?: boolean;
+    caseSensitive?: boolean;
+    wordBoundaries?: boolean;
+    customWords?: string[];
+    replaceWith?: string;
+    severityLevels?: boolean;
+    ignoreWords?: string[];
+    logProfanity?: boolean;
+    allowObfuscatedMatch?: boolean;
+    fuzzyToleranceLevel?: number;
+    /**
+     * Enable leetspeak detection (e.g., "f4ck" → "fuck").
+     * @default false
+     */
+    detectLeetspeak?: boolean;
+    /**
+     * Leetspeak detection intensity level.
+     * - `basic`: Numbers only (0→o, 1→i, 3→e, 4→a, 5→s)
+     * - `moderate`: Basic + symbols (@→a, $→s, !→i)
+     * - `aggressive`: All known substitutions
+     * @default 'moderate'
+     */
+    leetspeakLevel?: LeetspeakLevel;
+    /**
+     * Enable Unicode normalization to detect homoglyphs and obfuscation.
+     * @default true
+     */
+    normalizeUnicode?: boolean;
+    /**
+     * Cache profanity check results for repeated strings.
+     * @default false
+     */
+    cacheResults?: boolean;
+    /**
+     * Maximum cache size when caching is enabled.
+     * @default 1000
+     */
+    maxCacheSize?: number;
+}
+/** Result with minimum severity filtering */
+interface FilteredProfanityResult {
+    result: CheckProfanityResult;
+    filteredWords: string[];
+}
+
+/**
+ * Core profanity filter class.
+ * Provides comprehensive profanity detection with support for multiple languages,
+ * leetspeak detection, Unicode normalization, and context-aware filtering.
+ *
+ * @example
+ * ```typescript
+ * const filter = new Filter({
+ *   languages: ['english'],
+ *   detectLeetspeak: true,
+ *   normalizeUnicode: true,
+ * });
+ *
+ * filter.isProfane('f4ck');  // Returns: true
+ * filter.isProfane('fυck');  // Returns: true (Greek upsilon)
+ * ```
+ */
+declare class Filter {
+    private words;
+    private caseSensitive;
+    private wordBoundaries;
+    private replaceWith?;
+    private severityLevels;
+    private ignoreWords;
+    private logProfanity;
+    private allowObfuscatedMatch;
+    private fuzzyToleranceLevel;
+    private enableContextAware;
+    private contextWindow;
+    private confidenceThreshold;
+    private contextAnalyzer?;
+    private primaryLanguage;
+    private detectLeetspeak;
+    private leetspeakLevel;
+    private normalizeUnicodeEnabled;
+    private cacheResults;
+    private maxCacheSize;
+    private cache;
+    /**
+     * Creates a new Filter instance with the specified configuration.
+     *
+     * @param config - Filter configuration options
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const filter = new Filter({ languages: ['english'] });
+     *
+     * // With leetspeak detection
+     * const filter = new Filter({
+     *   languages: ['english'],
+     *   detectLeetspeak: true,
+     *   leetspeakLevel: 'moderate',
+     * });
+     *
+     * // With all advanced features
+     * const filter = new Filter({
+     *   languages: ['english', 'spanish'],
+     *   detectLeetspeak: true,
+     *   normalizeUnicode: true,
+     *   cacheResults: true,
+     *   enableContextAware: true,
+     * });
+     * ```
+     */
+    constructor(config?: FilterConfig);
+    private debugLog;
+    /**
+     * Normalizes text for profanity detection using all enabled normalization methods.
+     * Applies Unicode normalization, leetspeak detection, and obfuscation handling.
+     *
+     * @param text - The input text to normalize
+     * @returns The normalized text
+     */
+    private normalizeText;
+    /**
+     * Legacy obfuscation normalization method (for backward compatibility).
+     * @deprecated Use normalizeText() with detectLeetspeak option instead.
+     */
+    private normalizeObfuscated;
+    /**
+     * Clears the result cache.
+     * Useful when dictionary or configuration changes.
+     */
+    clearCache(): void;
+    /**
+     * Gets the current cache size.
+     * @returns Number of cached results
+     */
+    getCacheSize(): number;
+    /**
+     * Exports the current filter configuration as a JSON-serializable object.
+     * Useful for saving configuration to files or sharing between environments.
+     *
+     * @returns The current filter configuration
+     *
+     * @example
+     * ```typescript
+     * const filter = new Filter({
+     *   languages: ['english', 'spanish'],
+     *   detectLeetspeak: true,
+     *   leetspeakLevel: 'aggressive',
+     * });
+     *
+     * const config = filter.getConfig();
+     * // Save to file: fs.writeFileSync('filter.config.json', JSON.stringify(config));
+     *
+     * // Later, restore:
+     * // const saved = JSON.parse(fs.readFileSync('filter.config.json'));
+     * // const restored = new Filter(saved);
+     * ```
+     */
+    getConfig(): FilterConfig;
+    /**
+     * Returns the current word dictionary size.
+     * Useful for monitoring and debugging.
+     *
+     * @returns Number of words in the dictionary
+     */
+    getWordCount(): number;
+    /**
+     * Adds a result to the cache, evicting oldest entries if necessary.
+     */
+    private addToCache;
+    /**
+     * Gets a cached result if available.
+     */
+    private getFromCache;
+    private getRegex;
+    private isFuzzyToleranceMatch;
+    private evaluateSeverity;
+    /**
+     * Checks if the given text contains profanity.
+     *
+     * @param value - The text to check
+     * @returns True if the text contains profanity
+     *
+     * @example
+     * ```typescript
+     * const filter = new Filter({ detectLeetspeak: true });
+     *
+     * filter.isProfane('hello');     // false
+     * filter.isProfane('fuck');      // true
+     * filter.isProfane('f4ck');      // true (leetspeak)
+     * filter.isProfane('fυck');      // true (Unicode homoglyph)
+     * ```
+     */
+    isProfane(value: string): boolean;
+    matches(word: string): boolean;
+    /**
+     * Performs a comprehensive profanity check on the given text.
+     *
+     * @param text - The text to check for profanity
+     * @returns Result object containing detected profanity information
+     *
+     * @example
+     * ```typescript
+     * const filter = new Filter({
+     *   languages: ['english'],
+     *   detectLeetspeak: true,
+     *   normalizeUnicode: true,
+     * });
+     *
+     * const result = filter.checkProfanity('This is f4ck!ng bad');
+     * console.log(result.containsProfanity);  // true
+     * console.log(result.profaneWords);       // ['fuck']
+     *
+     * // With caching for repeated checks
+     * const filter2 = new Filter({ cacheResults: true });
+     * filter2.checkProfanity('same text');  // Computed
+     * filter2.checkProfanity('same text');  // Retrieved from cache
+     * ```
+     */
+    checkProfanity(text: string): CheckProfanityResult;
+    /**
+     * Checks profanity with minimum severity filtering.
+     *
+     * @param text - The text to check
+     * @param minSeverity - Minimum severity level to include in results
+     * @returns Object with filtered words and full result
+     */
+    checkProfanityWithMinSeverity(text: string, minSeverity?: SeverityLevel): {
+        filteredWords: string[];
+        result: CheckProfanityResult;
+    };
+}
+
+/**
+ * Type definitions for ML-based profanity detection.
+ */
+/**
+ * Toxicity categories detected by the TensorFlow.js model.
+ * These map to the civil comments dataset labels.
+ */
+type ToxicityLabel = 'identity_attack' | 'insult' | 'obscene' | 'severe_toxicity' | 'sexual_explicit' | 'threat' | 'toxicity';
+/**
+ * Result from a single toxicity prediction.
+ */
+interface ToxicityPrediction {
+    /** The toxicity category */
+    label: ToxicityLabel;
+    /** Whether the text matches this category (null if below threshold) */
+    match: boolean | null;
+    /** Probability scores [non-toxic, toxic] */
+    probabilities: [number, number];
+}
+/**
+ * Result from ML-based toxicity analysis.
+ */
+interface MLAnalysisResult {
+    /** Whether any toxicity was detected */
+    isToxic: boolean;
+    /** Overall toxicity score (0-1) */
+    overallScore: number;
+    /** Predictions for each category */
+    predictions: ToxicityPrediction[];
+    /** Categories that matched */
+    matchedCategories: ToxicityLabel[];
+    /** Processing time in milliseconds */
+    processingTimeMs: number;
+}
+/**
+ * Configuration for the ML toxicity detector.
+ */
+interface MLDetectorConfig {
+    /**
+     * Minimum confidence threshold for predictions.
+     * Values below this threshold will return null for match.
+     * @default 0.85
+     */
+    threshold?: number;
+    /**
+     * Specific toxicity categories to check.
+     * If not specified, all categories are checked.
+     */
+    labels?: ToxicityLabel[];
+    /**
+     * Whether to load the model immediately on instantiation.
+     * If false, model will be loaded on first use.
+     * @default false
+     */
+    preloadModel?: boolean;
+}
+/**
+ * Combined result from both rule-based and ML detection.
+ */
+interface HybridAnalysisResult {
+    /** Rule-based detection result */
+    ruleBasedResult: {
+        containsProfanity: boolean;
+        profaneWords: string[];
+    };
+    /** ML-based detection result (null if ML not enabled) */
+    mlResult: MLAnalysisResult | null;
+    /** Combined decision */
+    isToxic: boolean;
+    /** Confidence score for the decision */
+    confidence: number;
+    /** Reason for the decision */
+    reason: string;
+}
+
+export { type CheckProfanityResult as C, Filter as F, type HybridAnalysisResult as H, type Language as L, type Match as M, SeverityLevel as S, type ToxicityLabel as T, type FilterConfig as a, type FilteredProfanityResult as b, type ContextAwareConfig as c, type ToxicityPrediction as d, type MLAnalysisResult as e, type MLDetectorConfig as f };

package/dist/types-BgQe4FSE.d.ts

@@ -0,0 +1,350 @@
+/**
+ * Type definitions for glin-profanity JavaScript/TypeScript package.
+ * Unified API that mirrors the Python package structure.
+ */
+/** Severity levels for profanity matches - unified with Python */
+declare enum SeverityLevel {
+    EXACT = 1,
+    FUZZY = 2
+}
+/** Supported languages - unified list with Python */
+type Language = 'arabic' | 'chinese' | 'czech' | 'danish' | 'dutch' | 'english' | 'esperanto' | 'finnish' | 'french' | 'german' | 'hindi' | 'hungarian' | 'italian' | 'japanese' | 'korean' | 'norwegian' | 'persian' | 'polish' | 'portuguese' | 'russian' | 'spanish' | 'swedish' | 'thai' | 'turkish';
+/** Represents a profanity match in text - unified with Python */
+interface Match {
+    word: string;
+    index: number;
+    severity: SeverityLevel;
+    contextScore?: number;
+    reason?: string;
+    isWhitelisted?: boolean;
+}
+/** Result of profanity check operation - unified field names */
+interface CheckProfanityResult {
+    containsProfanity: boolean;
+    profaneWords: string[];
+    processedText?: string;
+    severityMap?: Record<string, SeverityLevel>;
+    matches?: Match[];
+    contextScore?: number;
+    reason?: string;
+}
+/** Configuration for context-aware filtering - unified with Python */
+interface ContextAwareConfig {
+    enableContextAware?: boolean;
+    contextWindow?: number;
+    confidenceThreshold?: number;
+    domainWhitelists?: Record<string, string[]>;
+}
+/** Leetspeak detection intensity levels */
+type LeetspeakLevel = 'basic' | 'moderate' | 'aggressive';
+/** Main filter configuration options - unified with Python */
+interface FilterConfig extends ContextAwareConfig {
+    languages?: Language[];
+    allLanguages?: boolean;
+    caseSensitive?: boolean;
+    wordBoundaries?: boolean;
+    customWords?: string[];
+    replaceWith?: string;
+    severityLevels?: boolean;
+    ignoreWords?: string[];
+    logProfanity?: boolean;
+    allowObfuscatedMatch?: boolean;
+    fuzzyToleranceLevel?: number;
+    /**
+     * Enable leetspeak detection (e.g., "f4ck" → "fuck").
+     * @default false
+     */
+    detectLeetspeak?: boolean;
+    /**
+     * Leetspeak detection intensity level.
+     * - `basic`: Numbers only (0→o, 1→i, 3→e, 4→a, 5→s)
+     * - `moderate`: Basic + symbols (@→a, $→s, !→i)
+     * - `aggressive`: All known substitutions
+     * @default 'moderate'
+     */
+    leetspeakLevel?: LeetspeakLevel;
+    /**
+     * Enable Unicode normalization to detect homoglyphs and obfuscation.
+     * @default true
+     */
+    normalizeUnicode?: boolean;
+    /**
+     * Cache profanity check results for repeated strings.
+     * @default false
+     */
+    cacheResults?: boolean;
+    /**
+     * Maximum cache size when caching is enabled.
+     * @default 1000
+     */
+    maxCacheSize?: number;
+}
+/** Result with minimum severity filtering */
+interface FilteredProfanityResult {
+    result: CheckProfanityResult;
+    filteredWords: string[];
+}
+
+/**
+ * Core profanity filter class.
+ * Provides comprehensive profanity detection with support for multiple languages,
+ * leetspeak detection, Unicode normalization, and context-aware filtering.
+ *
+ * @example
+ * ```typescript
+ * const filter = new Filter({
+ *   languages: ['english'],
+ *   detectLeetspeak: true,
+ *   normalizeUnicode: true,
+ * });
+ *
+ * filter.isProfane('f4ck');  // Returns: true
+ * filter.isProfane('fυck');  // Returns: true (Greek upsilon)
+ * ```
+ */
+declare class Filter {
+    private words;
+    private caseSensitive;
+    private wordBoundaries;
+    private replaceWith?;
+    private severityLevels;
+    private ignoreWords;
+    private logProfanity;
+    private allowObfuscatedMatch;
+    private fuzzyToleranceLevel;
+    private enableContextAware;
+    private contextWindow;
+    private confidenceThreshold;
+    private contextAnalyzer?;
+    private primaryLanguage;
+    private detectLeetspeak;
+    private leetspeakLevel;
+    private normalizeUnicodeEnabled;
+    private cacheResults;
+    private maxCacheSize;
+    private cache;
+    /**
+     * Creates a new Filter instance with the specified configuration.
+     *
+     * @param config - Filter configuration options
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const filter = new Filter({ languages: ['english'] });
+     *
+     * // With leetspeak detection
+     * const filter = new Filter({
+     *   languages: ['english'],
+     *   detectLeetspeak: true,
+     *   leetspeakLevel: 'moderate',
+     * });
+     *
+     * // With all advanced features
+     * const filter = new Filter({
+     *   languages: ['english', 'spanish'],
+     *   detectLeetspeak: true,
+     *   normalizeUnicode: true,
+     *   cacheResults: true,
+     *   enableContextAware: true,
+     * });
+     * ```
+     */
+    constructor(config?: FilterConfig);
+    private debugLog;
+    /**
+     * Normalizes text for profanity detection using all enabled normalization methods.
+     * Applies Unicode normalization, leetspeak detection, and obfuscation handling.
+     *
+     * @param text - The input text to normalize
+     * @returns The normalized text
+     */
+    private normalizeText;
+    /**
+     * Legacy obfuscation normalization method (for backward compatibility).
+     * @deprecated Use normalizeText() with detectLeetspeak option instead.
+     */
+    private normalizeObfuscated;
+    /**
+     * Clears the result cache.
+     * Useful when dictionary or configuration changes.
+     */
+    clearCache(): void;
+    /**
+     * Gets the current cache size.
+     * @returns Number of cached results
+     */
+    getCacheSize(): number;
+    /**
+     * Exports the current filter configuration as a JSON-serializable object.
+     * Useful for saving configuration to files or sharing between environments.
+     *
+     * @returns The current filter configuration
+     *
+     * @example
+     * ```typescript
+     * const filter = new Filter({
+     *   languages: ['english', 'spanish'],
+     *   detectLeetspeak: true,
+     *   leetspeakLevel: 'aggressive',
+     * });
+     *
+     * const config = filter.getConfig();
+     * // Save to file: fs.writeFileSync('filter.config.json', JSON.stringify(config));
+     *
+     * // Later, restore:
+     * // const saved = JSON.parse(fs.readFileSync('filter.config.json'));
+     * // const restored = new Filter(saved);
+     * ```
+     */
+    getConfig(): FilterConfig;
+    /**
+     * Returns the current word dictionary size.
+     * Useful for monitoring and debugging.
+     *
+     * @returns Number of words in the dictionary
+     */
+    getWordCount(): number;
+    /**
+     * Adds a result to the cache, evicting oldest entries if necessary.
+     */
+    private addToCache;
+    /**
+     * Gets a cached result if available.
+     */
+    private getFromCache;
+    private getRegex;
+    private isFuzzyToleranceMatch;
+    private evaluateSeverity;
+    /**
+     * Checks if the given text contains profanity.
+     *
+     * @param value - The text to check
+     * @returns True if the text contains profanity
+     *
+     * @example
+     * ```typescript
+     * const filter = new Filter({ detectLeetspeak: true });
+     *
+     * filter.isProfane('hello');     // false
+     * filter.isProfane('fuck');      // true
+     * filter.isProfane('f4ck');      // true (leetspeak)
+     * filter.isProfane('fυck');      // true (Unicode homoglyph)
+     * ```
+     */
+    isProfane(value: string): boolean;
+    matches(word: string): boolean;
+    /**
+     * Performs a comprehensive profanity check on the given text.
+     *
+     * @param text - The text to check for profanity
+     * @returns Result object containing detected profanity information
+     *
+     * @example
+     * ```typescript
+     * const filter = new Filter({
+     *   languages: ['english'],
+     *   detectLeetspeak: true,
+     *   normalizeUnicode: true,
+     * });
+     *
+     * const result = filter.checkProfanity('This is f4ck!ng bad');
+     * console.log(result.containsProfanity);  // true
+     * console.log(result.profaneWords);       // ['fuck']
+     *
+     * // With caching for repeated checks
+     * const filter2 = new Filter({ cacheResults: true });
+     * filter2.checkProfanity('same text');  // Computed
+     * filter2.checkProfanity('same text');  // Retrieved from cache
+     * ```
+     */
+    checkProfanity(text: string): CheckProfanityResult;
+    /**
+     * Checks profanity with minimum severity filtering.
+     *
+     * @param text - The text to check
+     * @param minSeverity - Minimum severity level to include in results
+     * @returns Object with filtered words and full result
+     */
+    checkProfanityWithMinSeverity(text: string, minSeverity?: SeverityLevel): {
+        filteredWords: string[];
+        result: CheckProfanityResult;
+    };
+}
+
+/**
+ * Type definitions for ML-based profanity detection.
+ */
+/**
+ * Toxicity categories detected by the TensorFlow.js model.
+ * These map to the civil comments dataset labels.
+ */
+type ToxicityLabel = 'identity_attack' | 'insult' | 'obscene' | 'severe_toxicity' | 'sexual_explicit' | 'threat' | 'toxicity';
+/**
+ * Result from a single toxicity prediction.
+ */
+interface ToxicityPrediction {
+    /** The toxicity category */
+    label: ToxicityLabel;
+    /** Whether the text matches this category (null if below threshold) */
+    match: boolean | null;
+    /** Probability scores [non-toxic, toxic] */
+    probabilities: [number, number];
+}
+/**
+ * Result from ML-based toxicity analysis.
+ */
+interface MLAnalysisResult {
+    /** Whether any toxicity was detected */
+    isToxic: boolean;
+    /** Overall toxicity score (0-1) */
+    overallScore: number;
+    /** Predictions for each category */
+    predictions: ToxicityPrediction[];
+    /** Categories that matched */
+    matchedCategories: ToxicityLabel[];
+    /** Processing time in milliseconds */
+    processingTimeMs: number;
+}
+/**
+ * Configuration for the ML toxicity detector.
+ */
+interface MLDetectorConfig {
+    /**
+     * Minimum confidence threshold for predictions.
+     * Values below this threshold will return null for match.
+     * @default 0.85
+     */
+    threshold?: number;
+    /**
+     * Specific toxicity categories to check.
+     * If not specified, all categories are checked.
+     */
+    labels?: ToxicityLabel[];
+    /**
+     * Whether to load the model immediately on instantiation.
+     * If false, model will be loaded on first use.
+     * @default false
+     */
+    preloadModel?: boolean;
+}
+/**
+ * Combined result from both rule-based and ML detection.
+ */
+interface HybridAnalysisResult {
+    /** Rule-based detection result */
+    ruleBasedResult: {
+        containsProfanity: boolean;
+        profaneWords: string[];
+    };
+    /** ML-based detection result (null if ML not enabled) */
+    mlResult: MLAnalysisResult | null;
+    /** Combined decision */
+    isToxic: boolean;
+    /** Confidence score for the decision */
+    confidence: number;
+    /** Reason for the decision */
+    reason: string;
+}
+
+export { type CheckProfanityResult as C, Filter as F, type HybridAnalysisResult as H, type Language as L, type Match as M, SeverityLevel as S, type ToxicityLabel as T, type FilterConfig as a, type FilteredProfanityResult as b, type ContextAwareConfig as c, type ToxicityPrediction as d, type MLAnalysisResult as e, type MLDetectorConfig as f };