bloomkit 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,214 @@
+/** @internal Compute optimal bit-array size m given n items and fpr. */
+declare function optimalM(n: number, fpr: number): number;
+/** @internal Compute optimal number of hash functions k given m bits and n items. */
+declare function optimalK(m: number, n: number): number;
+interface BloomFilterOptions {
+    /**
+     * Expected number of items that will be inserted.
+     * Used to size the filter optimally.
+     */
+    capacity: number;
+    /**
+     * Target false-positive rate (0 < fpr < 1). Default: 0.01 (1%).
+     */
+    errorRate?: number;
+}
+interface BloomFilterJSON {
+    type: "BloomFilter";
+    capacity: number;
+    errorRate: number;
+    m: number;
+    k: number;
+    bits: string;
+}
+/**
+ * Standard Bloom filter — space-efficient probabilistic set membership.
+ *
+ * - `add(item)` always works correctly.
+ * - `has(item)` may return `true` for items not added (false positive, rate ≤ `errorRate`).
+ * - `has(item)` never returns `false` for items that were added.
+ * - Items cannot be removed (use `CountingBloomFilter` for deletions).
+ *
+ * @example
+ * const bf = new BloomFilter({ capacity: 1_000_000, errorRate: 0.01 });
+ * bf.add("hello");
+ * bf.has("hello"); // true
+ * bf.has("world"); // false (with high probability)
+ */
+declare class BloomFilter {
+    readonly capacity: number;
+    readonly errorRate: number;
+    /** Bit-array size. */
+    readonly m: number;
+    /** Number of hash functions. */
+    readonly k: number;
+    private readonly _bits;
+    private _count;
+    constructor(options: BloomFilterOptions);
+    /** Add an item to the filter. */
+    add(item: string): this;
+    /**
+     * Test membership. Returns `true` if item *may* have been added,
+     * `false` if it *definitely* has not.
+     */
+    has(item: string): boolean;
+    /** Number of items added (may exceed capacity). */
+    get size(): number;
+    /** Current estimated false-positive rate based on items inserted. */
+    get currentFPR(): number;
+    /** Reset the filter. */
+    clear(): this;
+    /** Serialize to a plain object for JSON.stringify. */
+    toJSON(): BloomFilterJSON;
+    /** Restore a BloomFilter from the output of `toJSON`. */
+    static fromJSON(data: BloomFilterJSON): BloomFilter;
+}
+
+interface CountingBloomFilterOptions {
+    /** Expected number of items. */
+    capacity: number;
+    /** Target false-positive rate (default: 0.01). */
+    errorRate?: number;
+    /** Counter width in bits — 4 (default) supports up to 15 adds per cell. */
+    counterBits?: 4 | 8;
+}
+/**
+ * Counting Bloom filter — supports deletion by maintaining per-cell counters
+ * instead of single bits.
+ *
+ * - `add(item)` increments k counters.
+ * - `remove(item)` decrements k counters. Do NOT remove items that were never added.
+ * - `has(item)` returns `true` iff all k counters are > 0.
+ *
+ * @example
+ * const cbf = new CountingBloomFilter({ capacity: 10_000 });
+ * cbf.add("user:42");
+ * cbf.has("user:42"); // true
+ * cbf.remove("user:42");
+ * cbf.has("user:42"); // false
+ */
+declare class CountingBloomFilter {
+    readonly capacity: number;
+    readonly errorRate: number;
+    readonly m: number;
+    readonly k: number;
+    private readonly _counters;
+    private readonly _counterBits;
+    private readonly _maxCount;
+    private _count;
+    constructor(options: CountingBloomFilterOptions);
+    private _get;
+    private _increment;
+    private _decrement;
+    /** Add an item to the filter. */
+    add(item: string): this;
+    /**
+     * Remove an item from the filter.
+     * Only remove items you previously added — removing items never added leads
+     * to false negatives.
+     */
+    remove(item: string): this;
+    /** Test membership. */
+    has(item: string): boolean;
+    /** Number of items currently in the filter (approximate). */
+    get size(): number;
+    /** Reset the filter. */
+    clear(): this;
+}
+
+interface ScalableBloomFilterOptions {
+    /**
+     * Initial capacity (items before first resize). Default: 1000.
+     */
+    initialCapacity?: number;
+    /**
+     * Target overall false-positive rate. Default: 0.01.
+     * Each sub-filter uses `errorRate * tighteningRatio^i` so the series
+     * converges to a total FPR ≤ `errorRate`.
+     */
+    errorRate?: number;
+    /**
+     * Scale factor: each new sub-filter has `scaleFactor × previous capacity`.
+     * Common values: 2 (default) or 4.
+     */
+    scaleFactor?: number;
+    /**
+     * Ratio by which each sub-filter tightens its FPR. Default: 0.9.
+     * Must be in (0, 1).
+     */
+    tighteningRatio?: number;
+}
+/**
+ * Scalable Bloom filter — grows automatically as items are added, so you
+ * don't need to know the final set size upfront.
+ *
+ * Maintains a series of standard BloomFilters; when the current one is full,
+ * a new one is created with higher capacity and tighter FPR.
+ *
+ * Port of Python pybloom-live's `ScalableBloomFilter`.
+ *
+ * @example
+ * const sbf = new ScalableBloomFilter({ errorRate: 0.01 });
+ * for (const id of millionIds) sbf.add(id);
+ * sbf.has(id); // reliable, even with 1M+ items
+ */
+declare class ScalableBloomFilter {
+    private readonly _initialCapacity;
+    private readonly _errorRate;
+    private readonly _scaleFactor;
+    private readonly _tighteningRatio;
+    private _filters;
+    private _count;
+    constructor(options?: ScalableBloomFilterOptions);
+    private _createFilter;
+    /** Add an item. The filter grows automatically when the current slice is full. */
+    add(item: string): this;
+    /**
+     * Test membership — checks all sub-filters.
+     * Returns `true` if item may have been added, `false` if definitely not.
+     */
+    has(item: string): boolean;
+    /** Total number of items added (approximate). */
+    get size(): number;
+    /** Number of internal sub-filters created so far. */
+    get filterCount(): number;
+    /** Total bits allocated across all sub-filters. */
+    get bitsAllocated(): number;
+    /** Target false-positive rate. */
+    get errorRate(): number;
+    /** Reset the filter. */
+    clear(): this;
+}
+
+/**
+ * MurmurHash3 (32-bit, x86) — fast non-cryptographic hash.
+ * Returns an unsigned 32-bit integer.
+ */
+declare function murmur3(key: string, seed?: number): number;
+/**
+ * FNV-1a (32-bit) — second independent hash for double-hashing.
+ */
+declare function fnv1a(key: string, seed?: number): number;
+/**
+ * Generate `k` hash positions in `[0, m)` using double hashing.
+ * gi(x) = (h1(x) + i * h2(x)) mod m
+ */
+declare function hashPositions(key: string, k: number, m: number): number[];
+
+/** Compact fixed-size bit array backed by Uint32Array. */
+declare class BitArray {
+    private readonly _buf;
+    readonly size: number;
+    constructor(size: number);
+    set(index: number): void;
+    get(index: number): boolean;
+    clear(): void;
+    /** Number of bits set to 1 (popcount). */
+    popcount(): number;
+    /** Export as a base64-encoded string for serialization. */
+    toBase64(): string;
+    /** Restore from a base64 string produced by `toBase64`. */
+    static fromBase64(b64: string, size: number): BitArray;
+}
+
+export { BitArray, BloomFilter, type BloomFilterJSON, type BloomFilterOptions, CountingBloomFilter, type CountingBloomFilterOptions, ScalableBloomFilter, type ScalableBloomFilterOptions, fnv1a, hashPositions, murmur3, optimalK, optimalM };

package/dist/index.d.ts

@@ -0,0 +1,214 @@
+/** @internal Compute optimal bit-array size m given n items and fpr. */
+declare function optimalM(n: number, fpr: number): number;
+/** @internal Compute optimal number of hash functions k given m bits and n items. */
+declare function optimalK(m: number, n: number): number;
+interface BloomFilterOptions {
+    /**
+     * Expected number of items that will be inserted.
+     * Used to size the filter optimally.
+     */
+    capacity: number;
+    /**
+     * Target false-positive rate (0 < fpr < 1). Default: 0.01 (1%).
+     */
+    errorRate?: number;
+}
+interface BloomFilterJSON {
+    type: "BloomFilter";
+    capacity: number;
+    errorRate: number;
+    m: number;
+    k: number;
+    bits: string;
+}
+/**
+ * Standard Bloom filter — space-efficient probabilistic set membership.
+ *
+ * - `add(item)` always works correctly.
+ * - `has(item)` may return `true` for items not added (false positive, rate ≤ `errorRate`).
+ * - `has(item)` never returns `false` for items that were added.
+ * - Items cannot be removed (use `CountingBloomFilter` for deletions).
+ *
+ * @example
+ * const bf = new BloomFilter({ capacity: 1_000_000, errorRate: 0.01 });
+ * bf.add("hello");
+ * bf.has("hello"); // true
+ * bf.has("world"); // false (with high probability)
+ */
+declare class BloomFilter {
+    readonly capacity: number;
+    readonly errorRate: number;
+    /** Bit-array size. */
+    readonly m: number;
+    /** Number of hash functions. */
+    readonly k: number;
+    private readonly _bits;
+    private _count;
+    constructor(options: BloomFilterOptions);
+    /** Add an item to the filter. */
+    add(item: string): this;
+    /**
+     * Test membership. Returns `true` if item *may* have been added,
+     * `false` if it *definitely* has not.
+     */
+    has(item: string): boolean;
+    /** Number of items added (may exceed capacity). */
+    get size(): number;
+    /** Current estimated false-positive rate based on items inserted. */
+    get currentFPR(): number;
+    /** Reset the filter. */
+    clear(): this;
+    /** Serialize to a plain object for JSON.stringify. */
+    toJSON(): BloomFilterJSON;
+    /** Restore a BloomFilter from the output of `toJSON`. */
+    static fromJSON(data: BloomFilterJSON): BloomFilter;
+}
+
+interface CountingBloomFilterOptions {
+    /** Expected number of items. */
+    capacity: number;
+    /** Target false-positive rate (default: 0.01). */
+    errorRate?: number;
+    /** Counter width in bits — 4 (default) supports up to 15 adds per cell. */
+    counterBits?: 4 | 8;
+}
+/**
+ * Counting Bloom filter — supports deletion by maintaining per-cell counters
+ * instead of single bits.
+ *
+ * - `add(item)` increments k counters.
+ * - `remove(item)` decrements k counters. Do NOT remove items that were never added.
+ * - `has(item)` returns `true` iff all k counters are > 0.
+ *
+ * @example
+ * const cbf = new CountingBloomFilter({ capacity: 10_000 });
+ * cbf.add("user:42");
+ * cbf.has("user:42"); // true
+ * cbf.remove("user:42");
+ * cbf.has("user:42"); // false
+ */
+declare class CountingBloomFilter {
+    readonly capacity: number;
+    readonly errorRate: number;
+    readonly m: number;
+    readonly k: number;
+    private readonly _counters;
+    private readonly _counterBits;
+    private readonly _maxCount;
+    private _count;
+    constructor(options: CountingBloomFilterOptions);
+    private _get;
+    private _increment;
+    private _decrement;
+    /** Add an item to the filter. */
+    add(item: string): this;
+    /**
+     * Remove an item from the filter.
+     * Only remove items you previously added — removing items never added leads
+     * to false negatives.
+     */
+    remove(item: string): this;
+    /** Test membership. */
+    has(item: string): boolean;
+    /** Number of items currently in the filter (approximate). */
+    get size(): number;
+    /** Reset the filter. */
+    clear(): this;
+}
+
+interface ScalableBloomFilterOptions {
+    /**
+     * Initial capacity (items before first resize). Default: 1000.
+     */
+    initialCapacity?: number;
+    /**
+     * Target overall false-positive rate. Default: 0.01.
+     * Each sub-filter uses `errorRate * tighteningRatio^i` so the series
+     * converges to a total FPR ≤ `errorRate`.
+     */
+    errorRate?: number;
+    /**
+     * Scale factor: each new sub-filter has `scaleFactor × previous capacity`.
+     * Common values: 2 (default) or 4.
+     */
+    scaleFactor?: number;
+    /**
+     * Ratio by which each sub-filter tightens its FPR. Default: 0.9.
+     * Must be in (0, 1).
+     */
+    tighteningRatio?: number;
+}
+/**
+ * Scalable Bloom filter — grows automatically as items are added, so you
+ * don't need to know the final set size upfront.
+ *
+ * Maintains a series of standard BloomFilters; when the current one is full,
+ * a new one is created with higher capacity and tighter FPR.
+ *
+ * Port of Python pybloom-live's `ScalableBloomFilter`.
+ *
+ * @example
+ * const sbf = new ScalableBloomFilter({ errorRate: 0.01 });
+ * for (const id of millionIds) sbf.add(id);
+ * sbf.has(id); // reliable, even with 1M+ items
+ */
+declare class ScalableBloomFilter {
+    private readonly _initialCapacity;
+    private readonly _errorRate;
+    private readonly _scaleFactor;
+    private readonly _tighteningRatio;
+    private _filters;
+    private _count;
+    constructor(options?: ScalableBloomFilterOptions);
+    private _createFilter;
+    /** Add an item. The filter grows automatically when the current slice is full. */
+    add(item: string): this;
+    /**
+     * Test membership — checks all sub-filters.
+     * Returns `true` if item may have been added, `false` if definitely not.
+     */
+    has(item: string): boolean;
+    /** Total number of items added (approximate). */
+    get size(): number;
+    /** Number of internal sub-filters created so far. */
+    get filterCount(): number;
+    /** Total bits allocated across all sub-filters. */
+    get bitsAllocated(): number;
+    /** Target false-positive rate. */
+    get errorRate(): number;
+    /** Reset the filter. */
+    clear(): this;
+}
+
+/**
+ * MurmurHash3 (32-bit, x86) — fast non-cryptographic hash.
+ * Returns an unsigned 32-bit integer.
+ */
+declare function murmur3(key: string, seed?: number): number;
+/**
+ * FNV-1a (32-bit) — second independent hash for double-hashing.
+ */
+declare function fnv1a(key: string, seed?: number): number;
+/**
+ * Generate `k` hash positions in `[0, m)` using double hashing.
+ * gi(x) = (h1(x) + i * h2(x)) mod m
+ */
+declare function hashPositions(key: string, k: number, m: number): number[];
+
+/** Compact fixed-size bit array backed by Uint32Array. */
+declare class BitArray {
+    private readonly _buf;
+    readonly size: number;
+    constructor(size: number);
+    set(index: number): void;
+    get(index: number): boolean;
+    clear(): void;
+    /** Number of bits set to 1 (popcount). */
+    popcount(): number;
+    /** Export as a base64-encoded string for serialization. */
+    toBase64(): string;
+    /** Restore from a base64 string produced by `toBase64`. */
+    static fromBase64(b64: string, size: number): BitArray;
+}
+
+export { BitArray, BloomFilter, type BloomFilterJSON, type BloomFilterOptions, CountingBloomFilter, type CountingBloomFilterOptions, ScalableBloomFilter, type ScalableBloomFilterOptions, fnv1a, hashPositions, murmur3, optimalK, optimalM };