docs: add JSDoc to functions (#69)

Author: RafaelGSS

lib/histogram.js

@@ -1,5 +1,10 @@
 const { validateNumber } = require("./validators");
 
+/**
+ * A class that calculates and maintains statistical measurements for a set of numeric samples.
+ * Handles outlier removal, and calculates various statistical measures like mean, standard deviation,
+ * coefficient of variation, and percentiles.
+ */
 class StatisticalHistogram {
 	all = [];
 	min;

lib/lifecycle.js

@@ -31,6 +31,11 @@ function parsePluginsResult(plugins, name) {
 	return result;
 }
 
+/**
+ * Calculates and returns the initial number of iterations for a benchmark
+ * @param {import('./index').Benchmark} bench - The benchmark object to be executed
+ * @returns {Promise<number>} The calculated number of initial iterations
+ */
 async function getInitialIterations(bench) {
 	const { 0: duration, 1: realIterations } = await clockBenchmark(bench, 30);
 
@@ -49,6 +54,15 @@ async function getInitialIterations(bench) {
 	return getItersForOpDuration(durationPerOp, bench.minTime);
 }
 
+/**
+ * Executes the warmup phase of a benchmark
+ * @param {import('./index').Benchmark} bench - The benchmark object to be executed
+ * @param {number} initialIterations - The initial number of iterations to run
+ * @param {Object} options - Warmup options
+ * @param {number} [options.minTime] - Minimum time for warmup, defaults to bench.minTime
+ * @param {number} [options.maxTime] - Maximum time for warmup, defaults to bench.minTime
+ * @returns {Promise<void>}
+ */
 async function runWarmup(bench, initialIterations, { minTime, maxTime }) {
 	minTime = minTime ?? bench.minTime;
 	maxTime = maxTime ?? bench.minTime;
@@ -114,6 +128,14 @@ async function runBenchmarkOnce(
 	return { iterations, timeSpent };
 }
 
+/**
+ * Executes a benchmark with the specified parameters
+ * @param {import('./index').Benchmark} bench - The benchmark object to be executed
+ * @param {number} initialIterations - The initial number of iterations to run
+ * @param {number} repeatSuite - Number of times to repeat the benchmark suite
+ * @param {number} minSamples - Minimum number of samples to collect
+ * @returns {Promise<Object>} The benchmark results containing operations per second, iterations, histogram data and plugin results
+ */
 async function runBenchmark(bench, initialIterations, repeatSuite, minSamples) {
 	const histogram = new StatisticalHistogram();
 

lib/plugins.js

@@ -6,6 +6,12 @@ const { MemoryPlugin } = require("./plugins/memory");
 
 const { validateFunction, validateArray } = require("./validators");
 
+/**
+ * Validates that all plugins in the array implement the required plugin interface
+ * and that they are supported in the current environment
+ * @param {Array<Object>} plugins - Array of plugin objects to validate
+ * @throws {Error} If any plugin doesn't meet the requirements or isn't supported
+ */
 function validatePlugins(plugins) {
 	for (p of plugins) {
 		validateFunction(p.isSupported, "Plugins must have a isSupported method.");

lib/plugins/memory.js

@@ -4,6 +4,11 @@ const {
 	kStatisticalHistogramFinish,
 } = require("../histogram");
 
+/**
+ * Formats a byte value into a human-readable string with appropriate units (B, Kb, MB, GB)
+ * @param {number} bytes - The number of bytes to format
+ * @returns {string} Formatted string with appropriate unit suffix
+ */
 function formatBytes(bytes) {
 	if (bytes < 1024) return `${Math.round(bytes)}B`;
 
@@ -17,6 +22,10 @@ function formatBytes(bytes) {
 	return `${gbytes.toFixed(2)}GB`;
 }
 
+/**
+ * Plugin that measures memory usage during benchmark execution
+ * Collects heap usage statistics and provides reporting capabilities
+ */
 class MemoryPlugin {
 	static MEMORY_BEFORE_RUN = "memoryBeforeRun";
 	static MEMORY_AFTER_RUN = "memoryAfterRun";

lib/report.js

@@ -4,6 +4,24 @@ const { htmlReport } = require("./reporter/html");
 const { jsonReport } = require("./reporter/json");
 const { csvReport } = require("./reporter/csv");
 
+/**
+ * @typedef {Object} BenchmarkResult
+ * @property {string} name - The name of the benchmark
+ * @property {number} opsSec - Operations per second
+ * @property {number} iterations - Total number of iterations run
+ * @property {Object} histogram - Statistical data about the benchmark runs
+ * @property {Array} plugins - Results from plugins used during benchmarking
+ */
+
+/**
+ * Exports various report generators for benchmark results
+ * @type {Object}
+ * @property {function(BenchmarkResult[]): void} chartReport - Generates a chart visualization of benchmark results
+ * @property {function(BenchmarkResult[]): void} textReport - Generates a text report of benchmark results
+ * @property {function(BenchmarkResult[]): void} htmlReport - Generates an HTML report of benchmark results
+ * @property {function(BenchmarkResult[]): string} jsonReport - Generates a JSON report of benchmark results
+ * @property {function(BenchmarkResult[]): string} csvReport - Generates a CSV report of benchmark results
+ */
 module.exports = {
 	chartReport,
 	textReport,

lib/reporter/chart.js

@@ -6,6 +6,14 @@ const formatter = Intl.NumberFormat(undefined, {
 	maximumFractionDigits: 2,
 });
 
+/**
+ * Draws a bar chart representation of a benchmark result
+ * @param {string} label - The label for the bar (benchmark name)
+ * @param {number} value - The value to display (operations per second)
+ * @param {number} total - The maximum value in the dataset (for scaling)
+ * @param {number} samples - Number of samples collected
+ * @param {number} [length=30] - Length of the bar in characters
+ */
 function drawBar(label, value, total, samples, length = 30) {
 	const percentage = value / total;
 	const filledLength = Math.round(length * percentage);
@@ -29,6 +37,11 @@ const environment = {
 	hardware: `${cpus().length} vCPUs | ${(totalmem() / 1024 ** 3).toFixed(1)}GB Mem`,
 };
 
+/**
+ * Generates a chart visualization of benchmark results in the console
+ * Displays system information and a bar chart of operations per second
+ * @param {import('../report').BenchmarkResult[]} results - Array of benchmark results
+ */
 function chartReport(results) {
 	const maxOpsSec = Math.max(...results.map((b) => b.opsSec));
 

lib/reporter/text.js

@@ -6,6 +6,11 @@ const formatter = Intl.NumberFormat(undefined, {
 	maximumFractionDigits: 2,
 });
 
+/**
+ * Generates a text report of benchmark results, displaying each benchmark's name,
+ * operations per second, number of samples, plugin results, and min/max timings
+ * @param {import('../report').BenchmarkResult[]} results - Array of benchmark results
+ */
 function textReport(results) {
 	for (const result of results) {
 		const opsSecReported =

lib/validators.js

@@ -1,15 +1,33 @@
+/**
+ * Creates an error object with ERR_INVALID_ARG_TYPE code
+ * @param {string} message - The error message
+ * @returns {Error} Error with code ERR_INVALID_ARG_TYPE
+ */
 function ERR_INVALID_ARG_TYPE(message) {
 	const err = new Error(message);
 	err.code = "ERR_INVALID_ARG_TYPE";
 	return err;
 }
 
+/**
+ * Creates an error object with ERR_INVALID_ARG_VALUE code
+ * @param {string} message - The error message
+ * @returns {Error} Error with code ERR_INVALID_ARG_VALUE
+ */
 function ERR_INVALID_ARG_VALUE(message) {
 	const err = new Error(message);
 	err.code = "ERR_INVALID_ARG_VALUE";
 	return err;
 }
 
+/**
+ * Validates that a value is a number within an optional range
+ * @param {any} value - The value to validate
+ * @param {string} name - Name of the parameter being validated
+ * @param {number} [min] - Optional minimum value (inclusive)
+ * @param {number} [max] - Optional maximum value (inclusive)
+ * @throws {Error} If validation fails
+ */
 function validateNumber(value, name, min, max) {
 	if (typeof value !== "number")
 		throw ERR_INVALID_ARG_TYPE(
@@ -27,6 +45,12 @@ function validateNumber(value, name, min, max) {
 	}
 }
 
+/**
+ * Validates that a value is an object (not null and not an array)
+ * @param {any} value - The value to validate
+ * @param {string} name - Name of the parameter being validated
+ * @throws {Error} If validation fails
+ */
 function validateObject(value, name) {
 	if (value === null || Array.isArray(value)) {
 		throw ERR_INVALID_ARG_TYPE(
@@ -41,20 +65,38 @@ function validateObject(value, name) {
 	}
 }
 
+/**
+ * Validates that a value is a function
+ * @param {any} value - The value to validate
+ * @param {string} name - Name of the parameter being validated
+ * @throws {Error} If validation fails
+ */
 function validateFunction(value, name) {
 	if (typeof value !== "function")
 		throw ERR_INVALID_ARG_TYPE(
 			`value must be a function, name: ${name}, value: ${value}`,
 		);
 }
 
+/**
+ * Validates that a value is a string
+ * @param {any} value - The value to validate
+ * @param {string} name - Name of the parameter being validated
+ * @throws {Error} If validation fails
+ */
 function validateString(value, name) {
 	if (typeof value !== "string")
 		throw ERR_INVALID_ARG_TYPE(
 			`value must be a string, name: ${name}, value: ${value}`,
 		);
 }
 
+/**
+ * Validates that a value is an array
+ * @param {any} value - The value to validate
+ * @param {string} name - Name of the parameter being validated
+ * @throws {Error} If validation fails
+ */
 function validateArray(value, name) {
 	if (!Array.isArray(value))
 		throw ERR_INVALID_ARG_TYPE(