distillate 0.13.0 → 0.14.0

package/dist/topk/index.d.ts

@@ -0,0 +1,207 @@
+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/topk/topk.d.ts
+/**
+ * Thrown when an `add` or `union` would carry a stored count past
+ * `2^32 - 1`, or the total past `Number.MAX_SAFE_INTEGER`. Counts are `u32`,
+ * so a wrapped one would read back below the truth, the one outcome this
+ * structure rules out; a total past the safe range is one `fromBytes`
+ * refuses. Every sketch involved is left exactly as it was.
+ */
+export declare class TopKOverflowError extends RangeError {
+  /** Discriminates this error from other `Error`s. */
+  override readonly name = "TopKOverflowError";
+}
+/** Thrown when an operation requires two sketches built with identical parameters. */
+export declare class TopKParamMismatchError extends Error {
+  /** Discriminates this error from other `Error`s. */
+  override readonly name = "TopKParamMismatchError";
+}
+/** One of the heaviest keys, with the bracket its stored count implies. */
+interface TopKEntry {
+  /** The key exactly as it was recorded. A copy, safe to keep or mutate. */
+  key: Uint8Array;
+  /** Upper bound, `stored + error()`. Never below the true count. */
+  count: number;
+  /** Lower bound, the stored count alone. Never above the true count. */
+  lowerBound: number;
+}
+/** Low-level Top-K sketch parameters. */
+interface TopKParams {
+  /** Slots in the counter map; must be a power of two. */
+  capacity: number;
+}
+/**
+ * A Top-K sketch: Misra-Gries with reverse purge, answering which keys are
+ * heaviest in space fixed by the error you ask for.
+ *
+ * @example
+ * ```ts
+ * const sketch = TopK.create(0.001);
+ * sketch.add("alice");
+ * ```
+ */
+export declare class TopK {
+  #private;
+  /**
+   * Creates a sketch whose estimate is at most `epsilon` of the total recorded
+   * above the true count.
+   *
+   * Sized by the error it targets rather than by how many keys it will see, or
+   * by the k you will ask for: `top(k)` takes k per call.
+   *
+   * @param epsilon - Error factor relative to the total recorded, e.g. `0.001`.
+   * @returns A new, empty sketch.
+   */
+  static create(epsilon: number): TopK;
+  /**
+   * 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.
+   * @returns A new sketch holding every occurrence.
+   */
+  static from(keys: Iterable<BytesLike>, epsilon: number): TopK;
+  /**
+   * Restores a sketch from its {@link TopK.toBytes} serialization.
+   *
+   * @param bytes - The serialized sketch.
+   * @returns The reconstructed sketch.
+   */
+  static fromBytes(bytes: Uint8Array): TopK;
+  /**
+   * Constructs a sketch from low-level {@link TopKParams}. Prefer
+   * {@link TopK.create} unless restoring a specific geometry.
+   */
+  constructor({ capacity }: TopKParams);
+  /** Slots in the counter map. */
+  get capacity(): number;
+  /**
+   * Error factor the geometry implements, `1 / topKPurgeWidth(capacity)`.
+   *
+   * Sizing rounds the capacity up to a power of two, so this is at or below the
+   * `epsilon` passed to {@link TopK.create}: the sketch reports what it
+   * delivers rather than what was asked for.
+   */
+  get epsilon(): number;
+  /** Sum of every count recorded, whatever the map has since purged. */
+  get total(): number;
+  /**
+   * The most any estimate can exceed the truth by: everything the purges have
+   * subtracted so far.
+   *
+   * It is also the threshold of the one-sided guarantee. Every key whose true
+   * count exceeds this is still held, so nothing heavier than the error can
+   * have been silently dropped.
+   *
+   * @returns The accumulated purge offset, `0` before the first purge.
+   */
+  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;
+  /**
+   * Estimates how many times a key was added.
+   *
+   * For a key the map holds this is `stored + error()`, never below the true
+   * count. A key the map does not hold returns `0` rather than the offset,
+   * since its true count may genuinely be zero.
+   *
+   * @param key - The key to estimate.
+   * @returns The estimated count, `0` for a key the map does not hold.
+   */
+  count(key: BytesLike): number;
+  /**
+   * The `k` heaviest keys the map holds, heaviest first.
+   *
+   * `k` is taken per call rather than fixed when the sketch was built, so one
+   * sketch answers top-10 and top-100 without a rebuild.
+   *
+   * Fewer than `k` entries come back when the map holds fewer, and a key
+   * purged away is not among them: what is guaranteed present is every key
+   * whose true count exceeds {@link TopK.error}.
+   *
+   * @param k - How many entries to return at most.
+   * @returns The heaviest entries, each with its upper and lower bound.
+   */
+  top(k: number): TopKEntry[];
+  /**
+   * Combines this sketch with another built with the same parameters.
+   *
+   * Each key's stored counts are summed, as are the offsets and totals, and
+   * the merged entries are purged until they fit the load limit. The result
+   * holds the same guarantee as its inputs, with an error of at least the sum
+   * of theirs.
+   *
+   * Unlike Count-Min's union, this is not the sketch one stream fed both
+   * inputs would have produced. Misra-Gries depends on arrival order: a
+   * single sketch purges as it goes, while a union purges only what the two
+   * inputs kept. Both are correct, and their bytes can differ.
+   *
+   * @param other - The sketch to combine with.
+   * @returns A new sketch; neither input changes.
+   */
+  union(other: TopK): TopK;
+  /**
+   * Serializes the sketch to a portable little-endian byte layout.
+   *
+   * Entries are written in the order `top` returns them, so the bytes depend
+   * only on what the map holds and never on the order it was filled in.
+   *
+   * @returns The serialized sketch, readable by {@link TopK.fromBytes}.
+   */
+  toBytes(): Uint8Array;
+  /**
+   * Tests structural equality: `true` when `other` serializes to identical
+   * bytes, meaning identical geometry, offset, total and entries.
+   *
+   * Entries are written in canonical order, so equal bytes mean the same
+   * entries are held, whatever order they arrived in.
+   *
+   * @param other - The sketch to compare against.
+   * @returns `true` if the two sketches are byte-for-byte identical.
+   */
+  equals(other: TopK): boolean;
+  /**
+   * Serializes the sketch to a JSON-friendly envelope wrapping the base64 of
+   * {@link TopK.toBytes}.
+   *
+   * @returns The envelope, readable by {@link TopK.fromJSON}.
+   */
+  toJSON(): FilterJSON;
+  /**
+   * Restores a sketch from its {@link TopK.toJSON} envelope.
+   *
+   * @param value - The JSON envelope.
+   * @returns The reconstructed sketch.
+   */
+  static fromJSON(value: unknown): TopK;
+}
+//#endregion
+//#region src/topk/sizing.d.ts
+/** Top-K geometry: the `TopKParams` fields a sizing solve determines. */
+interface TopKSizing {
+  /** Slots in the counter map, a power of two. */
+  capacity: number;
+}
+/**
+ * Smallest power-of-two capacity whose purge width keeps the offset within
+ * `epsilon` of the total recorded. Throws {@link ParamError} when even
+ * `TOPK_MAX_CAPACITY` cannot.
+ *
+ * The bound is a function of capacity, not of k, which is why `top(k)` takes k
+ * per call instead of the sketch being built for one.
+ */
+export declare function topKSizing(epsilon: number): TopKSizing;
+//#endregion
+export { BadMagicError, ChecksumError, type FilterJSON, ParamError, ReservedBitsError, SerializationError, type TopKEntry, type TopKParams, type TopKSizing, TruncatedError, UnknownHashVariantError, UnknownVersionError };

package/dist/topk/index.js

@@ -0,0 +1,411 @@
+import { t as normalize } from "../bytes-Be7tq1F7.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 { i as assertProbability, o as assertUint32, r as assertPositiveInt, t as ParamError } from "../params-CeajSrwv.js";
+//#region src/topk/halfsip.ts
+function halfSipHash13(bytes, k0, k1) {
+	let v0 = k0 | 0;
+	let v1 = k1 | 0;
+	let v2 = 1819895653 ^ k0 | 0;
+	let v3 = 1952801890 ^ k1 | 0;
+	const len = bytes.length;
+	const end = len & -4;
+	for (let i = 0; i < end; i += 4) {
+		const m = (bytes[i] ?? 0) | (bytes[i + 1] ?? 0) << 8 | (bytes[i + 2] ?? 0) << 16 | (bytes[i + 3] ?? 0) << 24;
+		v3 ^= m;
+		v0 = v0 + v1 | 0;
+		v1 = v1 << 5 | v1 >>> 27;
+		v1 ^= v0;
+		v0 = v0 << 16 | v0 >>> 16;
+		v2 = v2 + v3 | 0;
+		v3 = v3 << 8 | v3 >>> 24;
+		v3 ^= v2;
+		v0 = v0 + v3 | 0;
+		v3 = v3 << 7 | v3 >>> 25;
+		v3 ^= v0;
+		v2 = v2 + v1 | 0;
+		v1 = v1 << 13 | v1 >>> 19;
+		v1 ^= v2;
+		v2 = v2 << 16 | v2 >>> 16;
+		v0 ^= m;
+	}
+	let b = len << 24;
+	for (let i = len - 1; i >= end; i--) b |= (bytes[i] ?? 0) << 8 * (i - end);
+	v3 ^= b;
+	for (let r = 0; r < 4; r++) {
+		if (r === 1) {
+			v0 ^= b;
+			v2 ^= 255;
+		}
+		v0 = v0 + v1 | 0;
+		v1 = v1 << 5 | v1 >>> 27;
+		v1 ^= v0;
+		v0 = v0 << 16 | v0 >>> 16;
+		v2 = v2 + v3 | 0;
+		v3 = v3 << 8 | v3 >>> 24;
+		v3 ^= v2;
+		v0 = v0 + v3 | 0;
+		v3 = v3 << 7 | v3 >>> 25;
+		v3 ^= v0;
+		v2 = v2 + v1 | 0;
+		v1 = v1 << 13 | v1 >>> 19;
+		v1 ^= v2;
+		v2 = v2 << 16 | v2 >>> 16;
+	}
+	return (v1 ^ v3) >>> 0;
+}
+const TOPK_MAX_CAPACITY = 2 ** 24;
+function topKLoadLimit(capacity) {
+	return Math.floor(.75 * capacity);
+}
+function topKPurgeWidth(capacity) {
+	return topKLoadLimit(capacity) + 2 >> 1;
+}
+function topKSizing(epsilon) {
+	assertProbability(epsilon, "epsilon");
+	for (let capacity = 4; capacity <= TOPK_MAX_CAPACITY; capacity *= 2) if (1 / topKPurgeWidth(capacity) <= epsilon) return { capacity };
+	throw new ParamError(`epsilon ${String(epsilon)} needs more than the maximum capacity ${String(TOPK_MAX_CAPACITY)}`);
+}
+//#endregion
+//#region src/topk/topk.ts
+const TYPE = 9;
+const TABLE_START = 8;
+const PARAMS_SIZE = 32;
+const PARAMS_FIELDS_END = 24;
+function assertCount(value, label) {
+	if (!Number.isSafeInteger(value) || value < 0) throw new SerializationError(`topk: ${label} ${String(value)} is not an integer in [0, ${String(Number.MAX_SAFE_INTEGER)}]`);
+}
+function compareBytes(a, b) {
+	for (let i = 0; i < Math.min(a.length, b.length); i++) {
+		const diff = (a[i] ?? 0) - (b[i] ?? 0);
+		if (diff !== 0) return diff;
+	}
+	return a.length - b.length;
+}
+var TopKOverflowError = class extends RangeError {
+	name = "TopKOverflowError";
+};
+var TopKParamMismatchError = class extends Error {
+	name = "TopKParamMismatchError";
+};
+var TopK = class TopK {
+	#capacity;
+	#loadLimit;
+	#k0 = 0;
+	#k1 = 0;
+	#keyed = false;
+	#size = 0;
+	#counts = new Uint32Array(0);
+	#keyOffsets = new Uint32Array(0);
+	#keyLengths = new Uint32Array(0);
+	#arena;
+	#arenaLen = 0;
+	#entries = 0;
+	#offset = 0;
+	#total = 0;
+	static create(epsilon) {
+		return new TopK(topKSizing(epsilon));
+	}
+	static from(keys, epsilon) {
+		const sketch = TopK.create(epsilon);
+		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, "topk");
+		assertParamsPadding(body, PARAMS_FIELDS_END, PARAMS_SIZE, "topk");
+		const view = new DataView(body.buffer, body.byteOffset, body.byteLength);
+		const capacity = view.getUint32(0, true);
+		const entries = view.getUint32(4, true);
+		if (entries > topKLoadLimit(capacity)) throw new SerializationError(`topk: frame holds ${String(entries)} entries, above the load limit ${String(topKLoadLimit(capacity))} for capacity ${String(capacity)}`);
+		const tableEnd = PARAMS_SIZE + 8 * entries;
+		assertMinBodyLength(body.length, tableEnd, "topk");
+		let keyBytes = 0;
+		for (let i = 0; i < entries; i++) keyBytes += view.getUint32(PARAMS_SIZE + 4 * (entries + i), true);
+		assertBodyLength(body.length, tableEnd + keyBytes, "topk");
+		const offset = view.getFloat64(8, true);
+		const total = view.getFloat64(16, true);
+		assertCount(offset, "offset");
+		assertCount(total, "total");
+		let sketch;
+		try {
+			sketch = new TopK({ capacity });
+			sketch.#allocate(sketch.#fit(entries));
+		} catch (err) {
+			if (err instanceof ParamError) throw new SerializationError(`topk: ${err.message}`);
+			throw err;
+		}
+		let keyAt = tableEnd;
+		let stored = 0;
+		let prevCount = Infinity;
+		let prevKey = new Uint8Array(0);
+		for (let i = 0; i < entries; i++) {
+			const count = view.getUint32(PARAMS_SIZE + 4 * i, true);
+			const len = view.getUint32(PARAMS_SIZE + 4 * (entries + i), true);
+			const key = body.subarray(keyAt, keyAt + len);
+			keyAt += len;
+			if (count === 0) throw new SerializationError(`topk: entry ${String(i)} has count 0`);
+			if (count > prevCount || count === prevCount && compareBytes(prevKey, key) >= 0) throw new SerializationError(`topk: entry ${String(i)} is out of canonical order`);
+			prevCount = count;
+			prevKey = key;
+			const slot = sketch.#slotFor(key);
+			if ((sketch.#counts[slot] ?? 0) !== 0) throw new SerializationError(`topk: entry ${String(i)} repeats a key already held`);
+			sketch.#storeKey(slot, key);
+			sketch.#counts[slot] = count;
+			stored += count;
+		}
+		const width = topKPurgeWidth(capacity);
+		if (stored + width * offset > total) throw new SerializationError(`topk: stored counts ${String(stored)} plus ${String(width)} x offset ${String(offset)} exceed total ${String(total)}`);
+		sketch.#entries = entries;
+		sketch.#offset = offset;
+		sketch.#total = total;
+		return sketch;
+	}
+	constructor({ capacity }) {
+		assertUint32(capacity, "capacity");
+		if (!Number.isInteger(Math.log2(capacity))) throw new ParamError(`capacity must be a power of two, got ${String(capacity)}`);
+		if (capacity < 4 || capacity > TOPK_MAX_CAPACITY) throw new ParamError(`capacity must be in [${String(4)}, ${String(TOPK_MAX_CAPACITY)}], got ${String(capacity)}`);
+		this.#capacity = capacity;
+		this.#loadLimit = topKLoadLimit(capacity);
+		this.#allocate(Math.min(TABLE_START, capacity));
+		this.#arena = new Uint8Array(256);
+	}
+	get capacity() {
+		return this.#capacity;
+	}
+	get epsilon() {
+		return 1 / topKPurgeWidth(this.#capacity);
+	}
+	get total() {
+		return this.#total;
+	}
+	error() {
+		return this.#offset;
+	}
+	#purge() {
+		const keys = [];
+		const counts = [];
+		for (let slot = 0; slot < this.#size; slot++) {
+			const stored = this.#counts[slot] ?? 0;
+			if (stored === 0) continue;
+			keys.push(this.#keyAt(slot).slice());
+			counts.push(stored);
+		}
+		this.#reduceTo(keys, counts);
+	}
+	#reduceTo(keys, counts) {
+		while (keys.length > this.#loadLimit) {
+			const median = [...counts].sort((a, b) => a - b)[counts.length >> 1] ?? 0;
+			let kept = 0;
+			for (let i = 0; i < keys.length; i++) {
+				const survived = (counts[i] ?? 0) - median;
+				if (survived <= 0) continue;
+				keys[kept] = keys[i] ?? new Uint8Array(0);
+				counts[kept] = survived;
+				kept++;
+			}
+			keys.length = kept;
+			counts.length = kept;
+			this.#offset += median;
+		}
+		const size = this.#fit(keys.length);
+		if (size > this.#size) this.#allocate(size);
+		else this.#counts.fill(0);
+		this.#arenaLen = 0;
+		this.#entries = keys.length;
+		for (let i = 0; i < keys.length; i++) {
+			const bytes = keys[i] ?? new Uint8Array(0);
+			const slot = this.#slotFor(bytes);
+			this.#storeKey(slot, bytes);
+			this.#counts[slot] = counts[i] ?? 0;
+		}
+	}
+	#allocate(size) {
+		this.#size = size;
+		this.#counts = new Uint32Array(size);
+		this.#keyOffsets = new Uint32Array(size);
+		this.#keyLengths = new Uint32Array(size);
+	}
+	#resize(size) {
+		const counts = this.#counts;
+		const offsets = this.#keyOffsets;
+		const lengths = this.#keyLengths;
+		this.#allocate(size);
+		for (let old = 0; old < counts.length; old++) {
+			const stored = counts[old] ?? 0;
+			if (stored === 0) continue;
+			const at = offsets[old] ?? 0;
+			const len = lengths[old] ?? 0;
+			const slot = this.#slotFor(this.#arena.subarray(at, at + len));
+			this.#counts[slot] = stored;
+			this.#keyOffsets[slot] = at;
+			this.#keyLengths[slot] = len;
+		}
+	}
+	#fit(entries) {
+		let size = Math.min(TABLE_START, this.#capacity);
+		while (size < this.#capacity && topKLoadLimit(size) < entries) size *= 2;
+		return size;
+	}
+	#slotHolds(slot, bytes) {
+		const len = this.#keyLengths[slot] ?? 0;
+		if (len !== bytes.length) return false;
+		const at = this.#keyOffsets[slot] ?? 0;
+		for (let i = 0; i < len; i++) if (this.#arena[at + i] !== bytes[i]) return false;
+		return true;
+	}
+	#storeKey(slot, bytes) {
+		let arena = this.#arena;
+		if (this.#arenaLen + bytes.length > arena.length) {
+			let size = arena.length;
+			while (size < this.#arenaLen + bytes.length) size *= 2;
+			const grown = new Uint8Array(size);
+			grown.set(arena.subarray(0, this.#arenaLen));
+			arena = grown;
+			this.#arena = grown;
+		}
+		arena.set(bytes, this.#arenaLen);
+		this.#keyOffsets[slot] = this.#arenaLen;
+		this.#keyLengths[slot] = bytes.length;
+		this.#arenaLen += bytes.length;
+	}
+	#slotFor(bytes) {
+		if (!this.#keyed) {
+			const key = crypto.getRandomValues(new Uint32Array(2));
+			this.#k0 = key[0] ?? 0;
+			this.#k1 = key[1] ?? 0;
+			this.#keyed = true;
+		}
+		const mask = this.#size - 1;
+		let slot = halfSipHash13(bytes, this.#k0, this.#k1) & mask;
+		for (;;) {
+			if ((this.#counts[slot] ?? 0) === 0) return slot;
+			if (this.#slotHolds(slot, bytes)) return slot;
+			slot = slot + 1 & mask;
+		}
+	}
+	add(key, count = 1) {
+		assertPositiveInt(count, "count");
+		if (this.#total + count > Number.MAX_SAFE_INTEGER) throw new TopKOverflowError(`adding ${String(count)} would carry the total past ${String(Number.MAX_SAFE_INTEGER)}`);
+		const bytes = normalize(key);
+		const slot = this.#slotFor(bytes);
+		const stored = this.#counts[slot] ?? 0;
+		if (stored + count > 4294967295) throw new TopKOverflowError(`adding ${String(count)} would carry a stored count past ${String(4294967295)}`);
+		if (stored === 0) {
+			this.#storeKey(slot, bytes);
+			this.#entries++;
+		}
+		this.#counts[slot] = stored + count;
+		this.#total += count;
+		if (this.#entries > topKLoadLimit(this.#size)) {
+			if (this.#size < this.#capacity) this.#resize(this.#size * 2);
+			else this.#purge();
+		}
+	}
+	count(key) {
+		const bytes = normalize(key);
+		const stored = this.#counts[this.#slotFor(bytes)] ?? 0;
+		return stored === 0 ? 0 : stored + this.#offset;
+	}
+	top(k) {
+		assertPositiveInt(k, "k");
+		return this.#canonicalSlots().slice(0, k).map((slot) => {
+			const at = this.#keyOffsets[slot] ?? 0;
+			return {
+				key: this.#arena.slice(at, at + (this.#keyLengths[slot] ?? 0)),
+				count: (this.#counts[slot] ?? 0) + this.#offset,
+				lowerBound: this.#counts[slot] ?? 0
+			};
+		});
+	}
+	union(other) {
+		if (this.#capacity !== other.#capacity) throw new TopKParamMismatchError(`cannot union Top-K sketches with capacity ${String(this.#capacity)} and ${String(other.#capacity)}`);
+		if (this.#total + other.#total > Number.MAX_SAFE_INTEGER) throw new TopKOverflowError(`union would carry the total past ${String(Number.MAX_SAFE_INTEGER)}`);
+		const keys = [];
+		const counts = [];
+		const indexOf = new Int32Array(this.#size).fill(-1);
+		for (let slot = 0; slot < this.#size; slot++) {
+			const stored = this.#counts[slot] ?? 0;
+			if (stored === 0) continue;
+			indexOf[slot] = keys.length;
+			keys.push(this.#keyAt(slot).slice());
+			counts.push(stored);
+		}
+		for (let slot = 0; slot < other.#size; slot++) {
+			const stored = other.#counts[slot] ?? 0;
+			if (stored === 0) continue;
+			const key = other.#keyAt(slot);
+			const at = indexOf[this.#slotFor(key)] ?? -1;
+			if (at >= 0) {
+				const sum = (counts[at] ?? 0) + stored;
+				if (sum > 4294967295) throw new TopKOverflowError(`union would carry a stored count to ${String(sum)}, past ${String(4294967295)}`);
+				counts[at] = sum;
+			} else {
+				keys.push(key.slice());
+				counts.push(stored);
+			}
+		}
+		const merged = new TopK({ capacity: this.#capacity });
+		merged.#offset = this.#offset + other.#offset;
+		merged.#total = this.#total + other.#total;
+		merged.#reduceTo(keys, counts);
+		return merged;
+	}
+	toBytes() {
+		const slots = this.#canonicalSlots();
+		const tableEnd = PARAMS_SIZE + 8 * slots.length;
+		return writeFrame({
+			version: 5,
+			type: TYPE,
+			flags: 0
+		}, PARAMS_SIZE, 8 * slots.length + this.#arenaLen, (body, view) => {
+			view.setUint32(0, this.#capacity, true);
+			view.setUint32(4, slots.length, true);
+			view.setFloat64(8, this.#offset, true);
+			view.setFloat64(16, this.#total, true);
+			let keyAt = tableEnd;
+			slots.forEach((slot, i) => {
+				const at = this.#keyOffsets[slot] ?? 0;
+				const len = this.#keyLengths[slot] ?? 0;
+				view.setUint32(PARAMS_SIZE + 4 * i, this.#counts[slot] ?? 0, true);
+				view.setUint32(PARAMS_SIZE + 4 * (slots.length + i), len, true);
+				body.set(this.#arena.subarray(at, at + len), keyAt);
+				keyAt += len;
+			});
+		});
+	}
+	equals(other) {
+		if (this.#capacity !== other.#capacity || this.#offset !== other.#offset || this.#total !== other.#total || this.#entries !== other.#entries) return false;
+		for (let slot = 0; slot < this.#size; slot++) {
+			const stored = this.#counts[slot] ?? 0;
+			if (stored === 0) continue;
+			if (other.#counts[other.#slotFor(this.#keyAt(slot))] !== stored) return false;
+		}
+		return true;
+	}
+	toJSON() {
+		return toJSONEnvelope(this.toBytes());
+	}
+	static fromJSON(value) {
+		return TopK.fromBytes(fromJSONEnvelope(value));
+	}
+	#canonicalSlots() {
+		const slots = [];
+		for (let slot = 0; slot < this.#size; slot++) if ((this.#counts[slot] ?? 0) !== 0) slots.push(slot);
+		return slots.sort((a, b) => {
+			const byCount = (this.#counts[b] ?? 0) - (this.#counts[a] ?? 0);
+			return byCount !== 0 ? byCount : this.#compareKeys(a, b);
+		});
+	}
+	#compareKeys(a, b) {
+		return compareBytes(this.#keyAt(a), this.#keyAt(b));
+	}
+	#keyAt(slot) {
+		const at = this.#keyOffsets[slot] ?? 0;
+		return this.#arena.subarray(at, at + (this.#keyLengths[slot] ?? 0));
+	}
+};
+//#endregion
+export { BadMagicError, ChecksumError, ParamError, ReservedBitsError, SerializationError, TopK, TopKOverflowError, TopKParamMismatchError, TruncatedError, UnknownHashVariantError, UnknownVersionError, topKSizing };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "distillate",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Probabilistic data structures for JavaScript. Space-efficient, approximate-membership filters (Bloom, Blocked Bloom, Binary Fuse) with tunable error and a portable binary format; zero dependencies, universal.",
   "keywords": [
     "bloom-filter",
@@ -95,6 +95,14 @@
       "import": "./dist/countmin/index.js",
       "require": "./dist/countmin/index.cjs"
     },
+    "./topk": {
+      "types": {
+        "import": "./dist/topk/index.d.ts",
+        "require": "./dist/topk/index.d.cts"
+      },
+      "import": "./dist/topk/index.js",
+      "require": "./dist/topk/index.cjs"
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/index.cjs",

package/dist/sizing-BmKfHf_V.d.cts

@@ -1,34 +0,0 @@
-//#region src/core/sizing.d.ts
-/** Bloom filter geometry: the `BloomParams` fields a sizing solve determines. */
-interface BloomSizing {
-  /** Number of bits in the filter. */
-  m: number;
-  /** Number of hash probes per key. */
-  k: number;
-}
-/** Optimal Bloom-filter sizing: `m` bits and `k` hashes for `n` items at target FPR `epsilon`. */
-declare function bloomSizing(n: number, epsilon: number): BloomSizing;
-/** 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.
- */
-declare function hllSizing(relativeError: number): HllSizing;
-/** 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`.
- */
-declare function countMinSizing(epsilon: number, delta: number): CountMinSizing;
-//#endregion
-export { countMinSizing as a, bloomSizing as i, CountMinSizing as n, hllSizing as o, HllSizing as r, BloomSizing as t };