distillate 0.4.0 → 0.6.0

package/dist/blocked/index.js

@@ -1,14 +1,41 @@
-import { a as writeHeader, c as reduce, i as readHeader, n as assertBodyLength, o as hash128KeyInto, r as assertMinBodyLength, t as SerializationError } from "../serialize-DkkBKDT0.js";
-import { a as assertUint32, i as assertProbability, n as assertPositiveFinite, r as assertPositiveInt, t as ParamError } from "../params-ChTRNxM9.js";
+import { _ as reduce, a as bytesEqual, c as toJSONEnvelope, i as assertMinBodyLength, l as writeFrame, m as hash32x2Into, n as UnknownHashVariantError, o as fromJSONEnvelope, r as assertBodyLength, s as readHeader, t as SerializationError } from "../serialize-BnwtzcMw.js";
+import { i as assertProbability, n as assertPositiveFinite, o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-BrWuBC2A.js";
 //#region src/blocked/blocked.ts
 const TYPE = 2;
 const SALT = Uint32Array.of(1203114875, 1150766481, 2284105051, 2729912477, 1884591559, 770785867, 2667333959, 1550580529);
-const scratchHash = {
-	h1lo: 0,
-	h1hi: 0,
-	h2lo: 0,
-	h2hi: 0
-};
+const scratch2 = /* @__PURE__ */ new Uint32Array(2);
+const BLOCK_BITS = 256;
+const LANE_BITS = 32;
+const LANES = 8;
+/**
+* Modeled false-positive rate of a split-block filter at `bitsPerKey`. A block
+* holding `j` keys has FPR `(1 - (1 - 1/32)^j)^8` (8 lanes of 32 bits, one probe
+* each); the filter's rate averages that over the Poisson block load
+* `lambda = 256 / bitsPerKey`. This clustering average is why the blocked curve
+* is not linear in `log10(1/epsilon)`.
+*/
+function blockedFprAt(bitsPerKey) {
+	const lambda = BLOCK_BITS / bitsPerKey;
+	let fpr = 0;
+	let p = Math.exp(-lambda);
+	for (let j = 0;; j++) {
+		if (j > 0) p *= lambda / j;
+		fpr += p * (1 - (1 - 1 / LANE_BITS) ** j) ** LANES;
+		if (j > lambda && p < 1e-15) break;
+	}
+	return fpr;
+}
+const MAX_BITS_PER_KEY = 128;
+/**
+* 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.
+*/
+function blockedBitsPerKey(epsilon) {
+	for (let bpk = 1; bpk <= MAX_BITS_PER_KEY; bpk++) if (blockedFprAt(bpk) <= epsilon) return bpk;
+	throw new ParamError(`epsilon ${String(epsilon)} is below the blocked-filter floor; use a classic or fuse filter`);
+}
 /** Thrown when an operation requires two filters built with identical parameters. */
 var BlockedBloomParamMismatchError = class extends Error {
 	/** Discriminates this error from other `Error`s. */
@@ -16,7 +43,7 @@ var BlockedBloomParamMismatchError = class extends Error {
 };
 /**
 * A blocked (split-block) Bloom filter: confines every lookup to a single cache
-* line, trading ~20-30% more space for cache-friendly throughput.
+* line, trading ~15% more space for higher lookup throughput and a lower FPR.
 *
 * @example
 * ```ts
@@ -32,11 +59,6 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	#n;
 	#words = /* @__PURE__ */ new Uint32Array(8);
 	#bits = /* @__PURE__ */ new Uint32Array(8);
-	static #ANCHORS = [
-		[2, 10.5],
-		[3, 16.9],
-		[4, 26.4]
-	];
 	/**
 	* Creates a filter sized for `n` expected keys at a target false-positive rate.
 	*
@@ -47,35 +69,62 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	static create(n, epsilon) {
 		assertPositiveInt(n, "n");
 		assertProbability(epsilon, "epsilon");
-		const t = Math.log10(1 / epsilon);
-		const a = BlockedBloomFilter.#ANCHORS;
-		let seg = a.findIndex((p) => t <= p[0]);
-		if (seg < 1) seg = seg === -1 ? a.length - 1 : 1;
-		const [t0, b0] = a[seg - 1] ?? [0, 0];
-		const [t1, b1] = a[seg] ?? [0, 0];
-		const bitsPerKey = b0 + (b1 - b0) / (t1 - t0) * (t - t0);
 		return new BlockedBloomFilter({
-			bitsPerKey: Math.max(1, Math.ceil(bitsPerKey)),
+			bitsPerKey: blockedBitsPerKey(epsilon),
 			capacity: n
 		});
 	}
 	/**
+	* Builds a filter from `keys`, sized for their count at the target
+	* false-positive rate. The ergonomic entry point when the key set is already
+	* in hand; use {@link BlockedBloomFilter.create} to size for a count known
+	* ahead.
+	*
+	* @param keys - The keys to insert.
+	* @param epsilon - Target false-positive rate, e.g. `0.01` for 1%.
+	* @returns A new filter containing every key.
+	*/
+	static from(keys, epsilon) {
+		const arr = [...keys];
+		const f = BlockedBloomFilter.create(Math.max(1, arr.length), epsilon);
+		for (const k of arr) f.add(k);
+		return f;
+	}
+	/**
 	* Constructs a filter from low-level {@link BlockedBloomParams}. Prefer
 	* {@link BlockedBloomFilter.create} unless restoring a specific configuration.
 	*/
 	constructor({ bitsPerKey, capacity, seed = 0 }) {
 		assertPositiveFinite(bitsPerKey, "bitsPerKey");
 		assertPositiveInt(capacity, "capacity");
+		assertUint32(capacity, "capacity");
 		assertUint32(seed, "seed");
 		this.#numBlocks = Math.max(1, Math.ceil(bitsPerKey * capacity / 256));
 		this.#lanes = new Uint32Array(this.#numBlocks * 8);
 		this.#seed = seed;
 		this.#n = capacity;
 	}
+	static #fromNumBlocks(numBlocks, seed, n) {
+		const f = new BlockedBloomFilter({
+			bitsPerKey: 256,
+			capacity: numBlocks,
+			seed
+		});
+		f.#n = n;
+		return f;
+	}
 	/** Actual bits allocated per key (`total bits / capacity`). */
 	get bitsPerKey() {
 		return this.#numBlocks * 256 / this.#n;
 	}
+	/** Number of 256-bit blocks; one of the two fields `union` requires to match. */
+	get numBlocks() {
+		return this.#numBlocks;
+	}
+	/** Hash seed; the other field `union` requires to match. */
+	get seed() {
+		return this.#seed;
+	}
 	/** Number of bits currently set across all lanes. */
 	get length() {
 		let bits = 0;
@@ -103,20 +152,17 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	* @returns The reconstructed filter.
 	*/
 	static fromBytes(bytes) {
-		const { type, body } = readHeader(bytes);
+		const { type, flags, body } = readHeader(bytes);
 		if (type !== TYPE) throw new SerializationError(`expected AMQF type ${String(TYPE)}, got ${String(type)}`);
+		if ((flags & 15) !== 0) throw new UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
 		assertMinBodyLength(body.length, 12, "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");
-		const f = new BlockedBloomFilter({
-			bitsPerKey: 256,
-			capacity: numBlocks,
-			seed
-		});
-		f.#n = n;
+		const f = BlockedBloomFilter.#fromNumBlocks(numBlocks, seed, n);
 		new Uint8Array(f.#lanes.buffer).set(body.subarray(12));
 		return f;
 	}
@@ -127,17 +173,44 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	*/
 	toBytes() {
 		const lanes = new Uint8Array(this.#lanes.buffer, this.#lanes.byteOffset, this.#lanes.byteLength);
-		const body = new Uint8Array(12 + lanes.length);
-		const dv = new DataView(body.buffer);
-		dv.setUint32(0, this.#numBlocks, true);
-		dv.setUint32(4, this.#seed, true);
-		dv.setUint32(8, this.#n, true);
-		body.set(lanes, 12);
-		return writeHeader({
-			version: 2,
+		return writeFrame({
+			version: 3,
 			type: TYPE,
 			flags: 0
-		}, body);
+		}, 12 + 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);
+		});
+	}
+	/**
+	* Tests structural equality: `true` when `other` serializes to identical
+	* bytes, meaning identical parameters and set bits.
+	*
+	* @param other - The filter to compare against.
+	* @returns `true` if the two filters are byte-for-byte identical.
+	*/
+	equals(other) {
+		return bytesEqual(this.toBytes(), other.toBytes());
+	}
+	/**
+	* Serializes the filter to a JSON-friendly envelope wrapping the base64 of
+	* {@link BlockedBloomFilter.toBytes}.
+	*
+	* @returns The envelope, readable by {@link BlockedBloomFilter.fromJSON}.
+	*/
+	toJSON() {
+		return toJSONEnvelope(this.toBytes());
+	}
+	/**
+	* Restores a filter from its {@link BlockedBloomFilter.toJSON} envelope.
+	*
+	* @param value - The JSON envelope.
+	* @returns The reconstructed filter.
+	*/
+	static fromJSON(value) {
+		return BlockedBloomFilter.fromBytes(fromJSONEnvelope(value));
 	}
 	/**
 	* Returns a new filter containing the union of this filter and `other`.
@@ -148,11 +221,7 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	*/
 	union(other) {
 		if (this.#numBlocks !== other.#numBlocks || this.#seed !== other.#seed) throw new BlockedBloomParamMismatchError("cannot union blocked Bloom filters whose parameters do not match");
-		const r = new BlockedBloomFilter({
-			bitsPerKey: this.bitsPerKey,
-			capacity: this.#n,
-			seed: this.#seed
-		});
+		const r = BlockedBloomFilter.#fromNumBlocks(this.#numBlocks, this.#seed, this.#n);
 		for (let i = 0; i < this.#lanes.length; i++) r.#lanes[i] = (this.#lanes[i] ?? 0) | (other.#lanes[i] ?? 0);
 		return r;
 	}
@@ -184,9 +253,9 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	}
 };
 function fillBlock(key, numBlocks, seed, outWords, outBits) {
-	hash128KeyInto(key, seed, scratchHash);
-	const block = reduce((scratchHash.h1lo ^ scratchHash.h1hi) >>> 0, numBlocks);
-	const x = (scratchHash.h2lo ^ scratchHash.h2hi) >>> 0;
+	hash32x2Into(key, seed, scratch2);
+	const block = reduce(scratch2[0] ?? 0, numBlocks);
+	const x = scratch2[1] ?? 0;
 	const base = block * 8;
 	for (let i = 0; i < 8; i++) {
 		outWords[i] = base + i;

package/dist/bloom/index.cjs

@@ -1,18 +1,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_serialize = require("../serialize-DPdiySxq.cjs");
-const require_params = require("../params-J8p3bKq5.cjs");
+const require_serialize = require("../serialize-BIIKUHH6.cjs");
+const require_params = require("../params--8CNXYWu.cjs");
 //#region src/core/bitset.ts
 var BitSetRangeError = class extends RangeError {
 	name = "BitSetRangeError";
 };
 const MAX_BITS = 2 ** 32;
-var BitSet = class BitSet {
+var BitSet = class {
 	#bits;
-	static fromBytes(bytes) {
-		const bs = new BitSet(bytes.length * 8);
-		bs.#bits.set(bytes);
-		return bs;
-	}
 	constructor(nbits) {
 		if (nbits > MAX_BITS) throw new BitSetRangeError(`BitSet capacity ${String(nbits)} exceeds the 2^32-bit limit`);
 		this.#bits = new Uint8Array(Math.ceil(nbits / 8));
@@ -82,9 +77,23 @@ var BloomFilter = class BloomFilter {
 	*/
 	static create(n, epsilon) {
 		require_params.assertPositiveInt(n, "n");
+		require_params.assertUint32(n, "n");
 		require_params.assertProbability(epsilon, "epsilon");
-		const f = new BloomFilter(optimal(n, epsilon));
-		f.#n = n;
+		return BloomFilter.#withN(optimal(n, epsilon), n);
+	}
+	/**
+	* Builds a filter from `keys`, sized for their count at the target
+	* false-positive rate. The ergonomic entry point when the key set is already
+	* in hand; use {@link BloomFilter.create} to size for a count known ahead.
+	*
+	* @param keys - The keys to insert.
+	* @param epsilon - Target false-positive rate, e.g. `0.01` for 1%.
+	* @returns A new filter containing every key.
+	*/
+	static from(keys, epsilon) {
+		const arr = [...keys];
+		const f = BloomFilter.create(Math.max(1, arr.length), epsilon);
+		for (const k of arr) f.add(k);
 		return f;
 	}
 	/**
@@ -94,8 +103,9 @@ var BloomFilter = class BloomFilter {
 	* @returns The reconstructed filter.
 	*/
 	static fromBytes(bytes) {
-		const { type, body } = require_serialize.readHeader(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 ((flags & 15) !== 0) throw new require_serialize.UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
 		require_serialize.assertMinBodyLength(body.length, 14, "bloom");
 		const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
 		const m = dv.getUint32(0, true);
@@ -103,12 +113,11 @@ var BloomFilter = class BloomFilter {
 		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 = new BloomFilter({
+		const f = BloomFilter.#withN({
 			m,
 			k,
 			seed
-		});
-		f.#n = n;
+		}, n);
 		f.#bits.bytes.set(body.subarray(14));
 		return f;
 	}
@@ -118,7 +127,9 @@ var BloomFilter = class BloomFilter {
 	*/
 	constructor({ m, k, seed = 0 }) {
 		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");
 		this.#bits = new BitSet(m);
 		this.#m = m;
@@ -127,6 +138,11 @@ var BloomFilter = class BloomFilter {
 		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;
+	}
 	/** Number of bits in the filter. */
 	get m() {
 		return this.#m;
@@ -164,18 +180,45 @@ var BloomFilter = class BloomFilter {
 	*/
 	toBytes() {
 		const payload = this.#bits.bytes;
-		const body = new Uint8Array(14 + payload.length);
-		const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
-		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);
-		return require_serialize.writeHeader({
-			version: 2,
+		return require_serialize.writeFrame({
+			version: 3,
 			type: TYPE,
 			flags: 0
-		}, body);
+		}, 14 + 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);
+		});
+	}
+	/**
+	* Tests structural equality: `true` when `other` serializes to identical
+	* bytes, meaning identical parameters and set bits.
+	*
+	* @param other - The filter to compare against.
+	* @returns `true` if the two filters are byte-for-byte identical.
+	*/
+	equals(other) {
+		return require_serialize.bytesEqual(this.toBytes(), other.toBytes());
+	}
+	/**
+	* Serializes the filter to a JSON-friendly envelope wrapping the base64 of
+	* {@link BloomFilter.toBytes}.
+	*
+	* @returns The envelope, readable by {@link BloomFilter.fromJSON}.
+	*/
+	toJSON() {
+		return require_serialize.toJSONEnvelope(this.toBytes());
+	}
+	/**
+	* Restores a filter from its {@link BloomFilter.toJSON} envelope.
+	*
+	* @param value - The JSON envelope.
+	* @returns The reconstructed filter.
+	*/
+	static fromJSON(value) {
+		return BloomFilter.fromBytes(require_serialize.fromJSONEnvelope(value));
 	}
 	/**
 	* Returns a new filter containing the union of this filter and `other`.
@@ -190,11 +233,11 @@ 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 = new BloomFilter({
+		const r = BloomFilter.#withN({
 			m: this.#m,
 			k: this.#k,
 			seed: this.#seed
-		});
+		}, this.#n);
 		r.#bits.bytes.set(merged);
 		return r;
 	}

package/dist/bloom/index.d.cts

@@ -1,4 +1,4 @@
-import { t as BytesLike } from "../bytes-DCuYtUVS.cjs";
+import { n as BytesLike, t as FilterJSON } from "../serialize-DRKh6QOr.cjs";
 import { t as ParamError } from "../params-DnqJBqLS.cjs";
 //#region src/bloom/bloom.d.ts
 /** Thrown when an operation requires two filters built with identical parameters. */
@@ -37,6 +37,16 @@ declare class BloomFilter {
    * @returns A new, empty filter.
    */
   static create(n: number, epsilon: number): BloomFilter;
+  /**
+   * Builds a filter from `keys`, sized for their count at the target
+   * false-positive rate. The ergonomic entry point when the key set is already
+   * in hand; use {@link BloomFilter.create} to size for a count known ahead.
+   *
+   * @param keys - The keys to insert.
+   * @param epsilon - Target false-positive rate, e.g. `0.01` for 1%.
+   * @returns A new filter containing every key.
+   */
+  static from(keys: Iterable<BytesLike>, epsilon: number): BloomFilter;
   /**
    * Restores a filter from its {@link BloomFilter.toBytes} serialization.
    *
@@ -73,6 +83,28 @@ declare class BloomFilter {
    * @returns The serialized filter, readable by {@link BloomFilter.fromBytes}.
    */
   toBytes(): Uint8Array;
+  /**
+   * Tests structural equality: `true` when `other` serializes to identical
+   * bytes, meaning identical parameters and set bits.
+   *
+   * @param other - The filter to compare against.
+   * @returns `true` if the two filters are byte-for-byte identical.
+   */
+  equals(other: BloomFilter): boolean;
+  /**
+   * Serializes the filter to a JSON-friendly envelope wrapping the base64 of
+   * {@link BloomFilter.toBytes}.
+   *
+   * @returns The envelope, readable by {@link BloomFilter.fromJSON}.
+   */
+  toJSON(): FilterJSON;
+  /**
+   * Restores a filter from its {@link BloomFilter.toJSON} envelope.
+   *
+   * @param value - The JSON envelope.
+   * @returns The reconstructed filter.
+   */
+  static fromJSON(value: unknown): BloomFilter;
   /**
    * Returns a new filter containing the union of this filter and `other`.
    *
@@ -96,4 +128,4 @@ declare class BloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BloomFilter, BloomParamMismatchError, type BloomParams, ParamError };
+export { BloomFilter, BloomParamMismatchError, type BloomParams, type FilterJSON, ParamError };

package/dist/bloom/index.d.ts

@@ -1,4 +1,4 @@
-import { t as BytesLike } from "../bytes-DCuYtUVS.js";
+import { n as BytesLike, t as FilterJSON } from "../serialize-DRKh6QOr.js";
 import { t as ParamError } from "../params-DnqJBqLS.js";
 //#region src/bloom/bloom.d.ts
 /** Thrown when an operation requires two filters built with identical parameters. */
@@ -37,6 +37,16 @@ declare class BloomFilter {
    * @returns A new, empty filter.
    */
   static create(n: number, epsilon: number): BloomFilter;
+  /**
+   * Builds a filter from `keys`, sized for their count at the target
+   * false-positive rate. The ergonomic entry point when the key set is already
+   * in hand; use {@link BloomFilter.create} to size for a count known ahead.
+   *
+   * @param keys - The keys to insert.
+   * @param epsilon - Target false-positive rate, e.g. `0.01` for 1%.
+   * @returns A new filter containing every key.
+   */
+  static from(keys: Iterable<BytesLike>, epsilon: number): BloomFilter;
   /**
    * Restores a filter from its {@link BloomFilter.toBytes} serialization.
    *
@@ -73,6 +83,28 @@ declare class BloomFilter {
    * @returns The serialized filter, readable by {@link BloomFilter.fromBytes}.
    */
   toBytes(): Uint8Array;
+  /**
+   * Tests structural equality: `true` when `other` serializes to identical
+   * bytes, meaning identical parameters and set bits.
+   *
+   * @param other - The filter to compare against.
+   * @returns `true` if the two filters are byte-for-byte identical.
+   */
+  equals(other: BloomFilter): boolean;
+  /**
+   * Serializes the filter to a JSON-friendly envelope wrapping the base64 of
+   * {@link BloomFilter.toBytes}.
+   *
+   * @returns The envelope, readable by {@link BloomFilter.fromJSON}.
+   */
+  toJSON(): FilterJSON;
+  /**
+   * Restores a filter from its {@link BloomFilter.toJSON} envelope.
+   *
+   * @param value - The JSON envelope.
+   * @returns The reconstructed filter.
+   */
+  static fromJSON(value: unknown): BloomFilter;
   /**
    * Returns a new filter containing the union of this filter and `other`.
    *
@@ -96,4 +128,4 @@ declare class BloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BloomFilter, BloomParamMismatchError, type BloomParams, ParamError };
+export { BloomFilter, BloomParamMismatchError, type BloomParams, type FilterJSON, ParamError };

package/dist/bloom/index.js

@@ -1,17 +1,12 @@
-import { a as writeHeader, i as readHeader, n as assertBodyLength, r as assertMinBodyLength, s as probeInto, t as SerializationError } from "../serialize-DkkBKDT0.js";
-import { a as assertUint32, i as assertProbability, r as assertPositiveInt, t as ParamError } from "../params-ChTRNxM9.js";
+import { a as bytesEqual, c as toJSONEnvelope, g as probeInto, i as assertMinBodyLength, l as writeFrame, n as UnknownHashVariantError, o as fromJSONEnvelope, r as assertBodyLength, s as readHeader, t as SerializationError } from "../serialize-BnwtzcMw.js";
+import { a as assertUint16, i as assertProbability, o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-BrWuBC2A.js";
 //#region src/core/bitset.ts
 var BitSetRangeError = class extends RangeError {
 	name = "BitSetRangeError";
 };
 const MAX_BITS = 2 ** 32;
-var BitSet = class BitSet {
+var BitSet = class {
 	#bits;
-	static fromBytes(bytes) {
-		const bs = new BitSet(bytes.length * 8);
-		bs.#bits.set(bytes);
-		return bs;
-	}
 	constructor(nbits) {
 		if (nbits > MAX_BITS) throw new BitSetRangeError(`BitSet capacity ${String(nbits)} exceeds the 2^32-bit limit`);
 		this.#bits = new Uint8Array(Math.ceil(nbits / 8));
@@ -81,9 +76,23 @@ var BloomFilter = class BloomFilter {
 	*/
 	static create(n, epsilon) {
 		assertPositiveInt(n, "n");
+		assertUint32(n, "n");
 		assertProbability(epsilon, "epsilon");
-		const f = new BloomFilter(optimal(n, epsilon));
-		f.#n = n;
+		return BloomFilter.#withN(optimal(n, epsilon), n);
+	}
+	/**
+	* Builds a filter from `keys`, sized for their count at the target
+	* false-positive rate. The ergonomic entry point when the key set is already
+	* in hand; use {@link BloomFilter.create} to size for a count known ahead.
+	*
+	* @param keys - The keys to insert.
+	* @param epsilon - Target false-positive rate, e.g. `0.01` for 1%.
+	* @returns A new filter containing every key.
+	*/
+	static from(keys, epsilon) {
+		const arr = [...keys];
+		const f = BloomFilter.create(Math.max(1, arr.length), epsilon);
+		for (const k of arr) f.add(k);
 		return f;
 	}
 	/**
@@ -93,8 +102,9 @@ var BloomFilter = class BloomFilter {
 	* @returns The reconstructed filter.
 	*/
 	static fromBytes(bytes) {
-		const { type, body } = readHeader(bytes);
+		const { type, flags, body } = readHeader(bytes);
 		if (type !== TYPE) throw new SerializationError(`expected AMQF type ${String(TYPE)}, got ${String(type)}`);
+		if ((flags & 15) !== 0) throw new UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
 		assertMinBodyLength(body.length, 14, "bloom");
 		const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
 		const m = dv.getUint32(0, true);
@@ -102,12 +112,11 @@ var BloomFilter = class BloomFilter {
 		const seed = dv.getUint32(6, true);
 		const n = dv.getUint32(10, true);
 		assertBodyLength(body.length, 14 + Math.ceil(m / 8), "bloom");
-		const f = new BloomFilter({
+		const f = BloomFilter.#withN({
 			m,
 			k,
 			seed
-		});
-		f.#n = n;
+		}, n);
 		f.#bits.bytes.set(body.subarray(14));
 		return f;
 	}
@@ -117,7 +126,9 @@ var BloomFilter = class BloomFilter {
 	*/
 	constructor({ m, k, seed = 0 }) {
 		assertPositiveInt(m, "m");
+		assertUint32(m, "m");
 		assertPositiveInt(k, "k");
+		assertUint16(k, "k");
 		assertUint32(seed, "seed");
 		this.#bits = new BitSet(m);
 		this.#m = m;
@@ -126,6 +137,11 @@ var BloomFilter = class BloomFilter {
 		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;
+	}
 	/** Number of bits in the filter. */
 	get m() {
 		return this.#m;
@@ -163,18 +179,45 @@ var BloomFilter = class BloomFilter {
 	*/
 	toBytes() {
 		const payload = this.#bits.bytes;
-		const body = new Uint8Array(14 + payload.length);
-		const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
-		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);
-		return writeHeader({
-			version: 2,
+		return writeFrame({
+			version: 3,
 			type: TYPE,
 			flags: 0
-		}, body);
+		}, 14 + 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);
+		});
+	}
+	/**
+	* Tests structural equality: `true` when `other` serializes to identical
+	* bytes, meaning identical parameters and set bits.
+	*
+	* @param other - The filter to compare against.
+	* @returns `true` if the two filters are byte-for-byte identical.
+	*/
+	equals(other) {
+		return bytesEqual(this.toBytes(), other.toBytes());
+	}
+	/**
+	* Serializes the filter to a JSON-friendly envelope wrapping the base64 of
+	* {@link BloomFilter.toBytes}.
+	*
+	* @returns The envelope, readable by {@link BloomFilter.fromJSON}.
+	*/
+	toJSON() {
+		return toJSONEnvelope(this.toBytes());
+	}
+	/**
+	* Restores a filter from its {@link BloomFilter.toJSON} envelope.
+	*
+	* @param value - The JSON envelope.
+	* @returns The reconstructed filter.
+	*/
+	static fromJSON(value) {
+		return BloomFilter.fromBytes(fromJSONEnvelope(value));
 	}
 	/**
 	* Returns a new filter containing the union of this filter and `other`.
@@ -189,11 +232,11 @@ 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 = new BloomFilter({
+		const r = BloomFilter.#withN({
 			m: this.#m,
 			k: this.#k,
 			seed: this.#seed
-		});
+		}, this.#n);
 		r.#bits.bytes.set(merged);
 		return r;
 	}