terlik.js 2.2.1 → 2.4.0

package/README.md

@@ -1,15 +1,15 @@
 # terlik.js
 
-![terlik.js](git-header.png)
+![terlik.js](assets/git-header.png)
 
 [![CI](https://github.com/badursun/terlik.js/actions/workflows/ci.yml/badge.svg)](https://github.com/badursun/terlik.js/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/terlik.js.svg)](https://www.npmjs.com/package/terlik.js)
 [![npm bundle size](https://img.shields.io/bundlephobia/minzip/terlik.js)](https://bundlephobia.com/package/terlik.js)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Production-grade multi-language profanity detection and filtering. Not a naive blacklist — a multi-layered normalization and pattern engine that catches what simple string matching misses.
+Turkish-first multi-language profanity detection and filtering. Not a naive blacklist — a multi-layered normalization and pattern engine that catches what simple string matching misses.
 
-Built-in support for **Turkish**, **English**, **Spanish**, and **German**. Adding a new language is just a folder with two files.
+**Turkish** is the flagship language with full coverage. **English**, **Spanish**, and **German** are community-maintained and open for contributions. Adding a new language is just a folder with two files.
 
 Zero runtime dependencies. Full TypeScript. ESM + CJS. **35 KB** gzipped. Works in Node.js, Bun, Deno, browsers, Cloudflare Workers, and Edge runtimes — no Node.js-specific APIs used.
 
@@ -119,6 +119,8 @@ For suffixable roots, the engine appends an optional suffix group (up to 2 chain
 
 ### Language Packs
 
+Community contributions to existing language packs (new words, variants, whitelist entries) and entirely new language packs are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for step-by-step instructions.
+
 Each language lives in its own folder under `src/lang/`:
 
 ```
@@ -161,12 +163,12 @@ terlik.js ships with a **deliberately narrow dictionary** — the goal is to **m
 
 ### Coverage
 
-| Language | Roots | Explicit Variants | Suffixes | Whitelist | Effective Forms |
-|---|---|---|---|---|---|
-| Turkish | 25 | 88 | 83 | 52 | ~3,000+ |
-| English | 23 | 106 | 8 | 42 | ~700+ |
-| Spanish | 19 | 73 | 13 | 15 | ~500+ |
-| German | 18 | 48 | 8 | 3 | ~300+ |
+| Language | Status | Roots | Explicit Variants | Suffixes | Whitelist | Effective Forms |
+|---|---|---|---|---|---|---|
+| Turkish | Flagship | 25 | 88 | 83 | 52 | ~3,000+ |
+| English | Community | 23 | 106 | 8 | 42 | ~700+ |
+| Spanish | Community | 19 | 73 | 13 | 15 | ~500+ |
+| German | Community | 18 | 48 | 8 | 3 | ~300+ |
 
 "Effective forms" = roots × normalization variants × suffix combinations × evasion patterns. A root like `sik` with 83 possible suffixes, leet decoding, separator tolerance, and repeat collapse produces thousands of detectable surface forms.
 
@@ -317,6 +319,7 @@ const terlik = new Terlik({
   fuzzyAlgorithm: "levenshtein", // "levenshtein" | "dice"
   maxLength: 10000,              // truncate input beyond this
   backgroundWarmup: false,       // compile patterns in background via setTimeout
+  extendDictionary: undefined,   // DictionaryData object to merge with built-in dictionary
 });
 ```
 
@@ -379,6 +382,30 @@ const cache = Terlik.warmup(["tr", "en", "es", "de"]);
 cache.get("en")!.containsProfanity("fuck"); // true — no cold start
 ```
 
+### `extendDictionary` Option
+
+Merge an external dictionary with the built-in one. Useful for teams managing custom word lists without modifying the core package:
+
+```ts
+const terlik = new Terlik({
+  extendDictionary: {
+    version: 1,
+    suffixes: ["ci", "cu"],
+    entries: [
+      { root: "customword", variants: ["cust0mword"], severity: "high", category: "general", suffixable: true },
+    ],
+    whitelist: ["safeterm"],
+  },
+});
+
+terlik.containsProfanity("customword");    // true
+terlik.containsProfanity("customwordci");  // true (suffix match)
+terlik.containsProfanity("safeterm");      // false (whitelisted)
+terlik.containsProfanity("siktir");        // true (built-in still works)
+```
+
+The extension dictionary must follow the same schema as built-in dictionaries. Duplicate roots are skipped; suffixes and whitelist entries are merged. Pattern cache is disabled for extended instances.
+
 ### `terlik.language: string`
 
 Read-only property. Returns the language code of the instance.
@@ -412,7 +439,7 @@ deNormalize("Scheiße"); // "scheisse"
 
 ## Testing
 
-631 tests covering all 4 languages, 25 Turkish root words, suffix detection, lazy compilation, multi-language isolation, normalization, fuzzy matching, cleaning, integration, ReDoS hardening, attack surface coverage, and edge cases:
+874 tests covering all 4 languages, 25 Turkish root words, suffix detection, lazy compilation, multi-language isolation, normalization, fuzzy matching, cleaning, integration, ReDoS hardening, attack surface coverage, external dictionary merging, and edge cases:
 
 ```bash
 pnpm test          # run once
@@ -427,7 +454,7 @@ An interactive browser-based test environment is included. Chat interface on the
 pnpm dev:live      # http://localhost:2026
 ```
 
-See [`live_test_server/README.md`](./live_test_server/README.md) for details.
+See [`tools/README.md`](./tools/README.md) for details.
 
 ### Integration Guide
 
@@ -451,6 +478,25 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines.
 
 ## Changelog
 
+### 2026-02-28 (v2.3.0) — 40x Faster Cold Start: V8 JIT Regex Optimization
+
+**Replaces `\p{L}`/`\p{N}` Unicode property escapes with explicit Latin ranges, eliminating V8 JIT bottleneck.**
+
+- **40x faster cold start** — First `containsProfanity()` call: 16,494ms → 404ms.
+- **356x faster multi-language warmup** — 4-language warmup: 19,234ms → 54ms.
+- **13x less memory** — Heap usage: 492MB → 38MB.
+- **Static pattern cache** — Same-language instances share compiled patterns via `Detector.patternCache`.
+- **Background warmup** — Dev server starts instantly, warms up in background.
+
+| Change | File |
+|---|---|
+| Replace `\p{L}\p{N}` with `[a-zA-Z0-9À-ɏ]` | `src/patterns.ts` |
+| Static pattern cache + explicit range in getSurroundingWord | `src/detector.ts` |
+| Explicit range in number expander + punctuation removal | `src/normalizer.ts` |
+| Pass cacheKey to Detector | `src/terlik.ts` |
+| Background warmup, lazy instance cache | `tools/server.ts` |
+| NODE_OPTIONS heap safety net | `.github/workflows/ci.yml` |
+
 ### 2026-02-28 (v2.2.1) — CI Fix: Timeout Race Condition + İ Platform Compatibility
 
 **Fixes detection failures on slow runners and cross-platform İ (U+0130) handling.**

package/dist/index.d.mts

@@ -1,3 +1,17 @@
+/** 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[];
+}
+
 /** Profanity severity level. */
 type Severity = "high" | "medium" | "low";
 /** Detection mode controlling the balance between precision and recall. */
@@ -45,6 +59,8 @@ interface TerlikOptions {
     replaceMask?: string;
     /** Background'da regex derleme + JIT warmup. Default: false. Serverless'da önerilmez. */
     backgroundWarmup?: boolean;
+    /** External dictionary data to merge with the built-in language dictionary. */
+    extendDictionary?: DictionaryData;
 }
 /** Per-call detection options that override instance defaults. */
 interface DetectOptions {
@@ -226,20 +242,6 @@ declare function levenshteinSimilarity(a: string, b: string): number;
  */
 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;

package/dist/index.d.ts

@@ -1,3 +1,17 @@
+/** 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[];
+}
+
 /** Profanity severity level. */
 type Severity = "high" | "medium" | "low";
 /** Detection mode controlling the balance between precision and recall. */
@@ -45,6 +59,8 @@ interface TerlikOptions {
     replaceMask?: string;
     /** Background'da regex derleme + JIT warmup. Default: false. Serverless'da önerilmez. */
     backgroundWarmup?: boolean;
+    /** External dictionary data to merge with the built-in language dictionary. */
+    extendDictionary?: DictionaryData;
 }
 /** Per-call detection options that override instance defaults. */
 interface DetectOptions {
@@ -226,20 +242,6 @@ declare function levenshteinSimilarity(a: string, b: string): number;
  */
 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;