@arraypress/blocklist

Email, IP, and word blocklist matching. Zero dependencies.

Uses the Fetch API — works in Cloudflare Workers, Node.js 18+, Deno, Bun, and browsers.

Installation

npm install @arraypress/blocklist

Usage

import { isEmailBlocked, isIPBlocked, containsBlockedWord } from '@arraypress/blocklist';

isEmailBlocked('[email protected]', '@*.ru');           // true
isIPBlocked('10.0.0.5', '10.0.0.0/24');           // true
containsBlockedWord('Buy now free stuff', 'buy now\nfree stuff'); // true

API

isEmailBlocked(email, rules)

Check if an email address is blocked. Rules can be a newline-separated string or an array.

function isEmailBlocked(email: string, rules: string | string[]): boolean

Supported rule formats:

| Format | Example | Matches | | ----------------- | ------------------- | ------------------------------------ | | Full email | [email protected] | Exact match only | | Domain | @example.com | All emails from that domain | | Wildcard TLD | @*.ru | All .ru domains | | Wildcard subdomain| @*.example.com | All subdomains of example.com |

isEmailBlocked('[email protected]', '@*.ru');                    // true
isEmailBlocked('[email protected]', '@disposable.email'); // true
isEmailBlocked('[email protected]', '@*.ru');                  // false

// Using an array of rules
isEmailBlocked('[email protected]', ['@throwaway.io', '@*.ru']);  // true

isIPBlocked(ip, rules)

Check if an IPv4 address is blocked. Rules can be a newline-separated string or an array.

function isIPBlocked(ip: string, rules: string | string[]): boolean

Supported rule formats:

| Format | Example | Matches | | ---------- | -------------- | ------------------------------ | | Exact IP | 1.2.3.4 | That single IP | | CIDR range | 10.0.0.0/24 | 10.0.0.0 through 10.0.0.255 |

isIPBlocked('10.0.0.5', '10.0.0.0/24');  // true
isIPBlocked('10.0.1.5', '10.0.0.0/24');  // false
isIPBlocked('1.2.3.4', '1.2.3.4');       // true

containsBlockedWord(text, rules)

Check if text contains any blocked words or phrases. Case-insensitive substring matching.

function containsBlockedWord(text: string, rules: string | string[]): boolean

containsBlockedWord('Buy now and get free stuff!', 'buy now\nfree stuff');  // true
containsBlockedWord('Great product, highly recommend', 'spam\nbuy now');     // false

findBlockedWords(text, rules)

Find which blocked words are present in the text. Returns an array of matched words.

function findBlockedWords(text: string, rules: string | string[]): string[]

const matches = findBlockedWords('Buy now and get free stuff!', 'buy now\nfree stuff\nspam');
// => ['buy now', 'free stuff']

parseBlocklist(text)

Parse a newline-separated blocklist string into an array of trimmed, lowercased, non-empty entries. Lines starting with # are treated as comments and ignored.

function parseBlocklist(text: string): string[]

const rules = parseBlocklist(`
  # Disposable email providers
  @mailinator.com
  @guerrillamail.com
  @*.ru
`);
// => ['@mailinator.com', '@guerrillamail.com', '@*.ru']

License

MIT