Detector API

Import from profanity-kit for bundled English, or from profanity-kit/core to select language packs. Both return an immutable ProfanityDetector.

createDetector() from profanity-kit

Creates a detector with the English pack already configured.

Signature

function createDetector(options?: DetectorOptions): ProfanityDetector<"en">;

Parameters

Returns

An immutable ProfanityDetector<"en">.

Throws

Throws ProfanityKitError for invalid dictionary entries or a replacement that is not exactly one Unicode code point.

Example

import { createDetector } from "profanity-kit";

const detector = createDetector();
detector.check("that is shit"); // => true
detector.isClean("that is fine"); // => true
detector.filter("that is shit"); // => "that is ****"

createDetector() from profanity-kit/core

Creates a detector from explicit language packs. Core contains no built-in dictionary, so unused language data can stay out of the bundle.

Signature

function createDetector<const TLanguages extends readonly LanguagePack[]>(
  options: LanguageDetectorOptions<TLanguages>
): ProfanityDetector<LanguageCodeOf<TLanguages[number]>>;

Parameters

Returns

An immutable detector whose language union is inferred from the packs. For example, [english, indonesian] yields ProfanityDetector<"en" | "id">.

Throws

Throws ProfanityKitError when:

• languages is missing, not an array, or empty.
• A pack, locale, or dictionary word is invalid.
• A blocklist or allowlist entry is not a non-empty string.
• replacement is not exactly one Unicode code point.

Example

import { createDetector } from "profanity-kit/core";
import { indonesian } from "profanity-kit/languages/id";

const detector = createDetector({ languages: [indonesian] });
detector.check("dasar goblok"); // => true
detector.filter("dasar goblok"); // => "dasar ******"

check()

Stops at the first whole-word match.

Signature

check(input: string): boolean;

Parameters

Returns

true when at least one match exists; otherwise false.

Throws

Throws TypeError at runtime when input is not a string.

Example

detector.check("what the shit"); // => true
detector.check("ship the update"); // => false

isClean()

The readable inverse of check(). It is callback-safe.

Signature

isClean(input: string): boolean;

Parameters

Returns

true when no match exists; otherwise false.

Throws

Throws TypeError at runtime when input is not a string.

Example

detector.isClean("ready to publish"); // => true
detector.isClean("what the shit"); // => false
const publishable = comments.filter(detector.isClean);

findAll()

Returns every match, including repetitions, in source order.

Signature

findAll(input: string): ProfanityMatch<TLanguage>[];

Parameters

Returns

An array of ProfanityMatch objects, or [] when nothing matches.

Throws

Throws TypeError at runtime when input is not a string.

Example

const matches = detector.findAll("shit, shit!");

Output

[
  {
    value: "shit",
    normalized: "shit",
    start: 0,
    end: 4,
    languages: ["en"],
    source: "dictionary",
  },
  {
    value: "shit",
    normalized: "shit",
    start: 6,
    end: 10,
    languages: ["en"],
    source: "dictionary",
  },
];

filter()

Replaces matches while preserving punctuation, whitespace, and unmatched text.

Signature

filter(input: string, options?: FilterOptions): string;

Parameters

options

Returns

A filtered string, or the unchanged input when there are no matches.

Throws

• TypeError when input is not a string.
• ProfanityKitError with INVALID_REPLACEMENT for an invalid per-call replacement.

Example

const detector = createDetector({ replacement: "•" });
detector.filter("hide this shit"); // => "hide this ••••"
detector.filter("hide this shit", { replacement: "😀" });
// => "hide this 😀😀😀😀"