@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('spam@temp.ru', '@*.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	user@example.com	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('spam@temp.ru', '@*.ru');                    // true
isEmailBlocked('user@disposable.email', '@disposable.email'); // true
isEmailBlocked('legit@gmail.com', '@*.ru');                  // false

// Using an array of rules
isEmailBlocked('user@throwaway.io', ['@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