diff --git a/README.md b/README.md new file mode 100644 index 0000000..e59c599 --- /dev/null +++ b/README.md @@ -0,0 +1,95 @@ +# Family Friendly + +Family Friendly is an advanced NPM package designed to offer developers an efficient way to filter profanity across multiple languages in their applications. This package now includes enhanced functionality with the ability to detect and mask profanity by considering common obfuscations and character substitutions that users might employ to bypass filters. With support for multiple languages including English, Arabic, Chinese, French, German, Indonesian, Italian, and Spanish, Family Friendly stands as a comprehensive solution for maintaining a respectful communication environment in your digital space. + +## Features + +- **Multi-language Support**: Filters profanity in English, Arabic, Chinese, French, German, Indonesian, Italian, and Spanish. +- **Customization**: Choose to include or exclude specific languages based on your application's user base. +- **Advanced Detection**: Recognizes common character substitutions and obfuscations in profanity. +- **Dynamic Word List Management**: Add or remove words from the filter list at runtime. +- **Flexible Profanity Handling**: Detect, mask, or replace profanity within strings. + +## Installation + +Ensure you have Node.js and npm installed, then run the following command in your project's root directory: + +```bash +npm install family-friendly +``` + +## Usage + +### Importing + +Start by importing the `FamilyFriendly` class: + +```javascript +import { FamilyFriendly } from "family-friendly"; +``` + +### Configuration + +Instantiate `FamilyFriendly` with specific language options or use default settings to filter all supported languages: + +```javascript +const familyFriendly = new FamilyFriendly({ + includeEnglish: true, // Include English + includeSpanish: true, // Include Spanish + // Additional languages as needed +}); +``` + +To filter all supported languages: + +```javascript +const familyFriendlyAll = new FamilyFriendly({ allLanguages: true }); +// or with no parameters for the same effect +const familyFriendlyDefault = new FamilyFriendly(); +``` + +### Detecting Profanity + +Check if a string contains profanity: + +```javascript +const hasProfanity = familyFriendly.containsBadWord("Check this text"); +console.log(hasProfanity ? "Profanity found!" : "Clean text."); +``` + +### Masking Profanity + +Mask profanity in a string, with optional custom masking character: + +```javascript +const maskedText = familyFriendly.maskBadWords("Some text to cleanse", "*"); +console.log(maskedText); +``` + +### Replacing Profanity + +Replace profanity in a string with a specified phrase: + +```javascript +const cleanText = familyFriendly.replaceBadWords( + "Text with profanity", + "[REMOVED]" +); +console.log(cleanText); +``` + +### Managing Word List + +Add or remove words from the filter: + +```javascript +// Adding words +familyFriendly.addWords(["newbadword"]); + +// Removing words +familyFriendly.removeWords(["notsobad"]); +``` + +## Support and Contribution + +For support, questions, or contributions, feel free to open an issue or pull request on the GitHub repository associated with this package. diff --git a/package.json b/package.json index 97b9ad7..25f56d2 100644 --- a/package.json +++ b/package.json @@ -1,21 +1,20 @@ { "name": "family-friendly", - "version": "0.1.1", - "description": "Detect or mask out, bad words in a string", + "version": "0.4.1", + "description": "Detect, replace, or mask out bad words in a string", "main": "dist/FamilyFriendly.js", "repository": { "type": "git", "url": "https://github.com/nightness/family-friendly" }, "scripts": { - "deploy": "yarn clean && yarn build && npm publish", - "build": "babel src --out-dir dist --extensions '.ts,.tsx' && tsc --emitDeclarationOnly", - "start": "node dist/FamilyFriendly.js", + "deploy": "yarn clean && yarn build && npm publish --access public", + "build": "yarn clean && babel src --out-dir dist --extensions '.ts,.tsx' && tsc --emitDeclarationOnly", + "start": "yarn build && node dist/FamilyFriendly.js", "dev": "nodemon src/FamilyFriendly.ts", "test": "echo 'Skipping tests'", "test:watch": "jest --watch", - "lint": "eslint . --ext .ts", - "lint:fix": "eslint . --ext .ts --fix", + "lint": "eslint . --ext .ts --fix", "clean": "rm -rf dist", "prepublishOnly": "npm run lint && npm run test && npm run build", "format": "prettier --write \"**/*.{js,ts,json}\"" diff --git a/src/FamilyFriendly.ts b/src/FamilyFriendly.ts index 8114c94..7b94e3f 100644 --- a/src/FamilyFriendly.ts +++ b/src/FamilyFriendly.ts @@ -23,9 +23,13 @@ export interface FamilyFriendlyOptions { // This class is used to detect or mask out, bad words in a string export class FamilyFriendly { // The list of bad words - private badWords: string[] = []; + private badWords: string[]; + private badWordPatterns: RegExp[]; constructor(options?: FamilyFriendlyOptions) { + this.badWords = []; + this.badWordPatterns = []; + const allFalse = options && !options.includeEnglish && @@ -92,7 +96,62 @@ export class FamilyFriendly { allWords.push(...badSpanishWords); } + // Derive bad words from the existing bad words, removing duplicate letters in a word + const derivedWords: string[] = []; + for (const word of allWords) { + const letters = word.split(""); + const uniqueLetters = letters.filter( + (letter, index) => letters.indexOf(letter) === index + ); + const stubWord = uniqueLetters.join(""); + + // No duplicate letters + if (allWords.includes(stubWord)) continue; + + // Add the stub word to the list of derived words + derivedWords.push(stubWord); + } + + // Add the derived words to the list of all words + allWords.push(...derivedWords); + + // Flatten the array of bad words and create regex patterns this.badWords = allWords.sort((a, b) => b.length - a.length); + this.badWordPatterns = this.badWords.map( + (word) => new RegExp(this.createRegexPattern(word), "gi") + ); + } + + private createRegexPattern(word: string): string { + const escapeRegExp = (string: string) => + string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + + // Define substitutions + const substitutions: { [key: string]: string } = { + a: "[a@4]", + e: "[e3]", + i: "[i1!]", + o: "[o0]", + s: "[s$5]", + t: "[t7]", + b: "[b8]", + g: "[g6]", + l: "[l1]", + q: "[q9]", + z: "[z2]", + }; + + // Replace each character with its substitutions (if any) + const pattern = word + .split("") + .map((char) => { + const sub = substitutions[char.toLowerCase()]; + return sub ? sub : escapeRegExp(char); + }) + .join(""); + + // Return the pattern with word boundaries + return `\\b${pattern}\\b`; } // Returns true if the string contains a bad word @@ -106,10 +165,56 @@ export class FamilyFriendly { } // Returns a string with bad words masked out - public maskBadWords(str: string, maskAs: string = "🤡"): string { + public maskBadWords(str: string, maskAs: string = "*"): string { for (const badWord of this.badWords) { - str = str.replaceAll(badWord, maskAs.repeat(badWord.length)); + str = str.replace( + new RegExp(this.createRegexPattern(badWord), "gi"), + maskAs.repeat(badWord.length) + ); } return str; } + + // Like maskBadWords, but replaces the bad word with the provided replacement + public replaceBadWords( + str: string, + replacementWordForABadWord: string = "[CENSORED]" + ): string { + for (const badWord of this.badWords) { + str = str.replace( + new RegExp(this.createRegexPattern(badWord), "gi"), + replacementWordForABadWord + ); + } + return str; + } + + public addWords(words: string[]): void { + words.forEach((word) => { + this.badWords.push(word); + this.badWordPatterns.push( + new RegExp(this.createRegexPattern(word), "gi") + ); + }); + } + + public removeWords(words: string[]): void { + words.forEach((word) => { + const index = this.badWords.indexOf(word); + if (index > -1) { + this.badWords.splice(index, 1); + this.badWordPatterns.splice(index, 1); + } + }); + } } + +/* +const familyFriendly = new FamilyFriendly(); + +const testString = "Don't be an ash0le ashole assh0le asshole"; +console.log("Original:", testString); +console.log("Masked:", familyFriendly.maskBadWords(testString)); +console.log("Contains bad word:", familyFriendly.containsBadWord(testString)); +console.log("Replaced:", familyFriendly.replaceBadWords(testString)); +*/