safe_text 3.0.2

safe_text: ^3.0.2 copied to clipboard

A high-performance pure Dart package for filtering offensive language (profanity) and detecting phone numbers. Powered by the Aho-Corasick algorithm for O(N) single-pass scanning across 80+ languages and 55,000+ curated words.

💙 Find SafeText useful? A like on pub.flutter-io.cn or star on GitHub helps others discover it.

Table of Contents #

• Table of Contents
• Features
• Installation
• Quick Start
• API Reference
  • SafeTextFilter.init
  • SafeTextFilter.isInitialized & SafeTextFilter.reset
  • SafeTextFilter.filterText
  • SafeTextFilter.containsBadWord
  • PhoneNumberChecker.containsPhoneNumber
• Supported Languages
• How it Works
• Migrating from v1.x
• Limitations
• Contributing
• Data Source
• Authors
• Contributors

Features #

• Scans thousands of bad words in a single pass of the input text.
• Catches common character substitutions: @→a, 4→a, 3→e, 0→o, $→s, and more.
• Detects phone numbers in digits, words, mixed formats, and multiplier words (e.g., "triple five").
• Multiple masking strategies — full (******), partial (f**k), or custom replacement ([censored]).
• Customizable — add your own words or exclude specific phrases.
• No setup required — lazily auto-initializes with the full Language.english word list (~13k words) on first use; init is optional.
• Non-blocking — PhoneNumberChecker runs in a separate isolate via Isolate.run.
• Works on Android, iOS, Web, macOS, Linux, and Windows.

Installation #

Add safe_text to your project using the Dart CLI:

dart pub add safe_text

Or manually add it to your pubspec.yaml:

dependencies:
  safe_text: ^3.0.0

Then run:

dart pub get

Quick Start #

import 'package:safe_text/safe_text.dart';

void main() async {
  // Optional: initialize once at app startup with a specific language.
  // If you skip this, the filter lazily auto-initializes with the full
  // Language.english word list (lib/data/en.dart, ~13k words) on first use —
  // not the small legacy constants/badwords.dart list from v1.x/v2.x.
  SafeTextFilter.init(language: Language.english);

  // Filter profanity (full masking — default)
  final clean = SafeTextFilter.filterText(text: "What the f@ck!");
  print(clean); // "What the ****!"

  // Partial masking — keeps first & last characters for 4+ letter words
  final partial = SafeTextFilter.filterText(
    text: "What the f@ck!",
    strategy: const MaskStrategy.partial(),
  );
  print(partial); // "What the f**k!"

  // Custom replacement
  final custom = SafeTextFilter.filterText(
    text: "What the f@ck!",
    strategy: const MaskStrategy.custom(replacement: '[censored]'),
  );
  print(custom); // "What the [censored]!"

  // Check for bad words
  final hasBad = SafeTextFilter.containsBadWord(text: "Some bad input");
  print(hasBad); // true or false

  // Detect phone numbers
  final hasPhone = await PhoneNumberChecker.containsPhoneNumber(
    text: "Call me at nine 7 eight 3 triple four",
  );
  print(hasPhone); // true
}

API Reference #

SafeTextFilter.init #

Optional. Builds the Aho-Corasick trie from the selected word list(s). If you never call it, the filter lazily auto-initializes with Language.english (lib/data/en.dart, ~13k words) on first use of filterText / containsBadWord. Call it explicitly when you want a specific language or combination.

Upgrading from v2.x? In 2.x, an app that never called init fell back to the small legacy list in constants/badwords.dart (~1.7k words). As of 3.0.0, an uninitialized filter now lazily loads the full Language.english list instead — a much larger, different word list. If your app relied on the old, smaller list (e.g. "adult" was previously not flagged), see below for how to opt back into it.

// Single language
SafeTextFilter.init(language: Language.english);

// Custom combination
SafeTextFilter.init(languages: [Language.english, Language.hindi, Language.spanish]);

// All 75+ languages
SafeTextFilter.init(language: Language.all);

Note: If neither parameter is provided, the filter defaults to Language.english.

SafeTextFilter.isInitialized & SafeTextFilter.reset #

Check initialization status or reset loaded word lists dynamically (e.g., when switching languages). Because init auto-initializes on first use, you generally don't need to guard calls with isInitialized — but it's available if you want to check, and reset() lets you reload with a different language:

// Reset state to reload with a different language
SafeTextFilter.reset();
SafeTextFilter.init(language: Language.spanish);

SafeTextFilter.filterText #

Synchronous. Returns the input text with matched bad words masked according to the chosen MaskStrategy.

// Full masking (default)
String result = SafeTextFilter.filterText(
  text: "Hello b4dass world!",
  extraWords: ["badterm"],      // optional: add custom words
  excludedWords: ["bass"],      // optional: never filter these
  useDefaultWords: true,        // use the built-in word list
);
// Result: "Hello ****** world!"

// Partial masking
String partial = SafeTextFilter.filterText(
  text: "Hello b4dass world!",
  strategy: const MaskStrategy.partial(),
);
// Result: "Hello b****s world!"

// Custom replacement
String custom = SafeTextFilter.filterText(
  text: "Hello b4dass world!",
  strategy: const MaskStrategy.custom(), // defaults to "[censored]"
);
// Result: "Hello [censored] world!"

Precedence: When strategy is provided, it takes full precedence over the deprecated fullMode and obscureSymbol parameters. When strategy is omitted, fullMode: true maps to MaskStrategy.full(obscureSymbol: obscureSymbol) and fullMode: false maps to MaskStrategy.partial(obscureSymbol: obscureSymbol).

Masking Strategies

Note: obscureSymbol must be exactly one character. This is enforced via assert in debug mode — a multi-character string will trigger an AssertionError during development.

SafeTextFilter.containsBadWord #

Asynchronous. Returns true if the text contains at least one filtered word.

bool hasBadWord = SafeTextFilter.containsBadWord(
  text: "Don't be a pendejo",
  extraWords: ["badterm"],   // optional
  excludedWords: ["pend"],   // optional
  useDefaultWords: true,     // optional
);

Keeping the legacy word list

If your app depends on the smaller v1.x/v2.x fallback list (constants/badwords.dart, ~1.7k words) instead of the full Language.english list (~13k words) that 3.0.0 lazily auto-initializes with, opt out of the default list and pass the legacy one in explicitly:

import 'package:safe_text/constants/badwords.dart';

bool hasBadWord = SafeTextFilter.containsBadWord(
  text: text,
  useDefaultWords: false,
  extraWords: badWords, // the legacy list from constants/badwords.dart
);

PhoneNumberChecker.containsPhoneNumber #

Asynchronous. Runs in a separate isolate via Dart's Isolate.run so it never blocks the calling thread.

Detects phone numbers expressed as:

• Pure digits: 9783444
• Word-based: nine seven eight three four four four
• Mixed: 9 seven 8 3444
• Multiplier words: nine seven eight three triple four

Supported multiplier words: double, triple, quadruple, quintuple, sextuple, septuple, octuple, nonuple, decuple.

bool hasPhone = await PhoneNumberChecker.containsPhoneNumber(
  text: "Call me at nine 7 eight 3 triple four",
  minLength: 7,   // minimum digit count to be considered a phone number
  maxLength: 15,  // maximum digit count
);

Supported Languages #

Pass any of these Language enum values to SafeTextFilter.init. Use Language.all to load every language simultaneously.

How it Works #

Legacy approach (v1.x): For each bad word in a list of 10,000+ words, run a separate regex scan over the entire input — O(W × N) where W is the word count.

v2.0.0 approach: The Aho-Corasick algorithm builds a Finite State Automaton (Trie) once from the entire word list. The engine then scans the input exactly once, matching all patterns simultaneously in O(N) time where N is the length of the text — regardless of how many words are in the list.

Input text  ──► [Normalizer] ──► [Aho-Corasick FSA] ──► Match ranges ──► [StringBuffer] ──► Filtered text
                  (leet-speak)     (single O(N) pass)    (merged)         (single-pass)

Migrating from v1.x #

The original SafeText class is still available but marked @Deprecated. It internally delegates to the new classes. Migrate when ready:

Before:

// v1.x — no init required, but slow
bool bad = await SafeText.containsBadWord(text: "some input");

After:

// v2.0.0 — init once, then use anywhere
SafeTextFilter.init(language: Language.english); // once, e.g. in main()
bool bad = SafeTextFilter.containsBadWord(text: "some input");

3.0.0 changed this again: init became fully optional. If you never call it, the filter now lazily auto-initializes with the full Language.english list (~13k words) — not the small legacy list above. See Keeping the legacy word list if you're upgrading from 2.x and relied on the smaller fallback.

Limitations #

• Skipping init is not behavior-preserving across major versions. An uninitialized filter now lazily loads the full Language.english list (~13k words); in 2.x, an uninitialized filter fell back to the small legacy constants/badwords.dart list (~1.7k words) instead. If you're upgrading from 2.x, see Keeping the legacy word list.
• Phone number detection is English-word based. Words like "nine", "triple", etc. are English only — the detector does not parse written numbers in other languages.
• False positives on technical terms. Short words in the filter list may match substrings of unrelated technical terms. Use excludedWords to suppress known false positives.

Contributing #

Contributions are welcome! Please read CONTRIBUTING.md for the full guidelines. The short version:

1. Clone the repo and check out the develop branch.
2. Create a feature branch: git checkout -b feature/your-feature
3. Add tests for any new behaviour.
4. Run checks before submitting:

   dart analyze
   dart test
   

5. Open a pull request targeting develop. Ensure CI passes.

For major changes, please open an issue first to discuss the approach.

Data Source #

SafeText uses the List of Dirty, Naughty, Obscene, and Otherwise Bad Words dataset:

• 80+ dialects and languages
• 55,000+ curated words

We are grateful to the contributors of this dataset for providing a robust multilingual foundation.

Authors #

_{Ronit Rameja}

LinkedIn • Report an Issue • Discussions • Buy me a coffee

Contributors #

Thanks to everyone who has contributed to SafeText!

Made with contrib.rocks