@warfighter77806/bloom-filter

A high-performance, lightweight Bloom filter implementation for Node.js and the browser, written in TypeScript.

Features

• 🚀 Fast: Uses optimized hashing and bitwise operations.
• 📦 Lightweight: Zero dependencies.
• 🛡️ Type-safe: Built with TypeScript.
• 🔧 Customizable: Set your expected item count and desired false positive rate.
• 💾 Serializable: Easily export/import filter state via JSON.

Installation

npm install @warfighter77806/bloom-filter

Usage

Basic Example

import { BloomFilter } from '@warfighter77806/bloom-filter';

// Create a filter for 10,000 expected items and a 1% false positive rate
const filter = new BloomFilter(10000, 0.01);

// Add items
filter.add('user-123');
filter.add('user-456');

// Check items
console.log(filter.has('user-123')); // true
console.log(filter.has('user-789')); // false (definitely not in set)

Serialization

const filter = new BloomFilter(1000);
filter.add('secret-key');

// Export to JSON
const data = filter.toJSON();

// Restore from JSON
const restoredFilter = BloomFilter.fromJSON(data);
console.log(restoredFilter.has('secret-key')); // true

How it Works

A Bloom filter is a space-efficient probabilistic data structure used to test whether an element is a member of a set.

• False Negatives: Impossible.
• False Positives: Possible, but the rate can be controlled.

This implementation uses the Kirsch-Mitzenmacher optimization to generate multiple hash values from two base hashes, reducing the computational overhead.

API

new BloomFilter(expectedItems: number, falsePositiveRate?: number)

• expectedItems: The number of items you expect to add.
• falsePositiveRate: (Default: 0.01) The desired probability of false positives.

add(item: string): void

Adds a string to the filter.

has(item: string): boolean

Returns false if the item is definitely not in the set, and true if it might be.

toJSON()

Returns a serializable representation of the filter.

static fromJSON(data: any): BloomFilter

Creates a new filter instance from a serialized state.

License

MIT