distillate 0.6.0 → 0.7.0

package/dist/blocked/index.cjs

@@ -267,3 +267,5 @@ function fillBlock(key, numBlocks, seed, outWords, outBits) {
 exports.BlockedBloomFilter = BlockedBloomFilter;
 exports.BlockedBloomParamMismatchError = BlockedBloomParamMismatchError;
 exports.ParamError = require_params.ParamError;
+exports.blockedBitsPerKey = blockedBitsPerKey;
+exports.blockedFprAt = blockedFprAt;

package/dist/blocked/index.d.cts

@@ -1,6 +1,21 @@
 import { n as BytesLike, t as FilterJSON } from "../serialize-DRKh6QOr.cjs";
 import { t as ParamError } from "../params-DnqJBqLS.cjs";
 //#region src/blocked/blocked.d.ts
+/**
+ * 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)`.
+ */
+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;
 /** Thrown when an operation requires two filters built with identical parameters. */
 declare class BlockedBloomParamMismatchError extends Error {
   /** Discriminates this error from other `Error`s. */
@@ -127,4 +142,4 @@ declare class BlockedBloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams, type FilterJSON, ParamError };
+export { BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams, type FilterJSON, ParamError, blockedBitsPerKey, blockedFprAt };

package/dist/blocked/index.d.ts

@@ -1,6 +1,21 @@
 import { n as BytesLike, t as FilterJSON } from "../serialize-DRKh6QOr.js";
 import { t as ParamError } from "../params-DnqJBqLS.js";
 //#region src/blocked/blocked.d.ts
+/**
+ * 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)`.
+ */
+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;
 /** Thrown when an operation requires two filters built with identical parameters. */
 declare class BlockedBloomParamMismatchError extends Error {
   /** Discriminates this error from other `Error`s. */
@@ -127,4 +142,4 @@ declare class BlockedBloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams, type FilterJSON, ParamError };
+export { BlockedBloomFilter, BlockedBloomParamMismatchError, type BlockedBloomParams, type FilterJSON, ParamError, blockedBitsPerKey, blockedFprAt };

package/dist/blocked/index.js

@@ -263,4 +263,4 @@ function fillBlock(key, numBlocks, seed, outWords, outBits) {
 	}
 }
 //#endregion
-export { BlockedBloomFilter, BlockedBloomParamMismatchError, ParamError };
+export { BlockedBloomFilter, BlockedBloomParamMismatchError, ParamError, blockedBitsPerKey, blockedFprAt };

package/dist/bloom/index.cjs

@@ -34,7 +34,7 @@ var BitSet = class {
 //#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,
@@ -79,7 +79,7 @@ var BloomFilter = class BloomFilter {
 		require_params.assertPositiveInt(n, "n");
 		require_params.assertUint32(n, "n");
 		require_params.assertProbability(epsilon, "epsilon");
-		return BloomFilter.#withN(optimal(n, epsilon), n);
+		return BloomFilter.#withN(bloomSizing(n, epsilon), n);
 	}
 	/**
 	* Builds a filter from `keys`, sized for their count at the target
@@ -266,3 +266,4 @@ var BloomFilter = class BloomFilter {
 exports.BloomFilter = BloomFilter;
 exports.BloomParamMismatchError = BloomParamMismatchError;
 exports.ParamError = require_params.ParamError;
+exports.bloomSizing = bloomSizing;

package/dist/bloom/index.d.cts

@@ -128,4 +128,15 @@ declare class BloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BloomFilter, BloomParamMismatchError, type BloomParams, type FilterJSON, ParamError };
+//#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 { BloomFilter, BloomParamMismatchError, type BloomParams, type BloomSizing, type FilterJSON, ParamError, bloomSizing };

package/dist/bloom/index.d.ts

@@ -128,4 +128,15 @@ declare class BloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BloomFilter, BloomParamMismatchError, type BloomParams, type FilterJSON, ParamError };
+//#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 { BloomFilter, BloomParamMismatchError, type BloomParams, type BloomSizing, type FilterJSON, ParamError, bloomSizing };

package/dist/bloom/index.js

@@ -33,7 +33,7 @@ var BitSet = class {
 //#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,
@@ -78,7 +78,7 @@ var BloomFilter = class BloomFilter {
 		assertPositiveInt(n, "n");
 		assertUint32(n, "n");
 		assertProbability(epsilon, "epsilon");
-		return BloomFilter.#withN(optimal(n, epsilon), n);
+		return BloomFilter.#withN(bloomSizing(n, epsilon), n);
 	}
 	/**
 	* Builds a filter from `keys`, sized for their count at the target
@@ -262,4 +262,4 @@ var BloomFilter = class BloomFilter {
 	}
 };
 //#endregion
-export { BloomFilter, BloomParamMismatchError, ParamError };
+export { BloomFilter, BloomParamMismatchError, ParamError, bloomSizing };

package/dist/fuse/index.cjs

@@ -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.
@@ -367,3 +380,4 @@ var BinaryFuse16 = class BinaryFuse16 extends BinaryFuse {
 exports.BinaryFuse16 = BinaryFuse16;
 exports.BinaryFuse8 = BinaryFuse8;
 exports.BinaryFuseBuildError = BinaryFuseBuildError;
+exports.fuseBitsPerKey = fuseBitsPerKey;

package/dist/fuse/index.d.cts

@@ -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;
@@ -130,4 +140,4 @@ declare class BinaryFuse16 extends BinaryFuse {
   static fromJSON(value: unknown): BinaryFuse16;
 }
 //#endregion
-export { BinaryFuse16, BinaryFuse8, BinaryFuseBuildError, type FilterJSON };
+export { BinaryFuse16, BinaryFuse8, BinaryFuseBuildError, type FilterJSON, fuseBitsPerKey };

package/dist/fuse/index.d.ts

@@ -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;
@@ -130,4 +140,4 @@ declare class BinaryFuse16 extends BinaryFuse {
   static fromJSON(value: unknown): BinaryFuse16;
 }
 //#endregion
-export { BinaryFuse16, BinaryFuse8, BinaryFuseBuildError, type FilterJSON };
+export { BinaryFuse16, BinaryFuse8, BinaryFuseBuildError, type FilterJSON, fuseBitsPerKey };

package/dist/fuse/index.js

@@ -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.
@@ -363,4 +376,4 @@ var BinaryFuse16 = class BinaryFuse16 extends BinaryFuse {
 	}
 };
 //#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.6.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.6.0";
+const VERSION = "0.7.0";
 //#endregion
 export { VERSION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "distillate",
-  "version": "0.6.0",
+  "version": "0.7.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",
@@ -66,13 +66,13 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@microsoft/api-extractor": "^7.58.12",
-    "@types/node": "^26.1.2",
+    "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^4.1.10",
     "fast-check": "^4.9.0",
     "mitata": "^1.0.34",
-    "publint": "^0.3.22",
+    "publint": "^0.3.23",
     "tsdown": "^0.22.14",
-    "tsx": "^4.23.1",
+    "tsx": "^4.23.12",
     "typedoc": "^0.28.20",
     "typedoc-plugin-markdown": "^4.12.0",
     "typescript": "^5.9.3",