Lightweight Bloom Filter for integers using splitmix64 and XOR fingerprinting
npm install bloom-filter-numbersA compact and efficient Bloom Filter implementation optimized for numbers, written in pure JavaScript.
It uses the high-quality splitmix64 as the hashing function and XOR-based fingerprinting to track inserted values.
---
- ⚡ Fast and lightweight
- 🔢 Optimized for integer keys (numbers / BigInts)
- 🧠 Tracks inserted values via a fingerprint
- 📤 Exportable & importable state
- 📦 No dependencies, works everywhere
---
This library is ideal for optimizing workflows where quick existence checks on numeric values are needed. Typical use cases include:
- Deduplication of numeric IDs such as user IDs, transaction hashes, or log entries
- Real-time data filtering to prevent reprocessing of already-seen events
- P2P systems and messaging layers to track seen message IDs, peers, or blocks
- Efficient sync algorithms, where Bloom filters can be exchanged to quickly detect missing items before deeper comparison
- Fingerprint verification: compare filters without transferring all data
- Performance-critical environments, where string hashing is too heavy or unnecessary
> 🔢 This implementation is optimized specifically for numbers (integers or BigInts), making it faster and more memory-efficient than generic string-based Bloom filters. It avoids encoding overhead and suits low-level protocols and systems that operate on numeric identifiers.
---
Bloom filters are probabilistic data structures that can quickly tell if a value is definitely not present — or maybe present.
- ✅ If has(x) returns false, you can be 100% sure the value does not exist.
- ❓ If has(x) returns true, the value might exist — and you can then run a deeper check (like querying a database).
This makes Bloom filters perfect for reducing unnecessary reads from databases or other expensive operations.
``js`
if (!bloom.has(userId)) {
// Definitely not seen before — safe to skip DB
handleNewUser(userId);
} else {
// Might have seen — verify with the database
db.checkUser(userId).then(user => {
if (!user) handleNewUser(userId);
});
}
---
`bash`
npm install bloom-filter-numbers
---
`js
const BloomFilterNumbers = require('bloom-filter-numbers');
// Create a Bloom Filter with 1024 bits and 4 hash functions
const bloom = new BloomFilterNumbers(1024, 4);
// Add values
bloom.add(123);
bloom.add(456);
// Check existence
console.log(bloom.has(123)); // true
console.log(bloom.has(999)); // false
// Get internal stats
console.log(bloom.getStats());
`
---
You can save the filter state and restore it later (for caching, syncing, persistence, etc).
`js
const exported = bloom.export();
/*
{
bits: Uint8Array(...),
size: 1024,
numHashes: 4,
itemCount: 2,
totalFingerprint: 812374123
}
*/
`
`js
const restored = new BloomFilterNumbers(
exported.bits,
exported.numHashes,
exported.itemCount
);
console.log(restored.has(123)); // true
`
> ✅ You must provide all three: bits, numHashes, and itemCount when importing.
---
Every inserted number is XORed into an internal fingerprint:
`js`
console.log(bloom.export().totalFingerprint); // Unique to inserted values
---
`js`
bloom.getStats();
/*
{
sizeBits: 1024,
numHashes: 4,
insertedItems: 2,
filterSizeBytes: 128,
rawSizeBytes: 16,
savedBytes: -112,
savedPercent: -700,
fingerprintSafeNumber: 812374123
}
*/
---
- Use size = itemCount * 10 for ~1% false positive ratenumHashes
- Increase (default: 4) for slightly better precisionbits
- Store , numHashes, itemCount` if you want to restore the filter later
---
- NPM: bloom-filter-numbers
- GitHub: colocohen/bloom-filter-numbers
---
Created with ❤️ by colocohen
---
MIT License
---
If you find this useful, feel free to star ⭐ the repo or sponsor me.
Pull requests are welcome!