es-toolkit 1.50.0-dev.1991 → 1.50.0-dev.1992

package/bigint.d.ts

@@ -0,0 +1 @@
+export * from './dist/bigint';

package/bigint.js

@@ -0,0 +1 @@
+module.exports = require('./dist/bigint');

package/dist/_internal/bigIntRangeLength.js

@@ -0,0 +1,19 @@
+//#region src/_internal/bigIntRangeLength.ts
+/**
+* Calculates how many elements a bigint range from `start` (inclusive) to `end` (exclusive) contains.
+*
+* This mirrors `Math.ceil((end - start) / step)` from the `number` implementations, but performs the
+* ceiling division with bigint arithmetic. Returns `0` when `step` points away from `end`.
+*
+* @param start - The start of the range.
+* @param end - The end of the range.
+* @param step - A non-zero step value.
+* @returns The number of elements in the range.
+*/
+function bigIntRangeLength(start, end, step) {
+	const difference = end - start;
+	if (step > 0n) return difference <= 0n ? 0 : Number((difference + step - 1n) / step);
+	return difference >= 0n ? 0 : Number((difference + step + 1n) / step);
+}
+//#endregion
+exports.bigIntRangeLength = bigIntRangeLength;

package/dist/_internal/bigIntRangeLength.mjs

@@ -0,0 +1,19 @@
+//#region src/_internal/bigIntRangeLength.ts
+/**
+* Calculates how many elements a bigint range from `start` (inclusive) to `end` (exclusive) contains.
+*
+* This mirrors `Math.ceil((end - start) / step)` from the `number` implementations, but performs the
+* ceiling division with bigint arithmetic. Returns `0` when `step` points away from `end`.
+*
+* @param start - The start of the range.
+* @param end - The end of the range.
+* @param step - A non-zero step value.
+* @returns The number of elements in the range.
+*/
+function bigIntRangeLength(start, end, step) {
+	const difference = end - start;
+	if (step > 0n) return difference <= 0n ? 0 : Number((difference + step - 1n) / step);
+	return difference >= 0n ? 0 : Number((difference + step + 1n) / step);
+}
+//#endregion
+export { bigIntRangeLength };

package/dist/bigint/clamp.d.mts

@@ -0,0 +1,37 @@
+//#region src/bigint/clamp.d.ts
+/**
+ * Clamps a bigint within the inclusive lower and upper bounds.
+ *
+ * This function takes a bigint and returns it constrained to the given range. Unlike `Math.min` and
+ * `Math.max`, which cannot accept bigints, it compares values directly so large integers stay exact.
+ *
+ * @param value - The bigint to clamp.
+ * @param maximum - The upper bound to clamp to.
+ * @returns The clamped bigint.
+ *
+ * @example
+ * const result = clamp(10n, 5n);
+ * // result will be 5n, because 10n is greater than the maximum
+ */
+declare function clamp(value: bigint, maximum: bigint): bigint;
+/**
+ * Clamps a bigint within the inclusive lower and upper bounds.
+ *
+ * This function takes a bigint and returns it constrained to the given range. Unlike `Math.min` and
+ * `Math.max`, which cannot accept bigints, it compares values directly so large integers stay exact.
+ *
+ * @param value - The bigint to clamp.
+ * @param minimum - The lower bound to clamp to.
+ * @param maximum - The upper bound to clamp to.
+ * @returns The clamped bigint.
+ *
+ * @example
+ * const result = clamp(10n, 0n, 5n);
+ * // result will be 5n, because 10n is greater than the maximum
+ *
+ * const result2 = clamp(-10n, 0n, 5n);
+ * // result2 will be 0n, because -10n is less than the minimum
+ */
+declare function clamp(value: bigint, minimum: bigint, maximum: bigint): bigint;
+//#endregion
+export { clamp };

package/dist/bigint/clamp.d.ts

@@ -0,0 +1,37 @@
+//#region src/bigint/clamp.d.ts
+/**
+ * Clamps a bigint within the inclusive lower and upper bounds.
+ *
+ * This function takes a bigint and returns it constrained to the given range. Unlike `Math.min` and
+ * `Math.max`, which cannot accept bigints, it compares values directly so large integers stay exact.
+ *
+ * @param value - The bigint to clamp.
+ * @param maximum - The upper bound to clamp to.
+ * @returns The clamped bigint.
+ *
+ * @example
+ * const result = clamp(10n, 5n);
+ * // result will be 5n, because 10n is greater than the maximum
+ */
+declare function clamp(value: bigint, maximum: bigint): bigint;
+/**
+ * Clamps a bigint within the inclusive lower and upper bounds.
+ *
+ * This function takes a bigint and returns it constrained to the given range. Unlike `Math.min` and
+ * `Math.max`, which cannot accept bigints, it compares values directly so large integers stay exact.
+ *
+ * @param value - The bigint to clamp.
+ * @param minimum - The lower bound to clamp to.
+ * @param maximum - The upper bound to clamp to.
+ * @returns The clamped bigint.
+ *
+ * @example
+ * const result = clamp(10n, 0n, 5n);
+ * // result will be 5n, because 10n is greater than the maximum
+ *
+ * const result2 = clamp(-10n, 0n, 5n);
+ * // result2 will be 0n, because -10n is less than the minimum
+ */
+declare function clamp(value: bigint, minimum: bigint, maximum: bigint): bigint;
+//#endregion
+export { clamp };

package/dist/bigint/clamp.js

@@ -0,0 +1,16 @@
+//#region src/bigint/clamp.ts
+/**
+* Clamps a bigint within the inclusive lower and upper bounds.
+*
+* @param value - The bigint to clamp.
+* @param bound1 - The upper bound when called with two arguments, otherwise the lower bound.
+* @param bound2 - The upper bound when called with three arguments.
+* @returns The clamped bigint.
+*/
+function clamp(value, bound1, bound2) {
+	if (bound2 == null) return value < bound1 ? value : bound1;
+	const lowerClamped = value > bound1 ? value : bound1;
+	return lowerClamped < bound2 ? lowerClamped : bound2;
+}
+//#endregion
+exports.clamp = clamp;

package/dist/bigint/clamp.mjs

@@ -0,0 +1,16 @@
+//#region src/bigint/clamp.ts
+/**
+* Clamps a bigint within the inclusive lower and upper bounds.
+*
+* @param value - The bigint to clamp.
+* @param bound1 - The upper bound when called with two arguments, otherwise the lower bound.
+* @param bound2 - The upper bound when called with three arguments.
+* @returns The clamped bigint.
+*/
+function clamp(value, bound1, bound2) {
+	if (bound2 == null) return value < bound1 ? value : bound1;
+	const lowerClamped = value > bound1 ? value : bound1;
+	return lowerClamped < bound2 ? lowerClamped : bound2;
+}
+//#endregion
+export { clamp };

package/dist/bigint/inRange.d.mts

@@ -0,0 +1,37 @@
+//#region src/bigint/inRange.d.ts
+/**
+ * Checks whether a bigint is within a range.
+ *
+ * The lower bound is inclusive and the upper bound is exclusive, so `inRange(5n, 0n, 5n)` is `false`.
+ *
+ * @param value - The bigint to check.
+ * @param maximum - The exclusive upper bound. The lower bound defaults to `0n`.
+ * @returns `true` if the bigint is within the range, `false` otherwise.
+ * @throws {Error} If the minimum is greater than or equal to the maximum.
+ *
+ * @example
+ * const result = inRange(3n, 5n);
+ * // result will be true, because 3n is within [0n, 5n)
+ */
+declare function inRange(value: bigint, maximum: bigint): boolean;
+/**
+ * Checks whether a bigint is within a range.
+ *
+ * The lower bound is inclusive and the upper bound is exclusive, so `inRange(5n, 0n, 5n)` is `false`.
+ *
+ * @param value - The bigint to check.
+ * @param minimum - The inclusive lower bound.
+ * @param maximum - The exclusive upper bound.
+ * @returns `true` if the bigint is within the range, `false` otherwise.
+ * @throws {Error} If the minimum is greater than or equal to the maximum.
+ *
+ * @example
+ * const result = inRange(5n, 0n, 10n);
+ * // result will be true
+ *
+ * const result2 = inRange(10n, 0n, 10n);
+ * // result2 will be false, because the upper bound is exclusive
+ */
+declare function inRange(value: bigint, minimum: bigint, maximum: bigint): boolean;
+//#endregion
+export { inRange };

package/dist/bigint/inRange.d.ts

@@ -0,0 +1,37 @@
+//#region src/bigint/inRange.d.ts
+/**
+ * Checks whether a bigint is within a range.
+ *
+ * The lower bound is inclusive and the upper bound is exclusive, so `inRange(5n, 0n, 5n)` is `false`.
+ *
+ * @param value - The bigint to check.
+ * @param maximum - The exclusive upper bound. The lower bound defaults to `0n`.
+ * @returns `true` if the bigint is within the range, `false` otherwise.
+ * @throws {Error} If the minimum is greater than or equal to the maximum.
+ *
+ * @example
+ * const result = inRange(3n, 5n);
+ * // result will be true, because 3n is within [0n, 5n)
+ */
+declare function inRange(value: bigint, maximum: bigint): boolean;
+/**
+ * Checks whether a bigint is within a range.
+ *
+ * The lower bound is inclusive and the upper bound is exclusive, so `inRange(5n, 0n, 5n)` is `false`.
+ *
+ * @param value - The bigint to check.
+ * @param minimum - The inclusive lower bound.
+ * @param maximum - The exclusive upper bound.
+ * @returns `true` if the bigint is within the range, `false` otherwise.
+ * @throws {Error} If the minimum is greater than or equal to the maximum.
+ *
+ * @example
+ * const result = inRange(5n, 0n, 10n);
+ * // result will be true
+ *
+ * const result2 = inRange(10n, 0n, 10n);
+ * // result2 will be false, because the upper bound is exclusive
+ */
+declare function inRange(value: bigint, minimum: bigint, maximum: bigint): boolean;
+//#endregion
+export { inRange };

package/dist/bigint/inRange.js

@@ -0,0 +1,20 @@
+//#region src/bigint/inRange.ts
+/**
+* Checks whether a bigint is within a range.
+*
+* @param value - The bigint to check.
+* @param minimum - The exclusive upper bound when called with two arguments, otherwise the inclusive lower bound.
+* @param maximum - The exclusive upper bound when called with three arguments.
+* @returns `true` if the bigint is within the range, `false` otherwise.
+* @throws {Error} If the minimum is greater than or equal to the maximum.
+*/
+function inRange(value, minimum, maximum) {
+	if (maximum == null) {
+		maximum = minimum;
+		minimum = 0n;
+	}
+	if (minimum >= maximum) throw new Error("The maximum value must be greater than the minimum value.");
+	return minimum <= value && value < maximum;
+}
+//#endregion
+exports.inRange = inRange;

package/dist/bigint/inRange.mjs

@@ -0,0 +1,20 @@
+//#region src/bigint/inRange.ts
+/**
+* Checks whether a bigint is within a range.
+*
+* @param value - The bigint to check.
+* @param minimum - The exclusive upper bound when called with two arguments, otherwise the inclusive lower bound.
+* @param maximum - The exclusive upper bound when called with three arguments.
+* @returns `true` if the bigint is within the range, `false` otherwise.
+* @throws {Error} If the minimum is greater than or equal to the maximum.
+*/
+function inRange(value, minimum, maximum) {
+	if (maximum == null) {
+		maximum = minimum;
+		minimum = 0n;
+	}
+	if (minimum >= maximum) throw new Error("The maximum value must be greater than the minimum value.");
+	return minimum <= value && value < maximum;
+}
+//#endregion
+export { inRange };

package/dist/bigint/index.d.mts

@@ -0,0 +1,14 @@
+import { clamp } from "./clamp.mjs";
+import { inRange } from "./inRange.mjs";
+import { max } from "./max.mjs";
+import { maxBy } from "./maxBy.mjs";
+import { median } from "./median.mjs";
+import { medianBy } from "./medianBy.mjs";
+import { min } from "./min.mjs";
+import { minBy } from "./minBy.mjs";
+import { percentile } from "./percentile.mjs";
+import { range } from "./range.mjs";
+import { rangeRight } from "./rangeRight.mjs";
+import { sum } from "./sum.mjs";
+import { sumBy } from "./sumBy.mjs";
+export { clamp, inRange, max, maxBy, median, medianBy, min, minBy, percentile, range, rangeRight, sum, sumBy };

package/dist/bigint/index.d.ts

@@ -0,0 +1,14 @@
+import { clamp } from "./clamp.js";
+import { inRange } from "./inRange.js";
+import { max } from "./max.js";
+import { maxBy } from "./maxBy.js";
+import { median } from "./median.js";
+import { medianBy } from "./medianBy.js";
+import { min } from "./min.js";
+import { minBy } from "./minBy.js";
+import { percentile } from "./percentile.js";
+import { range } from "./range.js";
+import { rangeRight } from "./rangeRight.js";
+import { sum } from "./sum.js";
+import { sumBy } from "./sumBy.js";
+export { clamp, inRange, max, maxBy, median, medianBy, min, minBy, percentile, range, rangeRight, sum, sumBy };

package/dist/bigint/index.js

@@ -0,0 +1,27 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_clamp = require("./clamp.js");
+const require_inRange = require("./inRange.js");
+const require_max = require("./max.js");
+const require_maxBy = require("./maxBy.js");
+const require_median = require("./median.js");
+const require_medianBy = require("./medianBy.js");
+const require_min = require("./min.js");
+const require_minBy = require("./minBy.js");
+const require_percentile = require("./percentile.js");
+const require_range = require("./range.js");
+const require_rangeRight = require("./rangeRight.js");
+const require_sum = require("./sum.js");
+const require_sumBy = require("./sumBy.js");
+exports.clamp = require_clamp.clamp;
+exports.inRange = require_inRange.inRange;
+exports.max = require_max.max;
+exports.maxBy = require_maxBy.maxBy;
+exports.median = require_median.median;
+exports.medianBy = require_medianBy.medianBy;
+exports.min = require_min.min;
+exports.minBy = require_minBy.minBy;
+exports.percentile = require_percentile.percentile;
+exports.range = require_range.range;
+exports.rangeRight = require_rangeRight.rangeRight;
+exports.sum = require_sum.sum;
+exports.sumBy = require_sumBy.sumBy;

package/dist/bigint/index.mjs

@@ -0,0 +1,14 @@
+import { clamp } from "./clamp.mjs";
+import { inRange } from "./inRange.mjs";
+import { max } from "./max.mjs";
+import { maxBy } from "./maxBy.mjs";
+import { median } from "./median.mjs";
+import { medianBy } from "./medianBy.mjs";
+import { min } from "./min.mjs";
+import { minBy } from "./minBy.mjs";
+import { percentile } from "./percentile.mjs";
+import { range } from "./range.mjs";
+import { rangeRight } from "./rangeRight.mjs";
+import { sum } from "./sum.mjs";
+import { sumBy } from "./sumBy.mjs";
+export { clamp, inRange, max, maxBy, median, medianBy, min, minBy, percentile, range, rangeRight, sum, sumBy };

package/dist/bigint/max.d.mts

@@ -0,0 +1,21 @@
+//#region src/bigint/max.d.ts
+/**
+ * Finds the largest bigint in an array.
+ *
+ * This function iterates through the array and returns the largest element. Unlike `Math.max`,
+ * which cannot accept bigints, it compares values directly so arbitrarily large integers stay exact.
+ *
+ * @param nums - An array of bigints to search.
+ * @returns The largest bigint in the array.
+ * @throws {RangeError} If the array is empty, since there is no bigint that represents "no maximum".
+ *
+ * @example
+ * const result = max([1n, 5n, 3n]);
+ * // result will be 5n
+ *
+ * const huge = max([9007199254740993n, 9007199254740992n]);
+ * // huge will be 9007199254740993n, a value `Math.max` cannot distinguish
+ */
+declare function max(nums: readonly bigint[]): bigint;
+//#endregion
+export { max };

package/dist/bigint/max.d.ts

@@ -0,0 +1,21 @@
+//#region src/bigint/max.d.ts
+/**
+ * Finds the largest bigint in an array.
+ *
+ * This function iterates through the array and returns the largest element. Unlike `Math.max`,
+ * which cannot accept bigints, it compares values directly so arbitrarily large integers stay exact.
+ *
+ * @param nums - An array of bigints to search.
+ * @returns The largest bigint in the array.
+ * @throws {RangeError} If the array is empty, since there is no bigint that represents "no maximum".
+ *
+ * @example
+ * const result = max([1n, 5n, 3n]);
+ * // result will be 5n
+ *
+ * const huge = max([9007199254740993n, 9007199254740992n]);
+ * // huge will be 9007199254740993n, a value `Math.max` cannot distinguish
+ */
+declare function max(nums: readonly bigint[]): bigint;
+//#endregion
+export { max };

package/dist/bigint/max.js

@@ -0,0 +1,26 @@
+//#region src/bigint/max.ts
+/**
+* Finds the largest bigint in an array.
+*
+* This function iterates through the array and returns the largest element. Unlike `Math.max`,
+* which cannot accept bigints, it compares values directly so arbitrarily large integers stay exact.
+*
+* @param nums - An array of bigints to search.
+* @returns The largest bigint in the array.
+* @throws {RangeError} If the array is empty, since there is no bigint that represents "no maximum".
+*
+* @example
+* const result = max([1n, 5n, 3n]);
+* // result will be 5n
+*
+* const huge = max([9007199254740993n, 9007199254740992n]);
+* // huge will be 9007199254740993n, a value `Math.max` cannot distinguish
+*/
+function max(nums) {
+	if (nums.length === 0) throw new RangeError("Cannot find the maximum of an empty array.");
+	let result = nums[0];
+	for (let i = 1; i < nums.length; i++) if (nums[i] > result) result = nums[i];
+	return result;
+}
+//#endregion
+exports.max = max;

package/dist/bigint/max.mjs

@@ -0,0 +1,26 @@
+//#region src/bigint/max.ts
+/**
+* Finds the largest bigint in an array.
+*
+* This function iterates through the array and returns the largest element. Unlike `Math.max`,
+* which cannot accept bigints, it compares values directly so arbitrarily large integers stay exact.
+*
+* @param nums - An array of bigints to search.
+* @returns The largest bigint in the array.
+* @throws {RangeError} If the array is empty, since there is no bigint that represents "no maximum".
+*
+* @example
+* const result = max([1n, 5n, 3n]);
+* // result will be 5n
+*
+* const huge = max([9007199254740993n, 9007199254740992n]);
+* // huge will be 9007199254740993n, a value `Math.max` cannot distinguish
+*/
+function max(nums) {
+	if (nums.length === 0) throw new RangeError("Cannot find the maximum of an empty array.");
+	let result = nums[0];
+	for (let i = 1; i < nums.length; i++) if (nums[i] > result) result = nums[i];
+	return result;
+}
+//#endregion
+export { max };

package/dist/bigint/maxBy.d.mts

@@ -0,0 +1,21 @@
+//#region src/bigint/maxBy.d.ts
+/**
+ * Finds the element in an array that has the largest bigint value returned by `getValue`.
+ *
+ * This function maps every element to a bigint and returns the element with the largest value.
+ * If several elements tie, the first one is returned.
+ *
+ * @template T - The type of elements in the array.
+ * @param items - An array of elements to search.
+ * @param getValue - A function that maps an element to the bigint to compare by.
+ * @returns The element with the largest mapped bigint.
+ * @throws {RangeError} If the array is empty, since there is no element to return.
+ *
+ * @example
+ * const accounts = [{ balance: 10n }, { balance: 30n }, { balance: 20n }];
+ * const result = maxBy(accounts, account => account.balance);
+ * // result will be { balance: 30n }
+ */
+declare function maxBy<T>(items: readonly T[], getValue: (element: T, index: number, array: readonly T[]) => bigint): T;
+//#endregion
+export { maxBy };

package/dist/bigint/maxBy.d.ts

@@ -0,0 +1,21 @@
+//#region src/bigint/maxBy.d.ts
+/**
+ * Finds the element in an array that has the largest bigint value returned by `getValue`.
+ *
+ * This function maps every element to a bigint and returns the element with the largest value.
+ * If several elements tie, the first one is returned.
+ *
+ * @template T - The type of elements in the array.
+ * @param items - An array of elements to search.
+ * @param getValue - A function that maps an element to the bigint to compare by.
+ * @returns The element with the largest mapped bigint.
+ * @throws {RangeError} If the array is empty, since there is no element to return.
+ *
+ * @example
+ * const accounts = [{ balance: 10n }, { balance: 30n }, { balance: 20n }];
+ * const result = maxBy(accounts, account => account.balance);
+ * // result will be { balance: 30n }
+ */
+declare function maxBy<T>(items: readonly T[], getValue: (element: T, index: number, array: readonly T[]) => bigint): T;
+//#endregion
+export { maxBy };

package/dist/bigint/maxBy.js

@@ -0,0 +1,34 @@
+//#region src/bigint/maxBy.ts
+/**
+* Finds the element in an array that has the largest bigint value returned by `getValue`.
+*
+* This function maps every element to a bigint and returns the element with the largest value.
+* If several elements tie, the first one is returned.
+*
+* @template T - The type of elements in the array.
+* @param items - An array of elements to search.
+* @param getValue - A function that maps an element to the bigint to compare by.
+* @returns The element with the largest mapped bigint.
+* @throws {RangeError} If the array is empty, since there is no element to return.
+*
+* @example
+* const accounts = [{ balance: 10n }, { balance: 30n }, { balance: 20n }];
+* const result = maxBy(accounts, account => account.balance);
+* // result will be { balance: 30n }
+*/
+function maxBy(items, getValue) {
+	if (items.length === 0) throw new RangeError("Cannot find the maximum of an empty array.");
+	let maxElement = items[0];
+	let max = getValue(items[0], 0, items);
+	for (let i = 1; i < items.length; i++) {
+		const element = items[i];
+		const value = getValue(element, i, items);
+		if (value > max) {
+			max = value;
+			maxElement = element;
+		}
+	}
+	return maxElement;
+}
+//#endregion
+exports.maxBy = maxBy;

package/dist/bigint/maxBy.mjs

@@ -0,0 +1,34 @@
+//#region src/bigint/maxBy.ts
+/**
+* Finds the element in an array that has the largest bigint value returned by `getValue`.
+*
+* This function maps every element to a bigint and returns the element with the largest value.
+* If several elements tie, the first one is returned.
+*
+* @template T - The type of elements in the array.
+* @param items - An array of elements to search.
+* @param getValue - A function that maps an element to the bigint to compare by.
+* @returns The element with the largest mapped bigint.
+* @throws {RangeError} If the array is empty, since there is no element to return.
+*
+* @example
+* const accounts = [{ balance: 10n }, { balance: 30n }, { balance: 20n }];
+* const result = maxBy(accounts, account => account.balance);
+* // result will be { balance: 30n }
+*/
+function maxBy(items, getValue) {
+	if (items.length === 0) throw new RangeError("Cannot find the maximum of an empty array.");
+	let maxElement = items[0];
+	let max = getValue(items[0], 0, items);
+	for (let i = 1; i < items.length; i++) {
+		const element = items[i];
+		const value = getValue(element, i, items);
+		if (value > max) {
+			max = value;
+			maxElement = element;
+		}
+	}
+	return maxElement;
+}
+//#endregion
+export { maxBy };

package/dist/bigint/median.d.mts

@@ -0,0 +1,22 @@
+//#region src/bigint/median.d.ts
+/**
+ * Calculates the median of an array of bigints.
+ *
+ * The median is the middle value of a sorted array. When the array has an even number of elements,
+ * the two middle values are averaged. Because bigints have no fractional part, that average is
+ * truncated toward zero: `median([1n, 2n])` is `1n` and `median([-3n, -2n])` is `-2n`.
+ *
+ * @param nums - An array of bigints to calculate the median of.
+ * @returns The median of the array.
+ * @throws {RangeError} If the array is empty, since there is no bigint that represents "no median".
+ *
+ * @example
+ * const result = median([1n, 2n, 3n, 4n, 5n]);
+ * // result will be 3n
+ *
+ * const truncated = median([1n, 2n, 3n, 4n]);
+ * // truncated will be 2n, because (2n + 3n) / 2n truncates toward zero
+ */
+declare function median(nums: readonly bigint[]): bigint;
+//#endregion
+export { median };

package/dist/bigint/median.d.ts

@@ -0,0 +1,22 @@
+//#region src/bigint/median.d.ts
+/**
+ * Calculates the median of an array of bigints.
+ *
+ * The median is the middle value of a sorted array. When the array has an even number of elements,
+ * the two middle values are averaged. Because bigints have no fractional part, that average is
+ * truncated toward zero: `median([1n, 2n])` is `1n` and `median([-3n, -2n])` is `-2n`.
+ *
+ * @param nums - An array of bigints to calculate the median of.
+ * @returns The median of the array.
+ * @throws {RangeError} If the array is empty, since there is no bigint that represents "no median".
+ *
+ * @example
+ * const result = median([1n, 2n, 3n, 4n, 5n]);
+ * // result will be 3n
+ *
+ * const truncated = median([1n, 2n, 3n, 4n]);
+ * // truncated will be 2n, because (2n + 3n) / 2n truncates toward zero
+ */
+declare function median(nums: readonly bigint[]): bigint;
+//#endregion
+export { median };

package/dist/bigint/median.js

@@ -0,0 +1,28 @@
+//#region src/bigint/median.ts
+/**
+* Calculates the median of an array of bigints.
+*
+* The median is the middle value of a sorted array. When the array has an even number of elements,
+* the two middle values are averaged. Because bigints have no fractional part, that average is
+* truncated toward zero: `median([1n, 2n])` is `1n` and `median([-3n, -2n])` is `-2n`.
+*
+* @param nums - An array of bigints to calculate the median of.
+* @returns The median of the array.
+* @throws {RangeError} If the array is empty, since there is no bigint that represents "no median".
+*
+* @example
+* const result = median([1n, 2n, 3n, 4n, 5n]);
+* // result will be 3n
+*
+* const truncated = median([1n, 2n, 3n, 4n]);
+* // truncated will be 2n, because (2n + 3n) / 2n truncates toward zero
+*/
+function median(nums) {
+	if (nums.length === 0) throw new RangeError("Cannot compute the median of an empty array.");
+	const sorted = nums.slice().sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+	const middleIndex = Math.floor(sorted.length / 2);
+	if (sorted.length % 2 === 0) return (sorted[middleIndex - 1] + sorted[middleIndex]) / 2n;
+	return sorted[middleIndex];
+}
+//#endregion
+exports.median = median;