@fast-china/utils 2.0.0 → 2.0.2

package/src/number/index.ts

@@ -1,235 +0,0 @@
-const byteUnits = ["B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"] as const;
-const binaryByteUnits = ["B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "ZiB", "YiB"] as const;
-
-/** 安全随机整数延迟读取的平台全局对象最小视图。 */
-interface RuntimeNumberGlobals {
-	/** 可选 Web Crypto 随机填充能力；缺失时安全随机整数明确失败。 */
-	crypto?: Partial<Pick<Crypto, "getRandomValues">>;
-}
-
-const runtimeNumberGlobals = globalThis as unknown as RuntimeNumberGlobals;
-
-/** {@link formatBytes} 的格式化选项。 */
-export interface FormatBytesOptions {
-	/** 计量基数。`1000` 生成 SI 单位，`1024` 生成 IEC 单位；默认 `1024`。 */
-	base?: 1000 | 1024;
-	/** 小数位数，范围 0 至 20；默认 `2`。 */
-	decimals?: number;
-	/** `Intl.NumberFormat` 使用的语言；默认固定为 `en-US` 以保证输出稳定。 */
-	locale?: string | readonly string[];
-}
-
-/**
- * 拒绝 NaN，同时允许具体 API 自行决定是否接受 Infinity。
- *
- * @param value - 待校验数值。
- * @param name - 用于错误消息的参数名称。
- * @throws `RangeError` 当值为 NaN。
- */
-const assertNotNaN = (value: number, name: string): void => {
-	if (Number.isNaN(value)) throw new RangeError(`${name} cannot be NaN.`);
-};
-
-/**
- * 校验有限数值。
- *
- * @param value - 待校验数值。
- * @param name - 用于错误消息的参数名称。
- * @throws `RangeError` 当值为 NaN 或无穷大。
- */
-const assertFinite = (value: number, name: string): void => {
-	if (!Number.isFinite(value)) throw new RangeError(`${name} must be finite.`);
-};
-
-/**
- * 使用科学计数法移动十进制位。
- *
- * @remarks 该方式用于 `roundTo`，可减少直接乘除十次幂造成的额外二进制舍入误差。
- * @param value - 原始数值。
- * @param exponent - 十进制移动位数；正数向右移动。
- * @returns 移动后的数值。
- */
-const shiftDecimal = (value: number, exponent: number): number => {
-	if (Object.is(value, -0)) return -0;
-	const [coefficient = "0", currentExponent = "0"] = value.toString().split("e");
-	return Number(`${coefficient}e${Number(currentExponent) + exponent}`);
-};
-
-/**
- * 把数字限制在闭区间内。
- *
- * @param value - 需要限制的数字。
- * @param minimum - 闭区间下界。
- * @param maximum - 闭区间上界。
- * @returns `minimum <= result <= maximum` 的值。
- * @throws `RangeError` 当参数为 `NaN` 或下界大于上界。
- */
-export function clamp(value: number, minimum: number, maximum: number): number {
-	assertNotNaN(value, "value");
-	assertNotNaN(minimum, "minimum");
-	assertNotNaN(maximum, "maximum");
-	if (minimum > maximum) throw new RangeError("minimum cannot be greater than maximum.");
-	return Math.min(Math.max(value, minimum), maximum);
-}
-
-/**
- * 判断数字是否位于指定区间。
- *
- * @param value - 待检查数字。
- * @param minimum - 包含的下界。
- * @param maximum - 上界。
- * @param includeMaximum - 是否包含上界；默认使用半开区间 `[minimum, maximum)`。
- * @returns 数字满足区间边界时返回 `true`。
- * @throws `RangeError` 当参数为 `NaN` 或下界大于上界。
- */
-export function inRange(value: number, minimum: number, maximum: number, includeMaximum = false): boolean {
-	assertNotNaN(value, "value");
-	assertNotNaN(minimum, "minimum");
-	assertNotNaN(maximum, "maximum");
-	if (minimum > maximum) throw new RangeError("minimum cannot be greater than maximum.");
-	return value >= minimum && (includeMaximum ? value <= maximum : value < maximum);
-}
-
-/**
- * 按十进制位数四舍五入。
- *
- * @remarks IEEE-754 浮点数仍可能存在不可表示误差；财务金额应使用十进制定点方案。
- * @param value - 有限数字。
- * @param digits - 小数位数；负数表示十位、百位等，范围 -15 至 15。
- * @returns 按 `Math.round` 语义舍入后的数字。
- * @throws `RangeError` 当值非有限或位数超出范围。
- */
-export function roundTo(value: number, digits = 0): number {
-	assertFinite(value, "value");
-	if (!Number.isSafeInteger(digits) || digits < -15 || digits > 15) {
-		throw new RangeError("digits must be a safe integer between -15 and 15.");
-	}
-	const shifted = shiftDecimal(value, digits);
-	// 对已经没有可表示小数的大数，乘以 10^digits 可能溢出；此时舍入不会改变值。
-	if (!Number.isFinite(shifted)) return value;
-	return shiftDecimal(Math.round(shifted), -digits);
-}
-
-/**
- * 对有限数字求和。
- *
- * @param values - 不会被修改的数字数组。
- * @returns 算术和；空数组返回 `0`。
- * @throws `RangeError` 当任一值非有限或累计结果溢出。
- */
-export function sum(values: readonly number[]): number {
-	let total = 0;
-	let compensation = 0;
-	values.forEach((value) => {
-		assertFinite(value, "value");
-		// Kahan 补偿保存上一次浮点加法丢失的低位，减少大量小数累计误差。
-		const adjusted = value - compensation;
-		const next = total + adjusted;
-		if (!Number.isFinite(next)) throw new RangeError("The sum exceeds the finite number range.");
-		compensation = next - total - adjusted;
-		total = next;
-	});
-	return total;
-}
-
-/**
- * 计算有限数字的算术平均值。
- *
- * @param values - 不会被修改的数字数组。
- * @returns 空数组或只有稀疏空位的数组返回 `undefined`；空位不参与分母。
- * @throws `RangeError` 当任一值非有限。
- */
-export function average(values: readonly number[]): number | undefined {
-	let count = 0;
-	let mean = 0;
-	values.forEach((value) => {
-		assertFinite(value, "value");
-		count += 1;
-		// 加权增量形式避免先求和导致 MAX_VALUE + MAX_VALUE 溢出。
-		mean = mean * ((count - 1) / count) + value / count;
-	});
-	return count === 0 ? undefined : mean;
-}
-
-/**
- * 在两个数字间做线性插值。
- *
- * @remarks `amount` 不限制在 0 至 1；区间外的值会执行线性外推。
- * @param start - `amount = 0` 时的起点。
- * @param end - `amount = 1` 时的终点。
- * @param amount - 插值或外推比例。
- * @returns 线性计算结果。
- * @throws `RangeError` 当任一参数非有限或结果超出有限数字范围。
- */
-export function lerp(start: number, end: number, amount: number): number {
-	assertFinite(start, "start");
-	assertFinite(end, "end");
-	assertFinite(amount, "amount");
-	const result = start * (1 - amount) + end * amount;
-	if (!Number.isFinite(result)) throw new RangeError("The interpolation result exceeds the finite number range.");
-	return result;
-}
-
-/**
- * 将非负字节数格式化为 SI 或 IEC 单位。
- *
- * @param bytes - 非负有限字节数。
- * @param options - 基数、小数位和语言选项。
- * @returns 例如 `1.5 KiB`。
- * @throws `RangeError` 当字节数为负或非有限、基数不是 1000/1024、小数位非法，或 Locale 无效。
- */
-export function formatBytes(bytes: number, options: FormatBytesOptions = {}): string {
-	assertFinite(bytes, "bytes");
-	if (bytes < 0) throw new RangeError("bytes cannot be negative.");
-	const requestedBase: unknown = options.base ?? 1024;
-	if (requestedBase !== 1000 && requestedBase !== 1024) throw new RangeError("base must be 1000 or 1024.");
-	const base = requestedBase;
-	const decimals = options.decimals ?? 2;
-	if (!Number.isSafeInteger(decimals) || decimals < 0 || decimals > 20) {
-		throw new RangeError("decimals must be a safe integer between 0 and 20.");
-	}
-	if (bytes === 0) return "0 B";
-
-	const units = base === 1024 ? binaryByteUnits : byteUnits;
-	const exponent = Math.min(Math.floor(Math.log(bytes) / Math.log(base)), units.length - 1);
-	const value = bytes / base ** exponent;
-	const formatted = new Intl.NumberFormat(options.locale ?? "en-US", {
-		maximumFractionDigits: decimals,
-		minimumFractionDigits: 0,
-		useGrouping: false,
-	}).format(value);
-	return `${formatted} ${units[exponent] ?? units.at(-1)}`;
-}
-
-/**
- * 使用 Web Crypto 在半开区间内生成无偏安全随机整数。
- *
- * @param minimum - 包含的安全整数下界。
- * @param maximumExclusive - 不包含的安全整数上界；区间宽度最大为 2^32。
- * @returns 均匀分布在 `[minimum, maximumExclusive)` 的安全整数。
- * @throws 缺少 Web Crypto 时抛出 `Error`；参数非法时抛出 `RangeError`。
- */
-export function secureRandomInt(minimum: number, maximumExclusive: number): number {
-	if (!Number.isSafeInteger(minimum) || !Number.isSafeInteger(maximumExclusive)) {
-		throw new RangeError("minimum and maximumExclusive must be safe integers.");
-	}
-	const range = maximumExclusive - minimum;
-	const uint32Range = 0x1_0000_0000;
-	if (range <= 0 || range > uint32Range) {
-		throw new RangeError("The interval must be non-empty and no wider than 2^32.");
-	}
-	const crypto = runtimeNumberGlobals.crypto;
-	if (typeof crypto?.getRandomValues !== "function") {
-		throw new Error("Web Crypto random generation is unavailable in the current runtime.");
-	}
-
-	// 只接受可以被区间宽度整除的最大 2^32 前缀，消除取模偏差。
-	const limit = Math.floor(uint32Range / range) * range;
-	const values = new Uint32Array(1);
-	let sample: number;
-	do {
-		crypto.getRandomValues(values);
-		sample = values[0] ?? uint32Range;
-	} while (sample >= limit);
-	return minimum + (sample % range);
-}

package/src/object/index.ts

@@ -1,160 +0,0 @@
-/** URL 查询参数支持的单值类型。 */
-export type QueryPrimitive = bigint | boolean | number | string | null | undefined;
-
-/** URL 查询参数值；数组使用重复键表示。 */
-export type QueryValue = QueryPrimitive | readonly QueryPrimitive[];
-
-/**
- * 判断 Query Value 是否为重复参数数组。
- *
- * @param value - 单值或数组形式的 Query Value。
- * @returns 是只读原始值数组时返回 `true`。
- */
-const isQueryPrimitiveArray = (value: QueryValue): value is readonly QueryPrimitive[] => Array.isArray(value);
-
-/** {@link toQueryString} 的序列化选项。 */
-export interface QueryStringOptions {
-	/** 返回非空结果时是否添加 `?`；默认 `false`。 */
-	prefixQuestionMark?: boolean;
-	/** 是否按键的 UTF-16 码元顺序稳定排序；默认保留对象枚举顺序。 */
-	sort?: boolean;
-	/** 空格编码方式；默认遵循表单编码并输出 `+`。 */
-	space?: "percent" | "plus";
-}
-
-/**
- * 安全写入结果对象的自有可枚举属性。
- *
- * @remarks 使用 `defineProperty` 避免 `__proto__` 触发 Setter，并显式拒绝三个原型污染键。
- * @param target - 要写入的结果对象。
- * @param key - 自有属性键。
- * @param value - 属性值。
- * @throws `TypeError` 当键为 `__proto__`、`prototype` 或 `constructor`。
- */
-const defineEnumerableProperty = (target: object, key: PropertyKey, value: unknown): void => {
-	Object.defineProperty(target, key, { configurable: true, enumerable: true, value, writable: true });
-};
-
-/**
- * 判断值是否是普通对象。
- *
- * @param value - 任意待检查值。
- * @returns 原型为 `Object.prototype` 或 `null` 时返回 `true`。
- */
-export function isPlainObject(value: unknown): value is Record<PropertyKey, unknown> {
-	if (typeof value !== "object" || value === null) return false;
-	const prototype = Object.getPrototypeOf(value) as object | null;
-	return prototype === null || prototype === Object.prototype;
-}
-
-/**
- * 安全判断对象是否拥有自己的属性。
- *
- * @remarks 不调用可能被对象覆盖的 `hasOwnProperty`。
- * @param value - 待检查对象。
- * @param key - 字符串、数字或 Symbol 属性键。
- * @returns 属性为对象自有属性时返回 `true`，并收窄键类型。
- */
-export function hasOwn<ObjectType extends object, Key extends PropertyKey>(value: ObjectType, key: Key): key is Key & keyof ObjectType {
-	return Object.hasOwn(value, key);
-}
-
-/**
- * 从对象中选择指定自有可枚举属性。
- *
- * @param source - 不会被修改的源对象。
- * @param keys - 需要保留的键；不存在的键被忽略。
- * @returns 新对象，保持 `keys` 的遍历顺序。
- */
-export function pick<Source extends object, Keys extends readonly (keyof Source)[]>(source: Source, keys: Keys): Pick<Source, Keys[number]> {
-	const result = {} as Pick<Source, Keys[number]>;
-	for (const key of keys) {
-		if (Object.prototype.propertyIsEnumerable.call(source, key)) defineEnumerableProperty(result, key, source[key]);
-	}
-	return result;
-}
-
-/**
- * 浅复制对象并删除指定属性。
- *
- * @param source - 不会被修改的源对象。
- * @param keys - 需要排除的键。
- * @returns 包含其余自有可枚举字符串与 Symbol 属性的新对象。
- */
-export function omit<Source extends object, Keys extends readonly (keyof Source)[]>(source: Source, keys: Keys): Omit<Source, Keys[number]> {
-	const result = { ...source };
-	for (const key of keys) Reflect.deleteProperty(result, key);
-	return result;
-}
-
-/**
- * 映射对象的自有可枚举属性值。
- *
- * @param source - 不会被修改的源对象。
- * @param mapper - 接收值、键和源对象的映射函数。
- * @returns 保留原键的新对象。
- */
-export function mapValues<Source extends object, Result>(
-	source: Source,
-	mapper: (value: Source[keyof Source], key: keyof Source, source: Source) => Result
-): { [Key in keyof Source]: Result } {
-	const result = {} as { [Key in keyof Source]: Result };
-	for (const key of Reflect.ownKeys(source) as (keyof Source)[]) {
-		if (Object.prototype.propertyIsEnumerable.call(source, key)) defineEnumerableProperty(result, key, mapper(source[key], key, source));
-	}
-	return result;
-}
-
-/**
- * 对自有可枚举属性执行 SameValue 浅比较。
- *
- * @remarks 嵌套对象只比较引用；`NaN` 相等，`0` 与 `-0` 不相等。
- * @param left - 第一对象。
- * @param right - 第二对象。
- * @returns 自有可枚举键集合与对应值均满足 SameValue 时返回 `true`。
- */
-export function shallowEqual(left: object, right: object): boolean {
-	if (Object.is(left, right)) return true;
-	const leftKeys = Reflect.ownKeys(left).filter((key) => Object.prototype.propertyIsEnumerable.call(left, key));
-	const rightKeys = Reflect.ownKeys(right).filter((key) => Object.prototype.propertyIsEnumerable.call(right, key));
-	if (leftKeys.length !== rightKeys.length) return false;
-	return leftKeys.every((key) => Object.hasOwn(right, key) && Object.is(Reflect.get(left, key), Reflect.get(right, key)));
-}
-
-/**
- * 把 Query 原始值规范化为文本。
- *
- * @param value - 已排除空值的字符串、数字、布尔值或 BigInt。
- * @returns 与 URLSearchParams 兼容的文本值。
- * @throws `RangeError` 当数字不是有限值。
- */
-const serializeQueryValue = (value: Exclude<QueryPrimitive, null | undefined>): string => {
-	if (typeof value === "number" && !Number.isFinite(value)) {
-		throw new RangeError("Query parameter numbers must be finite.");
-	}
-	return String(value);
-};
-
-/**
- * 将对象序列化为标准 URL 查询字符串。
- *
- * @remarks `null` 与 `undefined` 被跳过；数组使用重复键；返回值不会修改输入。
- * @param value - 查询参数对象。
- * @param options - 排序、空格和问号前缀选项。
- * @returns URL 编码后的查询字符串；没有参数时始终返回空字符串。
- * @throws `RangeError` 当参数包含 `NaN` 或无穷数字。
- */
-export function toQueryString(value: Readonly<Record<string, QueryValue>>, options: QueryStringOptions = {}): string {
-	const entries = Object.entries(value);
-	if (options.sort) entries.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
-	const parameters = new URLSearchParams();
-	for (const [key, rawValue] of entries) {
-		const values = isQueryPrimitiveArray(rawValue) ? rawValue : [rawValue];
-		for (const item of values) {
-			if (item !== null && item !== undefined) parameters.append(key, serializeQueryValue(item));
-		}
-	}
-	let result = parameters.toString();
-	if (options.space === "percent") result = result.replace(/\+/gu, "%20");
-	return result && options.prefixQuestionMark ? `?${result}` : result;
-}