distillate 0.5.0 → 0.7.0

package/dist/bloom/index.js

@@ -1,17 +1,12 @@
-import { a as readHeader, i as assertMinBodyLength, n as UnknownHashVariantError, o as writeHeader, p as probeInto, r as assertBodyLength, t as SerializationError } from "../serialize-BQ2UzZqq.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));
@@ -38,7 +33,7 @@ var BitSet = class BitSet {
 //#endregion
 //#region src/core/sizing.ts
 /** Optimal Bloom-filter sizing: `m` bits and `k` hashes for `n` items at target FPR `epsilon`. */
-function optimal(n, epsilon) {
+function bloomSizing(n, epsilon) {
 	const m = Math.ceil(-n * Math.log(epsilon) / (Math.LN2 * Math.LN2));
 	return {
 		m,
@@ -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(bloomSizing(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;
 	}
 	/**
@@ -95,7 +104,7 @@ var BloomFilter = class BloomFilter {
 	static fromBytes(bytes) {
 		const { type, flags, body } = readHeader(bytes);
 		if (type !== TYPE) throw new SerializationError(`expected AMQF type ${String(TYPE)}, got ${String(type)}`);
-		if ((flags & 15) !== 1) throw new UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
+		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);
@@ -103,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;
 	}
@@ -118,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;
@@ -127,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;
@@ -164,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: 1
-		}, body);
+			flags: 0
+		}, 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`.
@@ -190,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;
 	}
@@ -220,4 +262,4 @@ var BloomFilter = class BloomFilter {
 	}
 };
 //#endregion
-export { BloomFilter, BloomParamMismatchError, ParamError };
+export { BloomFilter, BloomParamMismatchError, ParamError, bloomSizing };

package/dist/fuse/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_serialize = require("../serialize-fa-pEUGq.cjs");
+const require_serialize = require("../serialize-BIIKUHH6.cjs");
 //#region src/fuse/fuse.ts
 const ARITY = 3;
 const TYPE_FUSE8 = 3;
@@ -10,10 +10,10 @@ var BinaryFuseBuildError = class extends Error {
 	name = "BinaryFuseBuildError";
 };
 const scratchHash = {
-	h1lo: 0,
-	h1hi: 0,
-	h2lo: 0,
-	h2hi: 0
+	w0: 0,
+	w1: 0,
+	w2: 0,
+	w3: 0
 };
 function mixSeed(lo, hi, seed) {
 	const l = (lo >>> 0) + (seed >>> 0);
@@ -60,6 +60,19 @@ function computeParams(size) {
 	};
 }
 /**
+* Bits stored per key by a binary fuse filter over `n` keys at a fingerprint
+* width, without building one. Counts `n` as distinct keys, since a built
+* filter sizes on its deduped hash count.
+*
+* @param n - Number of distinct keys.
+* @param width - Fingerprint width in bits: `8` for {@link BinaryFuse8}, `16` for {@link BinaryFuse16}.
+* @returns Bits per key (`0` for an empty filter).
+*/
+function fuseBitsPerKey(n, width) {
+	if (n === 0) return 0;
+	return computeParams(n).arrayLength * width / n;
+}
+/**
 * Peel the 3-hypergraph and assign fingerprints so every key's XOR of its 3
 * lanes equals its fingerprint. Retries with a bumped seed on a stall; returns
 * the seed that succeeded.
@@ -136,8 +149,8 @@ function buildState(keys, alloc) {
 	const seen = /* @__PURE__ */ new Set();
 	for (const key of keys) {
 		require_serialize.hash128KeyInto(key, 0, scratchHash);
-		const lo = scratchHash.h1lo >>> 0;
-		const hi = scratchHash.h1hi >>> 0;
+		const lo = scratchHash.w0 >>> 0;
+		const hi = scratchHash.w1 >>> 0;
 		const id = `${String(lo)},${String(hi)}`;
 		if (seen.has(id)) continue;
 		seen.add(id);
@@ -161,14 +174,17 @@ function buildState(keys, alloc) {
 	};
 }
 function fuseStateFromBytes(bytes, expectedType) {
-	const { type, body } = require_serialize.readHeader(bytes);
+	const { type, flags, body } = require_serialize.readHeader(bytes);
 	if (type !== expectedType) throw new require_serialize.SerializationError(`expected AMQF type ${String(expectedType)}, got ${String(type)}`);
+	if ((flags & 15) !== 0) throw new require_serialize.UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
 	require_serialize.assertMinBodyLength(body.length, 16, "fuse");
 	const dv = new DataView(body.buffer, body.byteOffset, body.byteLength);
 	const seed = dv.getUint32(0, true);
 	const seg = dv.getUint32(4, true);
 	const segCountLen = dv.getUint32(8, true);
 	const size = dv.getUint32(12, true);
+	if (seg === 0 || (seg & seg - 1) !== 0 || seg > 1 << 18) throw new require_serialize.SerializationError(`invalid fuse segment length ${String(seg)}`);
+	if (segCountLen % seg !== 0) throw new require_serialize.SerializationError(`fuse segment count length ${String(segCountLen)} is not a multiple of segment length ${String(seg)}`);
 	const bpe = expectedType === TYPE_FUSE8 ? 1 : 2;
 	const expectedArrayLength = size === 0 ? 0 : segCountLen + 2 * seg;
 	require_serialize.assertBodyLength(body.length, 16 + expectedArrayLength * bpe, "fuse");
@@ -212,6 +228,10 @@ var BinaryFuse = class {
 	get size() {
 		return this.#size;
 	}
+	/** Hash seed selected during construction (may differ from 0 after a peel retry). */
+	get seed() {
+		return this.#seed;
+	}
 	/** Actual bits stored per key (`0` for an empty filter). */
 	get bitsPerKey() {
 		return this.#size === 0 ? 0 : this.#fp.byteLength * 8 / this.#size;
@@ -223,18 +243,17 @@ var BinaryFuse = class {
 	*/
 	toBytes() {
 		const laneBytes = new Uint8Array(this.#fp.buffer, this.#fp.byteOffset, this.#fp.byteLength);
-		const body = new Uint8Array(16 + laneBytes.length);
-		const dv = new DataView(body.buffer);
-		dv.setUint32(0, this.#seed, true);
-		dv.setUint32(4, this.#seg, true);
-		dv.setUint32(8, this.#segCountLen, true);
-		dv.setUint32(12, this.#size, true);
-		body.set(laneBytes, 16);
-		return require_serialize.writeHeader({
-			version: 2,
+		return require_serialize.writeFrame({
+			version: 3,
 			type: this.#fp.BYTES_PER_ELEMENT === 1 ? TYPE_FUSE8 : TYPE_FUSE16,
 			flags: 0
-		}, body);
+		}, 16 + laneBytes.length, (body, dv) => {
+			dv.setUint32(0, this.#seed, true);
+			dv.setUint32(4, this.#seg, true);
+			dv.setUint32(8, this.#segCountLen, true);
+			dv.setUint32(12, this.#size, true);
+			body.set(laneBytes, 16);
+		});
 	}
 	/**
 	* Tests whether a key is in the set.
@@ -245,7 +264,7 @@ var BinaryFuse = class {
 	has(key) {
 		if (this.#fp.length === 0) return false;
 		require_serialize.hash128KeyInto(key, 0, scratchHash);
-		mixSeed(scratchHash.h1lo >>> 0, scratchHash.h1hi >>> 0, this.#seed);
+		mixSeed(scratchHash.w0 >>> 0, scratchHash.w1 >>> 0, this.#seed);
 		const mlo = require_serialize.RLO;
 		const mhi = require_serialize.RHI;
 		positionsInto(mlo, mhi, this.#seg, this.#segMask, this.#segCountLen, this.#pos);
@@ -255,6 +274,26 @@ var BinaryFuse = class {
 		const p2 = this.#pos[2] ?? 0;
 		return ((mlo ^ mhi) & mask) === (((this.#fp[p0] ?? 0) ^ (this.#fp[p1] ?? 0) ^ (this.#fp[p2] ?? 0)) & mask);
 	}
+	/**
+	* Tests structural equality: `true` when `other` serializes to identical
+	* bytes. A {@link BinaryFuse8} and a {@link BinaryFuse16} are never equal,
+	* since their frames carry different type bytes.
+	*
+	* @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
+	* the `toBytes` frame.
+	*
+	* @returns The envelope, readable by the matching `fromJSON`.
+	*/
+	toJSON() {
+		return require_serialize.toJSONEnvelope(this.toBytes());
+	}
 };
 /**
 * A static 8-bit binary fuse filter: built once from a key set, then immutable.
@@ -287,6 +326,15 @@ var BinaryFuse8 = class BinaryFuse8 extends BinaryFuse {
 	static fromBytes(bytes) {
 		return new BinaryFuse8(fuseStateFromBytes(bytes, TYPE_FUSE8));
 	}
+	/**
+	* Restores a filter from its {@link BinaryFuse8.toJSON} envelope.
+	*
+	* @param value - The JSON envelope.
+	* @returns The reconstructed filter.
+	*/
+	static fromJSON(value) {
+		return BinaryFuse8.fromBytes(require_serialize.fromJSONEnvelope(value));
+	}
 };
 /**
 * A static 16-bit binary fuse filter: like {@link BinaryFuse8} but twice the
@@ -318,8 +366,18 @@ var BinaryFuse16 = class BinaryFuse16 extends BinaryFuse {
 	static fromBytes(bytes) {
 		return new BinaryFuse16(fuseStateFromBytes(bytes, TYPE_FUSE16));
 	}
+	/**
+	* Restores a filter from its {@link BinaryFuse16.toJSON} envelope.
+	*
+	* @param value - The JSON envelope.
+	* @returns The reconstructed filter.
+	*/
+	static fromJSON(value) {
+		return BinaryFuse16.fromBytes(require_serialize.fromJSONEnvelope(value));
+	}
 };
 //#endregion
 exports.BinaryFuse16 = BinaryFuse16;
 exports.BinaryFuse8 = BinaryFuse8;
 exports.BinaryFuseBuildError = BinaryFuseBuildError;
+exports.fuseBitsPerKey = fuseBitsPerKey;

package/dist/fuse/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";
 //#region src/fuse/fuse.d.ts
 /** Thrown when binary fuse construction fails to converge on the key set. */
 declare class BinaryFuseBuildError extends Error {
@@ -11,6 +11,16 @@ interface FuseParams {
   segCountLen: number;
   arrayLength: number;
 }
+/**
+ * Bits stored per key by a binary fuse filter over `n` keys at a fingerprint
+ * width, without building one. Counts `n` as distinct keys, since a built
+ * filter sizes on its deduped hash count.
+ *
+ * @param n - Number of distinct keys.
+ * @param width - Fingerprint width in bits: `8` for {@link BinaryFuse8}, `16` for {@link BinaryFuse16}.
+ * @returns Bits per key (`0` for an empty filter).
+ */
+declare function fuseBitsPerKey(n: number, width: 8 | 16): number;
 interface FuseState {
   fp: Uint8Array | Uint16Array;
   seed: number;
@@ -26,6 +36,8 @@ declare abstract class BinaryFuse {
   protected constructor(state: FuseState);
   /** Number of distinct keys the filter was built from. */
   get size(): number;
+  /** Hash seed selected during construction (may differ from 0 after a peel retry). */
+  get seed(): number;
   /** Actual bits stored per key (`0` for an empty filter). */
   get bitsPerKey(): number;
   /**
@@ -41,6 +53,22 @@ declare abstract class BinaryFuse {
    * @returns `true` if present (possibly a false positive); `false` guarantees absence.
    */
   has(key: BytesLike): boolean;
+  /**
+   * Tests structural equality: `true` when `other` serializes to identical
+   * bytes. A {@link BinaryFuse8} and a {@link BinaryFuse16} are never equal,
+   * since their frames carry different type bytes.
+   *
+   * @param other - The filter to compare against.
+   * @returns `true` if the two filters are byte-for-byte identical.
+   */
+  equals(other: BinaryFuse8 | BinaryFuse16): boolean;
+  /**
+   * Serializes the filter to a JSON-friendly envelope wrapping the base64 of
+   * the `toBytes` frame.
+   *
+   * @returns The envelope, readable by the matching `fromJSON`.
+   */
+  toJSON(): FilterJSON;
 }
 /**
  * A static 8-bit binary fuse filter: built once from a key set, then immutable.
@@ -69,6 +97,13 @@ declare class BinaryFuse8 extends BinaryFuse {
    * @returns The reconstructed filter.
    */
   static fromBytes(bytes: Uint8Array): BinaryFuse8;
+  /**
+   * Restores a filter from its {@link BinaryFuse8.toJSON} envelope.
+   *
+   * @param value - The JSON envelope.
+   * @returns The reconstructed filter.
+   */
+  static fromJSON(value: unknown): BinaryFuse8;
 }
 /**
  * A static 16-bit binary fuse filter: like {@link BinaryFuse8} but twice the
@@ -96,6 +131,13 @@ declare class BinaryFuse16 extends BinaryFuse {
    * @returns The reconstructed filter.
    */
   static fromBytes(bytes: Uint8Array): BinaryFuse16;
+  /**
+   * Restores a filter from its {@link BinaryFuse16.toJSON} envelope.
+   *
+   * @param value - The JSON envelope.
+   * @returns The reconstructed filter.
+   */
+  static fromJSON(value: unknown): BinaryFuse16;
 }
 //#endregion
-export { BinaryFuse16, BinaryFuse8, BinaryFuseBuildError };
+export { BinaryFuse16, BinaryFuse8, BinaryFuseBuildError, type FilterJSON, fuseBitsPerKey };

package/dist/fuse/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";
 //#region src/fuse/fuse.d.ts
 /** Thrown when binary fuse construction fails to converge on the key set. */
 declare class BinaryFuseBuildError extends Error {
@@ -11,6 +11,16 @@ interface FuseParams {
   segCountLen: number;
   arrayLength: number;
 }
+/**
+ * Bits stored per key by a binary fuse filter over `n` keys at a fingerprint
+ * width, without building one. Counts `n` as distinct keys, since a built
+ * filter sizes on its deduped hash count.
+ *
+ * @param n - Number of distinct keys.
+ * @param width - Fingerprint width in bits: `8` for {@link BinaryFuse8}, `16` for {@link BinaryFuse16}.
+ * @returns Bits per key (`0` for an empty filter).
+ */
+declare function fuseBitsPerKey(n: number, width: 8 | 16): number;
 interface FuseState {
   fp: Uint8Array | Uint16Array;
   seed: number;
@@ -26,6 +36,8 @@ declare abstract class BinaryFuse {
   protected constructor(state: FuseState);
   /** Number of distinct keys the filter was built from. */
   get size(): number;
+  /** Hash seed selected during construction (may differ from 0 after a peel retry). */
+  get seed(): number;
   /** Actual bits stored per key (`0` for an empty filter). */
   get bitsPerKey(): number;
   /**
@@ -41,6 +53,22 @@ declare abstract class BinaryFuse {
    * @returns `true` if present (possibly a false positive); `false` guarantees absence.
    */
   has(key: BytesLike): boolean;
+  /**
+   * Tests structural equality: `true` when `other` serializes to identical
+   * bytes. A {@link BinaryFuse8} and a {@link BinaryFuse16} are never equal,
+   * since their frames carry different type bytes.
+   *
+   * @param other - The filter to compare against.
+   * @returns `true` if the two filters are byte-for-byte identical.
+   */
+  equals(other: BinaryFuse8 | BinaryFuse16): boolean;
+  /**
+   * Serializes the filter to a JSON-friendly envelope wrapping the base64 of
+   * the `toBytes` frame.
+   *
+   * @returns The envelope, readable by the matching `fromJSON`.
+   */
+  toJSON(): FilterJSON;
 }
 /**
  * A static 8-bit binary fuse filter: built once from a key set, then immutable.
@@ -69,6 +97,13 @@ declare class BinaryFuse8 extends BinaryFuse {
    * @returns The reconstructed filter.
    */
   static fromBytes(bytes: Uint8Array): BinaryFuse8;
+  /**
+   * Restores a filter from its {@link BinaryFuse8.toJSON} envelope.
+   *
+   * @param value - The JSON envelope.
+   * @returns The reconstructed filter.
+   */
+  static fromJSON(value: unknown): BinaryFuse8;
 }
 /**
  * A static 16-bit binary fuse filter: like {@link BinaryFuse8} but twice the
@@ -96,6 +131,13 @@ declare class BinaryFuse16 extends BinaryFuse {
    * @returns The reconstructed filter.
    */
   static fromBytes(bytes: Uint8Array): BinaryFuse16;
+  /**
+   * Restores a filter from its {@link BinaryFuse16.toJSON} envelope.
+   *
+   * @param value - The JSON envelope.
+   * @returns The reconstructed filter.
+   */
+  static fromJSON(value: unknown): BinaryFuse16;
 }
 //#endregion
-export { BinaryFuse16, BinaryFuse8, BinaryFuseBuildError };
+export { BinaryFuse16, BinaryFuse8, BinaryFuseBuildError, type FilterJSON, fuseBitsPerKey };