@antistatique/blaspjs

TypeScript / JavaScript library that ports the language-agnostic core of Blaspsoft Blasp v4: driver-based profanity detection, severity scoring, masking, and multi-language dictionaries (English, Spanish, German, French). It is intended for Node.js and bundlers (ESM); the build targets modern browsers as well.

Blasp itself is a Laravel package; this project does not ship Laravel integration. Use it in Express, Nest, Remix, serverless handlers, or any TS/JS runtime.

Installation

npm install @antistatique/blaspjs
# or
bun add @antistatique/blaspjs

Peer dependency: TypeScript ^5.0 (optional if you consume only JavaScript).

Quick start

import { Blasp, Severity } from '@antistatique/blaspjs';

const blasp = new Blasp();

const result = blasp.check('This is a fucking sentence');

result.isOffensive(); // true
result.clean(); // masked text (e.g. asterisks)
result.original(); // unchanged input
result.score(); // 0–100
result.count(); // number of matches
result.uniqueWords(); // unique dictionary bases
result.severity(); // highest SeverityLevel in matches, or null

A default instance is also exported as blasp (same defaults as new Blasp()).

Fluent API

Blasp mirrors the PHP PendingCheck surface: chain options, then call check(text) or checkMany(...).

Languages

blasp.in('spanish').check(text);
blasp.in('english', 'french').check(text);
blasp.inAllLanguages().check(text);

blasp.english().check(text);
blasp.spanish().check(text);
blasp.german().check(text);
blasp.french().check(text);

Drivers

blasp.driver('regex').check(text); // default; obfuscation, substitutions, separators
blasp.driver('pattern').check(text); // fast word-boundary exact match
blasp.driver('phonetic').check(text); // metaphone + Levenshtein (English-oriented)
blasp.driver('pipeline').check(text); // uses config `drivers.pipeline.drivers`

blasp.pipeline('regex', 'phonetic').check(text);

Modes

blasp.lenient().check(text); // forces the `pattern` driver (same as PHP)
blasp.strict().check(text); // clears lenient mode; included in the result cache key like PHP

Masking

blasp.mask('*').check(text);
blasp.mask('#').check(text);
blasp.mask('grawlix').check(text); // !@#$% rotation
blasp.mask((word, len) => '[CENSORED]').check(text);

Callback masks disable result caching (same idea as PHP: closures are not serializable).

Severity and lists

import { Severity } from '@antistatique/blaspjs';

blasp.withSeverity(Severity.High).check(text); // drops milder matches before masking

blasp.allow('damn', 'hell').check(text);
blasp.block('customword').check(text);

Batch

blasp.checkMany(['one', 'two']); // Result[]
blasp.checkMany({ a: 'x', b: 'y' }); // Record<string, Result>

Custom drivers

import type { Driver } from '@antistatique/blaspjs';

const myDriver: Driver = {
  detect(text, dictionary, mask, options) {
    /* return a Result */
  },
};

blasp.extend('my-driver', () => myDriver);
blasp.driver('my-driver').check(text);

Result

| Method | Returns | Description | | ---------------- | -------------------- | ------------------------------------ | | isOffensive() | boolean | Any profanity matched | | isClean() | boolean | No matches | | clean() | string | Masked text | | original() | string | Original input | | score() | number | 0–100 severity score | | count() | number | Match count | | uniqueWords() | string[] | Unique base words | | severity() | SeverityLevel \| null | Strongest severity among matches | | words() | MatchedWord[] | Positions, lengths, severity, etc. | | toArray() | object | JSON-friendly snapshot | | toJson() | string | JSON.stringify(toArray()) |

Legacy-style aliases from PHP v3 are available on Result (hasProfanity, getCleanString, …).

String(result) / template interpolation uses the clean string (like PHP Stringable).

Configuration

Pass a partial config to new Blasp(partialConfig); it is deep-merged with defaultBlaspConfig (see src/config/defaultConfig.ts and src/config/blasp-defaults.json).

Relevant keys include:

• default — default driver name (regex, pattern, phonetic, pipeline)
• language / default_language
• mask / mask_character
• allow, block, false_positives, separators, substitutions
• drivers.pipeline.drivers, drivers.phonetic.*
• cache.enabled, cache.results, cache.ttl

Middleware / Eloquent / Blade keys exist on the type for parity with PHP config shape; they are not used by this library.

Runtime options

import { Blasp, MemoryCache } from '@antistatique/blaspjs';

const blasp = new Blasp(undefined, {
  cache: new MemoryCache(), // or your own CacheAdapter; pass null to disable internal cache
  onProfanityDetected(result, originalText) {
    if (result.isOffensive()) {
      // logging, metrics, etc.
    }
  },
});

getCache() returns null when cache.enabled is false or runtime.cache === null.

Regenerating language data

Word lists and global separator/substitution defaults are vendored as JSON. To refresh from upstream Blaspsoft/blasp:

bun run export-languages

Requires curl and php on your PATH. This overwrites src/languages/*.json and src/config/blasp-defaults.json.

API parity vs PHP Blasp

| Feature | PHP (Blasp v4) | @antistatique/blaspjs | | ------- | ---------------------------------------------------- | ------- | | Drivers: regex, pattern, phonetic, pipeline | Yes | Yes | | Fluent PendingCheck API | Yes | Yes | | Result / MatchedWord, scoring, masking | Yes | Yes | | Multi-language dictionaries + normalizers | Yes | Yes | | Allow / block lists, severity filter | Yes | Yes | | Result caching (in-memory or custom) | Laravel cache | MemoryCache or CacheAdapter | | Custom drivers (extend) | Yes | Yes | | Laravel facade, service provider | Yes | No | | Middleware, validation rules, Blade | Yes | No | | Eloquent Blaspable, model events | Yes | No | | Artisan commands, Blasp::fake() | Yes | No |

For full behaviour and examples, see the upstream README.

Development

bun install
bun run build   # ESM + types in dist/
bun test        # Vitest
bun run lint:js

License

MIT. Profanity dictionaries and algorithmic behaviour are derived from Blaspsoft/blasp (MIT). This port is maintained separately and is not an official Blaspsoft package unless they choose to adopt it.