distillate 0.13.0 → 0.14.1

package/dist/topk/index.d.cts

@@ -0,0 +1,207 @@
+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/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.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 };