bloom-filter-driver 1.0.0

package/README.md

@@ -0,0 +1,321 @@
+# Bloom Filter Driver (TypeScript / Node.js HTTP Client)
+
+**BloomFilterDriver** là thư viện client (SDK) nhỏ gọn được viết bằng TypeScript, đóng vai trò cầu nối giao tiếp giữa các ứng dụng Node.js/TypeScript (như `BloomFilterApplication`) và máy chủ xử lý dữ liệu Bloom Filter (`BloomFilterProcess`) thông qua giao thức HTTP REST.
+
+Thư viện được thiết kế độc lập, tuân thủ nguyên tắc kiến trúc sạch (Clean Architecture) với các lớp phân tách rõ ràng, hỗ trợ đầy đủ kiểu dữ liệu TypeScript (Type Safety), cơ chế kiểm tra tính hợp lệ dữ liệu (Validation) chặt chẽ và khả năng quản lý vòng đời request (Timeout & Cancellation) thông qua `AbortSignal`.
+
+---
+
+## 📦 Cài đặt
+
+Bạn có thể cài đặt thư viện thông qua các công cụ quản lý gói thông dụng:
+
+```bash
+npm install bloom-filter-driver
+# hoặc
+yarn add bloom-filter-driver
+# hoặc
+pnpm add bloom-filter-driver
+```
+
+> **Lưu ý khi phát triển cục bộ (Local Development):**
+> Nếu bạn đang làm việc trực tiếp trong repository chứa mã nguồn của driver, hãy cài đặt các gói phụ thuộc và biên dịch mã nguồn trước khi sử dụng hoặc liên kết (link) tới ứng dụng:
+> ```bash
+> npm install
+> npm run build
+> ```
+
+---
+
+## 🚀 Khởi tạo & Cấu hình Driver
+
+Để sử dụng, bạn cần khởi tạo một đối tượng `BloomFilterDriver` với cấu hình `BloomDriverConfig`.
+
+```typescript
+import { BloomFilterDriver } from 'bloom-filter-driver';
+
+const driver = new BloomFilterDriver({
+  baseUrl: 'http://localhost:8080', // Địa chỉ gốc của máy chủ BloomFilterProcess
+  timeoutMs: 5000,                  // (Tùy chọn) Thời gian chờ tối đa cho mỗi request (mặc định: 5000ms)
+  // fetchImpl: customFetch         // (Tùy chọn) Hàm fetch tùy chỉnh (hữu ích khi viết mock/unit test)
+});
+```
+
+### Quản lý vòng đời Request (Timeout & Cancellation)
+
+Tất cả các phương thức API trong driver đều hỗ trợ tham số tùy chọn `options?: { signal?: AbortSignal }`. Điều này cho phép bạn:
+- Tự động hủy các request vượt quá thời gian `timeoutMs` đã cấu hình.
+- Chủ động hủy request từ bên ngoài thông qua `AbortController`.
+
+```typescript
+const controller = new AbortController();
+
+try {
+  await driver.add(
+    { bfName: 'users-bf', data: 'alice@example.com' },
+    { signal: controller.signal }
+  );
+} catch (error) {
+  // Xử lý khi request bị hủy hoặc lỗi
+}
+
+// Khi muốn chủ động hủy request đang thực thi:
+controller.abort();
+```
+
+---
+
+## 🏗️ Kiến trúc & Thiết kế
+
+Driver được phân chia thành các module chuyên biệt nhằm đảm bảo tính dễ bảo trì và mở rộng:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   BloomFilterDriver                     │ (Lớp Facade tổng quan)
+└────────────┬───────────────────────────────┬────────────┘
+             │                               │
+             ▼                               ▼
+┌─────────────────────────┐     ┌─────────────────────────┐
+│     BloomApiClient      │     │     RangeApiClient      │ (Lớp Client nghiệp vụ)
+└────────────┬────────────┘     └────────────┬────────────┘
+             │                               │
+             └───────────────┬───────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────┐
+│                       HttpClient                        │ (Lớp xử lý HTTP & Timeout)
+└────────────────────────────┬────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────┐
+│                     DriverValidator                     │ (Lớp kiểm tra dữ liệu)
+└─────────────────────────────────────────────────────────┘
+```
+
+- **`BloomFilterDriver`**: Lớp giao diện chính (Facade) tổng hợp toàn bộ các phương thức thao tác với Bloom Filter và RangeLH.
+- **`BloomApiClient`**: Quản lý các endpoint liên quan đến cấu trúc Bloom Filter (`/bloom/*`).
+- **`RangeApiClient`**: Quản lý các endpoint liên quan đến cấu trúc phân cấp/chỉ mục dải RangeLH (`/rangelh/*`).
+- **`HttpClient`**: Đóng gói hàm `fetch`, xử lý nối chuỗi URL, thiết lập HTTP headers, quản lý `AbortController` và chuẩn hóa lỗi HTTP.
+- **`DriverValidator`**: Kiểm tra tính hợp lệ của dữ liệu đầu vào (tên bộ lọc, dải giá trị, xác suất, tham số cấu hình) trước khi gửi request tới máy chủ.
+
+---
+
+## 📚 Tài liệu API Tham khảo (API Reference)
+
+---
+
+### 1. Bloom Filter API (`BloomApiClient`)
+
+Các API chuyên biệt dành cho bộ lọc Bloom thông thường (Standard Bloom Filter) và bộ lọc Bloom có đếm (Counting Bloom Filter).
+
+#### `createBloom(payload: BloomCreatePayload, options?: DriverRequestOptions): Promise<void>`
+Khởi tạo và cấu hình một bộ lọc Bloom mới trên máy chủ trước khi sử dụng.
+
+```typescript
+await driver.createBloom({
+  bfName: 'users-bf',              // Tên định danh của bộ lọc
+  expectedValues: 100000,          // Số lượng phần tử dự kiến thêm vào
+  bloomType: 'standard',           // 'standard' | 'counting' (mặc định: 'standard')
+  falsePositiveProbability: 0.01,  // (Tùy chọn) Xác suất dương tính giả mong muốn (ví dụ: 1%)
+  counterBits: 4                   // (Tùy chọn) Số bit cho mỗi bộ đếm (chỉ dùng khi bloomType là 'counting', từ 1-8)
+});
+```
+> *Lưu ý:* Thư viện cung cấp hàm alias `configureBloom` tương đương với `createBloom` nhằm mục đích tương thích ngược. Khuyến nghị sử dụng `createBloom` cho các dự án mới.
+
+#### `add(payload: BloomDataPayload, options?: DriverRequestOptions): Promise<void>`
+Thêm một phần tử (chuỗi dữ liệu) vào bộ lọc Bloom.
+
+```typescript
+await driver.add({
+  bfName: 'users-bf',
+  data: 'alice@example.com'
+});
+```
+
+#### `mightContain(payload: BloomDataPayload, options?: DriverRequestOptions): Promise<boolean>`
+Kiểm tra xem một phần tử **có thể** tồn tại trong bộ lọc Bloom hay không.
+
+```typescript
+const isPresent = await driver.mightContain({
+  bfName: 'users-bf',
+  data: 'alice@example.com'
+});
+
+if (isPresent) {
+  console.log('Phần tử CÓ THỂ tồn tại (có rủi ro dương tính giả theo xác suất đã cấu hình).');
+} else {
+  console.log('Phần tử CHẮC CHẮN KHÔNG tồn tại trong bộ lọc.');
+}
+```
+
+#### `remove(payload: BloomDataPayload, options?: DriverRequestOptions): Promise<void>`
+Xóa một phần tử khỏi bộ lọc Bloom. (Yêu cầu bộ lọc phải được khởi tạo với `bloomType: 'counting'`).
+
+```typescript
+await driver.remove({
+  bfName: 'users-bf',
+  data: 'alice@example.com'
+});
+```
+
+#### `benchLoadSequentialKeys(payload: BloomBenchSequentialPayload, options?: DriverRequestOptions): Promise<void>`
+API hỗ trợ nạp dữ liệu giả lập hàng loạt (bulk insert) trực tiếp trên máy chủ với hiệu năng cao (chỉ tốn 1 lần gọi HTTP và 1 lần lưu trữ/persist). Thường dùng cho mục đích benchmark hoặc khởi tạo dữ liệu mẫu.
+
+```typescript
+await driver.benchLoadSequentialKeys({
+  bfName: 'users-bf',
+  from: 1,         // (Tùy chọn) Chỉ số bắt đầu (mặc định: 1)
+  to: 100000,      // Chỉ số kết thúc
+  keyWidth: 10     // (Tùy chọn) Độ rộng chuỗi số được đệm zero (zero-padding, mặc định: 10)
+});
+// Máy chủ sẽ tự động nạp các key dạng: "k-0000000001", "k-0000000002", ..., "k-0000100000"
+```
+
+---
+
+### 2. RangeLH API (`RangeApiClient`)
+
+RangeLH (Range Linear Hashing) là cấu trúc chỉ mục nâng cao phân bổ theo `key`, hỗ trợ tối ưu hóa các truy vấn điểm (point query), truy vấn khoảng (range query) và tổng hợp dữ liệu (aggregation).
+
+#### `createRange(payload: RangeCreatePayload, options?: DriverRequestOptions): Promise<void>`
+Khởi tạo cấu trúc chỉ mục RangeLH với các tham số tinh chỉnh chuyên sâu.
+
+```typescript
+await driver.createRange({
+  bfName: 'orders-range',
+  config: {
+    masterInitNumBucket: 2,     // Số lượng bucket khởi tạo ban đầu cho Master Index
+    masterSplitPolicy: 0.5,     // Tỷ lệ/Chính sách tách bucket (split policy)
+    expectedNItems: 1000000,    // Tổng số lượng phần tử dự kiến
+    fpProbBloomRF: 0.01,        // Xác suất dương tính giả cho các Bloom Filter con
+    deltaBloomRF: 10,           // Tham số dải delta cho bộ lọc
+    keyLength: 20,              // Độ dài cố định của chuỗi key (từ 1-64)
+    maxBytesString: 8,          // Số byte tối đa cho phần chuỗi giá trị (từ 1-8)
+    floatScale: 100             // Tỷ lệ nhân (scale) cho dữ liệu số thực
+  }
+});
+```
+
+#### `addRange(payload: RangePayload, options?: Driver: RequestOptions): Promise<void>`
+Thêm một cặp định danh/khóa (key) đơn lẻ vào chỉ mục RangeLH.
+
+```typescript
+await driver.addRange({
+  bfName: 'orders-range',
+  key: '2026-05-17T12:00:00Z'
+});
+```
+
+#### `addRangeBulk(payload: RangeBulkAddPayload, options?: DriverRequestOptions): Promise<void>`
+Thêm nhiều khóa cùng lúc (bulk insert) vào chỉ mục RangeLH, giúp tiết kiệm băng thông và giảm thiểu độ trễ mạng.
+
+```typescript
+await driver.addRangeBulk({
+  bfName: 'orders-range',
+  keys: [
+    '2026-05-17T12:00:00Z',
+    '2026-05-17T13:00:00Z',
+    '2026-05-17T14:00:00Z'
+  ]
+});
+```
+
+#### `removeRange(payload: RangePayload, options?: DriverRequestOptions): Promise<void>`
+Xóa một khóa khỏi chỉ mục RangeLH.
+
+```typescript
+await driver.removeRange({
+  bfName: 'orders-range',
+  key: '2026-05-17T12:00:00Z'
+});
+```
+
+#### `pointQuery(payload: PointQueryPayload, options?: DriverRequestOptions): Promise<string[]>`
+Truy vấn điểm để lấy ra danh sách các khóa khớp chính xác.
+
+```typescript
+const results = await driver.pointQuery({
+  bfName: 'orders-range',
+  key: '2026-05-17T12:00:00Z'
+});
+// results: string[] (Danh sách các giá trị/khóa tìm thấy)
+```
+
+#### `rangeQuery(payload: RangeQueryPayload, options?: DriverRequestOptions): Promise<string[]>`
+Truy vấn khoảng để lấy ra danh sách các khóa nằm trong dải từ `from` đến `to`.
+
+```typescript
+const results = await driver.rangeQuery({
+  bfName: 'orders-range',
+  from: '2026-05-01T00:00:00Z',
+  to: '2026-05-31T23:59:59Z'
+});
+// results: string[] (Danh sách các khóa thuộc khoảng thời gian/dải truy vấn)
+```
+
+#### `aggregate(payload: RangeAggregatePayload, options?: DriverRequestOptions): Promise<number>`
+Thực hiện truy vấn tổng hợp (aggregation) dữ liệu trên một dải khóa cụ thể.
+
+```typescript
+const totalOrders = await driver.aggregate({
+  bfName: 'orders-range',
+  from: '2026-05-01T00:00:00Z',
+  to: '2026-05-31T23:59:59Z',
+  op: 'count' // Các phép toán hỗ trợ: 'sum' | 'avg' | 'min' | 'max' | 'count'
+});
+console.log(`Tổng số đơn hàng trong tháng 5: ${totalOrders}`);
+```
+
+---
+
+## ⚠️ Xử lý lỗi (Error Handling)
+
+Tất cả các lỗi phát sinh từ driver (bao gồm lỗi kiểm tra dữ liệu đầu vào, lỗi mạng, lỗi timeout hoặc lỗi nghiệp vụ từ phía máy chủ) đều được ném ra dưới dạng đối tượng `BloomDriverError`.
+
+```typescript
+import { BloomFilterDriver, BloomDriverError } from 'bloom-filter-driver';
+
+const driver = new BloomFilterDriver({ baseUrl: 'http://localhost:8080' });
+
+async function execute() {
+  try {
+    // Thử gửi dữ liệu không hợp lệ (chuỗi rỗng)
+    await driver.add({ bfName: 'users-bf', data: '' });
+  } catch (error) {
+    if (error instanceof BloomDriverError) {
+      console.error('[BloomDriverError] Thông báo lỗi:', error.message);
+      
+      if (error.status) {
+        console.error('Mã trạng thái HTTP:', error.status);
+      }
+      if (error.responseBody) {
+        console.error('Nội dung phản hồi từ máy chủ:', error.responseBody);
+      }
+    } else {
+      console.error('[Lỗi không xác định]:', error);
+    }
+  }
+}
+```
+
+---
+
+## 🛠️ Build & Publish (Dành cho nhà phát triển)
+
+Các lệnh thao tác chính khi tham gia phát triển gói thư viện `bloom-filter-driver`:
+
+- **Kiểm tra lỗi cú pháp và định dạng (Lint & Format):**
+  ```bash
+  npm run lint
+  ```
+
+- **Biên dịch mã nguồn TypeScript sang JavaScript (thư mục `dist`):**
+  ```bash
+  npm run build
+  ```
+
+- **Đóng gói và phát hành lên NPM registry:**
+  ```bash
+  npm publish
+  ```
+  *(Lưu ý: Script `prepublishOnly` trong `package.json` sẽ tự động kích hoạt tiến trình `build` trước khi publish để đảm bảo mã nguồn phát hành luôn mới nhất).*

package/dist/BloomApiClient.d.ts

@@ -0,0 +1,13 @@
+import type { BloomBenchSequentialPayload, BloomCreatePayload, BloomDataPayload, DriverRequestOptions } from './types';
+import { DriverValidator } from './DriverValidator';
+import { HttpClient } from './HttpClient';
+export declare class BloomApiClient {
+    private readonly http;
+    private readonly validator;
+    constructor(http: HttpClient, validator: DriverValidator);
+    add(payload: BloomDataPayload, options?: DriverRequestOptions): Promise<void>;
+    create(payload: BloomCreatePayload, options?: DriverRequestOptions): Promise<void>;
+    benchLoadSequentialKeys(payload: BloomBenchSequentialPayload, options?: DriverRequestOptions): Promise<void>;
+    mightContain(payload: BloomDataPayload, options?: DriverRequestOptions): Promise<boolean>;
+    remove(payload: BloomDataPayload, options?: DriverRequestOptions): Promise<void>;
+}

package/dist/BloomApiClient.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BloomApiClient = void 0;
+class BloomApiClient {
+    http;
+    validator;
+    constructor(http, validator) {
+        this.http = http;
+        this.validator = validator;
+    }
+    async add(payload, options) {
+        await this.http.post('/bloom/add', {
+            bfName: this.validator.bfName(payload.bfName),
+            data: this.validator.nonEmpty(payload.data, 'data')
+        }, options);
+    }
+    async create(payload, options) {
+        const bloomType = this.validator.bloomType(payload.bloomType);
+        const requestBody = {
+            bfName: this.validator.bfName(payload.bfName),
+            expectedValues: this.validator.positiveInt(payload.expectedValues, 'expectedValues'),
+            bloomType
+        };
+        if (payload.falsePositiveProbability !== undefined) {
+            requestBody.falsePositiveProbability = this.validator.probability(payload.falsePositiveProbability, 'falsePositiveProbability');
+        }
+        if (payload.counterBits !== undefined) {
+            requestBody.counterBits = this.validator.counterBits(payload.counterBits, bloomType);
+        }
+        await this.http.post('/bloom/create', requestBody, options);
+    }
+    async benchLoadSequentialKeys(payload, options) {
+        const requestBody = {
+            bfName: this.validator.bfName(payload.bfName),
+            to: this.validator.positiveInt(payload.to, 'to')
+        };
+        if (payload.from !== undefined) {
+            requestBody.from = this.validator.positiveInt(payload.from, 'from');
+        }
+        if (payload.keyWidth !== undefined) {
+            requestBody.keyWidth = this.validator.positiveInt(payload.keyWidth, 'keyWidth');
+        }
+        await this.http.post('/bloom/bench/load-sequential-keys', requestBody, options);
+    }
+    async mightContain(payload, options) {
+        const response = await this.http.get('/bloom/might-contain', {
+            bfName: this.validator.bfName(payload.bfName),
+            data: this.validator.nonEmpty(payload.data, 'data')
+        }, options);
+        return response === 'true';
+    }
+    async remove(payload, options) {
+        await this.http.post('/bloom/remove', {
+            bfName: this.validator.bfName(payload.bfName),
+            data: this.validator.nonEmpty(payload.data, 'data')
+        }, options);
+    }
+}
+exports.BloomApiClient = BloomApiClient;

package/dist/BloomFilterDriver.d.ts

@@ -0,0 +1,106 @@
+import type { BloomBenchSequentialPayload, BloomCreatePayload, BloomDataPayload, BloomDriverConfig, DriverRequestOptions, PointQueryPayload, RangeAggregatePayload, RangeBulkAddPayload, RangeCreatePayload, RangePayload, RangeQueryPayload } from './types';
+export declare class BloomFilterDriver {
+    private readonly bloomApi;
+    private readonly rangeApi;
+    /**
+     * Create a driver instance for talking to the Bloom Filter process service.
+     *
+     * @param config Driver configuration (base URL, defaults, timeouts, optional fetch implementation)
+     */
+    constructor(config: BloomDriverConfig);
+    /**
+     * Add a value to a Bloom Filter.
+     *
+     * @param payload Target bloom filter name and data to add
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @throws {BloomDriverError} If inputs are invalid or the process request fails.
+     */
+    add(payload: BloomDataPayload, options?: DriverRequestOptions): Promise<void>;
+    /**
+     * Create a bloom filter namespace before first use.
+     *
+     * @param payload Target bloom filter name and expected number of values
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @throws {BloomDriverError} If inputs are invalid or the process request fails.
+     */
+    createBloom(payload: BloomCreatePayload, options?: DriverRequestOptions): Promise<void>;
+    /**
+     * Backward-compatible alias for createBloom.
+     * Prefer calling createBloom in new code.
+     */
+    configureBloom(payload: BloomCreatePayload, options?: DriverRequestOptions): Promise<void>;
+    /**
+     * Bulk-load keys `k-{zeroPadded(i)}` for i in [from, to] via benchmark API (single HTTP, one persist).
+     */
+    benchLoadSequentialKeys(payload: BloomBenchSequentialPayload, options?: DriverRequestOptions): Promise<void>;
+    /**
+     * Check whether a value might be contained in the Bloom Filter.
+     *
+     * Note: Bloom filters can return false positives. `false` means "definitely not present".
+     *
+     * @param payload Target bloom filter name and data to check
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @returns `true` if the process returns "true"; otherwise `false`.
+     * @throws {BloomDriverError} If inputs are invalid or the process request fails.
+     */
+    mightContain(payload: BloomDataPayload, options?: DriverRequestOptions): Promise<boolean>;
+    /**
+     * Remove a value from a (counting) Bloom Filter.
+     *
+     * @param payload Target bloom filter name and data to remove
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @throws {BloomDriverError} If inputs are invalid or the process request fails.
+     */
+    remove(payload: BloomDataPayload, options?: DriverRequestOptions): Promise<void>;
+    /**
+     * Add a key into the RangeLH structure.
+     *
+     * @param payload Target bloom filter name and key to add
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @throws {BloomDriverError} If inputs are invalid or the process request fails.
+     */
+    addRange(payload: RangePayload, options?: DriverRequestOptions): Promise<void>;
+    /**
+     * Create a RangeLH namespace before first use.
+     */
+    createRange(payload: RangeCreatePayload, options?: DriverRequestOptions): Promise<void>;
+    /**
+     * Add many keys into RangeLH with a single request.
+     */
+    addRangeBulk(payload: RangeBulkAddPayload, options?: DriverRequestOptions): Promise<void>;
+    /**
+     * Remove a key from the RangeLH structure.
+     *
+     * @param payload Target bloom filter name and key to remove
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @throws {BloomDriverError} If inputs are invalid or the process request fails.
+     */
+    removeRange(payload: RangePayload, options?: DriverRequestOptions): Promise<void>;
+    /**
+     * Run a point query over the RangeLH structure.
+     *
+     * @param payload Target bloom filter name and query key
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @returns List of keys returned by the process (may be empty).
+     * @throws {BloomDriverError} If inputs are invalid, response parsing fails, or the process request fails.
+     */
+    pointQuery(payload: PointQueryPayload, options?: DriverRequestOptions): Promise<string[]>;
+    /**
+     * Run a range query over the RangeLH structure.
+     *
+     * @param payload Target bloom filter name and range bounds (inclusive/exclusive depends on the process)
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @returns List of keys returned by the process (may be empty).
+     * @throws {BloomDriverError} If inputs are invalid, response parsing fails, or the process request fails.
+     */
+    rangeQuery(payload: RangeQueryPayload, options?: DriverRequestOptions): Promise<string[]>;
+    /**
+     * Run aggregate query over a key range.
+     *
+     * @param payload Target bloom filter name, range bounds, and aggregate operation.
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @returns Numeric aggregate result from process.
+     * @throws {BloomDriverError} If inputs are invalid, response parsing fails, or the process request fails.
+     */
+    aggregate(payload: RangeAggregatePayload, options?: DriverRequestOptions): Promise<number>;
+}

package/dist/BloomFilterDriver.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BloomFilterDriver = void 0;
+const BloomApiClient_1 = require("./BloomApiClient");
+const HttpClient_1 = require("./HttpClient");
+const RangeApiClient_1 = require("./RangeApiClient");
+const DriverValidator_1 = require("./DriverValidator");
+class BloomFilterDriver {
+    bloomApi;
+    rangeApi;
+    /**
+     * Create a driver instance for talking to the Bloom Filter process service.
+     *
+     * @param config Driver configuration (base URL, defaults, timeouts, optional fetch implementation)
+     */
+    constructor(config) {
+        const httpClient = new HttpClient_1.HttpClient(config);
+        const validator = new DriverValidator_1.DriverValidator();
+        this.bloomApi = new BloomApiClient_1.BloomApiClient(httpClient, validator);
+        this.rangeApi = new RangeApiClient_1.RangeApiClient(httpClient, validator);
+    }
+    /**
+     * Add a value to a Bloom Filter.
+     *
+     * @param payload Target bloom filter name and data to add
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @throws {BloomDriverError} If inputs are invalid or the process request fails.
+     */
+    async add(payload, options) {
+        await this.bloomApi.add(payload, options);
+    }
+    /**
+     * Create a bloom filter namespace before first use.
+     *
+     * @param payload Target bloom filter name and expected number of values
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @throws {BloomDriverError} If inputs are invalid or the process request fails.
+     */
+    async createBloom(payload, options) {
+        await this.bloomApi.create(payload, options);
+    }
+    /**
+     * Backward-compatible alias for createBloom.
+     * Prefer calling createBloom in new code.
+     */
+    async configureBloom(payload, options) {
+        await this.createBloom(payload, options);
+    }
+    /**
+     * Bulk-load keys `k-{zeroPadded(i)}` for i in [from, to] via benchmark API (single HTTP, one persist).
+     */
+    async benchLoadSequentialKeys(payload, options) {
+        await this.bloomApi.benchLoadSequentialKeys(payload, options);
+    }
+    /**
+     * Check whether a value might be contained in the Bloom Filter.
+     *
+     * Note: Bloom filters can return false positives. `false` means "definitely not present".
+     *
+     * @param payload Target bloom filter name and data to check
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @returns `true` if the process returns "true"; otherwise `false`.
+     * @throws {BloomDriverError} If inputs are invalid or the process request fails.
+     */
+    async mightContain(payload, options) {
+        return this.bloomApi.mightContain(payload, options);
+    }
+    /**
+     * Remove a value from a (counting) Bloom Filter.
+     *
+     * @param payload Target bloom filter name and data to remove
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @throws {BloomDriverError} If inputs are invalid or the process request fails.
+     */
+    async remove(payload, options) {
+        await this.bloomApi.remove(payload, options);
+    }
+    /**
+     * Add a key into the RangeLH structure.
+     *
+     * @param payload Target bloom filter name and key to add
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @throws {BloomDriverError} If inputs are invalid or the process request fails.
+     */
+    async addRange(payload, options) {
+        await this.rangeApi.addRange(payload, options);
+    }
+    /**
+     * Create a RangeLH namespace before first use.
+     */
+    async createRange(payload, options) {
+        await this.rangeApi.createRange(payload, options);
+    }
+    /**
+     * Add many keys into RangeLH with a single request.
+     */
+    async addRangeBulk(payload, options) {
+        await this.rangeApi.addRangeBulk(payload, options);
+    }
+    /**
+     * Remove a key from the RangeLH structure.
+     *
+     * @param payload Target bloom filter name and key to remove
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @throws {BloomDriverError} If inputs are invalid or the process request fails.
+     */
+    async removeRange(payload, options) {
+        await this.rangeApi.removeRange(payload, options);
+    }
+    /**
+     * Run a point query over the RangeLH structure.
+     *
+     * @param payload Target bloom filter name and query key
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @returns List of keys returned by the process (may be empty).
+     * @throws {BloomDriverError} If inputs are invalid, response parsing fails, or the process request fails.
+     */
+    async pointQuery(payload, options) {
+        return this.rangeApi.pointQuery(payload, options);
+    }
+    /**
+     * Run a range query over the RangeLH structure.
+     *
+     * @param payload Target bloom filter name and range bounds (inclusive/exclusive depends on the process)
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @returns List of keys returned by the process (may be empty).
+     * @throws {BloomDriverError} If inputs are invalid, response parsing fails, or the process request fails.
+     */
+    async rangeQuery(payload, options) {
+        return this.rangeApi.rangeQuery(payload, options);
+    }
+    /**
+     * Run aggregate query over a key range.
+     *
+     * @param payload Target bloom filter name, range bounds, and aggregate operation.
+     * @param options Optional request options (supports cancellation via `options.signal`)
+     * @returns Numeric aggregate result from process.
+     * @throws {BloomDriverError} If inputs are invalid, response parsing fails, or the process request fails.
+     */
+    async aggregate(payload, options) {
+        return this.rangeApi.aggregate(payload, options);
+    }
+}
+exports.BloomFilterDriver = BloomFilterDriver;

package/dist/DriverValidator.d.ts

@@ -0,0 +1,16 @@
+import type { BloomType, RangeAggregateOp, RangeConfigPayload } from './types';
+export declare class DriverValidator {
+    bfName(value: string): string;
+    nonEmpty(value: string | undefined, fieldName: string): string;
+    positiveInt(value: number, fieldName: string): number;
+    bloomType(value: BloomType | undefined): BloomType;
+    counterBits(value: number, bloomType: BloomType): number;
+    probability(value: number, fieldName: string): number;
+    aggregateOp(value: RangeAggregateOp): RangeAggregateOp;
+    parseStringList(body: string): string[];
+    parseNumericValue(body: string): number;
+    positiveNumberInZeroOne(value: number, fieldName: string): number;
+    keysArray(values: string[]): string[];
+    rangeConfig(config: RangeConfigPayload): RangeConfigPayload;
+    integerInRange(value: number, fieldName: string, min: number, max: number): number;
+}

package/dist/DriverValidator.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DriverValidator = void 0;
+const errors_1 = require("./errors");
+class DriverValidator {
+    bfName(value) {
+        return this.nonEmpty(value, 'bfName');
+    }
+    nonEmpty(value, fieldName) {
+        if (typeof value !== 'string' || value.trim().length === 0) {
+            throw new errors_1.BloomDriverError(`"${fieldName}" must be a non-empty string`);
+        }
+        return value;
+    }
+    positiveInt(value, fieldName) {
+        if (!Number.isInteger(value) || value <= 0) {
+            throw new errors_1.BloomDriverError(`"${fieldName}" must be a positive integer`);
+        }
+        return value;
+    }
+    bloomType(value) {
+        if (value === undefined) {
+            return 'standard';
+        }
+        if (value !== 'standard' && value !== 'counting') {
+            throw new errors_1.BloomDriverError('"bloomType" must be either "standard" or "counting"');
+        }
+        return value;
+    }
+    counterBits(value, bloomType) {
+        if (bloomType !== 'counting') {
+            throw new errors_1.BloomDriverError('"counterBits" is only valid when bloomType is "counting"');
+        }
+        if (!Number.isInteger(value) || value < 1 || value > 8) {
+            throw new errors_1.BloomDriverError('"counterBits" must be an integer in [1, 8]');
+        }
+        return value;
+    }
+    probability(value, fieldName) {
+        if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value >= 1) {
+            throw new errors_1.BloomDriverError(`"${fieldName}" must be a number in (0, 1)`);
+        }
+        return value;
+    }
+    aggregateOp(value) {
+        if (value !== 'sum' && value !== 'avg' && value !== 'min' && value !== 'max' && value !== 'count') {
+            throw new errors_1.BloomDriverError('"op" must be one of: sum, avg, min, max, count');
+        }
+        return value;
+    }
+    parseStringList(body) {
+        if (body.length === 0) {
+            return [];
+        }
+        return body
+            .split(',')
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0);
+    }
+    parseNumericValue(body) {
+        const trimmed = body.trim();
+        const value = Number.parseFloat(trimmed);
+        if (!Number.isFinite(value)) {
+            throw new errors_1.BloomDriverError(`Unable to parse numeric value "${trimmed}" from process response`);
+        }
+        return value;
+    }
+    positiveNumberInZeroOne(value, fieldName) {
+        return this.probability(value, fieldName);
+    }
+    keysArray(values) {
+        if (!Array.isArray(values) || values.length === 0) {
+            throw new errors_1.BloomDriverError('"keys" must be a non-empty array');
+        }
+        return values.map((value, index) => this.nonEmpty(value, `keys[${index}]`));
+    }
+    rangeConfig(config) {
+        return {
+            masterInitNumBucket: this.positiveInt(config.masterInitNumBucket, 'masterInitNumBucket'),
+            masterSplitPolicy: this.probability(config.masterSplitPolicy, 'masterSplitPolicy'),
+            expectedNItems: this.positiveInt(config.expectedNItems, 'expectedNItems'),
+            fpProbBloomRF: this.probability(config.fpProbBloomRF, 'fpProbBloomRF'),
+            deltaBloomRF: this.integerInRange(config.deltaBloomRF, 'deltaBloomRF', 1, 31),
+            keyLength: this.integerInRange(config.keyLength, 'keyLength', 1, 64),
+            maxBytesString: this.integerInRange(config.maxBytesString, 'maxBytesString', 1, 8),
+            floatScale: this.positiveInt(config.floatScale, 'floatScale')
+        };
+    }
+    integerInRange(value, fieldName, min, max) {
+        if (!Number.isInteger(value) || value < min || value > max) {
+            throw new errors_1.BloomDriverError(`"${fieldName}" must be an integer in [${min}, ${max}]`);
+        }
+        return value;
+    }
+}
+exports.DriverValidator = DriverValidator;

package/dist/HttpClient.d.ts

@@ -0,0 +1,10 @@
+import type { BloomDriverConfig, DriverRequestOptions } from './types';
+export declare class HttpClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(config: BloomDriverConfig);
+    get(path: string, query: Record<string, string>, options?: DriverRequestOptions): Promise<string>;
+    post(path: string, body: unknown, options?: DriverRequestOptions): Promise<string>;
+    private request;
+}

package/dist/HttpClient.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+const errors_1 = require("./errors");
+const DEFAULT_TIMEOUT_MS = 5_000;
+class HttpClient {
+    baseUrl;
+    timeoutMs;
+    fetchImpl;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetchImpl = config.fetchImpl ?? fetch;
+    }
+    async get(path, query, options) {
+        const searchParams = new URLSearchParams(query);
+        return this.request(`${path}?${searchParams.toString()}`, {
+            method: 'GET',
+            signal: options?.signal
+        });
+    }
+    async post(path, body, options) {
+        return this.request(path, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify(body),
+            signal: options?.signal
+        });
+    }
+    async request(path, init) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        if (init.signal) {
+            init.signal.addEventListener('abort', () => controller.abort(), { once: true });
+        }
+        try {
+            const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                ...init,
+                signal: controller.signal
+            });
+            const body = (await response.text()).trim();
+            if (!response.ok) {
+                throw new errors_1.BloomDriverError(`Process request failed with status ${response.status}`, {
+                    status: response.status,
+                    responseBody: body
+                });
+            }
+            return body;
+        }
+        catch (error) {
+            if (error instanceof errors_1.BloomDriverError) {
+                throw error;
+            }
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new errors_1.BloomDriverError(`Process request timed out after ${this.timeoutMs}ms`);
+            }
+            throw new errors_1.BloomDriverError(error instanceof Error ? error.message : 'Unknown process request error');
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+exports.HttpClient = HttpClient;

package/dist/RangeApiClient.d.ts

@@ -0,0 +1,15 @@
+import type { DriverRequestOptions, PointQueryPayload, RangeAggregatePayload, RangeBulkAddPayload, RangeCreatePayload, RangePayload, RangeQueryPayload } from './types';
+import { DriverValidator } from './DriverValidator';
+import { HttpClient } from './HttpClient';
+export declare class RangeApiClient {
+    private readonly http;
+    private readonly validator;
+    constructor(http: HttpClient, validator: DriverValidator);
+    createRange(payload: RangeCreatePayload, options?: DriverRequestOptions): Promise<void>;
+    addRange(payload: RangePayload, options?: DriverRequestOptions): Promise<void>;
+    addRangeBulk(payload: RangeBulkAddPayload, options?: DriverRequestOptions): Promise<void>;
+    removeRange(payload: RangePayload, options?: DriverRequestOptions): Promise<void>;
+    pointQuery(payload: PointQueryPayload, options?: DriverRequestOptions): Promise<string[]>;
+    rangeQuery(payload: RangeQueryPayload, options?: DriverRequestOptions): Promise<string[]>;
+    aggregate(payload: RangeAggregatePayload, options?: DriverRequestOptions): Promise<number>;
+}

package/dist/RangeApiClient.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RangeApiClient = void 0;
+class RangeApiClient {
+    http;
+    validator;
+    constructor(http, validator) {
+        this.http = http;
+        this.validator = validator;
+    }
+    async createRange(payload, options) {
+        const config = this.validator.rangeConfig(payload.config);
+        await this.http.post('/rangelh/create', {
+            bfName: this.validator.bfName(payload.bfName),
+            masterInitNumBucket: config.masterInitNumBucket,
+            masterSplitPolicy: config.masterSplitPolicy,
+            expectedNItems: config.expectedNItems,
+            fpProbBloomRF: config.fpProbBloomRF,
+            deltaBloomRF: config.deltaBloomRF,
+            keyLength: config.keyLength,
+            maxBytesString: config.maxBytesString,
+            floatScale: config.floatScale
+        }, options);
+    }
+    async addRange(payload, options) {
+        await this.http.post('/rangelh/add', {
+            bfName: this.validator.bfName(payload.bfName),
+            key: this.validator.nonEmpty(payload.key, 'key')
+        }, options);
+    }
+    async addRangeBulk(payload, options) {
+        await this.http.post('/rangelh/add-bulk', {
+            bfName: this.validator.bfName(payload.bfName),
+            keys: this.validator.keysArray(payload.keys)
+        }, options);
+    }
+    async removeRange(payload, options) {
+        await this.http.post('/rangelh/remove', {
+            bfName: this.validator.bfName(payload.bfName),
+            key: this.validator.nonEmpty(payload.key, 'key')
+        }, options);
+    }
+    async pointQuery(payload, options) {
+        const response = await this.http.get('/rangelh/point-query', {
+            bfName: this.validator.bfName(payload.bfName),
+            key: this.validator.nonEmpty(payload.key, 'key')
+        }, options);
+        return this.validator.parseStringList(response);
+    }
+    async rangeQuery(payload, options) {
+        const response = await this.http.get('/rangelh/range-query', {
+            bfName: this.validator.bfName(payload.bfName),
+            from: this.validator.nonEmpty(payload.from, 'from'),
+            to: this.validator.nonEmpty(payload.to, 'to')
+        }, options);
+        return this.validator.parseStringList(response);
+    }
+    async aggregate(payload, options) {
+        const response = await this.http.get('/rangelh/aggregate', {
+            bfName: this.validator.bfName(payload.bfName),
+            from: this.validator.nonEmpty(payload.from, 'from'),
+            to: this.validator.nonEmpty(payload.to, 'to'),
+            op: this.validator.aggregateOp(payload.op)
+        }, options);
+        return this.validator.parseNumericValue(response);
+    }
+}
+exports.RangeApiClient = RangeApiClient;

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+export declare class BloomDriverError extends Error {
+    readonly status?: number;
+    readonly responseBody?: string;
+    constructor(message: string, options?: {
+        status?: number;
+        responseBody?: string;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BloomDriverError = void 0;
+class BloomDriverError extends Error {
+    status;
+    responseBody;
+    constructor(message, options) {
+        super(message);
+        this.name = 'BloomDriverError';
+        this.status = options?.status;
+        this.responseBody = options?.responseBody;
+    }
+}
+exports.BloomDriverError = BloomDriverError;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './BloomFilterDriver';
+export * from './BloomApiClient';
+export * from './RangeApiClient';
+export * from './HttpClient';
+export * from './DriverValidator';
+export * from './errors';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./BloomFilterDriver"), exports);
+__exportStar(require("./BloomApiClient"), exports);
+__exportStar(require("./RangeApiClient"), exports);
+__exportStar(require("./HttpClient"), exports);
+__exportStar(require("./DriverValidator"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./types"), exports);

package/dist/types.d.ts

@@ -0,0 +1,68 @@
+export interface BloomDriverConfig {
+    baseUrl: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+export interface BloomDataPayload {
+    bfName: string;
+    data: string;
+}
+export type BloomType = 'standard' | 'counting';
+export interface BloomCreatePayload {
+    bfName: string;
+    expectedValues: number;
+    bloomType?: BloomType;
+    falsePositiveProbability?: number;
+    counterBits?: number;
+}
+/** Matches POST /bloom/bench/load-sequential-keys (in-process bulk insert, one save). */
+export interface BloomBenchSequentialPayload {
+    bfName: string;
+    /** Inclusive start index; default 1 on server if omitted. */
+    from?: number;
+    /** Inclusive end index. */
+    to: number;
+    /** Zero-pad width for numeric part; default 10 on server. */
+    keyWidth?: number;
+}
+export interface RangePayload {
+    bfName: string;
+    key: string;
+}
+export interface RangeConfigPayload {
+    masterInitNumBucket: number;
+    masterSplitPolicy: number;
+    expectedNItems: number;
+    fpProbBloomRF: number;
+    deltaBloomRF: number;
+    keyLength: number;
+    maxBytesString: number;
+    floatScale: number;
+}
+export interface RangeCreatePayload {
+    bfName: string;
+    config: RangeConfigPayload;
+}
+export interface RangeBulkAddPayload {
+    bfName: string;
+    keys: string[];
+}
+export interface PointQueryPayload {
+    bfName: string;
+    key: string;
+}
+export interface RangeQueryPayload {
+    bfName: string;
+    from: string;
+    to: string;
+}
+export type RangeAggregateOp = 'sum' | 'avg' | 'min' | 'max' | 'count';
+export interface RangeAggregatePayload {
+    bfName: string;
+    from: string;
+    to: string;
+    op: RangeAggregateOp;
+}
+export interface DriverRequestOptions {
+    signal?: AbortSignal;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "bloom-filter-driver",
+  "version": "1.0.0",
+  "description": "HTTP driver for BloomFilterProcess",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rimraf ./dist && tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "bloom-filter",
+    "driver",
+    "http-client"
+  ],
+  "license": "ISC",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.5.0",
+    "jest": "^30.3.0",
+    "rimraf": "^6.1.3",
+    "ts-jest": "^29.4.9",
+    "typescript": "~5.9.3"
+  }
+}