node/lib/internal/histogram.js

'use strict';

const {
  BigInt,
  Float64Array,
  Map,
  MapPrototypeEntries,
  NumberIsNaN,
  NumberMAX_SAFE_INTEGER,
  ObjectFromEntries,
  Symbol,
} = primordials;

const {
  Histogram: _Histogram,
  SlidingWindowHistogram: _SlidingWindowHistogram,
} = internalBinding('performance');

const {
  customInspectSymbol: kInspect,
  kEmptyObject,
} = require('internal/util');

const { inspect } = require('util');

const {
  codes: {
    ERR_ILLEGAL_CONSTRUCTOR,
    ERR_INVALID_ARG_TYPE,
    ERR_INVALID_ARG_VALUE,
    ERR_INVALID_THIS,
    ERR_OUT_OF_RANGE,
  },
} = require('internal/errors');

const {
  validateArray,
  validateBoolean,
  validateInteger,
  validateNumber,
  validateObject,
  validateOneOf,
} = require('internal/validators');

const {
  isUint8Array,
} = require('internal/util/types');

const kDestroy = Symbol('kDestroy');
const kHandle = Symbol('kHandle');
const kRecordable = Symbol('kRecordable');
const kSlidingWindowHandle = Symbol('kSlidingWindowHandle');
const kQrdeDequantizationModes = ['none', 'hdr', 'all'];
const kMaxSlidingWindowHistogramChunks = 1024;
const kMaxChunkDuration = 18_446_744_073_709;
const kMaxInt64 = 9_223_372_036_854_775_807n;

const {
  kClone,
  kDeserialize,
  markTransferMode,
} = require('internal/worker/js_transferable');

function isHistogram(object) {
  return object?.[kHandle] !== undefined;
}

const kSkipThrow = Symbol('kSkipThrow');

class Histogram {
  constructor(skipThrowSymbol = undefined) {
    if (skipThrowSymbol !== kSkipThrow) {
      throw new ERR_ILLEGAL_CONSTRUCTOR();
    }
  }

  [kInspect](depth, options) {
    if (depth < 0)
      return this;

    const opts = {
      ...options,
      depth: options.depth == null ? null : options.depth - 1,
    };

    return `Histogram ${inspect({
      min: this.min,
      max: this.max,
      mean: this.mean,
      exceeds: this.exceeds,
      stddev: this.stddev,
      skewness: this.skewness,
      kurtosis: this.kurtosis,
      count: this.count,
      percentiles: this.percentiles,
    }, opts)}`;
  }

  /**
   * @readonly
   * @type {number}
   */
  get count() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.count();
  }

  /**
   * @readonly
   * @type {bigint}
   */
  get countBigInt() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.countBigInt();
  }

  /**
   * Returns the probability that a recorded value will exceed `value`
   * (the complement of the cumulative distribution function).
   * @param {number} value
   * @returns {number} A value between 0.0 and 1.0.
   */
  ccdf(value) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    validateNumber(value, 'value');
    return 1 - this[kHandle]?.cdf(value);
  }

  /**
   * Returns the cumulative distribution function (CDF) value for the
   * given value, representing the probability that a recorded value
   * will be less than or equal to `value`.
   * @param {number} value
   * @returns {number} A value between 0.0 and 1.0.
   */
  cdf(value) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    validateNumber(value, 'value');
    return this[kHandle]?.cdf(value);
  }

  /**
   * Returns the number of recorded values that fall within the
   * equivalent value range of the given value.
   * @param {number} value
   * @returns {number}
   */
  countAt(value) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    validateNumber(value, 'value');
    return this[kHandle]?.countAt(value);
  }

  /**
   * @readonly
   * @type {number}
   */
  get min() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.min();
  }

  /**
   * @readonly
   * @type {bigint}
   */
  get minBigInt() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.minBigInt();
  }

  /**
   * @readonly
   * @type {number}
   */
  get max() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.max();
  }

  /**
   * @readonly
   * @type {bigint}
   */
  get maxBigInt() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.maxBigInt();
  }

  /**
   * @readonly
   * @type {number}
   */
  get mean() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.mean();
  }

  /**
   * Returns a confidence interval for the mean using Student's t-distribution.
   * @param {{ confidence?: number }} [options]
   * @returns {{ mean: number, lower: number, upper: number }}
   */
  meanCI(options = kEmptyObject) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    validateObject(options, 'options');
    const { confidence = 0.95 } = options;
    validateNumber(confidence, 'options.confidence');
    if (NumberIsNaN(confidence) || confidence <= 0 || confidence >= 1)
      throw new ERR_OUT_OF_RANGE('options.confidence',
                                 '> 0 && < 1', confidence);
    const result = this[kHandle]?.meanCI(confidence);
    if (result === undefined) return undefined;
    return {
      __proto__: null,
      mean: result[0],
      lower: result[1],
      upper: result[2],
    };
  }

  /**
   * @readonly
   * @type {number}
   */
  get exceeds() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.exceeds();
  }

  /**
   * @readonly
   * @type {bigint}
   */
  get exceedsBigInt() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.exceedsBigInt();
  }

  /**
   * Serializes the histogram to a CBOR-encoded Uint8Array suitable for
   * transmission or storage. The data can be reconstructed into a new
   * histogram using `importHistogram()`.
   * @returns {Uint8Array}
   */
  export() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.export();
  }

  /**
   * Returns the exponentially weighted moving average of recorded values.
   * Only active when the histogram was created with a `halfLife` option.
   * Returns 0 when EWMA is not enabled or no values have been recorded.
   * @readonly
   * @type {number}
   */
  get ewmaMean() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.ewmaMean();
  }

  /**
   * Returns the exponentially weighted moving standard deviation.
   * Only active when the histogram was created with a `halfLife` option.
   * Returns 0 when EWMA is not enabled or no values have been recorded.
   * @readonly
   * @type {number}
   */
  get ewmaStddev() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.ewmaStddev();
  }

  /**
   * Returns the EWMA-smoothed error rate: the probability of a recorded
   * value exceeding the configured `threshold`. Only active when the
   * histogram was created with both `halfLife` and `threshold` options.
   * Returns 0 when not enabled or no values have been recorded.
   * @readonly
   * @type {number}
   */
  get ewmaErrorRate() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.ewmaErrorRate();
  }

  /**
   * Returns the SLO burn rate: how fast the error budget is being consumed.
   * A burn rate of 1 means the budget will be exactly exhausted over the
   * SLO window. A burn rate of 10 means it is being consumed 10x faster.
   * Requires `halfLife` and `threshold` to be configured.
   * @param {number} sloTarget - The SLO target as a fraction (e.g. 0.999
   *   for 99.9%).
   * @returns {number}
   */
  burnRate(sloTarget) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    validateNumber(sloTarget, 'sloTarget');
    if (NumberIsNaN(sloTarget) || sloTarget <= 0 || sloTarget >= 1)
      throw new ERR_OUT_OF_RANGE('sloTarget', '> 0 && < 1', sloTarget);
    const errorRate = this[kHandle]?.ewmaErrorRate();
    if (errorRate === undefined) return undefined;
    const errorBudget = 1 - sloTarget;
    return errorRate / errorBudget;
  }

  /**
   * Returns the Kolmogorov-Smirnov test statistic comparing this
   * histogram's distribution to another's. Returns a value between
   * 0.0 (identical distributions) and 1.0 (completely disjoint).
   * @param {Histogram} other
   * @returns {number}
   */
  ksTest(other) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    if (!isHistogram(other))
      throw new ERR_INVALID_ARG_TYPE('other', 'Histogram', other);
    return this[kHandle]?.ksTest(other[kHandle]);
  }

  /**
   * Performs Welch's t-test comparing this histogram to another.
   * Returns an object with the t-statistic, degrees of freedom,
   * two-tailed p-value, and confidence interval on the difference
   * of means.
   * @param {Histogram} other
   * @param {{ confidence?: number }} [options]
   * @returns {{ tStatistic: number, degreesOfFreedom: number,
   *             pValue: number,
   *             confidenceInterval: { lower: number, upper: number } }}
   */
  welchTest(other, options = kEmptyObject) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    if (!isHistogram(other))
      throw new ERR_INVALID_ARG_TYPE('other', 'Histogram', other);
    validateObject(options, 'options');
    const { confidence = 0.95 } = options;
    validateNumber(confidence, 'options.confidence');
    if (NumberIsNaN(confidence) || confidence <= 0 || confidence >= 1)
      throw new ERR_OUT_OF_RANGE('options.confidence',
                                 '> 0 && < 1', confidence);
    const result = this[kHandle]?.welchTest(other[kHandle], confidence);
    if (result === undefined) return undefined;
    return {
      __proto__: null,
      tStatistic: result[0],
      degreesOfFreedom: result[1],
      pValue: result[2],
      confidenceInterval: {
        __proto__: null,
        lower: result[3],
        upper: result[4],
      },
    };
  }

  /**
   * Performs a Mann-Whitney U test comparing this histogram to
   * another. Returns an object with the U statistic, z-score,
   * and two-tailed p-value (normal approximation).
   * @param {Histogram} other
   * @returns {{ uStatistic: number, zScore: number, pValue: number }}
   */
  mannWhitneyTest(other) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    if (!isHistogram(other))
      throw new ERR_INVALID_ARG_TYPE('other', 'Histogram', other);
    const result = this[kHandle]?.mannWhitneyTest(other[kHandle]);
    if (result === undefined) return undefined;
    return {
      __proto__: null,
      uStatistic: result[0],
      zScore: result[1],
      pValue: result[2],
    };
  }

  /**
   * Computes Cohen's d effect size comparing this histogram to
   * another. Uses the pooled standard deviation. Positive values
   * indicate this histogram has a higher mean.
   * @param {Histogram} other
   * @returns {number}
   */
  cohensD(other) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    if (!isHistogram(other))
      throw new ERR_INVALID_ARG_TYPE('other', 'Histogram', other);
    return this[kHandle]?.cohensD(other[kHandle]);
  }

  /**
   * Computes Cliff's delta comparing this histogram to another.
   * Returns a value between -1 and 1. Positive values indicate
   * this histogram tends to produce larger values.
   * @param {Histogram} other
   * @returns {number}
   */
  cliffsD(other) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    if (!isHistogram(other))
      throw new ERR_INVALID_ARG_TYPE('other', 'Histogram', other);
    return this[kHandle]?.cliffsD(other[kHandle]);
  }

  /**
   * Returns the excess kurtosis of the recorded values, a measure of
   * the heaviness of the distribution's tails. A positive value indicates
   * heavier tails (more outliers) than a normal distribution.
   * @readonly
   * @type {number}
   */
  get kurtosis() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.kurtosis();
  }

  /**
   * Returns a {Map} containing the histogram data bucketed into
   * linearly-spaced intervals of `stepSize`.
   * @param {number} stepSize The width of each linear bucket.
   * @returns {Map<number,number>}
   */
  linearBuckets(stepSize) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    validateInteger(stepSize, 'stepSize', 1);
    const map = new Map();
    this[kHandle]?.linearBuckets(stepSize, map);
    return map;
  }

  /**
   * Returns a {Map} containing the histogram data bucketed into
   * logarithmically-spaced intervals.
   * @param {number} firstBucket The value of the first bucket boundary.
   * @param {number} base The logarithmic base for bucket width growth.
   * @returns {Map<number,number>}
   */
  logBuckets(firstBucket, base) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    validateInteger(firstBucket, 'firstBucket', 1);
    validateNumber(base, 'base');
    if (base <= 1)
      throw new ERR_OUT_OF_RANGE('base', '> 1', base);
    const map = new Map();
    this[kHandle]?.logBuckets(firstBucket, base, map);
    return map;
  }

  /**
   * Returns the skewness of the recorded values, a measure of the
   * asymmetry of the distribution. A positive value indicates a
   * right-skewed distribution (longer right tail).
   * @readonly
   * @type {number}
   */
  get skewness() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.skewness();
  }

  /**
   * @readonly
   * @type {number}
   */
  get stddev() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.stddev();
  }

  /**
   * @param {number} percentile
   * @returns {number}
   */
  percentile(percentile) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    validateNumber(percentile, 'percentile');
    if (NumberIsNaN(percentile) || percentile <= 0 || percentile > 100)
      throw new ERR_OUT_OF_RANGE('percentile', '> 0 && <= 100', percentile);

    return this[kHandle]?.percentile(percentile);
  }

  /**
   * @param {number} percentile
   * @returns {bigint}
   */
  percentileBigInt(percentile) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    validateNumber(percentile, 'percentile');
    if (NumberIsNaN(percentile) || percentile <= 0 || percentile > 100)
      throw new ERR_OUT_OF_RANGE('percentile', '> 0 && <= 100', percentile);

    return this[kHandle]?.percentileBigInt(percentile);
  }

  /**
   * Returns a confidence interval for the given percentile using the
   * exact binomial method. The result contains the point estimate and
   * the lower/upper bounds of the interval.
   * @param {number} percentile
   * @param {{ confidence?: number }} [options]
   * @returns {{ value: number, lower: number, upper: number }}
   */
  percentileCI(percentile, options = kEmptyObject) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    validateNumber(percentile, 'percentile');
    if (NumberIsNaN(percentile) || percentile <= 0 || percentile > 100)
      throw new ERR_OUT_OF_RANGE('percentile', '> 0 && <= 100', percentile);
    validateObject(options, 'options');
    const { confidence = 0.95 } = options;
    validateNumber(confidence, 'options.confidence');
    if (NumberIsNaN(confidence) || confidence <= 0 || confidence >= 1)
      throw new ERR_OUT_OF_RANGE('options.confidence',
                                 '> 0 && < 1', confidence);
    const result = this[kHandle]?.percentileCI(percentile, confidence);
    if (result === undefined) return undefined;
    return {
      __proto__: null,
      value: result[0],
      lower: result[1],
      upper: result[2],
    };
  }

  /**
   * @readonly
   * @type {Map<number,number>}
   */
  get percentiles() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    const map = new Map();
    this[kHandle]?.percentiles(map);
    return map;
  }

  /**
   * @readonly
   * @type {Map<number,bigint>}
   */
  get percentilesBigInt() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    const map = new Map();
    this[kHandle]?.percentilesBigInt(map);
    return map;
  }

  /**
   * Returns a {Map} of values at the specified percentiles, computed
   * in a single efficient pass over the histogram.
   * @param {number[]} percentiles Array of percentile values (0, 100].
   * @returns {Map<number,number>}
   */
  percentilesAt(percentiles) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    validateArray(percentiles, 'percentiles');
    for (let i = 0; i < percentiles.length; i++) {
      validateNumber(percentiles[i], `percentiles[${i}]`);
      if (NumberIsNaN(percentiles[i]) ||
          percentiles[i] <= 0 || percentiles[i] > 100)
        throw new ERR_OUT_OF_RANGE(
          `percentiles[${i}]`, '> 0 && <= 100', percentiles[i]);
    }
    const sorted = [...percentiles].sort((a, b) => a - b);
    const input = new Float64Array(sorted);
    const map = new Map();
    this[kHandle]?.percentilesAt(map, input);
    return map;
  }

  /**
   * Builds a quantile-respectful density estimate using Harrell-Davis
   * quantiles. Values can be spread deterministically within their HDR
   * equivalent-value ranges to reduce quantization artifacts.
   * @param {{ bins?: number, probabilities?: number[],
   *   dequantize?: 'none'|'hdr'|'all', cache?: boolean }} [options]
   * @returns {Promise<{
   *   probabilities: Float64Array,
   *   quantiles: Float64Array,
   *   densities: Float64Array,
   *   count: bigint,
   *   bucketCount: number,
   *   corrections: number,
   *   dequantize: 'none'|'hdr'|'all',
   * }>}
   */
  qrde(options = kEmptyObject) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    validateObject(options, 'options');
    const { bins, probabilities, dequantize = 'hdr', cache = false } = options;
    if (bins !== undefined && probabilities !== undefined) {
      throw new ERR_INVALID_ARG_VALUE(
        'options', options, '"bins" and "probabilities" are mutually exclusive');
    }

    let boundaries;
    if (probabilities === undefined) {
      const binCount = bins ?? 100;
      validateInteger(binCount, 'options.bins', 1, 1000);
      boundaries = new Float64Array(binCount + 1);
      for (let i = 0; i <= binCount; i++) boundaries[i] = i / binCount;
    } else {
      validateArray(probabilities, 'options.probabilities', 2);
      const length = probabilities.length;
      if (length > 1001) {
        throw new ERR_OUT_OF_RANGE(
          'options.probabilities.length', '>= 2 && <= 1001', length);
      }

      boundaries = new Float64Array(length);
      let previous = -1;
      for (let i = 0; i < length; i++) {
        const probability = probabilities[i];
        validateNumber(probability, `options.probabilities[${i}]`, 0, 1);
        if (probability <= previous) {
          throw new ERR_INVALID_ARG_VALUE(
            'options.probabilities', probabilities, 'must be strictly increasing');
        }
        boundaries[i] = probability;
        previous = probability;
      }
      if (boundaries[0] !== 0 || boundaries[length - 1] !== 1) {
        throw new ERR_INVALID_ARG_VALUE(
          'options.probabilities', probabilities, 'must start with 0 and end with 1');
      }
    }

    validateOneOf(dequantize,
                  'options.dequantize', kQrdeDequantizationModes);
    validateBoolean(cache, 'options.cache');
    let mode = 0;
    if (dequantize === 'hdr') mode = 1;
    else if (dequantize === 'all') mode = 2;
    return this[kHandle]?.qrde(boundaries, mode, cache);
  }

  /**
   * @returns {void}
   */
  reset() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    this[kHandle]?.reset();
  }

  /**
   * The number of times values have been removed from the histogram by
   * `reset()` or `subtract()`.
   * @readonly
   * @type {number}
   */
  get resetCount() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return this[kHandle]?.resetCount();
  }

  /**
   * Returns a new, independent histogram containing a copy of this
   * histogram's current state. Values cannot be recorded into the returned
   * histogram.
   * @returns {Histogram}
   */
  snapshot() {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    return new ClonedHistogram(this[kHandle].snapshot());
  }

  /**
   * Returns a new histogram containing the values recorded in this histogram
   * after `other`, an earlier snapshot of it, was taken.
   * @param {Histogram} other
   * @returns {Histogram}
   */
  diff(other) {
    if (!isHistogram(this))
      throw new ERR_INVALID_THIS('Histogram');
    if (!isHistogram(other))
      throw new ERR_INVALID_ARG_TYPE('other', 'Histogram', other);
    return new ClonedHistogram(this[kHandle].diff(other[kHandle]));
  }

  [kClone]() {
    const handle = this[kHandle];
    return {
      data: { handle },
      deserializeInfo: 'internal/histogram:ClonedHistogram',
    };
  }

  [kDeserialize]({ handle }) {
    this[kHandle] = handle;
  }

  toJSON() {
    const json = {
      count: this.count,
      min: this.min,
      max: this.max,
      mean: this.mean,
      exceeds: this.exceeds,
      stddev: this.stddev,
      skewness: this.skewness,
      kurtosis: this.kurtosis,
      ewmaMean: this.ewmaMean,
      ewmaStddev: this.ewmaStddev,
      ewmaErrorRate: this.ewmaErrorRate,
      percentiles: ObjectFromEntries(MapPrototypeEntries(this.percentiles)),
    };
    return json;
  }
}

class RecordableHistogram extends Histogram {
  constructor(skipThrowSymbol = undefined) {
    if (skipThrowSymbol !== kSkipThrow) {
      throw new ERR_ILLEGAL_CONSTRUCTOR();
    }

    super(skipThrowSymbol);
  }

  /**
   * @param {number|bigint} val
   * @returns {void}
   */
  record(val) {
    if (this[kRecordable] === undefined)
      throw new ERR_INVALID_THIS('RecordableHistogram');
    if (typeof val === 'bigint') {
      this[kHandle]?.record(val);
      return;
    }

    validateInteger(val, 'val', 0);

    this[kHandle]?.record(val);
  }

  /**
   * @returns {void}
   */
  recordDelta() {
    if (this[kRecordable] === undefined)
      throw new ERR_INVALID_THIS('RecordableHistogram');
    this[kHandle]?.recordDelta();
  }

  /**
   * Records a value with coordinated omission correction, backfilling
   * intermediate values at `expectedInterval` steps between the last
   * recorded value and `val`. This compensates for measurement gaps
   * caused by the system being stalled.
   * @param {number|bigint} val The amount to record.
   * @param {number|bigint} expectedInterval The expected recording interval.
   * @returns {void}
   */
  recordCorrected(val, expectedInterval) {
    if (this[kRecordable] === undefined)
      throw new ERR_INVALID_THIS('RecordableHistogram');
    if (typeof val === 'bigint') {
      if (typeof expectedInterval !== 'bigint')
        throw new ERR_INVALID_ARG_TYPE(
          'expectedInterval', 'bigint', expectedInterval);
      this[kHandle]?.recordCorrected(val, expectedInterval);
      return;
    }
    validateInteger(val, 'val', 0);
    validateInteger(expectedInterval, 'expectedInterval', 1);
    this[kHandle]?.recordCorrected(val, expectedInterval);
  }

  /**
   * Subtracts the values of `other` from this histogram. Both
   * histograms must have compatible configurations. Counts that would
   * become negative are clamped to zero.
   * @param {RecordableHistogram} other
   */
  subtract(other) {
    if (this[kRecordable] === undefined)
      throw new ERR_INVALID_THIS('RecordableHistogram');
    if (other[kRecordable] === undefined)
      throw new ERR_INVALID_ARG_TYPE('other', 'RecordableHistogram', other);
    this[kHandle]?.subtract(other[kHandle]);
  }

  /**
   * @param {RecordableHistogram} other
   */
  add(other) {
    if (this[kRecordable] === undefined)
      throw new ERR_INVALID_THIS('RecordableHistogram');
    if (other[kRecordable] === undefined)
      throw new ERR_INVALID_ARG_TYPE('other', 'RecordableHistogram', other);
    this[kHandle]?.add(other[kHandle]);
  }

  [kClone]() {
    const handle = this[kHandle];
    return {
      data: { handle },
      deserializeInfo: 'internal/histogram:ClonedRecordableHistogram',
    };
  }

  [kDeserialize]({ handle }) {
    this[kHandle] = handle;
  }
}

class SlidingWindowHistogram {
  constructor(skipThrowSymbol = undefined) {
    if (skipThrowSymbol !== kSkipThrow) {
      throw new ERR_ILLEGAL_CONSTRUCTOR();
    }
  }

  /**
   * @param {number|bigint} val
   * @returns {void}
   */
  record(val) {
    if (this[kSlidingWindowHandle] === undefined)
      throw new ERR_INVALID_THIS('SlidingWindowHistogram');
    if (typeof val === 'bigint') {
      this[kSlidingWindowHandle].record(val);
      return;
    }

    validateInteger(val, 'val', 0);
    this[kSlidingWindowHandle].record(val);
  }

  /**
   * @returns {Histogram}
   */
  snapshot() {
    if (this[kSlidingWindowHandle] === undefined)
      throw new ERR_INVALID_THIS('SlidingWindowHistogram');
    return new ClonedHistogram(this[kSlidingWindowHandle].snapshot());
  }

  /**
   * @returns {void}
   */
  reset() {
    if (this[kSlidingWindowHandle] === undefined)
      throw new ERR_INVALID_THIS('SlidingWindowHistogram');
    this[kSlidingWindowHandle].reset();
  }
}

function ClonedHistogram(handle) {
  const histogram = new Histogram(kSkipThrow);
  markTransferMode(histogram, true, false);
  histogram[kHandle] = handle;
  return histogram;
}

ClonedHistogram.prototype[kDeserialize] = () => { };

function ClonedRecordableHistogram(handle) {
  const histogram = new RecordableHistogram(kSkipThrow);

  markTransferMode(histogram, true, false);
  histogram[kRecordable] = true;
  histogram[kHandle] = handle;
  histogram.constructor = RecordableHistogram;

  return histogram;
}

ClonedRecordableHistogram.prototype[kDeserialize] = () => { };

function createRecordableHistogram(handle) {
  return new ClonedRecordableHistogram(handle);
}

function validateHistogramOptions(lowest, highest, figures) {
  if (typeof lowest !== 'bigint') {
    validateInteger(lowest, 'options.lowest', 1, NumberMAX_SAFE_INTEGER);
  } else if (lowest < 1n || lowest > kMaxInt64) {
    throw new ERR_OUT_OF_RANGE(
      'options.lowest', `>= 1n && <= ${kMaxInt64}n`, lowest);
  }

  if (typeof highest !== 'bigint') {
    validateInteger(highest, 'options.highest', 1, NumberMAX_SAFE_INTEGER);
  } else if (highest < 1n || highest > kMaxInt64) {
    throw new ERR_OUT_OF_RANGE(
      'options.highest', `>= 1n && <= ${kMaxInt64}n`, highest);
  }

  const minimumHighest = 2n *
    (typeof lowest === 'bigint' ? lowest : BigInt(lowest));
  const highestBigInt = typeof highest === 'bigint' ?
    highest : BigInt(highest);
  if (highestBigInt < minimumHighest) {
    throw new ERR_OUT_OF_RANGE(
      'options.highest', `>= 2 * options.lowest (${minimumHighest}n)`, highest);
  }
  validateInteger(figures, 'options.figures', 1, 5);
}

/**
 * @param {{
 *   lowest? : number,
 *   highest? : number,
 *   figures? : number,
 *   halfLife? : number,
 *   threshold? : number
 * }} [options]
 * @returns {RecordableHistogram}
 */
function createHistogram(options = kEmptyObject) {
  validateObject(options, 'options');
  const {
    lowest = 1,
    highest = NumberMAX_SAFE_INTEGER,
    figures = 3,
    halfLife = 0,
    threshold = 0,
  } = options;
  validateHistogramOptions(lowest, highest, figures);
  validateNumber(halfLife, 'options.halfLife');
  if (halfLife < 0)
    throw new ERR_OUT_OF_RANGE('options.halfLife', '>= 0', halfLife);
  validateNumber(threshold, 'options.threshold');
  if (threshold < 0)
    throw new ERR_OUT_OF_RANGE('options.threshold', '>= 0', threshold);
  return createRecordableHistogram(
    new _Histogram(lowest, highest, figures, halfLife, threshold));
}

/**
 * @param {{
 *   chunks: number,
 *   chunkDuration? : number,
 *   recordsPerChunk? : number,
 *   lowest? : number|bigint,
 *   highest? : number|bigint,
 *   figures? : number,
 * }} options
 * @returns {SlidingWindowHistogram}
 */
function createSlidingWindowHistogram(options) {
  validateObject(options, 'options');
  const {
    chunks,
    chunkDuration,
    recordsPerChunk,
    lowest = 1,
    highest = NumberMAX_SAFE_INTEGER,
    figures = 3,
  } = options;

  validateInteger(
    chunks, 'options.chunks', 1, kMaxSlidingWindowHistogramChunks);
  validateHistogramOptions(lowest, highest, figures);

  const timeBased = chunkDuration !== undefined;
  if (timeBased === (recordsPerChunk !== undefined)) {
    throw new ERR_INVALID_ARG_VALUE(
      'options', options,
      'must specify exactly one of "chunkDuration" or "recordsPerChunk"');
  }

  let rotateAt;
  if (timeBased) {
    validateInteger(
      chunkDuration, 'options.chunkDuration', 1, kMaxChunkDuration);
    rotateAt = BigInt(chunkDuration) * 1_000_000n;
  } else {
    validateInteger(
      recordsPerChunk, 'options.recordsPerChunk', 1, NumberMAX_SAFE_INTEGER);
    rotateAt = BigInt(recordsPerChunk);
  }

  const histogram = new SlidingWindowHistogram(kSkipThrow);
  markTransferMode(histogram, false, false);
  histogram[kSlidingWindowHandle] = new _SlidingWindowHistogram(
    lowest, highest, figures, chunks, timeBased, rotateAt);
  return histogram;
}

/**
 * Reconstructs a histogram from a CBOR-encoded Uint8Array previously
 * produced by `histogram.export()`.
 * @param {Uint8Array} data
 * @returns {RecordableHistogram}
 */
function importHistogram(data) {
  if (!isUint8Array(data))
    throw new ERR_INVALID_ARG_TYPE('data', 'Uint8Array', data);
  return createRecordableHistogram(_Histogram.import(data));
}

module.exports = {
  Histogram,
  RecordableHistogram,
  SlidingWindowHistogram,
  ClonedHistogram,
  ClonedRecordableHistogram,
  isHistogram,
  kDestroy,
  kHandle,
  kMaxInt64,
  kSkipThrow,
  createHistogram,
  createSlidingWindowHistogram,
  importHistogram,
  validateHistogramOptions,
};