distillate 0.8.2 → 0.10.0

package/README.md

@@ -42,11 +42,16 @@ Every push runs a CI smoke matrix that imports the built package on Node 22/24,
 
 Each structure ships as its own subpath, so you only bundle what you import.
 
-| Import               | Structure     | Mutable? | Use for                                                  |
-| -------------------- | ------------- | -------- | -------------------------------------------------------- |
-| `distillate/bloom`   | Classic Bloom | yes      | Familiar default, migration from `bloom-filters`         |
-| `distillate/blocked` | Blocked Bloom | yes      | Faster lookups and a lower FPR for a small space premium |
-| `distillate/fuse`    | Binary Fuse   | no       | Static set built once and queried a lot; least space     |
+| Import               | Structure     | Answers            | Use for                                                  |
+| -------------------- | ------------- | ------------------ | -------------------------------------------------------- |
+| `distillate/bloom`   | Classic Bloom | seen this key?     | Familiar default, migration from `bloom-filters`         |
+| `distillate/blocked` | Blocked Bloom | seen this key?     | Faster lookups and a lower FPR for a small space premium |
+| `distillate/fuse`    | Binary Fuse   | seen this key?     | Static set built once and queried a lot; least space     |
+| `distillate/hll`     | HyperLogLog   | how many distinct? | Counting distinct users, IPs, or keys in fixed space     |
+
+The filters are mutable except Binary Fuse, which is built once from the whole
+key set. HyperLogLog is not a filter: it counts distinct keys and cannot report
+whether it saw any particular one.
 
 ### Classic Bloom (`distillate/bloom`)
 
@@ -86,7 +91,7 @@ import { BinaryFuse8, BinaryFuse16 } from "distillate/fuse";
 const filter = BinaryFuse8.from(["alice", "bob", "carol"]);
 filter.has("alice"); // true
 filter.size; // 3
-filter.bitsPerKey; // 64 at this size; see below
+filter.bitsPerKey; // 64
 
 // Lower false-positive rate, twice the space:
 const precise = BinaryFuse16.from(["alice", "bob", "carol"]);
@@ -96,6 +101,29 @@ const precise = BinaryFuse16.from(["alice", "bob", "carol"]);
 
 Also: `toBytes` / `fromBytes`. No `add` / `delete`; rebuild `from` the new set to change membership.
 
+### HyperLogLog (`distillate/hll`)
+
+A **sketch**, not a filter: it counts distinct keys in space fixed by precision rather than by the answer, and cannot report whether it saw any particular key. 12 KiB counts a thousand distinct keys or a billion, at about 0.8% relative error. Full API and sizing: [HyperLogLog guide](https://distillate.akxp.net/guides/hll/).
+
+```ts
+import { HyperLogLog } from "distillate/hll";
+
+const sketch = HyperLogLog.create(0.01); // target relative error
+sketch.add("alice");
+sketch.add("bob");
+sketch.add("alice"); // already counted
+
+sketch.count(); // 2
+
+// Merge per-shard sketches without double-counting the overlap:
+const other = HyperLogLog.from(["bob", "carol"], 0.01);
+sketch.union(other).count(); // 3
+```
+
+Below a few thousand distinct keys the sketch counts rather than estimates, so small answers are exact. It switches to fixed-size registers on its own once that stops paying, with nothing to configure.
+
+Also: `equals`, `toBytes` / `fromBytes`, `toJSON` / `fromJSON`, `standardError`, `hllSizing(relativeError)`, and a low-level `new HyperLogLog({ p, seed })`.
+
 ## Performance
 
 Classic Bloom head-to-head at a **matched 1% false-positive rate** over the same 100k keys, measured by identical code (cross-library harness, node v24.14.1, Apple M5):
@@ -107,6 +135,25 @@ Classic Bloom head-to-head at a **matched 1% false-positive rate** over the same
 
 Same space, same accuracy, **~75x the lookup throughput** of [`bloom-filters`](https://www.npmjs.com/package/bloom-filters) (the package distillate replaces), while hashing UTF-8 bytes with MurmurHash3 so filters stay portable and cross-language readable.
 
+Cardinality is a separate head-to-head, at a **matched register count** (`m = 2 ** p`, `p = 14`, the configuration Redis uses) over the same keys, swept from 1k to 10M distinct:
+
+| p = 14, m = 16384    | distillate      | bloom-filters    |
+| -------------------- | --------------- | ---------------- |
+| rel. error, n=1k     | 0.00%           | 49.63%           |
+| rel. error, n=100k   | 0.82%           | 0.78%            |
+| rel. error, n=10M    | 0.15%           | 0.41%            |
+| serialized, n=10M    | 12,314 B binary | 40,247 B JSON    |
+| build 10M keys       | 0.63 s          | 1,165 s (19 min) |
+| sustained add, n=10M | ~16 M ops/s     | ~9 k ops/s       |
+
+Both sketches carry the same theoretical error at this precision (`1.04 / sqrt(m)`, about 0.81%), and once `n` is well past `m` both stay inside it. The differences are elsewhere.
+
+**Small counts.** `bloom-filters` has no working small-range correction, so below roughly `2.5 * m` it is off by about half: counting a few thousand distinct keys in a 16k-register sketch, it answers 504 for 1,000. distillate is exact there because it is still holding sparse entries, not because its estimator is better.
+
+**Memory does not grow.** From 10k distinct keys to 10M, distillate stays at exactly 12,314 bytes. The incumbent's JSON grows from 32,904 to 40,247 bytes over the same range, because larger register values take more digits to spell out.
+
+**Building the sketch.** `bloom-filters` holds a flat 9k adds/sec at every size, so its cost is purely linear: 10.6 seconds for 100k distinct keys, 109 seconds for 1M, and 1,165 seconds for 10M. distillate counts the same 10M in 0.63 seconds, and its rate climbs with `n` rather than staying flat, reaching about 16 M ops/s once the registers are dense.
+
 These are a point-in-time snapshot on one machine. The full report (blocked/fuse, 1M capacity, the `bloomfilter` micro-package) and exactly how it is measured live in the [`apps/bench`](https://github.com/akshay-xp/distillate/tree/main/apps/bench) workspace: [RESULTS.md](https://github.com/akshay-xp/distillate/blob/main/apps/bench/RESULTS.md), [METHODOLOGY.md](https://github.com/akshay-xp/distillate/blob/main/apps/bench/METHODOLOGY.md).
 
 ## Docs

package/dist/blocked/index.cjs

@@ -1,8 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_serialize = require("../serialize-CXnRWItH.cjs");
+const require_hasher = require("../hasher-D8LCBTOM.cjs");
+const require_serialize = require("../serialize-CHikZ4GH.cjs");
 const require_params = require("../params-UTZbJ22c.cjs");
 //#region src/blocked/blocked.ts
 const TYPE = 2;
+const PARAMS_SIZE = 16;
+const PARAMS_FIELDS_END = 12;
 const SALT = Uint32Array.of(1203114875, 1150766481, 2284105051, 2729912477, 1884591559, 770785867, 2667333959, 1550580529);
 const scratch2 = new Uint32Array(2);
 const BLOCK_BITS = 256;
@@ -89,30 +92,31 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	}
 	static fromBytes(bytes) {
 		const { type, flags, body } = require_serialize.readHeader(bytes);
-		if (type !== TYPE) throw new require_serialize.SerializationError(`expected AMQF type ${String(TYPE)}, got ${String(type)}`);
+		if (type !== TYPE) throw new require_serialize.SerializationError(`expected DSTL type ${String(TYPE)}, got ${String(type)}`);
 		if ((flags & 15) !== 0) throw new require_serialize.UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
-		require_serialize.assertMinBodyLength(body.length, 12, "blocked");
+		require_serialize.assertMinBodyLength(body.length, PARAMS_SIZE, "blocked");
+		require_serialize.assertParamsPadding(body, PARAMS_FIELDS_END, PARAMS_SIZE, "blocked");
 		const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
 		const numBlocks = dv.getUint32(0, true);
 		const seed = dv.getUint32(4, true);
 		const n = dv.getUint32(8, true);
 		if (numBlocks === 0 || n === 0) throw new require_serialize.SerializationError(`blocked frame declares numBlocks=${String(numBlocks)}, n=${String(n)}; both must be positive`);
-		require_serialize.assertBodyLength(body.length, 12 + numBlocks * 32, "blocked");
+		require_serialize.assertBodyLength(body.length, PARAMS_SIZE + numBlocks * 32, "blocked");
 		const f = BlockedBloomFilter.#fromNumBlocks(numBlocks, seed, n);
-		new Uint8Array(f.#lanes.buffer).set(body.subarray(12));
+		new Uint8Array(f.#lanes.buffer).set(body.subarray(PARAMS_SIZE));
 		return f;
 	}
 	toBytes() {
 		const lanes = new Uint8Array(this.#lanes.buffer, this.#lanes.byteOffset, this.#lanes.byteLength);
 		return require_serialize.writeFrame({
-			version: 3,
+			version: 5,
 			type: TYPE,
 			flags: 0
-		}, 12 + lanes.length, (body, dv) => {
+		}, PARAMS_SIZE, lanes.length, (body, dv) => {
 			dv.setUint32(0, this.#numBlocks, true);
 			dv.setUint32(4, this.#seed, true);
 			dv.setUint32(8, this.#n, true);
-			body.set(lanes, 12);
+			body.set(lanes, PARAMS_SIZE);
 		});
 	}
 	equals(other) {
@@ -147,8 +151,8 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	}
 };
 function fillBlock(key, numBlocks, seed, outWords, outBits) {
-	require_serialize.hash32x2Into(key, seed, scratch2);
-	const block = require_serialize.reduce(scratch2[0] ?? 0, numBlocks);
+	require_hasher.hash32x2Into(key, seed, scratch2);
+	const block = require_hasher.reduce(scratch2[0] ?? 0, numBlocks);
 	const x = scratch2[1] ?? 0;
 	const base = block * 8;
 	for (let i = 0; i < 8; i++) {
@@ -162,6 +166,7 @@ exports.BlockedBloomFilter = BlockedBloomFilter;
 exports.BlockedBloomParamMismatchError = BlockedBloomParamMismatchError;
 exports.ChecksumError = require_serialize.ChecksumError;
 exports.ParamError = require_params.ParamError;
+exports.ReservedBitsError = require_serialize.ReservedBitsError;
 exports.SerializationError = require_serialize.SerializationError;
 exports.TruncatedError = require_serialize.TruncatedError;
 exports.UnknownHashVariantError = require_serialize.UnknownHashVariantError;

package/dist/blocked/index.d.cts

@@ -1,4 +1,5 @@
-import { a as TruncatedError, c as BytesLike, i as SerializationError, n as ChecksumError, o as UnknownHashVariantError, r as FilterJSON, s as UnknownVersionError, t as BadMagicError } from "../serialize-ChyWpB9F.cjs";
+import { t as BytesLike } from "../bytes-DCuYtUVS.cjs";
+import { a as ReservedBitsError, c as UnknownHashVariantError, l as UnknownVersionError, n as ChecksumError, o as SerializationError, r as FilterJSON, s as TruncatedError, t as BadMagicError } from "../serialize--xR6vGSW.cjs";
 import { t as ParamError } from "../params-DnqJBqLS.cjs";
 //#region src/blocked/blocked.d.ts
 /**
@@ -8,16 +9,16 @@ import { t as ParamError } from "../params-DnqJBqLS.cjs";
  * `lambda = 256 / bitsPerKey`. This clustering average is why the blocked curve
  * is not linear in `log10(1/epsilon)`.
  */
-declare function blockedFprAt(bitsPerKey: number): number;
+export declare function blockedFprAt(bitsPerKey: number): number;
 /**
  * Minimal integer bits-per-key whose modeled split-block FPR is at or below
  * `epsilon`. Throws {@link ParamError} when even the densest supported filter
  * cannot reach the target, so callers get a typed rejection instead of a
  * silently under-provisioned filter.
  */
-declare function blockedBitsPerKey(epsilon: number): number;
+export declare function blockedBitsPerKey(epsilon: number): number;
 /** Thrown when an operation requires two filters built with identical parameters. */
-declare class BlockedBloomParamMismatchError extends Error {
+export declare class BlockedBloomParamMismatchError extends Error {
   /** Discriminates this error from other `Error`s. */
   override readonly name = "BlockedBloomParamMismatchError";
 }
@@ -41,7 +42,7 @@ interface BlockedBloomParams {
  * filter.has("alice"); // true
  * ```
  */
-declare class BlockedBloomFilter {
+export declare class BlockedBloomFilter {
   #private;
   /**
    * Creates a filter sized for `n` expected keys at a target false-positive rate.
@@ -142,4 +143,4 @@ declare class BlockedBloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BadMagicError, BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams, ChecksumError, type FilterJSON, ParamError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, blockedBitsPerKey, blockedFprAt };
+export { BadMagicError, type BlockedBloomParams, ChecksumError, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError };

package/dist/blocked/index.d.ts

@@ -1,4 +1,5 @@
-import { a as TruncatedError, c as BytesLike, i as SerializationError, n as ChecksumError, o as UnknownHashVariantError, r as FilterJSON, s as UnknownVersionError, t as BadMagicError } from "../serialize-ChyWpB9F.js";
+import { t as BytesLike } from "../bytes-DCuYtUVS.js";
+import { a as ReservedBitsError, c as UnknownHashVariantError, l as UnknownVersionError, n as ChecksumError, o as SerializationError, r as FilterJSON, s as TruncatedError, t as BadMagicError } from "../serialize--xR6vGSW.js";
 import { t as ParamError } from "../params-DnqJBqLS.js";
 //#region src/blocked/blocked.d.ts
 /**
@@ -8,16 +9,16 @@ import { t as ParamError } from "../params-DnqJBqLS.js";
  * `lambda = 256 / bitsPerKey`. This clustering average is why the blocked curve
  * is not linear in `log10(1/epsilon)`.
  */
-declare function blockedFprAt(bitsPerKey: number): number;
+export declare function blockedFprAt(bitsPerKey: number): number;
 /**
  * Minimal integer bits-per-key whose modeled split-block FPR is at or below
  * `epsilon`. Throws {@link ParamError} when even the densest supported filter
  * cannot reach the target, so callers get a typed rejection instead of a
  * silently under-provisioned filter.
  */
-declare function blockedBitsPerKey(epsilon: number): number;
+export declare function blockedBitsPerKey(epsilon: number): number;
 /** Thrown when an operation requires two filters built with identical parameters. */
-declare class BlockedBloomParamMismatchError extends Error {
+export declare class BlockedBloomParamMismatchError extends Error {
   /** Discriminates this error from other `Error`s. */
   override readonly name = "BlockedBloomParamMismatchError";
 }
@@ -41,7 +42,7 @@ interface BlockedBloomParams {
  * filter.has("alice"); // true
  * ```
  */
-declare class BlockedBloomFilter {
+export declare class BlockedBloomFilter {
   #private;
   /**
    * Creates a filter sized for `n` expected keys at a target false-positive rate.
@@ -142,4 +143,4 @@ declare class BlockedBloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BadMagicError, BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams, ChecksumError, type FilterJSON, ParamError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, blockedBitsPerKey, blockedFprAt };
+export { BadMagicError, type BlockedBloomParams, ChecksumError, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError };

package/dist/blocked/index.js

@@ -1,7 +1,10 @@
-import { a as UnknownHashVariantError, c as assertMinBodyLength, d as readHeader, f as toJSONEnvelope, i as TruncatedError, l as bytesEqual, n as ChecksumError, o as UnknownVersionError, p as writeFrame, r as SerializationError, s as assertBodyLength, t as BadMagicError, u as fromJSONEnvelope, v as hash32x2Into, x as reduce } from "../serialize-BqIcsR2J.js";
+import { a as hash32x2Into, c as reduce } from "../hasher-DVWXS_vJ.js";
+import { a as TruncatedError, c as assertBodyLength, d as bytesEqual, f as fromJSONEnvelope, g as writeFrame, h as toJSONEnvelope, i as SerializationError, l as assertMinBodyLength, m as readHeader, n as ChecksumError, o as UnknownHashVariantError, r as ReservedBitsError, s as UnknownVersionError, t as BadMagicError, u as assertParamsPadding } from "../serialize-CMSYFym-.js";
 import { i as assertProbability, n as assertPositiveFinite, o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-CeajSrwv.js";
 //#region src/blocked/blocked.ts
 const TYPE = 2;
+const PARAMS_SIZE = 16;
+const PARAMS_FIELDS_END = 12;
 const SALT = Uint32Array.of(1203114875, 1150766481, 2284105051, 2729912477, 1884591559, 770785867, 2667333959, 1550580529);
 const scratch2 = new Uint32Array(2);
 const BLOCK_BITS = 256;
@@ -88,30 +91,31 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	}
 	static fromBytes(bytes) {
 		const { type, flags, body } = readHeader(bytes);
-		if (type !== TYPE) throw new SerializationError(`expected AMQF type ${String(TYPE)}, got ${String(type)}`);
+		if (type !== TYPE) throw new SerializationError(`expected DSTL type ${String(TYPE)}, got ${String(type)}`);
 		if ((flags & 15) !== 0) throw new UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
-		assertMinBodyLength(body.length, 12, "blocked");
+		assertMinBodyLength(body.length, PARAMS_SIZE, "blocked");
+		assertParamsPadding(body, PARAMS_FIELDS_END, PARAMS_SIZE, "blocked");
 		const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
 		const numBlocks = dv.getUint32(0, true);
 		const seed = dv.getUint32(4, true);
 		const n = dv.getUint32(8, true);
 		if (numBlocks === 0 || n === 0) throw new SerializationError(`blocked frame declares numBlocks=${String(numBlocks)}, n=${String(n)}; both must be positive`);
-		assertBodyLength(body.length, 12 + numBlocks * 32, "blocked");
+		assertBodyLength(body.length, PARAMS_SIZE + numBlocks * 32, "blocked");
 		const f = BlockedBloomFilter.#fromNumBlocks(numBlocks, seed, n);
-		new Uint8Array(f.#lanes.buffer).set(body.subarray(12));
+		new Uint8Array(f.#lanes.buffer).set(body.subarray(PARAMS_SIZE));
 		return f;
 	}
 	toBytes() {
 		const lanes = new Uint8Array(this.#lanes.buffer, this.#lanes.byteOffset, this.#lanes.byteLength);
 		return writeFrame({
-			version: 3,
+			version: 5,
 			type: TYPE,
 			flags: 0
-		}, 12 + lanes.length, (body, dv) => {
+		}, PARAMS_SIZE, lanes.length, (body, dv) => {
 			dv.setUint32(0, this.#numBlocks, true);
 			dv.setUint32(4, this.#seed, true);
 			dv.setUint32(8, this.#n, true);
-			body.set(lanes, 12);
+			body.set(lanes, PARAMS_SIZE);
 		});
 	}
 	equals(other) {
@@ -156,4 +160,4 @@ function fillBlock(key, numBlocks, seed, outWords, outBits) {
 	}
 }
 //#endregion
-export { BadMagicError, BlockedBloomFilter, BlockedBloomParamMismatchError, ChecksumError, ParamError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, blockedBitsPerKey, blockedFprAt };
+export { BadMagicError, BlockedBloomFilter, BlockedBloomParamMismatchError, ChecksumError, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, blockedBitsPerKey, blockedFprAt };

package/dist/bloom/index.cjs

@@ -1,6 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_serialize = require("../serialize-CXnRWItH.cjs");
+const require_hasher = require("../hasher-D8LCBTOM.cjs");
+const require_serialize = require("../serialize-CHikZ4GH.cjs");
 const require_params = require("../params-UTZbJ22c.cjs");
+const require_sizing = require("../sizing-BLzZk2zr.cjs");
 //#region src/core/bitset.ts
 var BitSetRangeError = class extends RangeError {
 	name = "BitSetRangeError";
@@ -32,17 +34,10 @@ var BitSet = class {
 	}
 };
 //#endregion
-//#region src/core/sizing.ts
-function bloomSizing(n, epsilon) {
-	const m = Math.ceil(-n * Math.log(epsilon) / (Math.LN2 * Math.LN2));
-	return {
-		m,
-		k: Math.max(1, Math.round(m / n * Math.LN2))
-	};
-}
-//#endregion
 //#region src/bloom/bloom.ts
 const TYPE = 1;
+const PARAMS_SIZE = 16;
+const PARAMS_FIELDS_END = 14;
 var BloomParamMismatchError = class extends Error {
 	name = "BloomParamMismatchError";
 };
@@ -57,7 +52,10 @@ var BloomFilter = class BloomFilter {
 		require_params.assertPositiveInt(n, "n");
 		require_params.assertUint32(n, "n");
 		require_params.assertProbability(epsilon, "epsilon");
-		return BloomFilter.#withN(bloomSizing(n, epsilon), n);
+		return new BloomFilter({
+			...require_sizing.bloomSizing(n, epsilon),
+			n
+		});
 	}
 	static from(keys, epsilon) {
 		const arr = [...keys];
@@ -67,40 +65,41 @@ var BloomFilter = class BloomFilter {
 	}
 	static fromBytes(bytes) {
 		const { type, flags, body } = require_serialize.readHeader(bytes);
-		if (type !== TYPE) throw new require_serialize.SerializationError(`expected AMQF type ${String(TYPE)}, got ${String(type)}`);
+		if (type !== TYPE) throw new require_serialize.SerializationError(`expected DSTL type ${String(TYPE)}, got ${String(type)}`);
 		if ((flags & 15) !== 0) throw new require_serialize.UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
-		require_serialize.assertMinBodyLength(body.length, 14, "bloom");
+		require_serialize.assertMinBodyLength(body.length, PARAMS_SIZE, "bloom");
+		require_serialize.assertParamsPadding(body, PARAMS_FIELDS_END, PARAMS_SIZE, "bloom");
 		const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
 		const m = dv.getUint32(0, true);
 		const k = dv.getUint16(4, true);
 		const seed = dv.getUint32(6, true);
 		const n = dv.getUint32(10, true);
-		require_serialize.assertBodyLength(body.length, 14 + Math.ceil(m / 8), "bloom");
-		const f = BloomFilter.#withN({
+		require_serialize.assertBodyLength(body.length, PARAMS_SIZE + Math.ceil(m / 8), "bloom");
+		const f = new BloomFilter({
 			m,
 			k,
-			seed
-		}, n);
-		f.#bits.bytes.set(body.subarray(14));
+			seed,
+			n
+		});
+		f.#bits.bytes.set(body.subarray(PARAMS_SIZE));
 		return f;
 	}
-	constructor({ m, k, seed = 0 }) {
+	constructor({ m, k, seed = 0, n }) {
 		require_params.assertPositiveInt(m, "m");
 		require_params.assertUint32(m, "m");
 		require_params.assertPositiveInt(k, "k");
 		require_params.assertUint16(k, "k");
 		require_params.assertUint32(seed, "seed");
+		if (n !== void 0) {
+			require_params.assertPositiveInt(n, "n");
+			require_params.assertUint32(n, "n");
+		}
 		this.#bits = new BitSet(m);
 		this.#m = m;
 		this.#k = k;
 		this.#seed = seed;
 		this.#scratch = new Uint32Array(k);
-		this.#n = Math.round(m * Math.LN2 / k);
-	}
-	static #withN(params, n) {
-		const f = new BloomFilter(params);
-		f.#n = n;
-		return f;
+		this.#n = n ?? Math.max(1, Math.round(m * Math.LN2 / k));
 	}
 	get m() {
 		return this.#m;
@@ -123,15 +122,15 @@ var BloomFilter = class BloomFilter {
 	toBytes() {
 		const payload = this.#bits.bytes;
 		return require_serialize.writeFrame({
-			version: 3,
+			version: 5,
 			type: TYPE,
 			flags: 0
-		}, 14 + payload.length, (body, dv) => {
+		}, PARAMS_SIZE, payload.length, (body, dv) => {
 			dv.setUint32(0, this.#m, true);
 			dv.setUint16(4, this.#k, true);
 			dv.setUint32(6, this.#seed, true);
 			dv.setUint32(10, this.#n, true);
-			body.set(payload, 14);
+			body.set(payload, PARAMS_SIZE);
 		});
 	}
 	equals(other) {
@@ -149,20 +148,21 @@ var BloomFilter = class BloomFilter {
 		const b = other.#bits.bytes;
 		const merged = new Uint8Array(a.length);
 		for (let i = 0; i < a.length; i++) merged[i] = (a[i] ?? 0) | (b[i] ?? 0);
-		const r = BloomFilter.#withN({
+		const r = new BloomFilter({
 			m: this.#m,
 			k: this.#k,
-			seed: this.#seed
-		}, this.#n);
+			seed: this.#seed,
+			n: this.#n
+		});
 		r.#bits.bytes.set(merged);
 		return r;
 	}
 	add(key) {
-		require_serialize.probeInto(key, this.#k, this.#m, this.#seed, this.#scratch);
+		require_hasher.probeInto(key, this.#k, this.#m, this.#seed, this.#scratch);
 		for (let i = 0; i < this.#k; i++) this.#bits.set(this.#scratch[i] ?? 0);
 	}
 	has(key) {
-		require_serialize.probeInto(key, this.#k, this.#m, this.#seed, this.#scratch);
+		require_hasher.probeInto(key, this.#k, this.#m, this.#seed, this.#scratch);
 		for (let i = 0; i < this.#k; i++) if (!this.#bits.get(this.#scratch[i] ?? 0)) return false;
 		return true;
 	}
@@ -173,8 +173,9 @@ exports.BloomFilter = BloomFilter;
 exports.BloomParamMismatchError = BloomParamMismatchError;
 exports.ChecksumError = require_serialize.ChecksumError;
 exports.ParamError = require_params.ParamError;
+exports.ReservedBitsError = require_serialize.ReservedBitsError;
 exports.SerializationError = require_serialize.SerializationError;
 exports.TruncatedError = require_serialize.TruncatedError;
 exports.UnknownHashVariantError = require_serialize.UnknownHashVariantError;
 exports.UnknownVersionError = require_serialize.UnknownVersionError;
-exports.bloomSizing = bloomSizing;
+exports.bloomSizing = require_sizing.bloomSizing;

package/dist/bloom/index.d.cts

@@ -1,8 +1,10 @@
-import { a as TruncatedError, c as BytesLike, i as SerializationError, n as ChecksumError, o as UnknownHashVariantError, r as FilterJSON, s as UnknownVersionError, t as BadMagicError } from "../serialize-ChyWpB9F.cjs";
+import { t as BytesLike } from "../bytes-DCuYtUVS.cjs";
+import { a as ReservedBitsError, c as UnknownHashVariantError, l as UnknownVersionError, n as ChecksumError, o as SerializationError, r as FilterJSON, s as TruncatedError, t as BadMagicError } from "../serialize--xR6vGSW.cjs";
 import { t as ParamError } from "../params-DnqJBqLS.cjs";
+import { r as bloomSizing, t as BloomSizing } from "../sizing-wYOW27eY.cjs";
 //#region src/bloom/bloom.d.ts
 /** Thrown when an operation requires two filters built with identical parameters. */
-declare class BloomParamMismatchError extends Error {
+export declare class BloomParamMismatchError extends Error {
   /** Discriminates this error from other `Error`s. */
   override readonly name = "BloomParamMismatchError";
 }
@@ -14,6 +16,12 @@ interface BloomParams {
   k: number;
   /** Hash seed; defaults to `0`. */
   seed?: number;
+  /**
+   * Expected number of keys. Omitted, it is derived as `m * ln2 / k`, the
+   * count this geometry is optimal for, which need not be the count the
+   * geometry was solved for.
+   */
+  n?: number;
 }
 /**
  * A classic Bloom filter: a space-efficient set with a tunable false-positive
@@ -27,7 +35,7 @@ interface BloomParams {
  * filter.has("bob"); // false (or a ~1% false positive)
  * ```
  */
-declare class BloomFilter {
+export declare class BloomFilter {
   #private;
   /**
    * Creates a filter sized for `n` expected keys at a target false-positive rate.
@@ -58,7 +66,7 @@ declare class BloomFilter {
    * Constructs a filter from low-level {@link BloomParams}. Prefer
    * {@link BloomFilter.create} unless restoring a specific configuration.
    */
-  constructor({ m, k, seed }: BloomParams);
+  constructor({ m, k, seed, n }: BloomParams);
   /** Number of bits in the filter. */
   get m(): number;
   /** Number of hash probes per key. */
@@ -67,7 +75,15 @@ declare class BloomFilter {
   get seed(): number;
   /** Number of bits currently set. */
   get length(): number;
-  /** Analytic design bits-per-key `m / n`. */
+  /**
+   * Analytic design bits-per-key, `m / n`.
+   *
+   * A filter built without an explicit `n` derives one as `m * ln2 / k`, the
+   * count its geometry is optimal for. That need not be the count the
+   * geometry was solved for, so the same `m` and `k` can report a different
+   * cost depending on how the filter was constructed. `create` and
+   * `fromBytes` always carry the real `n`.
+   */
   get bitsPerKey(): number;
   /**
    * Estimates the current false-positive rate from the actual fill,
@@ -128,15 +144,4 @@ declare class BloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-//#region src/core/sizing.d.ts
-/** Bloom filter geometry: the `BloomParams` fields a sizing solve determines. */
-interface BloomSizing {
-  /** Number of bits in the filter. */
-  m: number;
-  /** Number of hash probes per key. */
-  k: number;
-}
-/** Optimal Bloom-filter sizing: `m` bits and `k` hashes for `n` items at target FPR `epsilon`. */
-declare function bloomSizing(n: number, epsilon: number): BloomSizing;
-//#endregion
-export { BadMagicError, BloomFilter, BloomParamMismatchError, type BloomParams, type BloomSizing, ChecksumError, type FilterJSON, ParamError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, bloomSizing };
+export { BadMagicError, type BloomParams, type BloomSizing, ChecksumError, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, bloomSizing };

package/dist/bloom/index.d.ts

@@ -1,8 +1,10 @@
-import { a as TruncatedError, c as BytesLike, i as SerializationError, n as ChecksumError, o as UnknownHashVariantError, r as FilterJSON, s as UnknownVersionError, t as BadMagicError } from "../serialize-ChyWpB9F.js";
+import { t as BytesLike } from "../bytes-DCuYtUVS.js";
+import { a as ReservedBitsError, c as UnknownHashVariantError, l as UnknownVersionError, n as ChecksumError, o as SerializationError, r as FilterJSON, s as TruncatedError, t as BadMagicError } from "../serialize--xR6vGSW.js";
 import { t as ParamError } from "../params-DnqJBqLS.js";
+import { r as bloomSizing, t as BloomSizing } from "../sizing-wYOW27eY.js";
 //#region src/bloom/bloom.d.ts
 /** Thrown when an operation requires two filters built with identical parameters. */
-declare class BloomParamMismatchError extends Error {
+export declare class BloomParamMismatchError extends Error {
   /** Discriminates this error from other `Error`s. */
   override readonly name = "BloomParamMismatchError";
 }
@@ -14,6 +16,12 @@ interface BloomParams {
   k: number;
   /** Hash seed; defaults to `0`. */
   seed?: number;
+  /**
+   * Expected number of keys. Omitted, it is derived as `m * ln2 / k`, the
+   * count this geometry is optimal for, which need not be the count the
+   * geometry was solved for.
+   */
+  n?: number;
 }
 /**
  * A classic Bloom filter: a space-efficient set with a tunable false-positive
@@ -27,7 +35,7 @@ interface BloomParams {
  * filter.has("bob"); // false (or a ~1% false positive)
  * ```
  */
-declare class BloomFilter {
+export declare class BloomFilter {
   #private;
   /**
    * Creates a filter sized for `n` expected keys at a target false-positive rate.
@@ -58,7 +66,7 @@ declare class BloomFilter {
    * Constructs a filter from low-level {@link BloomParams}. Prefer
    * {@link BloomFilter.create} unless restoring a specific configuration.
    */
-  constructor({ m, k, seed }: BloomParams);
+  constructor({ m, k, seed, n }: BloomParams);
   /** Number of bits in the filter. */
   get m(): number;
   /** Number of hash probes per key. */
@@ -67,7 +75,15 @@ declare class BloomFilter {
   get seed(): number;
   /** Number of bits currently set. */
   get length(): number;
-  /** Analytic design bits-per-key `m / n`. */
+  /**
+   * Analytic design bits-per-key, `m / n`.
+   *
+   * A filter built without an explicit `n` derives one as `m * ln2 / k`, the
+   * count its geometry is optimal for. That need not be the count the
+   * geometry was solved for, so the same `m` and `k` can report a different
+   * cost depending on how the filter was constructed. `create` and
+   * `fromBytes` always carry the real `n`.
+   */
   get bitsPerKey(): number;
   /**
    * Estimates the current false-positive rate from the actual fill,
@@ -128,15 +144,4 @@ declare class BloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-//#region src/core/sizing.d.ts
-/** Bloom filter geometry: the `BloomParams` fields a sizing solve determines. */
-interface BloomSizing {
-  /** Number of bits in the filter. */
-  m: number;
-  /** Number of hash probes per key. */
-  k: number;
-}
-/** Optimal Bloom-filter sizing: `m` bits and `k` hashes for `n` items at target FPR `epsilon`. */
-declare function bloomSizing(n: number, epsilon: number): BloomSizing;
-//#endregion
-export { BadMagicError, BloomFilter, BloomParamMismatchError, type BloomParams, type BloomSizing, ChecksumError, type FilterJSON, ParamError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, bloomSizing };
+export { BadMagicError, type BloomParams, type BloomSizing, ChecksumError, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, bloomSizing };