API

All functions accept string | null | undefined. Empty or missing text is treated as clean (contains → false, mask → "").

import {
  contains,
  mask,
  inspect,
  explain,
  createFilter,
  blockedError,
  PROFANITY_BLOCKED,
  WORDLIST_STATS,
  VERSION,
} from "anti-ttyah";

contains(text)

true if any listed term or phrase matches after normalization.

mask(text)

Replace each hit with the mask character. Default style preserves hit length (****). Surrounding text is unchanged.

inspect(text)

type Hit = {
  start: number;
  end: number;
  raw: string;
  lang?: "ar" | "ar-latn" | "fr" | "en" | "tz";
  category?: "sexual" | "insult" | "slur" | "mild";
};

type InspectResult = { blocked: boolean; hits: Hit[] };

Offsets refer to the original string.

explain(text)

Like inspect, plus one row per token:

type ExplainToken = {
  raw: string;
  start: number;
  end: number;
  keys: string[];
  matched: boolean;
  lang?: Hit["lang"];
  category?: Hit["category"];
};

Used by the playground trace and npx anti-ttyah --explain.

blockedError(...fields)

Scan strings, string arrays, or shallow objects ({ title, body }). Returns { error: "PROFANITY_BLOCKED" } on the first hit, otherwise null. Constant: PROFANITY_BLOCKED.

createFilter(options)

Returns a { contains, mask, inspect, explain, blockedError } instance.

Option	Default	Role
extraTerms	[]	Extra tokens (spaces become phrases)
extraPhrases	[]	Extra multi-word phrases
allowlist	[]	Never match these tokens/phrases
maskChar	"*"	First character only
maskStyle	"preserve"	"token" → three mask chars per hit
matchSeparators	true	Fold . * - _ ' inside tokens
categories	all	Restrict the default list; extras still apply

Normalization helpers

normalizeLatin, normalizeArabic, tokenKeys, stripSeparators are exported for tooling. Prefer explain unless you are building your own matcher.

Aliases

containsProfanity → contains, maskProfanity → mask, profanityError → blockedError.

isTermCategory(value) is a type guard for CLI / config parsing.

Wordlist exports

PROFANITY_TERMS, PROFANITY_PHRASES (string[]), PROFANITY_TERM_ENTRIES, PROFANITY_PHRASE_ENTRIES, WORDLIST_STATS, TERM_LANGS, TERM_CATEGORIES.