Text Profanity (text-validation)

Một thư viện gọn nhẹ và cực kỳ mạnh mẽ dùng để kiểm tra, lọc và che (mask) các từ khóa nhạy cảm, từ chửi thề (Profanity/Bad words) trong văn bản.

Đặc biệt, hệ thống được thiết kế với Hệ thống Chống lách luật (Anti-Bypass) toàn diện nhất, có thể chặn đứng gần như 100% các thủ thuật biến tấu qua mặt chữ của người dùng trên nhiều ngôn ngữ (Vietnamese, English, Japanese).

🌟 Tính năng Nổi bật

Thư viện không chỉ đơn thuần khớp chuỗi (string matching) mà còn tích hợp bộ lọc AI-like để bóc tách các thủ thuật "teencode" và lách luật của người dùng:

• Bỏ qua Ký tự Gây nhiễu (Noise & Punctuation): Dấu chấm, phẩy, khoảng trắng, hoặc ký tự đặc biệt chèn giữa từ đều bị vô hiệu hoá. Ví dụ: v.c.l, đ_m, c@o -> Bị chặn.
• Rút gọn Ký tự Lặp lại (Repeating Chars): Tự động phát hiện và thu gọn các chữ cái cố tình viết lặp dài. Ví dụ: nguuuuuu, đmmmm -> Khớp với ngu, đm.
• Dịch Leetspeak / Teencode: Convert các số hoặc ký tự biến tấu về mặt chữ gốc. (vd: 3 -> e, @/4 -> a, 1/! -> i, 0 -> o). Ví dụ: ch3t, d!t -> Bị chặn.
• Bắt không dấu tự động (Unaccented Matching): Bất cứ từ tiếng Việt nào đưa vào từ điển đều tự động sinh ra một dạng "không dấu". (vd: ngu vai, d m sẽ match với ngu vãi, đ m).
• Chuẩn hóa Zalgo / Extended Latin: Các ký tự vay mượn trông nguy hiểm như nğü, vãį sẽ bị lột trần về ngu, vai.
• Xử lý siêu cấp Tiếng Nhật (Japanese Armor):
  • Gộp Katakana và Hiragana thành một (E.g: シネ -> しね).
  • Gộp các dấu âm đục (Dakuon) bị tách rời hoặc chữ Half-width (E.g: ハ゛カ, ﾊﾞｶ -> ばか).
  • Lọc dấu kéo dài âm (Long Vowels) cực chuẩn (E.g: シーーーネ -> しね).

📦 Cài đặt

(Đang cập nhật NPM) Hiện tại, build và import thông qua thư mục dist/src:

npm install
npm run build

🚀 Hướng dẫn Sử dụng

Khởi tạo một WordFilter và chỉ định các bộ ngôn ngữ bạn muốn sử dụng (hệ thống có sẵn data cho vi, en, ja).

import { WordFilter } from "text-profanity";

// Khởi tạo filter (mặc định lấy ngôn ngữ "vi" nếu không truyền param)
const filter = new WordFilter({ 
    languages: ["vi", "en", "ja"], 
    placeholder: "*" // Ký tự dùng để mask (mặc định là *)
});

// 1. Kiểm tra văn bản có chứa từ bậy hay không
console.log(filter.hasBadWord("v.c.l")); // Trả về: true
console.log(filter.hasBadWord("Hôm nay thời tiết đẹp quá")); // Trả về: false

// 2. Che (Mask) từ bậy trong văn bản (giữ nguyên độ dài và định dạng)
const safeText = filter.mask("đ!!!t... mmmẹẹẹẹẹ mày là thằng chhhhóoooo"); 
console.log(safeText); 
// Kết quả: "*****... mmmẹẹẹẹẹ mày là thằng *********"

// 3. Nạp thêm từ khóa nhạy cảm tùy chỉnh của hệ thống bạn
filter.addBadWords(["trường học lừa đảo", "đa cấp", "scam"]);
console.log(filter.mask("Cái trung tâm này là scam, trường học lừa đảo!"));
// Kết quả: "Cái trung tâm này là ****, ******************!"

🧠 Sức mạnh Chống Cố Tình Lách Luật

Xem các ví dụ dới đây để thấy thư viện có thể trị các thủ thuật phức tạp như thế nào:

// 1. Chia tách / Ngắt dòng (Splitting)
filter.hasBadWord("n\ng\nu"); // true

// 2. Teencode / Ký tự thay thế
filter.hasBadWord("ngu l0n"); // true (0 -> o)

// 3. Tiếng Nhật đổi bảng chữ cái và ký hiệu
filter.hasBadWord("ハ゛カ"); // true (Match với "ばか" - Đồ ngốc)

// 4. Mã hoá chữ cái Latin
filter.hasBadWord("nğü"); // true (Match với "ngu")

📝 Phát triển (Development)

Thư viện sử dụng TypeScript và Jest chuẩn cho Testing.

# Compiler / Watch script
npm run dev

# Chạy test suite (đã cover 100% các bypass scenarios)
npm run test