distillate 0.11.0 → 0.13.0

package/README.md

@@ -6,7 +6,7 @@
 
 Probabilistic data structures for JavaScript: space-efficient, approximate answers with tunable error and zero false negatives. TypeScript-first, zero dependencies, and the right structure per workload. It opens with a family of membership filters and is built to grow into other sketches.
 
-> **Pre-release (0.x).** The published structures are correct, tested, and benchmarked, but the public API may still change before `1.0`, and more structures (Cuckoo, Scalable Bloom) are on the way. Pin a version if you depend on it.
+> **Pre-release (0.x).** The published structures are correct, tested, and benchmarked, but the public API may still change before `1.0`. Pin a version if you depend on it.
 
 ## Why
 
@@ -48,11 +48,14 @@ Each structure ships as its own subpath, so you only bundle what you import.
 | `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                   |
 
 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 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.
 
 ### Classic Bloom (`distillate/bloom`)
 
@@ -120,6 +123,25 @@ const precise = BinaryFuse16.from(["alice", "bob", "carol"]);
 
 Also: `toBytes` / `fromBytes`. No `add` / `delete`; rebuild `from` the new set to change membership.
 
+### Cuckoo (`distillate/cuckoo`)
+
+For a set that shrinks as well as grows: the one filter here with `delete`. Full API and trade-offs: [Cuckoo guide](https://distillate.akxp.net/guides/cuckoo/).
+
+```ts
+import { CuckooFilter } from "distillate/cuckoo";
+
+const sessions = CuckooFilter.create(100_000, 0.01);
+sessions.add("alice");
+sessions.has("alice"); // true
+
+sessions.delete("alice"); // true
+sessions.has("alice"); // false
+```
+
+Only delete keys you added: a key never added can share a fingerprint with one that was, and deleting it removes that one instead. An add into a full filter throws `CuckooFullError` and leaves the filter unchanged. It is larger than a Classic Bloom at common targets and smaller only at about 0.2% and below, so pick it for delete, not for space.
+
+Also: `from(keys, epsilon)`, `equals`, `rate`, `count`, `toBytes` / `fromBytes`, `toJSON` / `fromJSON`, `cuckooSizing(n, epsilon)`, and a `seed` option.
+
 ### HyperLogLog (`distillate/hll`)
 
 A **sketch**, not a filter: it counts distinct keys in space fixed by precision rather than by the answer, and cannot report whether it saw any particular key. 12 KiB counts a thousand distinct keys or a billion, at about 0.8% relative error. Full API and sizing: [HyperLogLog guide](https://distillate.akxp.net/guides/hll/).
@@ -143,6 +165,30 @@ 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 })`.
+
 ## 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/bloom/index.cjs

@@ -3,7 +3,7 @@ const require_bitset = require("../bitset-QYGqxnEf.cjs");
 const require_hasher = require("../hasher-MhY7aQ8F.cjs");
 const require_serialize = require("../serialize-CHikZ4GH.cjs");
 const require_params = require("../params-UTZbJ22c.cjs");
-const require_sizing = require("../sizing-BLzZk2zr.cjs");
+const require_sizing = require("../sizing-R1pwbzjC.cjs");
 //#region src/bloom/bloom.ts
 const TYPE = 1;
 const PARAMS_SIZE = 16;

package/dist/bloom/index.d.cts

@@ -1,7 +1,7 @@
 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";
+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 {

package/dist/bloom/index.d.ts

@@ -1,7 +1,7 @@
 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";
+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 {

package/dist/bloom/index.js

@@ -2,7 +2,7 @@ import { t as BitSet } from "../bitset-Cf2jwRJX.js";
 import { c as probeInto } from "../hasher-3Cyn7Yg-.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";
+import { t as bloomSizing } from "../sizing-D3-_7pdP.js";
 //#region src/bloom/bloom.ts
 const TYPE = 1;
 const PARAMS_SIZE = 16;

package/dist/countmin/index.cjs

@@ -0,0 +1,194 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_hasher = require("../hasher-MhY7aQ8F.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/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,
+			...require_sizing.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 = require_sizing.countMinSizing;

package/dist/countmin/index.d.cts

@@ -0,0 +1,178 @@
+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 {
+  /** 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
+export { BadMagicError, ChecksumError, type CountMinOptions, type CountMinParams, type CountMinSizing, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, countMinSizing };

package/dist/countmin/index.d.ts

@@ -0,0 +1,178 @@
+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 {
+  /** 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
+export { BadMagicError, ChecksumError, type CountMinOptions, type CountMinParams, type CountMinSizing, type FilterJSON, ParamError, ReservedBitsError, SerializationError, TruncatedError, UnknownHashVariantError, UnknownVersionError, countMinSizing };