distillate 0.5.0 → 0.7.0

package/dist/fuse/index.js

@@ -1,4 +1,4 @@
-import { a as readHeader, c as RLO, f as mul64, i as assertMinBodyLength, l as fmix64, o as writeHeader, r as assertBodyLength, s as RHI, t as SerializationError, u as hash128KeyInto } from "../serialize-BQ2UzZqq.js";
+import { a as bytesEqual, c as toJSONEnvelope, d as RLO, f as fmix64, h as mul64, i as assertMinBodyLength, l as writeFrame, n as UnknownHashVariantError, o as fromJSONEnvelope, p as hash128KeyInto, r as assertBodyLength, s as readHeader, t as SerializationError, u as RHI } from "../serialize-BnwtzcMw.js";
 //#region src/fuse/fuse.ts
 const ARITY = 3;
 const TYPE_FUSE8 = 3;
@@ -9,10 +9,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);
@@ -59,6 +59,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.
@@ -135,8 +148,8 @@ function buildState(keys, alloc) {
 	const seen = /* @__PURE__ */ new Set();
 	for (const key of keys) {
 		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);
@@ -160,14 +173,17 @@ function buildState(keys, alloc) {
 	};
 }
 function fuseStateFromBytes(bytes, expectedType) {
-	const { type, body } = readHeader(bytes);
+	const { type, flags, body } = readHeader(bytes);
 	if (type !== expectedType) throw new SerializationError(`expected AMQF type ${String(expectedType)}, got ${String(type)}`);
+	if ((flags & 15) !== 0) throw new UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
 	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 SerializationError(`invalid fuse segment length ${String(seg)}`);
+	if (segCountLen % seg !== 0) throw new 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;
 	assertBodyLength(body.length, 16 + expectedArrayLength * bpe, "fuse");
@@ -211,6 +227,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;
@@ -222,18 +242,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 writeHeader({
-			version: 2,
+		return 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.
@@ -244,7 +263,7 @@ var BinaryFuse = class {
 	has(key) {
 		if (this.#fp.length === 0) return false;
 		hash128KeyInto(key, 0, scratchHash);
-		mixSeed(scratchHash.h1lo >>> 0, scratchHash.h1hi >>> 0, this.#seed);
+		mixSeed(scratchHash.w0 >>> 0, scratchHash.w1 >>> 0, this.#seed);
 		const mlo = RLO;
 		const mhi = RHI;
 		positionsInto(mlo, mhi, this.#seg, this.#segMask, this.#segCountLen, this.#pos);
@@ -254,6 +273,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 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 toJSONEnvelope(this.toBytes());
+	}
 };
 /**
 * A static 8-bit binary fuse filter: built once from a key set, then immutable.
@@ -286,6 +325,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(fromJSONEnvelope(value));
+	}
 };
 /**
 * A static 16-bit binary fuse filter: like {@link BinaryFuse8} but twice the
@@ -317,6 +365,15 @@ 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(fromJSONEnvelope(value));
+	}
 };
 //#endregion
-export { BinaryFuse16, BinaryFuse8, BinaryFuseBuildError };
+export { BinaryFuse16, BinaryFuse8, BinaryFuseBuildError, fuseBitsPerKey };

package/dist/index.cjs

@@ -2,6 +2,6 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#endregion
 //#region src/index.ts
 /** The installed `distillate` package version. */
-const VERSION = "0.5.0";
+const VERSION = "0.7.0";
 //#endregion
 exports.VERSION = VERSION;

package/dist/index.js

@@ -1,6 +1,6 @@
 //#endregion
 //#region src/index.ts
 /** The installed `distillate` package version. */
-const VERSION = "0.5.0";
+const VERSION = "0.7.0";
 //#endregion
 export { VERSION };

package/dist/{params-J8p3bKq5.cjs → params--8CNXYWu.cjs}

@@ -12,6 +12,10 @@ function assertPositiveInt(value, label) {
 function assertPositiveFinite(value, label) {
 	if (!Number.isFinite(value) || value <= 0) throw new ParamError(`${label} must be a positive number, got ${String(value)}`);
 }
+/** Asserts `value` is an integer in the uint16 range `[0, 65535]`. */
+function assertUint16(value, label) {
+	if (!Number.isInteger(value) || value < 0 || value > 65535) throw new ParamError(`${label} must be a uint16, got ${String(value)}`);
+}
 /** Asserts `value` is an integer in the uint32 range `[0, 2^32 - 1]`. */
 function assertUint32(value, label) {
 	if (!Number.isInteger(value) || value < 0 || value > 4294967295) throw new ParamError(`${label} must be a uint32, got ${String(value)}`);
@@ -45,6 +49,12 @@ Object.defineProperty(exports, "assertProbability", {
 		return assertProbability;
 	}
 });
+Object.defineProperty(exports, "assertUint16", {
+	enumerable: true,
+	get: function() {
+		return assertUint16;
+	}
+});
 Object.defineProperty(exports, "assertUint32", {
 	enumerable: true,
 	get: function() {

package/dist/{params-ChTRNxM9.js → params-BrWuBC2A.js}

@@ -12,6 +12,10 @@ function assertPositiveInt(value, label) {
 function assertPositiveFinite(value, label) {
 	if (!Number.isFinite(value) || value <= 0) throw new ParamError(`${label} must be a positive number, got ${String(value)}`);
 }
+/** Asserts `value` is an integer in the uint16 range `[0, 65535]`. */
+function assertUint16(value, label) {
+	if (!Number.isInteger(value) || value < 0 || value > 65535) throw new ParamError(`${label} must be a uint16, got ${String(value)}`);
+}
 /** Asserts `value` is an integer in the uint32 range `[0, 2^32 - 1]`. */
 function assertUint32(value, label) {
 	if (!Number.isInteger(value) || value < 0 || value > 4294967295) throw new ParamError(`${label} must be a uint32, got ${String(value)}`);
@@ -21,4 +25,4 @@ function assertProbability(value, label) {
 	if (!Number.isFinite(value) || value <= 0 || value >= 1) throw new ParamError(`${label} must be in the open interval (0, 1), got ${String(value)}`);
 }
 //#endregion
-export { assertUint32 as a, assertProbability as i, assertPositiveFinite as n, assertPositiveInt as r, ParamError as t };
+export { assertUint16 as a, assertProbability as i, assertPositiveFinite as n, assertUint32 as o, assertPositiveInt as r, ParamError as t };