terlik.js 2.2.0

package/dist/index.d.mts

@@ -0,0 +1,278 @@
+/** Profanity severity level. */
+type Severity = "high" | "medium" | "low";
+/** Detection mode controlling the balance between precision and recall. */
+type Mode = "strict" | "balanced" | "loose";
+/** Masking style used when cleaning text. */
+type MaskStyle = "stars" | "partial" | "replace";
+/** Fuzzy matching algorithm. */
+type FuzzyAlgorithm = "levenshtein" | "dice";
+/** How a match was detected. */
+type MatchMethod = "exact" | "pattern" | "fuzzy";
+/** A single entry in the profanity dictionary. */
+interface WordEntry {
+    /** The canonical root form of the word. */
+    root: string;
+    /** Alternative spellings or forms of the root. */
+    variants: string[];
+    /** Severity level of the word. */
+    severity: Severity;
+    /** Content category (e.g. "sexual", "insult", "slur", "general"). */
+    category?: string;
+    /** Whether the suffix engine should match grammatical suffixes on this root. */
+    suffixable?: boolean;
+}
+/** Configuration options for creating a Terlik instance. */
+interface TerlikOptions {
+    /** Language code (default: `"tr"`). */
+    language?: string;
+    /** Detection mode (default: `"balanced"`). */
+    mode?: Mode;
+    /** Masking style (default: `"stars"`). */
+    maskStyle?: MaskStyle;
+    /** Additional words to detect. */
+    customList?: string[];
+    /** Additional words to exclude from detection. */
+    whitelist?: string[];
+    /** Enable fuzzy matching (default: `false`). */
+    enableFuzzy?: boolean;
+    /** Fuzzy similarity threshold between 0 and 1 (default: `0.8`). */
+    fuzzyThreshold?: number;
+    /** Fuzzy matching algorithm (default: `"levenshtein"`). */
+    fuzzyAlgorithm?: FuzzyAlgorithm;
+    /** Maximum input length before truncation (default: `10000`). */
+    maxLength?: number;
+    /** Custom mask text for "replace" mask style (default: `"[***]"`). */
+    replaceMask?: string;
+    /** Background'da regex derleme + JIT warmup. Default: false. Serverless'da önerilmez. */
+    backgroundWarmup?: boolean;
+}
+/** Per-call detection options that override instance defaults. */
+interface DetectOptions {
+    mode?: Mode;
+    enableFuzzy?: boolean;
+    fuzzyThreshold?: number;
+    fuzzyAlgorithm?: FuzzyAlgorithm;
+}
+/** Per-call clean options that override instance defaults. */
+interface CleanOptions extends DetectOptions {
+    maskStyle?: MaskStyle;
+    replaceMask?: string;
+}
+/** A single profanity match found in the input text. */
+interface MatchResult {
+    /** The matched text from the original input. */
+    word: string;
+    /** The dictionary root word. */
+    root: string;
+    /** Character index in the original input. */
+    index: number;
+    /** Severity of the matched word. */
+    severity: Severity;
+    /** How the match was detected. */
+    method: MatchMethod;
+}
+
+/**
+ * Multi-language profanity detection and filtering engine.
+ *
+ * @example
+ * ```ts
+ * const terlik = new Terlik();
+ * terlik.containsProfanity("siktir"); // true
+ * terlik.clean("siktir git");         // "****** git"
+ * ```
+ */
+declare class Terlik {
+    private dictionary;
+    private detector;
+    private mode;
+    private maskStyle;
+    private enableFuzzy;
+    private fuzzyThreshold;
+    private fuzzyAlgorithm;
+    private maxLength;
+    private replaceMask;
+    /** The language code this instance was created with. */
+    readonly language: string;
+    /**
+     * Creates a new Terlik instance.
+     * @param options - Configuration options.
+     * @throws {Error} If the specified language is not supported.
+     */
+    constructor(options?: TerlikOptions);
+    /**
+     * Creates and JIT-warms instances for multiple languages at once.
+     * Useful for server deployments to eliminate cold-start latency.
+     *
+     * @param languages - Language codes to warm up (e.g. `["tr", "en"]`).
+     * @param baseOptions - Shared options applied to all instances.
+     * @returns A map of language code to warmed-up Terlik instance.
+     *
+     * @example
+     * ```ts
+     * const cache = Terlik.warmup(["tr", "en", "es"]);
+     * cache.get("en")!.containsProfanity("fuck"); // true, no cold start
+     * ```
+     */
+    static warmup(languages: string[], baseOptions?: Omit<TerlikOptions, "language">): Map<string, Terlik>;
+    /**
+     * Checks whether the text contains profanity.
+     * @param text - The text to check.
+     * @param options - Per-call detection options (overrides instance defaults).
+     * @returns `true` if profanity is detected, `false` otherwise.
+     */
+    containsProfanity(text: string, options?: DetectOptions): boolean;
+    /**
+     * Returns all profanity matches with details (word, root, index, severity, method).
+     * @param text - The text to analyze.
+     * @param options - Per-call detection options (overrides instance defaults).
+     * @returns Array of match results, sorted by index.
+     */
+    getMatches(text: string, options?: DetectOptions): MatchResult[];
+    /**
+     * Returns the text with detected profanity masked.
+     * @param text - The text to clean.
+     * @param options - Per-call clean options (overrides instance defaults).
+     * @returns The cleaned text with profanity replaced by mask characters.
+     */
+    clean(text: string, options?: CleanOptions): string;
+    /**
+     * Adds custom words to the detection dictionary at runtime.
+     * Triggers pattern recompilation.
+     * @param words - Words to add.
+     */
+    addWords(words: string[]): void;
+    /**
+     * Removes words from the detection dictionary at runtime.
+     * Triggers pattern recompilation.
+     * @param words - Words to remove.
+     */
+    removeWords(words: string[]): void;
+    /**
+     * Returns the compiled regex patterns keyed by root word.
+     * Useful for debugging or advanced usage.
+     * @returns Map of root word to compiled RegExp.
+     */
+    getPatterns(): Map<string, RegExp>;
+    private mergeDetectOptions;
+}
+
+/** Configuration for creating a language-specific normalizer. */
+interface NormalizerConfig {
+    locale: string;
+    charMap: Record<string, string>;
+    leetMap: Record<string, string>;
+    numberExpansions?: [string, string][];
+}
+/**
+ * Creates a language-specific normalize function using the given config.
+ * The returned function applies a 6-stage pipeline: lowercase, char folding,
+ * number expansion, leet decode, punctuation removal, repeat collapse.
+ *
+ * @param config - Language-specific normalization settings.
+ * @returns A normalize function for the configured language.
+ *
+ * @example
+ * ```ts
+ * const normalize = createNormalizer({
+ *   locale: "de",
+ *   charMap: { ä: "a", ö: "o", ü: "u", ß: "ss" },
+ *   leetMap: { "0": "o", "3": "e" },
+ * });
+ * normalize("Scheiße"); // "scheisse"
+ * ```
+ */
+declare function createNormalizer(config: NormalizerConfig): (text: string) => string;
+/**
+ * Normalizes text using the default Turkish locale pipeline.
+ * Shorthand for `createNormalizer()` with Turkish defaults.
+ *
+ * @param text - The text to normalize.
+ * @returns The normalized text.
+ *
+ * @example
+ * ```ts
+ * normalize("S.İ.K.T.İ.R"); // "siktir"
+ * normalize("$1kt1r");       // "siktir"
+ * ```
+ */
+declare function normalize(text: string): string;
+
+/**
+ * Computes the Levenshtein edit distance between two strings.
+ * Uses O(n) space optimization with two-row approach.
+ *
+ * @param a - First string.
+ * @param b - Second string.
+ * @returns The minimum number of single-character edits (insertions, deletions, substitutions).
+ */
+declare function levenshteinDistance(a: string, b: string): number;
+/**
+ * Computes the Levenshtein similarity ratio between two strings.
+ * Returns a value between 0 (completely different) and 1 (identical).
+ *
+ * @param a - First string.
+ * @param b - Second string.
+ * @returns Similarity ratio (0–1).
+ */
+declare function levenshteinSimilarity(a: string, b: string): number;
+/**
+ * Computes the Dice coefficient (bigram similarity) between two strings.
+ * Returns a value between 0 (no shared bigrams) and 1 (identical bigrams).
+ *
+ * @param a - First string (must be at least 2 characters for meaningful result).
+ * @param b - Second string (must be at least 2 characters for meaningful result).
+ * @returns Dice coefficient (0–1).
+ */
+declare function diceSimilarity(a: string, b: string): number;
+
+/** Raw dictionary data structure as loaded from JSON. */
+interface DictionaryData {
+    version: number;
+    suffixes: string[];
+    entries: Array<{
+        root: string;
+        variants: string[];
+        severity: string;
+        category: string;
+        suffixable: boolean;
+    }>;
+    whitelist: string[];
+}
+
+interface LanguageConfig {
+    /** BCP-47 locale tag for toLocaleLowerCase (e.g. "tr", "en", "es", "de") */
+    locale: string;
+    /** Diacritics normalization: language-specific characters to base Latin.
+     *  e.g. Turkish: ç→c, ğ→g, ı→i; German: ä→a, ö→o, ü→u, ß→ss */
+    charMap: Record<string, string>;
+    /** Leet speak substitution map.
+     *  e.g. "0"→"o", "1"→"i", "@"→"a", "$"→"s" */
+    leetMap: Record<string, string>;
+    /** Visual similarity regex character classes for the pattern engine.
+     *  Each key is a base letter, value is a regex character class string.
+     *  e.g. a: "[a4@àáâãäå]", s: "[s5$şŞß]" */
+    charClasses: Record<string, string>;
+    /** Optional number-to-word expansions applied between letters.
+     *  e.g. Turkish: [["2", "iki"], ["10", "on"]]
+     *  Most languages leave this undefined. */
+    numberExpansions?: [string, string][];
+    /** Validated dictionary data (entries, whitelist, suffixes, version). */
+    dictionary: DictionaryData;
+}
+
+/**
+ * Retrieves the configuration for a supported language.
+ *
+ * @param lang - Language code (e.g. "tr", "en", "es", "de").
+ * @returns The language configuration including dictionary, charMap, and leetMap.
+ * @throws {Error} If the language is not supported or the dictionary version is too old.
+ */
+declare function getLanguageConfig(lang: string): LanguageConfig;
+/**
+ * Returns all available language codes.
+ * @returns Array of supported language codes (e.g. `["tr", "en", "es", "de"]`).
+ */
+declare function getSupportedLanguages(): string[];
+
+export { type CleanOptions, type DetectOptions, type FuzzyAlgorithm, type LanguageConfig, type MaskStyle, type MatchMethod, type MatchResult, type Mode, type NormalizerConfig, type Severity, Terlik, type TerlikOptions, type WordEntry, createNormalizer, diceSimilarity, getLanguageConfig, getSupportedLanguages, levenshteinDistance, levenshteinSimilarity, normalize };

package/dist/index.d.ts

@@ -0,0 +1,278 @@
+/** Profanity severity level. */
+type Severity = "high" | "medium" | "low";
+/** Detection mode controlling the balance between precision and recall. */
+type Mode = "strict" | "balanced" | "loose";
+/** Masking style used when cleaning text. */
+type MaskStyle = "stars" | "partial" | "replace";
+/** Fuzzy matching algorithm. */
+type FuzzyAlgorithm = "levenshtein" | "dice";
+/** How a match was detected. */
+type MatchMethod = "exact" | "pattern" | "fuzzy";
+/** A single entry in the profanity dictionary. */
+interface WordEntry {
+    /** The canonical root form of the word. */
+    root: string;
+    /** Alternative spellings or forms of the root. */
+    variants: string[];
+    /** Severity level of the word. */
+    severity: Severity;
+    /** Content category (e.g. "sexual", "insult", "slur", "general"). */
+    category?: string;
+    /** Whether the suffix engine should match grammatical suffixes on this root. */
+    suffixable?: boolean;
+}
+/** Configuration options for creating a Terlik instance. */
+interface TerlikOptions {
+    /** Language code (default: `"tr"`). */
+    language?: string;
+    /** Detection mode (default: `"balanced"`). */
+    mode?: Mode;
+    /** Masking style (default: `"stars"`). */
+    maskStyle?: MaskStyle;
+    /** Additional words to detect. */
+    customList?: string[];
+    /** Additional words to exclude from detection. */
+    whitelist?: string[];
+    /** Enable fuzzy matching (default: `false`). */
+    enableFuzzy?: boolean;
+    /** Fuzzy similarity threshold between 0 and 1 (default: `0.8`). */
+    fuzzyThreshold?: number;
+    /** Fuzzy matching algorithm (default: `"levenshtein"`). */
+    fuzzyAlgorithm?: FuzzyAlgorithm;
+    /** Maximum input length before truncation (default: `10000`). */
+    maxLength?: number;
+    /** Custom mask text for "replace" mask style (default: `"[***]"`). */
+    replaceMask?: string;
+    /** Background'da regex derleme + JIT warmup. Default: false. Serverless'da önerilmez. */
+    backgroundWarmup?: boolean;
+}
+/** Per-call detection options that override instance defaults. */
+interface DetectOptions {
+    mode?: Mode;
+    enableFuzzy?: boolean;
+    fuzzyThreshold?: number;
+    fuzzyAlgorithm?: FuzzyAlgorithm;
+}
+/** Per-call clean options that override instance defaults. */
+interface CleanOptions extends DetectOptions {
+    maskStyle?: MaskStyle;
+    replaceMask?: string;
+}
+/** A single profanity match found in the input text. */
+interface MatchResult {
+    /** The matched text from the original input. */
+    word: string;
+    /** The dictionary root word. */
+    root: string;
+    /** Character index in the original input. */
+    index: number;
+    /** Severity of the matched word. */
+    severity: Severity;
+    /** How the match was detected. */
+    method: MatchMethod;
+}
+
+/**
+ * Multi-language profanity detection and filtering engine.
+ *
+ * @example
+ * ```ts
+ * const terlik = new Terlik();
+ * terlik.containsProfanity("siktir"); // true
+ * terlik.clean("siktir git");         // "****** git"
+ * ```
+ */
+declare class Terlik {
+    private dictionary;
+    private detector;
+    private mode;
+    private maskStyle;
+    private enableFuzzy;
+    private fuzzyThreshold;
+    private fuzzyAlgorithm;
+    private maxLength;
+    private replaceMask;
+    /** The language code this instance was created with. */
+    readonly language: string;
+    /**
+     * Creates a new Terlik instance.
+     * @param options - Configuration options.
+     * @throws {Error} If the specified language is not supported.
+     */
+    constructor(options?: TerlikOptions);
+    /**
+     * Creates and JIT-warms instances for multiple languages at once.
+     * Useful for server deployments to eliminate cold-start latency.
+     *
+     * @param languages - Language codes to warm up (e.g. `["tr", "en"]`).
+     * @param baseOptions - Shared options applied to all instances.
+     * @returns A map of language code to warmed-up Terlik instance.
+     *
+     * @example
+     * ```ts
+     * const cache = Terlik.warmup(["tr", "en", "es"]);
+     * cache.get("en")!.containsProfanity("fuck"); // true, no cold start
+     * ```
+     */
+    static warmup(languages: string[], baseOptions?: Omit<TerlikOptions, "language">): Map<string, Terlik>;
+    /**
+     * Checks whether the text contains profanity.
+     * @param text - The text to check.
+     * @param options - Per-call detection options (overrides instance defaults).
+     * @returns `true` if profanity is detected, `false` otherwise.
+     */
+    containsProfanity(text: string, options?: DetectOptions): boolean;
+    /**
+     * Returns all profanity matches with details (word, root, index, severity, method).
+     * @param text - The text to analyze.
+     * @param options - Per-call detection options (overrides instance defaults).
+     * @returns Array of match results, sorted by index.
+     */
+    getMatches(text: string, options?: DetectOptions): MatchResult[];
+    /**
+     * Returns the text with detected profanity masked.
+     * @param text - The text to clean.
+     * @param options - Per-call clean options (overrides instance defaults).
+     * @returns The cleaned text with profanity replaced by mask characters.
+     */
+    clean(text: string, options?: CleanOptions): string;
+    /**
+     * Adds custom words to the detection dictionary at runtime.
+     * Triggers pattern recompilation.
+     * @param words - Words to add.
+     */
+    addWords(words: string[]): void;
+    /**
+     * Removes words from the detection dictionary at runtime.
+     * Triggers pattern recompilation.
+     * @param words - Words to remove.
+     */
+    removeWords(words: string[]): void;
+    /**
+     * Returns the compiled regex patterns keyed by root word.
+     * Useful for debugging or advanced usage.
+     * @returns Map of root word to compiled RegExp.
+     */
+    getPatterns(): Map<string, RegExp>;
+    private mergeDetectOptions;
+}
+
+/** Configuration for creating a language-specific normalizer. */
+interface NormalizerConfig {
+    locale: string;
+    charMap: Record<string, string>;
+    leetMap: Record<string, string>;
+    numberExpansions?: [string, string][];
+}
+/**
+ * Creates a language-specific normalize function using the given config.
+ * The returned function applies a 6-stage pipeline: lowercase, char folding,
+ * number expansion, leet decode, punctuation removal, repeat collapse.
+ *
+ * @param config - Language-specific normalization settings.
+ * @returns A normalize function for the configured language.
+ *
+ * @example
+ * ```ts
+ * const normalize = createNormalizer({
+ *   locale: "de",
+ *   charMap: { ä: "a", ö: "o", ü: "u", ß: "ss" },
+ *   leetMap: { "0": "o", "3": "e" },
+ * });
+ * normalize("Scheiße"); // "scheisse"
+ * ```
+ */
+declare function createNormalizer(config: NormalizerConfig): (text: string) => string;
+/**
+ * Normalizes text using the default Turkish locale pipeline.
+ * Shorthand for `createNormalizer()` with Turkish defaults.
+ *
+ * @param text - The text to normalize.
+ * @returns The normalized text.
+ *
+ * @example
+ * ```ts
+ * normalize("S.İ.K.T.İ.R"); // "siktir"
+ * normalize("$1kt1r");       // "siktir"
+ * ```
+ */
+declare function normalize(text: string): string;
+
+/**
+ * Computes the Levenshtein edit distance between two strings.
+ * Uses O(n) space optimization with two-row approach.
+ *
+ * @param a - First string.
+ * @param b - Second string.
+ * @returns The minimum number of single-character edits (insertions, deletions, substitutions).
+ */
+declare function levenshteinDistance(a: string, b: string): number;
+/**
+ * Computes the Levenshtein similarity ratio between two strings.
+ * Returns a value between 0 (completely different) and 1 (identical).
+ *
+ * @param a - First string.
+ * @param b - Second string.
+ * @returns Similarity ratio (0–1).
+ */
+declare function levenshteinSimilarity(a: string, b: string): number;
+/**
+ * Computes the Dice coefficient (bigram similarity) between two strings.
+ * Returns a value between 0 (no shared bigrams) and 1 (identical bigrams).
+ *
+ * @param a - First string (must be at least 2 characters for meaningful result).
+ * @param b - Second string (must be at least 2 characters for meaningful result).
+ * @returns Dice coefficient (0–1).
+ */
+declare function diceSimilarity(a: string, b: string): number;
+
+/** Raw dictionary data structure as loaded from JSON. */
+interface DictionaryData {
+    version: number;
+    suffixes: string[];
+    entries: Array<{
+        root: string;
+        variants: string[];
+        severity: string;
+        category: string;
+        suffixable: boolean;
+    }>;
+    whitelist: string[];
+}
+
+interface LanguageConfig {
+    /** BCP-47 locale tag for toLocaleLowerCase (e.g. "tr", "en", "es", "de") */
+    locale: string;
+    /** Diacritics normalization: language-specific characters to base Latin.
+     *  e.g. Turkish: ç→c, ğ→g, ı→i; German: ä→a, ö→o, ü→u, ß→ss */
+    charMap: Record<string, string>;
+    /** Leet speak substitution map.
+     *  e.g. "0"→"o", "1"→"i", "@"→"a", "$"→"s" */
+    leetMap: Record<string, string>;
+    /** Visual similarity regex character classes for the pattern engine.
+     *  Each key is a base letter, value is a regex character class string.
+     *  e.g. a: "[a4@àáâãäå]", s: "[s5$şŞß]" */
+    charClasses: Record<string, string>;
+    /** Optional number-to-word expansions applied between letters.
+     *  e.g. Turkish: [["2", "iki"], ["10", "on"]]
+     *  Most languages leave this undefined. */
+    numberExpansions?: [string, string][];
+    /** Validated dictionary data (entries, whitelist, suffixes, version). */
+    dictionary: DictionaryData;
+}
+
+/**
+ * Retrieves the configuration for a supported language.
+ *
+ * @param lang - Language code (e.g. "tr", "en", "es", "de").
+ * @returns The language configuration including dictionary, charMap, and leetMap.
+ * @throws {Error} If the language is not supported or the dictionary version is too old.
+ */
+declare function getLanguageConfig(lang: string): LanguageConfig;
+/**
+ * Returns all available language codes.
+ * @returns Array of supported language codes (e.g. `["tr", "en", "es", "de"]`).
+ */
+declare function getSupportedLanguages(): string[];
+
+export { type CleanOptions, type DetectOptions, type FuzzyAlgorithm, type LanguageConfig, type MaskStyle, type MatchMethod, type MatchResult, type Mode, type NormalizerConfig, type Severity, Terlik, type TerlikOptions, type WordEntry, createNormalizer, diceSimilarity, getLanguageConfig, getSupportedLanguages, levenshteinDistance, levenshteinSimilarity, normalize };