distillate 0.12.0 → 0.14.0

package/README.md

@@ -42,18 +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     |
+| 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 is not a filter: it counts distinct keys and cannot report
-whether it saw any particular one.
+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`)
 
@@ -163,6 +167,54 @@ Below a few thousand distinct keys the sketch counts rather than estimates, so s
 
 Also: `equals`, `toBytes` / `fromBytes`, `toJSON` / `fromJSON`, `standardError`, `hllSizing(relativeError)`, and a low-level `new HyperLogLog({ p, seed })`.
 
+### Count-Min (`distillate/countmin`)
+
+A **sketch**, not a filter: it estimates how many times each key appeared, in space fixed by the error you ask for rather than by how many keys arrive. The estimate is never below the truth, and at most `epsilon` of the total above it. Full API and sizing: [Count-Min guide](https://distillate.akxp.net/guides/countmin/).
+
+```ts
+import { CountMinSketch } from "distillate/countmin";
+
+const hits = CountMinSketch.create(0.001, 0.001); // error factor, failure probability
+hits.add("/login");
+hits.add("/login", 4);
+hits.add("/signup");
+
+hits.count("/login"); // 5
+hits.total; // 6
+
+// Combine per-shard sketches: counts add, exactly as if one sketch saw both streams.
+const other = CountMinSketch.from(["/login", "/login"], 0.001, 0.001);
+hits.union(other).count("/login"); // 7
+```
+
+`from` counts repeats, unlike `CuckooFilter.from` which ignores them: for a frequency sketch the repeats are the measurement. A counter that would pass `2^32 - 1` throws `CountMinOverflowError` rather than wrapping, since a wrapped counter would read as an underestimate.
+
+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-BLzZk2zr.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 { r as bloomSizing, t as BloomSizing } from "../sizing-wYOW27eY.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 { r as bloomSizing, t as BloomSizing } from "../sizing-wYOW27eY.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-BtUrtvF_.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

@@ -0,0 +1,203 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_hasher = require("../hasher-DPXmP7SH.cjs");
+const require_serialize = require("../serialize-CHikZ4GH.cjs");
+const require_params = require("../params-UTZbJ22c.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;
+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 require_serialize.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 require_serialize.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 } = require_serialize.readHeader(bytes);
+		if (type !== TYPE) throw new require_serialize.SerializationError(`expected DSTL type ${String(TYPE)}, got ${String(type)}`);
+		if ((flags & 15) !== 0) throw new require_serialize.UnknownHashVariantError(`unsupported hash variant ${String(flags & 15)}`);
+		require_serialize.assertMinBodyLength(body.length, PARAMS_SIZE, "countmin");
+		require_serialize.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);
+		require_serialize.assertBodyLength(body.length, PARAMS_SIZE + 4 * width * depth, "countmin");
+		let sketch;
+		try {
+			sketch = new CountMinSketch({
+				width,
+				depth,
+				seed
+			});
+		} catch (err) {
+			if (err instanceof require_params.ParamError) throw new require_serialize.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 }) {
+		require_params.assertPositiveInt(width, "width");
+		require_params.assertUint32(width, "width");
+		require_params.assertPositiveInt(depth, "depth");
+		require_params.assertUint32(depth, "depth");
+		require_params.assertUint32(seed, "seed");
+		if (width * depth > 4294967295) throw new require_params.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 + require_hasher.probeAt(this.#words[0] ?? 0, this.#words[1] ?? 0, row, this.#width);
+	}
+	add(key, count = 1) {
+		require_params.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)}`);
+		require_hasher.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 require_serialize.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 require_serialize.bytesEqual(counterBytes(this.#counters), counterBytes(other.#counters));
+	}
+	toJSON() {
+		return require_serialize.toJSONEnvelope(this.toBytes());
+	}
+	static fromJSON(value) {
+		return CountMinSketch.fromBytes(require_serialize.fromJSONEnvelope(value));
+	}
+	count(key) {
+		require_hasher.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
+exports.BadMagicError = require_serialize.BadMagicError;
+exports.ChecksumError = require_serialize.ChecksumError;
+exports.CountMinOverflowError = CountMinOverflowError;
+exports.CountMinParamMismatchError = CountMinParamMismatchError;
+exports.CountMinSketch = CountMinSketch;
+exports.ParamError = require_params.ParamError;
+exports.ReservedBitsError = require_serialize.ReservedBitsError;
+exports.SerializationError = require_serialize.SerializationError;
+exports.TruncatedError = require_serialize.TruncatedError;
+exports.UnknownHashVariantError = require_serialize.UnknownHashVariantError;
+exports.UnknownVersionError = require_serialize.UnknownVersionError;
+exports.countMinSizing = countMinSizing;

package/dist/countmin/index.d.cts

@@ -0,0 +1,191 @@
+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";
+//#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 };