distillate 0.14.1 → 0.15.0

package/dist/ddsketch/protobuf/index.js

@@ -0,0 +1,294 @@
+import { i as SerializationError } from "../../serialize-CMSYFym-.js";
+import { d as isIndexable, i as sketchFromBins, m as mappingWithGamma, o as collapsingLowestStore, r as sketchBins } from "../../ddsketch-D3Sy8CAU.js";
+//#region src/ddsketch/protobuf/protobuf.ts
+const KINDS = [
+	"log",
+	"linear",
+	"quadratic",
+	"cubic"
+];
+const VARINT = 0;
+const FIXED64 = 1;
+const LENGTH = 2;
+const FIXED32 = 5;
+var Reader = class Reader {
+	#bytes;
+	#view;
+	#at;
+	#end;
+	constructor(bytes, at = 0, end = bytes.length) {
+		this.#bytes = bytes;
+		this.#view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+		this.#at = at;
+		this.#end = end;
+	}
+	get done() {
+		return this.#at >= this.#end;
+	}
+	varint() {
+		let value = 0;
+		for (let shift = 0; shift < 70; shift += 7) {
+			if (this.#at >= this.#end) throw new SerializationError("protobuf: truncated varint");
+			const byte = this.#bytes[this.#at++] ?? 0;
+			value += (byte & 127) * 2 ** shift;
+			if (byte < 128) return value;
+		}
+		throw new SerializationError("protobuf: varint longer than ten bytes");
+	}
+	sint32() {
+		const u = this.varint() % 2 ** 32;
+		return u >>> 1 ^ -(u & 1);
+	}
+	double() {
+		this.#need(8);
+		const value = this.#view.getFloat64(this.#at, true);
+		this.#at += 8;
+		return value;
+	}
+	message() {
+		const length = this.varint();
+		this.#need(length);
+		const sub = new Reader(this.#bytes, this.#at, this.#at + length);
+		this.#at += length;
+		return sub;
+	}
+	tag() {
+		const tag = this.varint();
+		return [Math.floor(tag / 8), tag % 8];
+	}
+	skip(wire) {
+		if (wire === VARINT) this.varint();
+		else if (wire === FIXED64) this.#skipBytes(8);
+		else if (wire === LENGTH) this.message();
+		else if (wire === FIXED32) this.#skipBytes(4);
+		else throw new SerializationError(`protobuf: unsupported wire type ${String(wire)}`);
+	}
+	#skipBytes(n) {
+		this.#need(n);
+		this.#at += n;
+	}
+	#need(n) {
+		if (this.#at + n > this.#end) throw new SerializationError("protobuf: field runs past the end of its message");
+	}
+};
+function expectWire(field, wire, want) {
+	if (wire !== want) throw new SerializationError(`protobuf: ${field} has wire type ${String(wire)}, want ${String(want)}`);
+}
+function readMapping(r, into) {
+	while (!r.done) {
+		const [field, wire] = r.tag();
+		if (field === 1) {
+			expectWire("gamma", wire, FIXED64);
+			into.gamma = r.double();
+		} else if (field === 2) {
+			expectWire("indexOffset", wire, FIXED64);
+			into.indexOffset = r.double();
+		} else if (field === 3) {
+			expectWire("interpolation", wire, VARINT);
+			into.interpolation = r.varint();
+		} else r.skip(wire);
+	}
+}
+function readStore(r, bins) {
+	const contiguous = [];
+	let offset = 0;
+	while (!r.done) {
+		const [field, wire] = r.tag();
+		if (field === 1) {
+			expectWire("binCounts", wire, LENGTH);
+			const entry = r.message();
+			let index = 0;
+			let count = 0;
+			while (!entry.done) {
+				const [f, w] = entry.tag();
+				if (f === 1) {
+					expectWire("binCounts key", w, VARINT);
+					index = entry.sint32();
+				} else if (f === 2) {
+					expectWire("binCounts value", w, FIXED64);
+					count = entry.double();
+				} else entry.skip(w);
+			}
+			bins.set(index, (bins.get(index) ?? 0) + count);
+		} else if (field === 2) {
+			if (wire === LENGTH) {
+				const packed = r.message();
+				while (!packed.done) contiguous.push(packed.double());
+			} else {
+				expectWire("contiguousBinCounts", wire, FIXED64);
+				contiguous.push(r.double());
+			}
+		} else if (field === 3) {
+			expectWire("contiguousBinIndexOffset", wire, VARINT);
+			offset = r.sint32();
+		} else r.skip(wire);
+	}
+	contiguous.forEach((count, i) => {
+		if (count !== 0) bins.set(offset + i, (bins.get(offset + i) ?? 0) + count);
+	});
+}
+function fromProtobuf(bytes, options = {}) {
+	const { store = collapsingLowestStore(4096) } = options;
+	const r = new Reader(bytes);
+	const mapped = {
+		gamma: 0,
+		indexOffset: 0,
+		interpolation: 0
+	};
+	const positive = new Map();
+	const negative = new Map();
+	let zeroCount = 0;
+	while (!r.done) {
+		const [field, wire] = r.tag();
+		if (field === 1) {
+			expectWire("mapping", wire, LENGTH);
+			readMapping(r.message(), mapped);
+		} else if (field === 2) {
+			expectWire("positiveValues", wire, LENGTH);
+			readStore(r.message(), positive);
+		} else if (field === 3) {
+			expectWire("negativeValues", wire, LENGTH);
+			readStore(r.message(), negative);
+		} else if (field === 4) {
+			expectWire("zeroCount", wire, FIXED64);
+			zeroCount = r.double();
+		} else r.skip(wire);
+	}
+	const kind = KINDS[mapped.interpolation];
+	if (kind === void 0) throw new SerializationError(`protobuf: unknown interpolation ${String(mapped.interpolation)}`);
+	const { gamma, indexOffset } = mapped;
+	if (!(gamma > 1 && gamma < Infinity) || !Number.isFinite(indexOffset)) throw new SerializationError("protobuf: gamma must be finite and above 1, and indexOffset finite");
+	if (!(zeroCount >= 0 && zeroCount < Infinity)) throw new SerializationError(`protobuf: zeroCount must be finite and not negative, got ${String(zeroCount)}`);
+	const mapping = mappingWithGamma(kind, gamma, indexOffset);
+	if (!isIndexable(mapping)) throw new SerializationError("protobuf: the mapping leaves no value indexable");
+	const lo = mapping.index(mapping.minIndexableValue);
+	const hi = mapping.index(mapping.maxIndexableValue);
+	for (const bins of [positive, negative]) for (const [index, count] of bins) if (count === 0) bins.delete(index);
+	else if (!(count > 0 && count < Infinity) || index < lo || index > hi) throw new SerializationError(`protobuf: bin ${String(index)} with count ${String(count)} is not one a sketch could hold`);
+	return sketchFromBins(mapping, store, positive, negative, zeroCount);
+}
+function varintSize(value) {
+	let size = 1;
+	while (value >= 128) {
+		value = Math.floor(value / 128);
+		size++;
+	}
+	return size;
+}
+function zigzag(value) {
+	return (value << 1 ^ value >> 31) >>> 0;
+}
+function present(value) {
+	return value !== 0 || Object.is(value, -0);
+}
+function storeBody(store, sparse) {
+	const indices = [];
+	const counts = [];
+	store.forEach((index, count) => {
+		indices.push(index);
+		counts.push(count);
+	});
+	let size = 0;
+	const first = indices[0];
+	if (sparse) for (const index of indices) {
+		const entry = 1 + varintSize(zigzag(index)) + 1 + 8;
+		size += 1 + varintSize(entry) + entry;
+	}
+	else if (first !== void 0) {
+		const packed = 8 * ((indices.at(-1) ?? first) - first + 1);
+		size = 1 + varintSize(packed) + packed;
+		if (first !== 0) size += 1 + varintSize(zigzag(first));
+	}
+	return {
+		indices,
+		counts,
+		sparse,
+		size
+	};
+}
+var Writer = class {
+	bytes;
+	#view;
+	#at = 0;
+	constructor(size) {
+		this.bytes = new Uint8Array(size);
+		this.#view = new DataView(this.bytes.buffer);
+	}
+	tag(field, wire) {
+		this.bytes[this.#at++] = field * 8 + wire;
+	}
+	varint(value) {
+		while (value >= 128) {
+			this.bytes[this.#at++] = value % 128 | 128;
+			value = Math.floor(value / 128);
+		}
+		this.bytes[this.#at++] = value;
+	}
+	double(value) {
+		this.#view.setFloat64(this.#at, value, true);
+		this.#at += 8;
+	}
+	store(field, body) {
+		this.tag(field, LENGTH);
+		this.varint(body.size);
+		const { indices, counts } = body;
+		const first = indices[0];
+		if (first === void 0) return;
+		if (body.sparse) {
+			indices.forEach((index, i) => {
+				const key = zigzag(index);
+				this.tag(1, LENGTH);
+				this.varint(1 + varintSize(key) + 1 + 8);
+				this.tag(1, VARINT);
+				this.varint(key);
+				this.tag(2, FIXED64);
+				this.double(counts[i] ?? 0);
+			});
+			return;
+		}
+		const span = (indices.at(-1) ?? first) - first + 1;
+		this.tag(2, LENGTH);
+		this.varint(8 * span);
+		indices.forEach((index, i) => {
+			this.#view.setFloat64(this.#at + 8 * (index - first), counts[i] ?? 0, true);
+		});
+		this.#at += 8 * span;
+		if (first !== 0) {
+			this.tag(3, VARINT);
+			this.varint(zigzag(first));
+		}
+	}
+};
+function toProtobuf(sketch) {
+	const { mapping } = sketch;
+	const { positive, negative, zeroCount } = sketchBins(sketch);
+	const sparse = sketch.store.kind === "sparse";
+	const pos = storeBody(positive, sparse);
+	const neg = storeBody(negative, sparse);
+	const interpolation = KINDS.indexOf(mapping.kind);
+	const mappingSize = (present(mapping.gamma) ? 9 : 0) + (present(mapping.indexOffset) ? 9 : 0) + (interpolation !== 0 ? 1 + varintSize(interpolation) : 0);
+	const w = new Writer(1 + varintSize(mappingSize) + mappingSize + (1 + varintSize(pos.size) + pos.size) + (1 + varintSize(neg.size) + neg.size) + (present(zeroCount) ? 9 : 0));
+	w.tag(1, LENGTH);
+	w.varint(mappingSize);
+	if (present(mapping.gamma)) {
+		w.tag(1, FIXED64);
+		w.double(mapping.gamma);
+	}
+	if (present(mapping.indexOffset)) {
+		w.tag(2, FIXED64);
+		w.double(mapping.indexOffset);
+	}
+	if (interpolation !== 0) {
+		w.tag(3, VARINT);
+		w.varint(interpolation);
+	}
+	w.store(2, pos);
+	w.store(3, neg);
+	if (present(zeroCount)) {
+		w.tag(4, FIXED64);
+		w.double(zeroCount);
+	}
+	return w.bytes;
+}
+//#endregion
+export { SerializationError, fromProtobuf, toProtobuf };

package/dist/ddsketch-1Buc9M3P.d.cts

@@ -0,0 +1,293 @@
+import { r as FilterJSON } from "./serialize--xR6vGSW.cjs";
+//#region src/ddsketch/mapping.d.ts
+/** Which approximation of the logarithm a mapping bins values by. */
+type MappingKind = "log" | "linear" | "quadratic" | "cubic";
+/**
+ * Maps a positive value to the integer index of the bin holding it, and an
+ * index back to a value within `relativeAccuracy` of everything in that bin.
+ * Built by this module's factories only: a sketch serializes its mapping by
+ * `kind`, so a custom implementation would be written, and read back, as the
+ * built-in one of that kind.
+ */
+interface IndexMapping {
+  /** Which approximation of the logarithm the mapping uses. */
+  readonly kind: MappingKind;
+  /** The base the bins grow by. */
+  readonly gamma: number;
+  /** Shift added to every index, carried so foreign sketches decode exactly. */
+  readonly indexOffset: number;
+  /** The relative error any value read back from a bin is within. */
+  readonly relativeAccuracy: number;
+  /** The smallest value with a bin; anything smaller counts as zero. */
+  readonly minIndexableValue: number;
+  /** The largest value with a bin. */
+  readonly maxIndexableValue: number;
+  /** The bin index of a value in the indexable range. */
+  index(value: number): number;
+  /** The value a bin reads back as. */
+  value(index: number): number;
+  /** The smallest value that falls in a bin. */
+  lowerBound(index: number): number;
+}
+/**
+ * A mapping whose bins grow by exactly `gamma`: the most compact for a given
+ * accuracy, at the cost of a `Math.log` per value.
+ *
+ * @param relativeAccuracy - Relative error bound, in `(0, 1)`.
+ * @throws {@link ParamError} when `relativeAccuracy` is outside `(0, 1)`, or
+ * so small that no value is indexable.
+ */
+declare function logMapping(relativeAccuracy: number): IndexMapping;
+/**
+ * A mapping that interpolates log2 linearly from the float's bits instead of
+ * calling `Math.log`, at about 44% more bins than {@link logMapping} for the
+ * same accuracy. For matching sketches built with it elsewhere; in V8 it adds
+ * only slightly faster than the log mapping.
+ *
+ * @param relativeAccuracy - Relative error bound, in `(0, 1)`.
+ * @throws {@link ParamError} when `relativeAccuracy` is outside `(0, 1)`, or
+ * so small that no value is indexable.
+ */
+declare function linearMapping(relativeAccuracy: number): IndexMapping;
+/**
+ * The fastest mapping: a value's bin is its float's exponent and top
+ * significand bits read as one integer, with no logarithm or other floating
+ * point arithmetic, as in sketches-java's `DDSketch.fast()`. It spends about
+ * 1.85 times the bins of {@link logMapping} at 1%, and is at least as accurate
+ * as asked: its bins come in powers of two, so it takes the finest that meets
+ * `relativeAccuracy`. Datadog's protobuf carries it as a linear mapping.
+ *
+ * @param relativeAccuracy - Relative error bound, in `(0, 1)`.
+ * @throws {@link ParamError} when `relativeAccuracy` is outside `(0, 1)`, or
+ * so small that no value is indexable.
+ */
+declare function bitwiseMapping(relativeAccuracy: number): IndexMapping;
+/**
+ * A mapping that approximates log2 with a quadratic in the float's
+ * significand: between {@link linearMapping} and {@link cubicMapping} in
+ * bins per accuracy. Matches sketches-java, the reference that has it.
+ *
+ * @param relativeAccuracy - Relative error bound, in `(0, 1)`.
+ * @throws {@link ParamError} when `relativeAccuracy` is outside `(0, 1)`, or
+ * so small that no value is indexable.
+ */
+declare function quadraticMapping(relativeAccuracy: number): IndexMapping;
+/**
+ * A mapping that approximates log2 with a cubic in the float's significand:
+ * nearly as compact as {@link logMapping}. For matching sketches built with it
+ * elsewhere; in V8 it adds slower than the log mapping, `Math.log` being cheap.
+ *
+ * @param relativeAccuracy - Relative error bound, in `(0, 1)`.
+ * @throws {@link ParamError} when `relativeAccuracy` is outside `(0, 1)`, or
+ * so small that no value is indexable.
+ */
+declare function cubicMapping(relativeAccuracy: number): IndexMapping;
+//#endregion
+//#region src/ddsketch/store.d.ts
+/** How a store lays out its bins and what it gives up to bound memory. */
+type StoreKind = "dense" | "sparse" | "collapsingLowest" | "collapsingHighest";
+/** Counts per bin index for one sign of a sketch. */
+interface Store {
+  /** The sum of every count added. */
+  readonly total: number;
+  /** Adds `count` to the bin at `index`. */
+  add(index: number, count: number): void;
+  /**
+   * The index of the bin holding the value at `rank`, counting from 0 in
+   * ascending index order, or descending when `descending` is set.
+   */
+  keyAtRank(rank: number, descending?: boolean): number;
+  /** Calls `fn` for every non-empty bin, in ascending index order. */
+  forEach(fn: (index: number, count: number) => void): void;
+  /** Adds every bin of `other`, as adding them in ascending index order would. */
+  merge(other: Store): void;
+}
+/**
+ * Builds the stores a sketch keeps, one per sign, both with the same policy.
+ * Passed to {@link DDSketch.create} as `store`. Built by this module's
+ * factories only: a sketch serializes its store by `kind` and `maxBins`, so a
+ * custom one would be read back as the built-in store of that kind.
+ */
+interface StoreFactory {
+  /** Which store this builds. */
+  readonly kind: StoreKind;
+  /** The most bins a store keeps, or 0 when unbounded. */
+  readonly maxBins: number;
+  /** A new, empty store. */
+  create(): Store;
+}
+/**
+ * Bins over one contiguous range of indices that grows to fit, with no bound
+ * on memory: a stream spanning a wide range of magnitudes keeps every bin.
+ */
+declare function denseStore(): StoreFactory;
+/**
+ * Bins only where values landed, so memory follows the number of distinct
+ * bins rather than the range between the smallest and largest.
+ */
+declare function sparseStore(): StoreFactory;
+/**
+ * A dense store that never spans more than `maxBins` bins. Past that it folds
+ * the lowest bins into the lowest one it keeps, giving up accuracy on the
+ * smallest magnitudes, near zero on either sign, and keeping it for the
+ * largest. The default, since the tails are what quantiles are read for.
+ *
+ * @param maxBins - The most bins kept per sign; a positive integer.
+ * @throws {@link ParamError} when `maxBins` is not a positive integer.
+ */
+declare function collapsingLowestStore(maxBins: number): StoreFactory;
+/**
+ * A dense store that never spans more than `maxBins` bins. Past that it folds
+ * the highest bins into the highest one it keeps, giving up accuracy on the
+ * largest magnitudes and keeping it for the smallest.
+ *
+ * @param maxBins - The most bins kept per sign; a positive integer.
+ * @throws {@link ParamError} when `maxBins` is not a positive integer.
+ */
+declare function collapsingHighestStore(maxBins: number): StoreFactory;
+//#endregion
+//#region src/ddsketch/ddsketch.d.ts
+/** Options for {@link DDSketch.create}. */
+interface DDSketchOptions {
+  /**
+   * The mapping factory that bins values. Defaults to {@link bitwiseMapping},
+   * the mapping sketches-java's fast sketch uses and the fastest, adding about
+   * twice as fast as the log mapping in the benchmarks; take {@link logMapping}
+   * for the fewest bins. The interpolated mappings exist to
+   * match sketches built with them by Datadog's libraries.
+   */
+  mapping?: (relativeAccuracy: number) => IndexMapping;
+  /**
+   * The store factory that holds each sign's bins. Defaults to
+   * {@link collapsingLowestStore} at 4096 bins, about 19 orders of magnitude
+   * at 1% with the default mapping, which bounds memory while keeping the
+   * tails accurate.
+   */
+  store?: StoreFactory;
+}
+/** Thrown by {@link DDSketch.union} when the two sketches' bins differ. */
+declare class DDSketchParamMismatchError extends Error {
+  /** Discriminates this error from other `Error`s. */
+  override readonly name = "DDSketchParamMismatchError";
+}
+/**
+ * A quantile sketch whose every answer is within a relative error of the true
+ * value at that quantile, tails included.
+ */
+declare class DDSketch {
+  #private;
+  /**
+   * Builds an empty sketch.
+   *
+   * @param relativeAccuracy - Relative error bound on every quantile, in `(0, 1)`.
+   * @param options - Optional mapping and store factories.
+   * @throws {@link ParamError} when `relativeAccuracy` is outside `(0, 1)`, or
+   * so small that the mapping indexes no value.
+   */
+  static create(relativeAccuracy: number, options?: DDSketchOptions): DDSketch;
+  /**
+   * Builds a sketch holding `values`.
+   *
+   * @param values - Finite numbers within the mapping's indexable range.
+   * @param relativeAccuracy - Relative error bound on every quantile, in `(0, 1)`.
+   * @param options - Optional mapping and store factories.
+   * @throws {@link ParamError} when `relativeAccuracy` is outside `(0, 1)` or
+   * so small that the mapping indexes no value, or a value cannot be recorded.
+   */
+  static from(values: Iterable<number>, relativeAccuracy: number, options?: DDSketchOptions): DDSketch;
+  /**
+   * Restores a sketch from its {@link DDSketch.toBytes} serialization.
+   *
+   * @param bytes - The serialized sketch.
+   * @returns The reconstructed sketch.
+   * @throws {@link SerializationError} when the frame is malformed or not a
+   * DDSketch.
+   */
+  static fromBytes(bytes: Uint8Array): DDSketch;
+  /** See {@link DDSketch.create}. */
+  constructor(relativeAccuracy: number, options?: DDSketchOptions);
+  /** The relative error bound the sketch was built for. */
+  get relativeAccuracy(): number;
+  /** The mapping that bins values. */
+  get mapping(): IndexMapping;
+  /** The store factory holding each sign's bins. */
+  get store(): StoreFactory;
+  /** How many values have been added. */
+  get count(): number;
+  /**
+   * The sum of every value added. Past the largest double it is `Infinity`
+   * or `-Infinity`, and NaN once both signs have overflowed.
+   */
+  get sum(): number;
+  /** The smallest value added, exactly; `NaN` when empty. */
+  get min(): number;
+  /** The largest value added, exactly; `NaN` when empty. */
+  get max(): number;
+  /**
+   * Returns a new sketch holding everything this one and `other` have
+   * recorded: the same bins, count, min and max one sketch over both streams
+   * would hold, with `sum` equal up to float rounding. It takes this sketch's
+   * accuracy, mapping and store; both operands are left untouched.
+   *
+   * @param other - A sketch whose mapping bins values identically.
+   * @returns A new sketch holding both streams.
+   * @throws {@link DDSketchParamMismatchError} when the mappings differ in
+   * kind, or in `gamma` or `indexOffset` by more than 1e-12 relative.
+   */
+  union(other: DDSketch): DDSketch;
+  /**
+   * Serializes the sketch into a self-describing DSTL frame (type 10): its
+   * mapping and store, summaries, and each sign's non-empty bins in ascending
+   * index order, so equal sketches give equal bytes.
+   *
+   * @returns The serialized sketch, readable by {@link DDSketch.fromBytes}.
+   */
+  toBytes(): Uint8Array;
+  /**
+   * Tests structural equality: `true` when `other` serializes to identical
+   * bytes, meaning the same mapping, store, summaries and bins.
+   *
+   * @param other - The sketch to compare against.
+   * @returns `true` if the two sketches are byte-for-byte identical.
+   */
+  equals(other: DDSketch): boolean;
+  /**
+   * Serializes the sketch into the JSON envelope: the base64 of
+   * {@link DDSketch.toBytes}.
+   *
+   * @returns The envelope, readable by {@link DDSketch.fromJSON}.
+   */
+  toJSON(): FilterJSON;
+  /**
+   * Restores a sketch from its {@link DDSketch.toJSON} envelope.
+   *
+   * @param value - The parsed envelope.
+   * @returns The reconstructed sketch.
+   * @throws {@link SerializationError} when the envelope or frame is malformed.
+   */
+  static fromJSON(value: unknown): DDSketch;
+  /**
+   * The value at quantile `q`, within `relativeAccuracy` of the exact value at
+   * rank `floor(q * (count - 1))`. `q = 0` and `q = 1` give `min` and `max`
+   * exactly.
+   *
+   * @param q - The quantile, in `[0, 1]`.
+   * @returns The estimate, or `NaN` when the sketch is empty.
+   * @throws {@link ParamError} when `q` is outside `[0, 1]`.
+   */
+  quantile(q: number): number;
+  /** {@link DDSketch.quantile} for each of `qs`, in order. */
+  quantiles(qs: readonly number[]): number[];
+  /**
+   * Records a value.
+   *
+   * @param value - Any finite number within the mapping's indexable range.
+   * @param count - How many times to record it; finite and positive.
+   * @throws {@link ParamError} when `value` is not finite or beyond
+   * `mapping.maxIndexableValue` in magnitude, or `count` is not a finite
+   * positive number. Nothing is recorded.
+   */
+  add(value: number, count?: number): void;
+}
+//#endregion
+export { quadraticMapping as _, StoreFactory as a, collapsingLowestStore as c, IndexMapping as d, MappingKind as f, logMapping as g, linearMapping as h, Store as i, denseStore as l, cubicMapping as m, DDSketchOptions as n, StoreKind as o, bitwiseMapping as p, DDSketchParamMismatchError as r, collapsingHighestStore as s, DDSketch as t, sparseStore as u };