Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

bad-words-next

alexzel9.3kMIT3.1.1TypeScript support: included

JavaScript/TypeScript filter and checker for bad words aka profanity

curse, swear, words, profanity, filter, checker, badwords, detect, sanitize

readme

bad-words-next

workflows-nodejs-ci npm version NPM license npm bundle size npm downloads

JavaScript/TypeScript filter and checker for bad words aka profanity.

API documentation in GitHub Wiki.

NOTE: we don't supply with raw json data files in version >= 3.0.0. See the example below to update paths in your import or require statements.

Install

yarn add bad-words-next

or

npm install bad-words-next

Basic usage

const BadWordsNext = require('bad-words-next')
const en = require('bad-words-next/lib/en')

const badwords = new BadWordsNext({ data: en })

// Returns true when passed string contains a bad word
console.log(badwords.check('S0me sh!++ is here'))
// will print `true`

// Returns filtered string with masked bad words
console.log(badwords.filter('S0me sh!++ is here'))
// will print `S0me *** is here`

// Returns filtered string and catches bad words
badwords.filter('S0me sh!++ is here', badword => {
  console.log(badword)
})
// will print `sh!++`

// Use exclusions
const badwords = new BadWordsNext({ data: en, exclusions: ['sh+it+' /*works with lookalikes or the actual words*/] })
console.log(badwords.filter('S0me sh!++ is here'))
// will keep the `sh!++` word

Add more dictionaries

const BadWordsNext = require('bad-words-next')

const en = require('bad-words-next/lib/en')
const es = require('bad-words-next/lib/es')
const fr = require('bad-words-next/lib/fr')
const de = require('bad-words-next/lib/de')
const ru = require('bad-words-next/lib/ru')
const rl = require('bad-words-next/lib/ru_lat')
const ua = require('bad-words-next/lib/ua')
const pl = require('bad-words-next/lib/pl')
const ch = require('bad-words-next/lib/ch')

const badwords = new BadWordsNext()
badwords.add(en)
badwords.add(es)
badwords.add(fr)
badwords.add(de)
badwords.add(ru)
badwords.add(rl)
badwords.add(ua)
badwords.add(pl)
badwords.add(ch)

Dictionary data format

interface Data {
  id: string  // Unique dictionary ID
  words: string[] // Words list
  lookalike: Lookalike // Lookalike homoglyphs map
}

type Lookalike = Record<string | number, string> // Simple key-value object

You can use the following pattern characters in a word string:

  • * indicates any characters, use it only on start and/or end of a word
  • + indicates one or more repeating characters
  • _ indicates special characters

Here is an example of a typical data object:

{
  "id": "en",
  "words": [
    "any",      // just a word
    "ba+d*",    // word `bad` with repeating `a` and anything after `d`
    "*words*",  // word `words` with anything at start and end of it
    "are_here"  // word `are_here` with pseudo space chars between `r` and `h`
  ],
  "lookalike": {
    "@": "a",
    "1": "i"
  }
}

Options

interface Options {
  data?: Data // Dictionary data
  placeholder?: string // Filter placeholder - default '***'
  placeholderMode?: 'repeat' | 'replace' // Placeholder mode to either replace with or repeat the placeholder - default 'replace'
  specialChars?: RegExp // Special chars to allow on start and/or end of a word - default /\d|[!@#$%^&*()[\];:'",.?\-_=+~`|]|a|(?:the)|(?:el)|(?:la)/
  spaceChars?: string[] // Pseudo space chars, a list of values for `_` symbol in a dictionary word string - default ['', '.', '-', ';', '|']
  confusables?: string[] // List of ids to apply transformations from `confusables` npm package - default ['en', 'es', 'de', 'ru_lat']
  maxCacheSize?: number // Max items to store in cache - default 100
  exclusions?: string[] // The list of exclusions
}

See Options API for more details.

Notes

  • Dictionary words with spaces won't work b/c they do not represent a single word

  • Dictionaries have to be improved over time

changelog

Changelog

3.1.1 (2024-12-26)

Bug Fixes

  • improve regexp into internal string convertion (04b3b16)
  • trim dictionary words and replace spaces with pseudo space chars (ef7d437)

3.1.0 (2024-12-24)

Features

3.0.0 (2024-12-13)

⚠ BREAKING CHANGES

  • remove json files and encode dictionaries b/c of sensitivity

Features

  • remove json files and encode dictionaries b/c of sensitivity (e7a4758)
  • use decoder in benchmarks (e650dea)

Bug Fixes

  • add rollup cache to .gitignore file (95d1d51)
  • fix dictionary data import in benchmark script (c6f50ae)
  • fix some types and props visibility for docs wiki (9b8bc8f)
  • remove resolveJsonModule from typescript config (65278e1)

2.3.2 (2024-12-11)

Bug Fixes

  • update libs usage to their latest interfaces (d96238b)
  • update lookalikes in en.json to treat 3 as E (#19) (6f78bbd)

2.3.1 (2024-04-07)

Bug Fixes

  • add build command into benchmarks readme file (42d84f7)
  • use lookalike instead of the actual bad word in the readme (71668ae)

2.3.0 (2024-04-07)

Features

  • a test for exclusions (6efc106)
  • ability to add exclusions (97c08b9)
  • example how to use exclusions (5893721)

Bug Fixes

  • compile exclusions regexps only once (8184425)
  • improve exclusions performance by employing internal cache (b798d8a)
  • readme example was fixed (09dcf02)

2.2.1 (2023-06-21)

Performance Improvements

  • move string comparison out of map (99bc141)

2.2.0 (2023-06-21)

Features

  • implement placeholderMode to address the feature request (5aa1b76)

2.1.0 (2023-06-04)

Features

  • data: improve en.json dictionary (98d0d11)
  • data: improve ru.json and ru_lat.json dictionaries (71c19b4)

2.0.1 (2023-06-02)

Bug Fixes

  • fix typedoc missing plugins (a85a9ee)

2.0.0 (2023-06-02)

⚠ BREAKING CHANGES

  • convert benchmark to esm
  • fix rollup build
  • fix ts warnings and use different types
  • convert package to esm and bump latest dependencies

Features

  • convert package to esm and bump latest dependencies (479824a)

Bug Fixes

  • convert benchmark to esm (28ea0f3)
  • fix rollup build (d73190e)
  • fix ts warnings and use different types (1044011)

1.6.8 (2023-06-02)

Features

  • data: update dictionaries (62fe324)

Miscellaneous Chores

1.6.7 (2023-04-03)

Features

  • data: update dictionaries (f685c6e)

Miscellaneous Chores

1.6.6 (2023-04-03)

Bug Fixes

  • remove wiki workflow badge (6625662)

1.6.5 (2023-04-03)

Bug Fixes

  • add missing prepare husky script (dc40aa0)

1.6.4 (2023-04-03)

Bug Fixes

1.6.3 (2023-04-03)

Bug Fixes

1.6.2 (2023-04-03)

Bug Fixes

1.6.1 (2023-04-03)

Miscellaneous Chores

1.6.0 (2023-04-03)

Features

  • added optional onBadword callback to the filter method (0065215)