distillate 0.12.0 → 0.14.0

package/dist/countmin/index.d.ts

@@ -0,0 +1,191 @@
+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";
+//#region src/countmin/countmin.d.ts
+/** Thrown when an operation requires two sketches built with identical parameters. */
+export declare class CountMinParamMismatchError extends Error {
+  /** Discriminates this error from other `Error`s. */
+  override readonly name = "CountMinParamMismatchError";
+}
+/** Thrown when an add would carry a counter past what a u32 holds. */
+export declare class CountMinOverflowError extends RangeError {
+  /** Discriminates this error from other `Error`s. */
+  override readonly name = "CountMinOverflowError";
+}
+/** Options accepted alongside a sizing solve: everything but the geometry. */
+type CountMinOptions = Omit<CountMinParams, "width" | "depth">;
+/** Low-level Count-Min sketch parameters. */
+interface CountMinParams {
+  /** Counters per row. */
+  width: number;
+  /** Number of rows, one probe each. */
+  depth: number;
+  /** Hash seed; defaults to `0`. */
+  seed?: number;
+}
+/**
+ * A Count-Min sketch: a fixed-size frequency estimate with a tunable
+ * overestimate and no underestimate.
+ *
+ * @example
+ * ```ts
+ * const sketch = CountMinSketch.create(0.001, 0.001);
+ * sketch.add("alice");
+ * sketch.add("alice", 3);
+ * sketch.count("alice"); // 4 (or a rare overestimate)
+ * ```
+ */
+export declare class CountMinSketch {
+  #private;
+  /**
+   * Creates a sketch whose estimate is at most `epsilon * total` above the
+   * true count, with probability `1 - delta`.
+   *
+   * Unlike a filter, a sketch is sized by the error it targets rather than by
+   * how many keys it will see, so no key count is needed.
+   *
+   * @param epsilon - Error factor relative to the total recorded, e.g. `0.001`.
+   * @param delta - Probability the bound is exceeded, e.g. `0.001`.
+   * @param options - Optional seed.
+   * @returns A new, empty sketch.
+   */
+  static create(epsilon: number, delta: number, options?: CountMinOptions): CountMinSketch;
+  /**
+   * Builds a sketch recording `keys`, at the target error bound. The
+   * ergonomic entry point when the stream is already in hand.
+   *
+   * A repeated key is counted once per occurrence, which is the whole point of
+   * a frequency sketch. This is the opposite of `CuckooFilter.from`, where a
+   * repeat costs a slot and is therefore dropped.
+   *
+   * @param keys - The keys to record, repeats included.
+   * @param epsilon - Error factor relative to the total recorded.
+   * @param delta - Probability the bound is exceeded.
+   * @param options - Optional seed.
+   * @returns A new sketch holding every occurrence.
+   */
+  static from(keys: Iterable<BytesLike>, epsilon: number, delta: number, options?: CountMinOptions): CountMinSketch;
+  /**
+   * Restores a sketch from its {@link CountMinSketch.toBytes} serialization.
+   *
+   * Built from the geometry the frame stores, never from a sizing solve: the
+   * constructor takes `width` and `depth` directly, so there is nothing to
+   * re-derive and nothing to disagree about.
+   *
+   * @param bytes - The serialized sketch.
+   * @returns The reconstructed sketch.
+   */
+  static fromBytes(bytes: Uint8Array): CountMinSketch;
+  /**
+   * Constructs a sketch from low-level {@link CountMinParams}. Prefer
+   * {@link CountMinSketch.create} unless restoring a specific geometry.
+   */
+  constructor({ width, depth, seed }: CountMinParams);
+  /** Counters per row. */
+  get width(): number;
+  /** Number of rows, one probe each. */
+  get depth(): number;
+  /** Hash seed. */
+  get seed(): number;
+  /** Sum of every count recorded, the denominator of the error bound. */
+  get total(): number;
+  /**
+   * Error factor the geometry implements, `e / width`.
+   *
+   * Sizing rounds `width` up, so this is at or below the `epsilon` passed to
+   * {@link CountMinSketch.create}: the sketch reports what it delivers rather
+   * than what was asked for.
+   */
+  get epsilon(): number;
+  /**
+   * Probability the error bound is exceeded, `e ** -depth`. At or below the
+   * `delta` passed to {@link CountMinSketch.create}, for the same reason.
+   */
+  get delta(): number;
+  /**
+   * The additive error bound right now, `epsilon * total`. A count is at most
+   * this far above the truth, with probability `1 - delta`.
+   *
+   * It grows with what the sketch has recorded, so an estimate means less as
+   * the stream goes on, the way a filter's `rate()` rises as it fills.
+   *
+   * @returns The bound, `0` for an empty sketch.
+   */
+  error(): number;
+  /**
+   * Records `count` occurrences of a key.
+   *
+   * @param key - The key to record, as a string or bytes.
+   * @param count - How many occurrences to record; defaults to `1`.
+   */
+  add(key: BytesLike, count?: number): void;
+  /**
+   * Returns a new sketch counting everything both this one and `other` have
+   * recorded, as if one sketch had seen both streams.
+   *
+   * Both operands are left untouched.
+   *
+   * Unlike the filters, this is not idempotent: `a.union(a)` doubles every
+   * count, because counts add where bits only ever turn on.
+   *
+   * @param other - A sketch built with an identical geometry and seed.
+   * @returns A new sketch holding both streams.
+   */
+  union(other: CountMinSketch): CountMinSketch;
+  /**
+   * Serializes the sketch to a portable little-endian byte layout.
+   *
+   * The total is not stored. Under plain increment every row sums to it, so
+   * the field would be redundant, and a reader deriving it instead gets an
+   * integrity check on the counters for free.
+   *
+   * @returns The serialized sketch, readable by {@link CountMinSketch.fromBytes}.
+   */
+  toBytes(): Uint8Array;
+  /**
+   * Tests structural equality: `true` when `other` serializes to identical
+   * bytes, meaning identical geometry, seed and counters.
+   *
+   * @param other - The sketch to compare against.
+   * @returns `true` if the two sketches are byte-for-byte identical.
+   */
+  equals(other: CountMinSketch): boolean;
+  /**
+   * Serializes the sketch to a JSON-friendly envelope wrapping the base64 of
+   * {@link CountMinSketch.toBytes}.
+   *
+   * @returns The envelope, readable by {@link CountMinSketch.fromJSON}.
+   */
+  toJSON(): FilterJSON;
+  /**
+   * Restores a sketch from its {@link CountMinSketch.toJSON} envelope.
+   *
+   * @param value - The JSON envelope.
+   * @returns The reconstructed sketch.
+   */
+  static fromJSON(value: unknown): CountMinSketch;
+  /**
+   * Estimates how many times a key was added. The estimate is never below the
+   * true count and is at most {@link CountMinSketch.error} above it.
+   *
+   * @param key - The key to estimate.
+   * @returns The estimated count, `0` for a key the sketch has not seen.
+   */
+  count(key: BytesLike): number;
+}
+//#endregion
+//#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

@@ -0,0 +1,191 @@
+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 { 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;
+const PARAMS_FIELDS_END = 12;
+const counterBytes = (counters) => new Uint8Array(counters.buffer, counters.byteOffset, counters.byteLength);
+function rowSum(counters, width, depth) {
+	let expected = 0;
+	for (let r = 0; r < depth; r++) {
+		let sum = 0;
+		const from = r * width;
+		for (let c = from; c < from + width; c++) sum += counters[c] ?? 0;
+		if (sum > Number.MAX_SAFE_INTEGER) throw new SerializationError(`countmin: row ${String(r)} sums to ${String(sum)}, past the safe integer range`);
+		if (r === 0) expected = sum;
+		else if (sum !== expected) throw new SerializationError(`countmin: row ${String(r)} sums to ${String(sum)}, but row 0 sums to ${String(expected)}`);
+	}
+	return expected;
+}
+var CountMinParamMismatchError = class extends Error {
+	name = "CountMinParamMismatchError";
+};
+var CountMinOverflowError = class extends RangeError {
+	name = "CountMinOverflowError";
+};
+var CountMinSketch = class CountMinSketch {
+	#counters;
+	#width;
+	#depth;
+	#seed;
+	#words = new Uint32Array(2);
+	#positions;
+	#total = 0;
+	static create(epsilon, delta, options = {}) {
+		return new CountMinSketch({
+			...options,
+			...countMinSizing(epsilon, delta)
+		});
+	}
+	static from(keys, epsilon, delta, options = {}) {
+		const sketch = CountMinSketch.create(epsilon, delta, options);
+		for (const key of keys) sketch.add(key);
+		return sketch;
+	}
+	static fromBytes(bytes) {
+		const { type, flags, body } = readHeader(bytes);
+		if (type !== TYPE) throw new SerializationError(`expected DSTL type ${String(TYPE)}, got ${String(type)}`);
+		if ((flags & 15) !== 0) throw new UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
+		assertMinBodyLength(body.length, PARAMS_SIZE, "countmin");
+		assertParamsPadding(body, PARAMS_FIELDS_END, PARAMS_SIZE, "countmin");
+		const view = new DataView(body.buffer, body.byteOffset, body.byteLength);
+		const width = view.getUint32(0, true);
+		const depth = view.getUint32(4, true);
+		const seed = view.getUint32(8, true);
+		assertBodyLength(body.length, PARAMS_SIZE + 4 * width * depth, "countmin");
+		let sketch;
+		try {
+			sketch = new CountMinSketch({
+				width,
+				depth,
+				seed
+			});
+		} catch (err) {
+			if (err instanceof ParamError) throw new SerializationError(`countmin: ${err.message}`);
+			throw err;
+		}
+		const counters = sketch.#counters;
+		for (let i = 0; i < counters.length; i++) counters[i] = view.getUint32(PARAMS_SIZE + 4 * i, true);
+		sketch.#total = rowSum(counters, width, depth);
+		return sketch;
+	}
+	constructor({ width, depth, seed = 0 }) {
+		assertPositiveInt(width, "width");
+		assertUint32(width, "width");
+		assertPositiveInt(depth, "depth");
+		assertUint32(depth, "depth");
+		assertUint32(seed, "seed");
+		if (width * depth > 4294967295) throw new ParamError(`width ${String(width)} by depth ${String(depth)} needs ${String(width * depth)} counters, above the maximum ${String(4294967295)}`);
+		this.#counters = new Uint32Array(width * depth);
+		this.#positions = new Uint32Array(depth);
+		this.#width = width;
+		this.#depth = depth;
+		this.#seed = seed;
+	}
+	get width() {
+		return this.#width;
+	}
+	get depth() {
+		return this.#depth;
+	}
+	get seed() {
+		return this.#seed;
+	}
+	get total() {
+		return this.#total;
+	}
+	get epsilon() {
+		return Math.E / this.#width;
+	}
+	get delta() {
+		return Math.exp(-this.#depth);
+	}
+	error() {
+		return this.epsilon * this.#total;
+	}
+	#positionAt(row) {
+		return row * this.#width + probeAt(this.#words[0] ?? 0, this.#words[1] ?? 0, row, this.#width);
+	}
+	add(key, count = 1) {
+		assertPositiveInt(count, "count");
+		if (this.#total + count > Number.MAX_SAFE_INTEGER) throw new CountMinOverflowError(`adding ${String(count)} would carry the total past ${String(Number.MAX_SAFE_INTEGER)}`);
+		hash32x2Into(key, this.#seed, this.#words);
+		const headroom = 4294967295 - count;
+		for (let r = 0; r < this.#depth; r++) {
+			const at = this.#positionAt(r);
+			if ((this.#counters[at] ?? 0) > headroom) throw new CountMinOverflowError(`adding ${String(count)} would carry a counter past ${String(4294967295)}`);
+			this.#positions[r] = at;
+		}
+		for (let r = 0; r < this.#depth; r++) {
+			const at = this.#positions[r] ?? 0;
+			this.#counters[at] = (this.#counters[at] ?? 0) + count;
+		}
+		this.#total += count;
+	}
+	union(other) {
+		if (this.#width !== other.#width || this.#depth !== other.#depth || this.#seed !== other.#seed) throw new CountMinParamMismatchError("cannot union Count-Min sketches whose parameters do not match");
+		if (this.#total + other.#total > Number.MAX_SAFE_INTEGER) throw new CountMinOverflowError(`union would carry the total past ${String(Number.MAX_SAFE_INTEGER)}`);
+		const mine = this.#counters;
+		const theirs = other.#counters;
+		const merged = new CountMinSketch({
+			width: this.#width,
+			depth: this.#depth,
+			seed: this.#seed
+		});
+		const into = merged.#counters;
+		for (let i = 0; i < into.length; i++) {
+			const sum = (mine[i] ?? 0) + (theirs[i] ?? 0);
+			if (sum > 4294967295) throw new CountMinOverflowError(`union would carry a counter to ${String(sum)}, past ${String(4294967295)}`);
+			into[i] = sum;
+		}
+		merged.#total = this.#total + other.#total;
+		return merged;
+	}
+	toBytes() {
+		const counters = this.#counters;
+		return writeFrame({
+			version: 5,
+			type: TYPE,
+			flags: 0
+		}, PARAMS_SIZE, 4 * counters.length, (_, view) => {
+			view.setUint32(0, this.#width, true);
+			view.setUint32(4, this.#depth, true);
+			view.setUint32(8, this.#seed, true);
+			counters.forEach((c, i) => {
+				view.setUint32(PARAMS_SIZE + 4 * i, c, true);
+			});
+		});
+	}
+	equals(other) {
+		if (this.#width !== other.#width || this.#depth !== other.#depth || this.#seed !== other.#seed) return false;
+		return bytesEqual(counterBytes(this.#counters), counterBytes(other.#counters));
+	}
+	toJSON() {
+		return toJSONEnvelope(this.toBytes());
+	}
+	static fromJSON(value) {
+		return CountMinSketch.fromBytes(fromJSONEnvelope(value));
+	}
+	count(key) {
+		hash32x2Into(key, this.#seed, this.#words);
+		let min = Infinity;
+		for (let r = 0; r < this.#depth; r++) {
+			const at = this.#counters[this.#positionAt(r)] ?? 0;
+			if (at < min) min = at;
+		}
+		return min;
+	}
+};
+//#endregion
+export { BadMagicError, ChecksumError, CountMinOverflowError, CountMinParamMismatchError, CountMinSketch, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, countMinSizing };

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) {
@@ -195,7 +195,7 @@ var CuckooFilter = class CuckooFilter {
 		});
 	}
 	equals(other) {
-		return this.#n === other.#n && this.#epsilon === other.#epsilon && this.#seed === other.#seed && this.#count === other.#count && require_serialize.bytesEqual(wordBytes(this.#words), wordBytes(other.#words));
+		return this.#n === other.#n && this.#epsilon === other.#epsilon && this.#seed === other.#seed && this.#count === other.#count && this.#f === other.#f && this.#buckets === other.#buckets && require_serialize.bytesEqual(wordBytes(this.#words), wordBytes(other.#words));
 	}
 	toJSON() {
 		return require_serialize.toJSONEnvelope(this.toBytes());

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) {
@@ -194,7 +194,7 @@ var CuckooFilter = class CuckooFilter {
 		});
 	}
 	equals(other) {
-		return this.#n === other.#n && this.#epsilon === other.#epsilon && this.#seed === other.#seed && this.#count === other.#count && bytesEqual(wordBytes(this.#words), wordBytes(other.#words));
+		return this.#n === other.#n && this.#epsilon === other.#epsilon && this.#seed === other.#seed && this.#count === other.#count && this.#f === other.#f && this.#buckets === other.#buckets && bytesEqual(wordBytes(this.#words), wordBytes(other.#words));
 	}
 	toJSON() {
 		return toJSONEnvelope(this.toBytes());

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-BLzZk2zr.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 { i as hllSizing, n as HllSizing } from "../sizing-wYOW27eY.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 { i as hllSizing, n as HllSizing } from "../sizing-wYOW27eY.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 { n as hllSizing } from "../sizing-BtUrtvF_.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.12.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.12.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-BLzZk2zr.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-BtUrtvF_.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;
+	}
+});