distillate 0.13.0 → 0.14.0

package/README.md

@@ -42,20 +42,22 @@ Every push runs a CI smoke matrix that imports the built package on Node 22/24,
 
 Each structure ships as its own subpath, so you only bundle what you import.
 
-| Import                | Structure      | Answers            | Use for                                                  |
-| --------------------- | -------------- | ------------------ | -------------------------------------------------------- |
-| `distillate/bloom`    | Classic Bloom  | seen this key?     | Familiar default, migration from `bloom-filters`         |
-| `distillate/scalable` | Scalable Bloom | seen this key?     | Key count unknown or growing; keeps its FPR bound        |
-| `distillate/blocked`  | Blocked Bloom  | seen this key?     | Faster lookups and a lower FPR for a small space premium |
-| `distillate/fuse`     | Binary Fuse    | seen this key?     | Static set built once and queried a lot; least space     |
-| `distillate/cuckoo`   | Cuckoo         | seen this key?     | Keys come and go; the one filter with delete             |
-| `distillate/hll`      | HyperLogLog    | how many distinct? | Counting distinct users, IPs, or keys in fixed space     |
-| `distillate/countmin` | Count-Min      | how many times?    | Counting events per key in fixed space                   |
+| Import                | Structure      | Answers             | Use for                                                  |
+| --------------------- | -------------- | ------------------- | -------------------------------------------------------- |
+| `distillate/bloom`    | Classic Bloom  | seen this key?      | Familiar default, migration from `bloom-filters`         |
+| `distillate/scalable` | Scalable Bloom | seen this key?      | Key count unknown or growing; keeps its FPR bound        |
+| `distillate/blocked`  | Blocked Bloom  | seen this key?      | Faster lookups and a lower FPR for a small space premium |
+| `distillate/fuse`     | Binary Fuse    | seen this key?      | Static set built once and queried a lot; least space     |
+| `distillate/cuckoo`   | Cuckoo         | seen this key?      | Keys come and go; the one filter with delete             |
+| `distillate/hll`      | HyperLogLog    | how many distinct?  | Counting distinct users, IPs, or keys in fixed space     |
+| `distillate/countmin` | Count-Min      | how many times?     | Counting events per key in fixed space                   |
+| `distillate/topk`     | Top-K          | which are heaviest? | Finding the most frequent keys in fixed space            |
 
 The filters are mutable except Binary Fuse, which is built once from the whole
-key set. HyperLogLog and Count-Min are sketches rather than filters: neither
-reports whether it saw any particular key. HyperLogLog counts distinct keys,
-Count-Min counts how often each key appeared.
+key set. HyperLogLog, Count-Min and Top-K are sketches rather than filters:
+none reports whether it saw any particular key. HyperLogLog counts distinct
+keys, Count-Min counts how often each key appeared, and Top-K reports which
+keys appeared most.
 
 ### Classic Bloom (`distillate/bloom`)
 
@@ -189,6 +191,30 @@ hits.union(other).count("/login"); // 7
 
 Also: `equals`, `toBytes` / `fromBytes`, `toJSON` / `fromJSON`, `error()`, `epsilon`, `delta`, `width`, `depth`, `countMinSizing(epsilon, delta)`, and a low-level `new CountMinSketch({ width, depth, seed })`.
 
+### Top-K (`distillate/topk`)
+
+A **sketch** that lists the keys seen most often, in a table fixed by the error you ask for rather than by how many keys arrive. A key it holds never reads below its true count, and any key heavier than `error()` is guaranteed to be held. Full API and the bound: [Top-K guide](https://distillate.akxp.net/guides/topk/).
+
+```ts
+import { TopK } from "distillate/topk";
+
+const routes = TopK.create(0.01); // error factor
+routes.add("/login", 5);
+routes.add("/signup", 2);
+routes.add("/about");
+
+const decoder = new TextDecoder();
+routes
+  .top(2)
+  .map((e) => decoder.decode(e.key))
+  .join(); // "/login,/signup"
+routes.count("/login"); // 5
+```
+
+Keys come back as `Uint8Array`, exactly as recorded, so a serialized Top-K sketch holds your keys verbatim, unlike every other frame here. `union` combines sketches soundly but, unlike Count-Min's, not byte for byte as one sketch fed both streams.
+
+Also: `equals`, `toBytes` / `fromBytes`, `toJSON` / `fromJSON`, `total`, `error()`, `epsilon`, `capacity`, `topKSizing(epsilon)`, and a low-level `new TopK({ capacity, seed })`.
+
 ## Performance
 
 Classic Bloom head-to-head at a **matched 1% false-positive rate** over the same 100k keys, measured by identical code (cross-library harness, node v24.14.1, Apple M5):

package/dist/blocked/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_hasher = require("../hasher-MhY7aQ8F.cjs");
+const require_hasher = require("../hasher-DPXmP7SH.cjs");
 const require_serialize = require("../serialize-CHikZ4GH.cjs");
 const require_params = require("../params-UTZbJ22c.cjs");
 //#region src/blocked/blocked.ts

package/dist/blocked/index.js

@@ -1,4 +1,4 @@
-import { a as hash32x2Into, u as reduce } from "../hasher-3Cyn7Yg-.js";
+import { a as hash32x2Into, u as reduce } from "../hasher-DOdmZ-LI.js";
 import { a as TruncatedError, c as assertBodyLength, d as bytesEqual, f as fromJSONEnvelope, g as writeFrame, h as toJSONEnvelope, i as SerializationError, l as assertMinBodyLength, m as readHeader, n as ChecksumError, o as UnknownHashVariantError, r as ReservedBitsError, s as UnknownVersionError, t as BadMagicError, u as assertParamsPadding } from "../serialize-CMSYFym-.js";
 import { i as assertProbability, n as assertPositiveFinite, o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-CeajSrwv.js";
 //#region src/blocked/blocked.ts

package/dist/bloom/index.cjs

@@ -1,9 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_bitset = require("../bitset-QYGqxnEf.cjs");
-const require_hasher = require("../hasher-MhY7aQ8F.cjs");
+const require_sizing = require("../sizing-Ch0SDdza.cjs");
+const require_hasher = require("../hasher-DPXmP7SH.cjs");
 const require_serialize = require("../serialize-CHikZ4GH.cjs");
 const require_params = require("../params-UTZbJ22c.cjs");
-const require_sizing = require("../sizing-R1pwbzjC.cjs");
 //#region src/bloom/bloom.ts
 const TYPE = 1;
 const PARAMS_SIZE = 16;
@@ -64,7 +63,7 @@ var BloomFilter = class BloomFilter {
 			require_params.assertPositiveInt(n, "n");
 			require_params.assertUint32(n, "n");
 		}
-		this.#bits = new require_bitset.BitSet(m);
+		this.#bits = new require_sizing.BitSet(m);
 		this.#m = m;
 		this.#k = k;
 		this.#seed = seed;

package/dist/bloom/index.d.cts

@@ -1,7 +1,6 @@
 import { t as BytesLike } from "../bytes-DCuYtUVS.cjs";
 import { a as ReservedBitsError, c as UnknownHashVariantError, l as UnknownVersionError, n as ChecksumError, o as SerializationError, r as FilterJSON, s as TruncatedError, t as BadMagicError } from "../serialize--xR6vGSW.cjs";
 import { t as ParamError } from "../params-DnqJBqLS.cjs";
-import { i as bloomSizing, t as BloomSizing } from "../sizing-BmKfHf_V.cjs";
 //#region src/bloom/bloom.d.ts
 /** Thrown when an operation requires two filters built with identical parameters. */
 export declare class BloomParamMismatchError extends Error {
@@ -144,4 +143,15 @@ export declare class BloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BadMagicError, type BloomParams, type BloomSizing, ChecksumError, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, bloomSizing };
+//#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`. */
+export declare function bloomSizing(n: number, epsilon: number): BloomSizing;
+//#endregion
+export { BadMagicError, type BloomParams, type BloomSizing, ChecksumError, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError };

package/dist/bloom/index.d.ts

@@ -1,7 +1,6 @@
 import { t as BytesLike } from "../bytes-DCuYtUVS.js";
 import { a as ReservedBitsError, c as UnknownHashVariantError, l as UnknownVersionError, n as ChecksumError, o as SerializationError, r as FilterJSON, s as TruncatedError, t as BadMagicError } from "../serialize--xR6vGSW.js";
 import { t as ParamError } from "../params-DnqJBqLS.js";
-import { i as bloomSizing, t as BloomSizing } from "../sizing-BmKfHf_V.js";
 //#region src/bloom/bloom.d.ts
 /** Thrown when an operation requires two filters built with identical parameters. */
 export declare class BloomParamMismatchError extends Error {
@@ -144,4 +143,15 @@ export declare class BloomFilter {
   has(key: BytesLike): boolean;
 }
 //#endregion
-export { BadMagicError, type BloomParams, type BloomSizing, ChecksumError, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, bloomSizing };
+//#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`. */
+export declare function bloomSizing(n: number, epsilon: number): BloomSizing;
+//#endregion
+export { BadMagicError, type BloomParams, type BloomSizing, ChecksumError, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError };

package/dist/bloom/index.js

@@ -1,8 +1,7 @@
-import { t as BitSet } from "../bitset-Cf2jwRJX.js";
-import { c as probeInto } from "../hasher-3Cyn7Yg-.js";
+import { n as BitSet, t as bloomSizing } from "../sizing-zxCBlyhO.js";
+import { c as probeInto } from "../hasher-DOdmZ-LI.js";
 import { a as TruncatedError, c as assertBodyLength, d as bytesEqual, f as fromJSONEnvelope, g as writeFrame, h as toJSONEnvelope, i as SerializationError, l as assertMinBodyLength, m as readHeader, n as ChecksumError, o as UnknownHashVariantError, r as ReservedBitsError, s as UnknownVersionError, t as BadMagicError, u as assertParamsPadding } from "../serialize-CMSYFym-.js";
 import { a as assertUint16, i as assertProbability, o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-CeajSrwv.js";
-import { t as bloomSizing } from "../sizing-D3-_7pdP.js";
 //#region src/bloom/bloom.ts
 const TYPE = 1;
 const PARAMS_SIZE = 16;

package/dist/bytes-Be7tq1F7.js

@@ -0,0 +1,9 @@
+//#region src/core/bytes.ts
+const encoder = new TextEncoder();
+function normalize(input) {
+	if (typeof input === "string") return encoder.encode(input);
+	if (input instanceof Uint8Array) return input;
+	return new Uint8Array(input);
+}
+//#endregion
+export { normalize as t };

package/dist/bytes-D2duG1jq.cjs

@@ -0,0 +1,14 @@
+//#region src/core/bytes.ts
+const encoder = new TextEncoder();
+function normalize(input) {
+	if (typeof input === "string") return encoder.encode(input);
+	if (input instanceof Uint8Array) return input;
+	return new Uint8Array(input);
+}
+//#endregion
+Object.defineProperty(exports, "normalize", {
+	enumerable: true,
+	get: function() {
+		return normalize;
+	}
+});

package/dist/countmin/index.cjs

@@ -1,8 +1,17 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_hasher = require("../hasher-MhY7aQ8F.cjs");
+const require_hasher = require("../hasher-DPXmP7SH.cjs");
 const require_serialize = require("../serialize-CHikZ4GH.cjs");
 const require_params = require("../params-UTZbJ22c.cjs");
-const require_sizing = require("../sizing-R1pwbzjC.cjs");
+//#region src/countmin/sizing.ts
+function countMinSizing(epsilon, delta) {
+	require_params.assertProbability(epsilon, "epsilon");
+	require_params.assertProbability(delta, "delta");
+	return {
+		width: Math.ceil(Math.E / epsilon),
+		depth: Math.ceil(Math.log(1 / delta))
+	};
+}
+//#endregion
 //#region src/countmin/countmin.ts
 const TYPE = 8;
 const PARAMS_SIZE = 16;
@@ -37,7 +46,7 @@ var CountMinSketch = class CountMinSketch {
 	static create(epsilon, delta, options = {}) {
 		return new CountMinSketch({
 			...options,
-			...require_sizing.countMinSizing(epsilon, delta)
+			...countMinSizing(epsilon, delta)
 		});
 	}
 	static from(keys, epsilon, delta, options = {}) {
@@ -191,4 +200,4 @@ exports.SerializationError = require_serialize.SerializationError;
 exports.TruncatedError = require_serialize.TruncatedError;
 exports.UnknownHashVariantError = require_serialize.UnknownHashVariantError;
 exports.UnknownVersionError = require_serialize.UnknownVersionError;
-exports.countMinSizing = require_sizing.countMinSizing;
+exports.countMinSizing = countMinSizing;

package/dist/countmin/index.d.cts

@@ -1,7 +1,6 @@
 import { t as BytesLike } from "../bytes-DCuYtUVS.cjs";
 import { a as ReservedBitsError, c as UnknownHashVariantError, l as UnknownVersionError, n as ChecksumError, o as SerializationError, r as FilterJSON, s as TruncatedError, t as BadMagicError } from "../serialize--xR6vGSW.cjs";
 import { t as ParamError } from "../params-DnqJBqLS.cjs";
-import { a as countMinSizing, n as CountMinSizing } from "../sizing-BmKfHf_V.cjs";
 //#region src/countmin/countmin.d.ts
 /** Thrown when an operation requires two sketches built with identical parameters. */
 export declare class CountMinParamMismatchError extends Error {
@@ -175,4 +174,18 @@ export declare class CountMinSketch {
   count(key: BytesLike): number;
 }
 //#endregion
-export { BadMagicError, ChecksumError, type CountMinOptions, type CountMinParams, type CountMinSizing, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, countMinSizing };
+//#region src/countmin/sizing.d.ts
+/** Count-Min geometry: the `CountMinParams` fields a sizing solve determines. */
+interface CountMinSizing {
+  /** Counters per row. */
+  width: number;
+  /** Number of rows, one probe each. */
+  depth: number;
+}
+/**
+ * Count-Min sizing: `width` columns and `depth` rows for an estimate at most
+ * `epsilon * total` above the true count, with probability `1 - delta`.
+ */
+export declare function countMinSizing(epsilon: number, delta: number): CountMinSizing;
+//#endregion
+export { BadMagicError, ChecksumError, type CountMinOptions, type CountMinParams, type CountMinSizing, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError };

package/dist/countmin/index.d.ts

@@ -1,7 +1,6 @@
 import { t as BytesLike } from "../bytes-DCuYtUVS.js";
 import { a as ReservedBitsError, c as UnknownHashVariantError, l as UnknownVersionError, n as ChecksumError, o as SerializationError, r as FilterJSON, s as TruncatedError, t as BadMagicError } from "../serialize--xR6vGSW.js";
 import { t as ParamError } from "../params-DnqJBqLS.js";
-import { a as countMinSizing, n as CountMinSizing } from "../sizing-BmKfHf_V.js";
 //#region src/countmin/countmin.d.ts
 /** Thrown when an operation requires two sketches built with identical parameters. */
 export declare class CountMinParamMismatchError extends Error {
@@ -175,4 +174,18 @@ export declare class CountMinSketch {
   count(key: BytesLike): number;
 }
 //#endregion
-export { BadMagicError, ChecksumError, type CountMinOptions, type CountMinParams, type CountMinSizing, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, countMinSizing };
+//#region src/countmin/sizing.d.ts
+/** Count-Min geometry: the `CountMinParams` fields a sizing solve determines. */
+interface CountMinSizing {
+  /** Counters per row. */
+  width: number;
+  /** Number of rows, one probe each. */
+  depth: number;
+}
+/**
+ * Count-Min sizing: `width` columns and `depth` rows for an estimate at most
+ * `epsilon * total` above the true count, with probability `1 - delta`.
+ */
+export declare function countMinSizing(epsilon: number, delta: number): CountMinSizing;
+//#endregion
+export { BadMagicError, ChecksumError, type CountMinOptions, type CountMinParams, type CountMinSizing, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError };

package/dist/countmin/index.js

@@ -1,7 +1,16 @@
-import { a as hash32x2Into, s as probeAt } from "../hasher-3Cyn7Yg-.js";
+import { a as hash32x2Into, s as probeAt } from "../hasher-DOdmZ-LI.js";
 import { a as TruncatedError, c as assertBodyLength, d as bytesEqual, f as fromJSONEnvelope, g as writeFrame, h as toJSONEnvelope, i as SerializationError, l as assertMinBodyLength, m as readHeader, n as ChecksumError, o as UnknownHashVariantError, r as ReservedBitsError, s as UnknownVersionError, t as BadMagicError, u as assertParamsPadding } from "../serialize-CMSYFym-.js";
-import { o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-CeajSrwv.js";
-import { n as countMinSizing } from "../sizing-D3-_7pdP.js";
+import { i as assertProbability, o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-CeajSrwv.js";
+//#region src/countmin/sizing.ts
+function countMinSizing(epsilon, delta) {
+	assertProbability(epsilon, "epsilon");
+	assertProbability(delta, "delta");
+	return {
+		width: Math.ceil(Math.E / epsilon),
+		depth: Math.ceil(Math.log(1 / delta))
+	};
+}
+//#endregion
 //#region src/countmin/countmin.ts
 const TYPE = 8;
 const PARAMS_SIZE = 16;

package/dist/cuckoo/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_hasher = require("../hasher-MhY7aQ8F.cjs");
+const require_hasher = require("../hasher-DPXmP7SH.cjs");
 const require_serialize = require("../serialize-CHikZ4GH.cjs");
 const require_params = require("../params-UTZbJ22c.cjs");
 function cuckooSizing(n, epsilon) {

package/dist/cuckoo/index.js

@@ -1,4 +1,4 @@
-import { i as hash128KeyInto, u as reduce } from "../hasher-3Cyn7Yg-.js";
+import { i as hash128KeyInto, u as reduce } from "../hasher-DOdmZ-LI.js";
 import { a as TruncatedError, c as assertBodyLength, d as bytesEqual, f as fromJSONEnvelope, g as writeFrame, h as toJSONEnvelope, i as SerializationError, l as assertMinBodyLength, m as readHeader, n as ChecksumError, o as UnknownHashVariantError, r as ReservedBitsError, s as UnknownVersionError, t as BadMagicError, u as assertParamsPadding } from "../serialize-CMSYFym-.js";
 import { i as assertProbability, o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-CeajSrwv.js";
 function cuckooSizing(n, epsilon) {

package/dist/fuse/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_hasher = require("../hasher-MhY7aQ8F.cjs");
+const require_hasher = require("../hasher-DPXmP7SH.cjs");
 const require_serialize = require("../serialize-CHikZ4GH.cjs");
 //#region src/fuse/fuse.ts
 const ARITY = 3;

package/dist/fuse/index.js

@@ -1,4 +1,4 @@
-import { i as hash128KeyInto, n as RLO, o as mul64, r as fmix64, t as RHI } from "../hasher-3Cyn7Yg-.js";
+import { i as hash128KeyInto, n as RLO, o as mul64, r as fmix64, t as RHI } from "../hasher-DOdmZ-LI.js";
 import { a as TruncatedError, c as assertBodyLength, d as bytesEqual, f as fromJSONEnvelope, g as writeFrame, h as toJSONEnvelope, i as SerializationError, l as assertMinBodyLength, m as readHeader, n as ChecksumError, o as UnknownHashVariantError, r as ReservedBitsError, s as UnknownVersionError, t as BadMagicError } from "../serialize-CMSYFym-.js";
 //#region src/fuse/fuse.ts
 const ARITY = 3;

package/dist/{hasher-3Cyn7Yg-.js → hasher-DOdmZ-LI.js}

@@ -1,11 +1,4 @@
-//#region src/core/bytes.ts
-const encoder = new TextEncoder();
-function normalize(input) {
-	if (typeof input === "string") return encoder.encode(input);
-	if (input instanceof Uint8Array) return input;
-	return new Uint8Array(input);
-}
-//#endregion
+import { t as normalize } from "./bytes-Be7tq1F7.js";
 //#region src/core/hasher.ts
 let RLO = 0;
 let RHI = 0;

package/dist/{hasher-MhY7aQ8F.cjs → hasher-DPXmP7SH.cjs}

@@ -1,11 +1,4 @@
-//#region src/core/bytes.ts
-const encoder = new TextEncoder();
-function normalize(input) {
-	if (typeof input === "string") return encoder.encode(input);
-	if (input instanceof Uint8Array) return input;
-	return new Uint8Array(input);
-}
-//#endregion
+const require_bytes = require("./bytes-D2duG1jq.cjs");
 //#region src/core/hasher.ts
 let RLO = 0;
 let RHI = 0;
@@ -185,7 +178,7 @@ function encodeKey(key) {
 		encBytes = keyBuf;
 		return;
 	}
-	encBytes = normalize(key);
+	encBytes = require_bytes.normalize(key);
 	encLen = encBytes.length;
 }
 function keyToLanes(key, seed) {

package/dist/hll/index.cjs

@@ -1,8 +1,14 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_hasher = require("../hasher-MhY7aQ8F.cjs");
+const require_hasher = require("../hasher-DPXmP7SH.cjs");
 const require_serialize = require("../serialize-CHikZ4GH.cjs");
 const require_params = require("../params-UTZbJ22c.cjs");
-const require_sizing = require("../sizing-R1pwbzjC.cjs");
+function hllSizing(relativeError) {
+	require_params.assertProbability(relativeError, "relativeError");
+	const p = Math.max(4, Math.ceil(2 * Math.log2(1.04 / relativeError)));
+	if (p > 18) throw new require_params.ParamError(`relativeError ${String(relativeError)} needs precision ${String(p)}, above the maximum ${String(18)}`);
+	return { p };
+}
+//#endregion
 //#region src/hll/estimate.ts
 const ALPHA_INF = .5 / Math.LN2;
 function sigma(x) {
@@ -171,7 +177,7 @@ var HyperLogLog = class HyperLogLog {
 		this.#sparse = new Int32Array(sparseCapacity(this.#registers));
 	}
 	static create(relativeError) {
-		return new HyperLogLog(require_sizing.hllSizing(relativeError));
+		return new HyperLogLog(hllSizing(relativeError));
 	}
 	static from(keys, relativeError) {
 		const sketch = HyperLogLog.create(relativeError);
@@ -363,4 +369,4 @@ exports.SerializationError = require_serialize.SerializationError;
 exports.TruncatedError = require_serialize.TruncatedError;
 exports.UnknownHashVariantError = require_serialize.UnknownHashVariantError;
 exports.UnknownVersionError = require_serialize.UnknownVersionError;
-exports.hllSizing = require_sizing.hllSizing;
+exports.hllSizing = hllSizing;

package/dist/hll/index.d.cts

@@ -1,7 +1,6 @@
 import { t as BytesLike } from "../bytes-DCuYtUVS.cjs";
 import { a as ReservedBitsError, c as UnknownHashVariantError, l as UnknownVersionError, n as ChecksumError, o as SerializationError, r as FilterJSON, s as TruncatedError, t as BadMagicError } from "../serialize--xR6vGSW.cjs";
 import { t as ParamError } from "../params-DnqJBqLS.cjs";
-import { o as hllSizing, r as HllSizing } from "../sizing-BmKfHf_V.cjs";
 //#region src/hll/hll.d.ts
 /** Construction parameters for a {@link HyperLogLog} sketch. */
 interface HllParams {
@@ -117,4 +116,16 @@ export declare class HyperLogLog {
   count(): number;
 }
 //#endregion
-export { BadMagicError, ChecksumError, type FilterJSON, type HllParams, type HllSizing, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, hllSizing };
+//#region src/hll/sizing.d.ts
+/** HyperLogLog geometry: the `HllParams` fields a sizing solve determines. */
+interface HllSizing {
+  /** Precision: the sketch holds `2 ** p` registers. */
+  p: number;
+}
+/**
+ * Smallest precision whose standard error `1.04 / sqrt(2 ** p)` meets
+ * `relativeError`. Throws {@link ParamError} when even `HLL_MAX_P` cannot.
+ */
+export declare function hllSizing(relativeError: number): HllSizing;
+//#endregion
+export { BadMagicError, ChecksumError, type FilterJSON, type HllParams, type HllSizing, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError };

package/dist/hll/index.d.ts

@@ -1,7 +1,6 @@
 import { t as BytesLike } from "../bytes-DCuYtUVS.js";
 import { a as ReservedBitsError, c as UnknownHashVariantError, l as UnknownVersionError, n as ChecksumError, o as SerializationError, r as FilterJSON, s as TruncatedError, t as BadMagicError } from "../serialize--xR6vGSW.js";
 import { t as ParamError } from "../params-DnqJBqLS.js";
-import { o as hllSizing, r as HllSizing } from "../sizing-BmKfHf_V.js";
 //#region src/hll/hll.d.ts
 /** Construction parameters for a {@link HyperLogLog} sketch. */
 interface HllParams {
@@ -117,4 +116,16 @@ export declare class HyperLogLog {
   count(): number;
 }
 //#endregion
-export { BadMagicError, ChecksumError, type FilterJSON, type HllParams, type HllSizing, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, hllSizing };
+//#region src/hll/sizing.d.ts
+/** HyperLogLog geometry: the `HllParams` fields a sizing solve determines. */
+interface HllSizing {
+  /** Precision: the sketch holds `2 ** p` registers. */
+  p: number;
+}
+/**
+ * Smallest precision whose standard error `1.04 / sqrt(2 ** p)` meets
+ * `relativeError`. Throws {@link ParamError} when even `HLL_MAX_P` cannot.
+ */
+export declare function hllSizing(relativeError: number): HllSizing;
+//#endregion
+export { BadMagicError, ChecksumError, type FilterJSON, type HllParams, type HllSizing, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError };

package/dist/hll/index.js

@@ -1,7 +1,13 @@
-import { i as hash128KeyInto } from "../hasher-3Cyn7Yg-.js";
+import { i as hash128KeyInto } from "../hasher-DOdmZ-LI.js";
 import { a as TruncatedError, c as assertBodyLength, f as fromJSONEnvelope, g as writeFrame, h as toJSONEnvelope, i as SerializationError, l as assertMinBodyLength, m as readHeader, n as ChecksumError, o as UnknownHashVariantError, r as ReservedBitsError, s as UnknownVersionError, t as BadMagicError, u as assertParamsPadding } from "../serialize-CMSYFym-.js";
-import { o as assertUint32, t as ParamError } from "../params-CeajSrwv.js";
-import { r as hllSizing } from "../sizing-D3-_7pdP.js";
+import { i as assertProbability, o as assertUint32, t as ParamError } from "../params-CeajSrwv.js";
+function hllSizing(relativeError) {
+	assertProbability(relativeError, "relativeError");
+	const p = Math.max(4, Math.ceil(2 * Math.log2(1.04 / relativeError)));
+	if (p > 18) throw new ParamError(`relativeError ${String(relativeError)} needs precision ${String(p)}, above the maximum ${String(18)}`);
+	return { p };
+}
+//#endregion
 //#region src/hll/estimate.ts
 const ALPHA_INF = .5 / Math.LN2;
 function sigma(x) {

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#endregion
 //#region src/index.ts
-const VERSION = "0.13.0";
+const VERSION = "0.14.0";
 //#endregion
 exports.VERSION = VERSION;

package/dist/index.js

@@ -1,5 +1,5 @@
 //#endregion
 //#region src/index.ts
-const VERSION = "0.13.0";
+const VERSION = "0.14.0";
 //#endregion
 export { VERSION };

package/dist/scalable/index.cjs

@@ -1,9 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_bitset = require("../bitset-QYGqxnEf.cjs");
-const require_hasher = require("../hasher-MhY7aQ8F.cjs");
+const require_sizing = require("../sizing-Ch0SDdza.cjs");
+const require_hasher = require("../hasher-DPXmP7SH.cjs");
 const require_serialize = require("../serialize-CHikZ4GH.cjs");
 const require_params = require("../params-UTZbJ22c.cjs");
-const require_sizing = require("../sizing-R1pwbzjC.cjs");
 //#region src/scalable/scalable.ts
 const MAX_BITS = 4294967295;
 const TYPE = 6;
@@ -35,7 +34,7 @@ function readStages(body, entries, start) {
 	let at = start;
 	return entries.map((entry, i) => {
 		const length = Math.ceil(entry.m / 8);
-		const bits = new require_bitset.BitSet(entry.m);
+		const bits = new require_sizing.BitSet(entry.m);
 		bits.bytes.set(body.subarray(at, at + length));
 		for (let j = at + length; j < at + padded8(length); j++) if (body[j] !== 0) throw new require_serialize.SerializationError(`scalable: stage ${String(i)} bit padding is not zero`);
 		at += padded8(length);
@@ -103,7 +102,7 @@ var ScalableBloomFilter = class ScalableBloomFilter {
 	}
 	#open({ capacity, m, k }) {
 		const stage = {
-			bits: new require_bitset.BitSet(m),
+			bits: new require_sizing.BitSet(m),
 			m,
 			k,
 			capacity,
@@ -206,7 +205,7 @@ var ScalableBloomFilter = class ScalableBloomFilter {
 		this.#assertMergeable(other);
 		const [longer, shorter] = this.#stages.length >= other.#stages.length ? [this.#stages, other.#stages] : [other.#stages, this.#stages];
 		const stages = longer.map((stage, i) => {
-			const bits = new require_bitset.BitSet(stage.m);
+			const bits = new require_sizing.BitSet(stage.m);
 			bits.bytes.set(stage.bits.bytes);
 			const twin = shorter[i];
 			if (twin) {

package/dist/scalable/index.js

@@ -1,8 +1,7 @@
-import { t as BitSet } from "../bitset-Cf2jwRJX.js";
-import { i as hash128KeyInto, l as probeLanesInto, s as probeAt } from "../hasher-3Cyn7Yg-.js";
+import { n as BitSet, t as bloomSizing } from "../sizing-zxCBlyhO.js";
+import { i as hash128KeyInto, l as probeLanesInto, s as probeAt } from "../hasher-DOdmZ-LI.js";
 import { a as TruncatedError, c as assertBodyLength, d as bytesEqual, f as fromJSONEnvelope, g as writeFrame, h as toJSONEnvelope, i as SerializationError, l as assertMinBodyLength, m as readHeader, n as ChecksumError, o as UnknownHashVariantError, r as ReservedBitsError, s as UnknownVersionError, t as BadMagicError, u as assertParamsPadding } from "../serialize-CMSYFym-.js";
 import { i as assertProbability, o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-CeajSrwv.js";
-import { t as bloomSizing } from "../sizing-D3-_7pdP.js";
 //#region src/scalable/scalable.ts
 const MAX_BITS = 4294967295;
 const TYPE = 6;

package/dist/{bitset-QYGqxnEf.cjs → sizing-Ch0SDdza.cjs}

@@ -29,9 +29,24 @@ var BitSet = class {
 	}
 };
 //#endregion
+//#region src/core/sizing.ts
+function bloomSizing(n, epsilon) {
+	const m = Math.ceil(-n * Math.log(epsilon) / (Math.LN2 * Math.LN2));
+	return {
+		m,
+		k: Math.max(1, Math.round(m / n * Math.LN2))
+	};
+}
+//#endregion
 Object.defineProperty(exports, "BitSet", {
 	enumerable: true,
 	get: function() {
 		return BitSet;
 	}
 });
+Object.defineProperty(exports, "bloomSizing", {
+	enumerable: true,
+	get: function() {
+		return bloomSizing;
+	}
+});

package/dist/{bitset-Cf2jwRJX.js → sizing-zxCBlyhO.js}

@@ -29,4 +29,13 @@ var BitSet = class {
 	}
 };
 //#endregion
-export { BitSet as t };
+//#region src/core/sizing.ts
+function bloomSizing(n, epsilon) {
+	const m = Math.ceil(-n * Math.log(epsilon) / (Math.LN2 * Math.LN2));
+	return {
+		m,
+		k: Math.max(1, Math.round(m / n * Math.LN2))
+	};
+}
+//#endregion
+export { BitSet as n, bloomSizing as t };