🌸 BloomKit

Plug-and-play probabilistic search optimization for modern web apps. Reduce unnecessary API calls by up to 70% using client-side Bloom filters.

---

🧠 What is BloomKit?

BloomKit is a full-stack toolkit that acts as a search gatekeeper.

Instead of hitting your backend on every keystroke, BloomKit:

User types → Bloom Filter check →
    ❌ Definitely NOT present → No API call (instant response)
    ✅ Maybe present → API call triggered

👉 Result:

• ⚡ Instant “no results” UX
• 🔥 Fewer API calls
• 💰 Lower backend load

---

🔌 Plug & Play (Core Value)

No complex logic required.

Just:

1. Generate a filter from your database
2. Wrap your UI with a provider
3. Use the search component

👉 That’s it. BloomKit handles the rest.

---

📦 Packages

• @smui/bloom-core → Core Bloom filter engine (zero dependencies)
• @smui/bloom-node → Backend utilities (filter generation)
• @smui/bloom-react → React components & hooks
• @smui/demo-nextjs → Demo app

---

⚡ Quick Start

1. Install

npm install

---

🛠 Backend Setup

Generate a Bloom filter from your database:

import { generateFilter } from "@smui/bloom-node";

export async function GET() {
  const products = ["iphone", "macbook", "ipad"]; // from DB

  const filter = generateFilter({
    items: products,
    errorRate: 0.01,
  });

  return Response.json({
    filter: filter.serialize(),
    version: "v1",
  });
}

👉 This API sends a compact filter instead of full data

---

⚛️ Frontend Setup

import { BloomProvider, BloomSearchInput } from "@smui/bloom-react";

export default function App() {
  return (
    <BloomProvider src="/api/bloom">
      <BloomSearchInput
        onHit={(query) => fetch(`/api/search?q=${query}`)}
        onMiss={() => console.log("No results instantly")}
      />
    </BloomProvider>
  );
}

---

🧩 Optional Hook Usage

import { useBloom } from "@smui/bloom-react";

const { has } = useBloom();

const exists = has("iphone");

---

🎯 How It Works (Under the Hood)

• Backend converts DB values → Bloom filter
• Filter sent to client (compressed)
• Stored in memory / storage
• Every search is checked locally first

---

🚀 Key Features

• 🔌 Plug-and-play integration
• ⚡ Sub-millisecond lookups
• 📦 Tiny bundle size (<5KB core)
• 🔄 Versioned filter updates
• 💾 Client-side caching (session / IndexedDB)
• ⚛️ React-first developer experience

---

📊 Performance Impact

Metric	Improvement
API Calls	↓ 30–70%
No-result latency	Instant
Backend load	Reduced

---

🧪 Demo

Run locally:

npm run dev

• /api/bloom → Bloom filter payload
• /api/search?q= → Triggered only when needed

---

🏗 Workspace Structure

apps/
  demo-nextjs/

packages/
  bloom-core/
  bloom-node/
  bloom-react/

---

🛠 Commands

npm run dev
npm run build
npm run test
npm run typecheck
npm run lint

---

⚠️ Important Notes

• Bloom filters can return false positives (expected)
• They never return false negatives
• API calls are skipped only when result is guaranteed absent

---

🧭 Roadmap

• <BloomListFilter /> (smart category filtering)
• <BloomProtect /> (permission gating)
• Cuckoo filter support (deletions)
• Multi-filter scaling

---

💡 Why BloomKit?

BloomKit turns a low-level data structure into a:

👉 Production-ready performance layer for frontend apps

No need to manually optimize search calls anymore.

---

⭐ Support

If you find this useful, consider giving it a star ⭐