distillate 0.1.2 → 0.3.0

package/dist/blocked/index.cjs

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_serialize = require("../serialize-CHHDM4TQ.cjs");
+const require_params = require("../params-J8p3bKq5.cjs");
 //#region src/blocked/blocked.ts
 const TYPE = 2;
 const SALT = Uint32Array.of(1203114875, 1150766481, 2284105051, 2729912477, 1884591559, 770785867, 2667333959, 1550580529);
@@ -45,6 +46,8 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	* @returns A new, empty filter.
 	*/
 	static create(n, epsilon) {
+		require_params.assertPositiveInt(n, "n");
+		require_params.assertProbability(epsilon, "epsilon");
 		const t = Math.log10(1 / epsilon);
 		const a = BlockedBloomFilter.#ANCHORS;
 		let seg = a.findIndex((p) => t <= p[0]);
@@ -53,7 +56,7 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 		const [t1, b1] = a[seg] ?? [0, 0];
 		const bitsPerKey = b0 + (b1 - b0) / (t1 - t0) * (t - t0);
 		return new BlockedBloomFilter({
-			bitsPerKey: Math.ceil(bitsPerKey),
+			bitsPerKey: Math.max(1, Math.ceil(bitsPerKey)),
 			capacity: n
 		});
 	}
@@ -62,6 +65,9 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	* {@link BlockedBloomFilter.create} unless restoring a specific configuration.
 	*/
 	constructor({ bitsPerKey, capacity, seed = 0 }) {
+		require_params.assertPositiveFinite(bitsPerKey, "bitsPerKey");
+		require_params.assertPositiveInt(capacity, "capacity");
+		require_params.assertUint32(seed, "seed");
 		this.#numBlocks = Math.max(1, Math.ceil(bitsPerKey * capacity / 256));
 		this.#lanes = new Uint32Array(this.#numBlocks * 8);
 		this.#seed = seed;
@@ -71,6 +77,26 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	get bitsPerKey() {
 		return this.#numBlocks * 256 / this.#n;
 	}
+	/** Number of bits currently set across all lanes. */
+	get length() {
+		let bits = 0;
+		for (let w of this.#lanes) while (w) {
+			w &= w - 1;
+			bits++;
+		}
+		return bits;
+	}
+	/**
+	* Estimates the current false-positive rate from the actual fill,
+	* `(length / totalBits) ** 8`. A split-block query checks exactly 8 lane-bits,
+	* so the exponent is 8 rather than a classic probe count `k`. This reflects
+	* how full the filter is right now, not the design target.
+	*
+	* @returns The estimated false-positive rate, `0` for an empty filter.
+	*/
+	rate() {
+		return (this.length / (this.#numBlocks * 256)) ** 8;
+	}
 	/**
 	* Restores a filter from its {@link BlockedBloomFilter.toBytes} serialization.
 	*
@@ -168,3 +194,4 @@ function fillBlock(key, numBlocks, seed, outWords, outBits) {
 //#endregion
 exports.BlockedBloomFilter = BlockedBloomFilter;
 exports.BlockedBloomParamMismatchError = BlockedBloomParamMismatchError;
+exports.ParamError = require_params.ParamError;

package/dist/blocked/index.d.cts

@@ -1,4 +1,5 @@
 import { t as BytesLike } from "../bytes-DCuYtUVS.cjs";
+import { t as ParamError } from "../params-DnqJBqLS.cjs";
 //#region src/blocked/blocked.d.ts
 /** Thrown when an operation requires two filters built with identical parameters. */
 declare class BlockedBloomParamMismatchError extends Error {
@@ -42,6 +43,17 @@ declare class BlockedBloomFilter {
   constructor({ bitsPerKey, capacity, seed }: BlockedBloomParams);
   /** Actual bits allocated per key (`total bits / capacity`). */
   get bitsPerKey(): number;
+  /** Number of bits currently set across all lanes. */
+  get length(): number;
+  /**
+   * Estimates the current false-positive rate from the actual fill,
+   * `(length / totalBits) ** 8`. A split-block query checks exactly 8 lane-bits,
+   * so the exponent is 8 rather than a classic probe count `k`. This reflects
+   * how full the filter is right now, not the design target.
+   *
+   * @returns The estimated false-positive rate, `0` for an empty filter.
+   */
+  rate(): number;
   /**
    * Restores a filter from its {@link BlockedBloomFilter.toBytes} serialization.
    *
@@ -78,4 +90,4 @@ declare class BlockedBloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams };
+export { BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams, ParamError };

package/dist/blocked/index.d.ts

@@ -1,4 +1,5 @@
 import { t as BytesLike } from "../bytes-DCuYtUVS.js";
+import { t as ParamError } from "../params-DnqJBqLS.js";
 //#region src/blocked/blocked.d.ts
 /** Thrown when an operation requires two filters built with identical parameters. */
 declare class BlockedBloomParamMismatchError extends Error {
@@ -42,6 +43,17 @@ declare class BlockedBloomFilter {
   constructor({ bitsPerKey, capacity, seed }: BlockedBloomParams);
   /** Actual bits allocated per key (`total bits / capacity`). */
   get bitsPerKey(): number;
+  /** Number of bits currently set across all lanes. */
+  get length(): number;
+  /**
+   * Estimates the current false-positive rate from the actual fill,
+   * `(length / totalBits) ** 8`. A split-block query checks exactly 8 lane-bits,
+   * so the exponent is 8 rather than a classic probe count `k`. This reflects
+   * how full the filter is right now, not the design target.
+   *
+   * @returns The estimated false-positive rate, `0` for an empty filter.
+   */
+  rate(): number;
   /**
    * Restores a filter from its {@link BlockedBloomFilter.toBytes} serialization.
    *
@@ -78,4 +90,4 @@ declare class BlockedBloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams };
+export { BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams, ParamError };

package/dist/blocked/index.js

@@ -1,4 +1,5 @@
 import { i as hash128KeyInto, n as readHeader, o as reduce, r as writeHeader } from "../serialize-5XQ5y_R-.js";
+import { a as assertUint32, i as assertProbability, n as assertPositiveFinite, r as assertPositiveInt, t as ParamError } from "../params-ChTRNxM9.js";
 //#region src/blocked/blocked.ts
 const TYPE = 2;
 const SALT = Uint32Array.of(1203114875, 1150766481, 2284105051, 2729912477, 1884591559, 770785867, 2667333959, 1550580529);
@@ -44,6 +45,8 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	* @returns A new, empty filter.
 	*/
 	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]);
@@ -52,7 +55,7 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 		const [t1, b1] = a[seg] ?? [0, 0];
 		const bitsPerKey = b0 + (b1 - b0) / (t1 - t0) * (t - t0);
 		return new BlockedBloomFilter({
-			bitsPerKey: Math.ceil(bitsPerKey),
+			bitsPerKey: Math.max(1, Math.ceil(bitsPerKey)),
 			capacity: n
 		});
 	}
@@ -61,6 +64,9 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	* {@link BlockedBloomFilter.create} unless restoring a specific configuration.
 	*/
 	constructor({ bitsPerKey, capacity, seed = 0 }) {
+		assertPositiveFinite(bitsPerKey, "bitsPerKey");
+		assertPositiveInt(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;
@@ -70,6 +76,26 @@ var BlockedBloomFilter = class BlockedBloomFilter {
 	get bitsPerKey() {
 		return this.#numBlocks * 256 / this.#n;
 	}
+	/** Number of bits currently set across all lanes. */
+	get length() {
+		let bits = 0;
+		for (let w of this.#lanes) while (w) {
+			w &= w - 1;
+			bits++;
+		}
+		return bits;
+	}
+	/**
+	* Estimates the current false-positive rate from the actual fill,
+	* `(length / totalBits) ** 8`. A split-block query checks exactly 8 lane-bits,
+	* so the exponent is 8 rather than a classic probe count `k`. This reflects
+	* how full the filter is right now, not the design target.
+	*
+	* @returns The estimated false-positive rate, `0` for an empty filter.
+	*/
+	rate() {
+		return (this.length / (this.#numBlocks * 256)) ** 8;
+	}
 	/**
 	* Restores a filter from its {@link BlockedBloomFilter.toBytes} serialization.
 	*
@@ -165,4 +191,4 @@ function fillBlock(key, numBlocks, seed, outWords, outBits) {
 	}
 }
 //#endregion
-export { BlockedBloomFilter, BlockedBloomParamMismatchError };
+export { BlockedBloomFilter, BlockedBloomParamMismatchError, ParamError };

package/dist/bloom/index.cjs

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_serialize = require("../serialize-CHHDM4TQ.cjs");
+const require_params = require("../params-J8p3bKq5.cjs");
 //#region src/core/bitset.ts
 var BitSetRangeError = class extends RangeError {
 	name = "BitSetRangeError";
@@ -80,6 +81,8 @@ var BloomFilter = class BloomFilter {
 	* @returns A new, empty filter.
 	*/
 	static create(n, epsilon) {
+		require_params.assertPositiveInt(n, "n");
+		require_params.assertProbability(epsilon, "epsilon");
 		const f = new BloomFilter(optimal(n, epsilon));
 		f.#n = n;
 		return f;
@@ -109,6 +112,9 @@ var BloomFilter = class BloomFilter {
 	* {@link BloomFilter.create} unless restoring a specific configuration.
 	*/
 	constructor({ m, k, seed = 0 }) {
+		require_params.assertPositiveInt(m, "m");
+		require_params.assertPositiveInt(k, "k");
+		require_params.assertUint32(seed, "seed");
 		this.#bits = new BitSet(m);
 		this.#m = m;
 		this.#k = k;
@@ -116,11 +122,37 @@ var BloomFilter = class BloomFilter {
 		this.#scratch = new Uint32Array(k);
 		this.#n = Math.round(m * Math.LN2 / k);
 	}
+	/** Number of bits in the filter. */
+	get m() {
+		return this.#m;
+	}
+	/** Number of hash probes per key. */
+	get k() {
+		return this.#k;
+	}
+	/** Hash seed. */
+	get seed() {
+		return this.#seed;
+	}
+	/** Number of bits currently set. */
+	get length() {
+		return this.#bits.count();
+	}
 	/** Analytic design bits-per-key `m / n`. */
 	get bitsPerKey() {
 		return this.#m / this.#n;
 	}
 	/**
+	* Estimates the current false-positive rate from the actual fill,
+	* `(length / m) ** k`. This reflects how full the filter is right now, not
+	* the design target; it rises as keys are added.
+	*
+	* @returns The estimated false-positive rate, `0` for an empty filter.
+	*/
+	rate() {
+		return (this.length / this.#m) ** this.#k;
+	}
+	/**
 	* Serializes the filter to a portable little-endian byte layout.
 	*
 	* @returns The serialized filter, readable by {@link BloomFilter.fromBytes}.
@@ -184,3 +216,4 @@ var BloomFilter = class BloomFilter {
 //#endregion
 exports.BloomFilter = BloomFilter;
 exports.BloomParamMismatchError = BloomParamMismatchError;
+exports.ParamError = require_params.ParamError;

package/dist/bloom/index.d.cts

@@ -1,4 +1,5 @@
 import { t as BytesLike } from "../bytes-DCuYtUVS.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. */
 declare class BloomParamMismatchError extends Error {
@@ -48,8 +49,24 @@ declare class BloomFilter {
    * {@link BloomFilter.create} unless restoring a specific configuration.
    */
   constructor({ m, k, seed }: BloomParams);
+  /** Number of bits in the filter. */
+  get m(): number;
+  /** Number of hash probes per key. */
+  get k(): number;
+  /** Hash seed. */
+  get seed(): number;
+  /** Number of bits currently set. */
+  get length(): number;
   /** Analytic design bits-per-key `m / n`. */
   get bitsPerKey(): number;
+  /**
+   * Estimates the current false-positive rate from the actual fill,
+   * `(length / m) ** k`. This reflects how full the filter is right now, not
+   * the design target; it rises as keys are added.
+   *
+   * @returns The estimated false-positive rate, `0` for an empty filter.
+   */
+  rate(): number;
   /**
    * Serializes the filter to a portable little-endian byte layout.
    *
@@ -79,4 +96,4 @@ declare class BloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BloomFilter, BloomParamMismatchError, type BloomParams };
+export { BloomFilter, BloomParamMismatchError, type BloomParams, ParamError };

package/dist/bloom/index.d.ts

@@ -1,4 +1,5 @@
 import { t as BytesLike } from "../bytes-DCuYtUVS.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. */
 declare class BloomParamMismatchError extends Error {
@@ -48,8 +49,24 @@ declare class BloomFilter {
    * {@link BloomFilter.create} unless restoring a specific configuration.
    */
   constructor({ m, k, seed }: BloomParams);
+  /** Number of bits in the filter. */
+  get m(): number;
+  /** Number of hash probes per key. */
+  get k(): number;
+  /** Hash seed. */
+  get seed(): number;
+  /** Number of bits currently set. */
+  get length(): number;
   /** Analytic design bits-per-key `m / n`. */
   get bitsPerKey(): number;
+  /**
+   * Estimates the current false-positive rate from the actual fill,
+   * `(length / m) ** k`. This reflects how full the filter is right now, not
+   * the design target; it rises as keys are added.
+   *
+   * @returns The estimated false-positive rate, `0` for an empty filter.
+   */
+  rate(): number;
   /**
    * Serializes the filter to a portable little-endian byte layout.
    *
@@ -79,4 +96,4 @@ declare class BloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BloomFilter, BloomParamMismatchError, type BloomParams };
+export { BloomFilter, BloomParamMismatchError, type BloomParams, ParamError };

package/dist/bloom/index.js

@@ -1,4 +1,5 @@
 import { a as probeInto, n as readHeader, r as writeHeader } from "../serialize-5XQ5y_R-.js";
+import { a as assertUint32, i as assertProbability, r as assertPositiveInt, t as ParamError } from "../params-ChTRNxM9.js";
 //#region src/core/bitset.ts
 var BitSetRangeError = class extends RangeError {
 	name = "BitSetRangeError";
@@ -79,6 +80,8 @@ var BloomFilter = class BloomFilter {
 	* @returns A new, empty filter.
 	*/
 	static create(n, epsilon) {
+		assertPositiveInt(n, "n");
+		assertProbability(epsilon, "epsilon");
 		const f = new BloomFilter(optimal(n, epsilon));
 		f.#n = n;
 		return f;
@@ -108,6 +111,9 @@ var BloomFilter = class BloomFilter {
 	* {@link BloomFilter.create} unless restoring a specific configuration.
 	*/
 	constructor({ m, k, seed = 0 }) {
+		assertPositiveInt(m, "m");
+		assertPositiveInt(k, "k");
+		assertUint32(seed, "seed");
 		this.#bits = new BitSet(m);
 		this.#m = m;
 		this.#k = k;
@@ -115,11 +121,37 @@ var BloomFilter = class BloomFilter {
 		this.#scratch = new Uint32Array(k);
 		this.#n = Math.round(m * Math.LN2 / k);
 	}
+	/** Number of bits in the filter. */
+	get m() {
+		return this.#m;
+	}
+	/** Number of hash probes per key. */
+	get k() {
+		return this.#k;
+	}
+	/** Hash seed. */
+	get seed() {
+		return this.#seed;
+	}
+	/** Number of bits currently set. */
+	get length() {
+		return this.#bits.count();
+	}
 	/** Analytic design bits-per-key `m / n`. */
 	get bitsPerKey() {
 		return this.#m / this.#n;
 	}
 	/**
+	* Estimates the current false-positive rate from the actual fill,
+	* `(length / m) ** k`. This reflects how full the filter is right now, not
+	* the design target; it rises as keys are added.
+	*
+	* @returns The estimated false-positive rate, `0` for an empty filter.
+	*/
+	rate() {
+		return (this.length / this.#m) ** this.#k;
+	}
+	/**
 	* Serializes the filter to a portable little-endian byte layout.
 	*
 	* @returns The serialized filter, readable by {@link BloomFilter.fromBytes}.
@@ -181,4 +213,4 @@ var BloomFilter = class BloomFilter {
 	}
 };
 //#endregion
-export { BloomFilter, BloomParamMismatchError };
+export { BloomFilter, BloomParamMismatchError, ParamError };

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.1.2";
+const VERSION = "0.3.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.1.2";
+const VERSION = "0.3.0";
 //#endregion
 export { VERSION };

package/dist/params-ChTRNxM9.js

@@ -0,0 +1,24 @@
+//#region src/core/params.ts
+/** Thrown when a structure is constructed with invalid parameters. */
+var ParamError = class extends RangeError {
+	/** Discriminates this error from other `Error`s. */
+	name = "ParamError";
+};
+/** Asserts `value` is an integer greater than or equal to 1. */
+function assertPositiveInt(value, label) {
+	if (!Number.isInteger(value) || value < 1) throw new ParamError(`${label} must be a positive integer, got ${String(value)}`);
+}
+/** Asserts `value` is a finite number greater than 0 (a positive real). */
+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 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)}`);
+}
+/** Asserts `value` is a finite number in the open interval `(0, 1)`. */
+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 };

package/dist/params-DnqJBqLS.d.cts

@@ -0,0 +1,8 @@
+//#region src/core/params.d.ts
+/** Thrown when a structure is constructed with invalid parameters. */
+declare class ParamError extends RangeError {
+  /** Discriminates this error from other `Error`s. */
+  override readonly name = "ParamError";
+}
+//#endregion
+export { ParamError as t };

package/dist/params-DnqJBqLS.d.ts

@@ -0,0 +1,8 @@
+//#region src/core/params.d.ts
+/** Thrown when a structure is constructed with invalid parameters. */
+declare class ParamError extends RangeError {
+  /** Discriminates this error from other `Error`s. */
+  override readonly name = "ParamError";
+}
+//#endregion
+export { ParamError as t };

package/dist/params-J8p3bKq5.cjs

@@ -0,0 +1,53 @@
+//#region src/core/params.ts
+/** Thrown when a structure is constructed with invalid parameters. */
+var ParamError = class extends RangeError {
+	/** Discriminates this error from other `Error`s. */
+	name = "ParamError";
+};
+/** Asserts `value` is an integer greater than or equal to 1. */
+function assertPositiveInt(value, label) {
+	if (!Number.isInteger(value) || value < 1) throw new ParamError(`${label} must be a positive integer, got ${String(value)}`);
+}
+/** Asserts `value` is a finite number greater than 0 (a positive real). */
+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 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)}`);
+}
+/** Asserts `value` is a finite number in the open interval `(0, 1)`. */
+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
+Object.defineProperty(exports, "ParamError", {
+	enumerable: true,
+	get: function() {
+		return ParamError;
+	}
+});
+Object.defineProperty(exports, "assertPositiveFinite", {
+	enumerable: true,
+	get: function() {
+		return assertPositiveFinite;
+	}
+});
+Object.defineProperty(exports, "assertPositiveInt", {
+	enumerable: true,
+	get: function() {
+		return assertPositiveInt;
+	}
+});
+Object.defineProperty(exports, "assertProbability", {
+	enumerable: true,
+	get: function() {
+		return assertProbability;
+	}
+});
+Object.defineProperty(exports, "assertUint32", {
+	enumerable: true,
+	get: function() {
+		return assertUint32;
+	}
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "distillate",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Probabilistic data structures for JavaScript. Space-efficient, approximate-membership filters (Bloom, Blocked Bloom, Binary Fuse) with tunable error and a portable binary format; zero dependencies, universal.",
   "keywords": [
     "bloom-filter",