feat: polish release v2 experience (#6800)
This commit is contained in:
1 parent
925b0fb801
commit
a4a903d7c3
295 files changed
+10627
-7115
No files matched your search
@@ -12,4 +12,3 @@ export * from "./error";
|
||||
export * from "./theme";
|
||||
export * from "./function";
|
||||
export * from "./grid-algorithm";
|
||||
export * from "./id";
|
||||
@@ -16,53 +16,17 @@ export const formatNumber = (value: number, decimalPlaces: number) => {
|
||||
return value.toFixed(decimalPlaces);
|
||||
};
|
||||
|
||||
export const randomInt = (min: number, max: number) => {
|
||||
return Math.floor(Math.random() * (max - min + 1) + min);
|
||||
};
|
||||
|
||||
/**
|
||||
* Number of bytes to a human-readable string using binary (KiB) suffixes.
|
||||
* Does not accept floats; size in bytes should be an integer.
|
||||
* Will return "NaI" and log a warning if a float is passed.
|
||||
* `concat` is appended after the unit so it is omitted when the returned
|
||||
* value is "NaI" or "∞". Returns "∞" if the size is too large to be
|
||||
* represented in the current format.
|
||||
*
|
||||
* @deprecated Use `formatBytes` for single values, `formatBytesPair` for
|
||||
* paired "used / total" displays, and `formatByteRate` for byte-per-second
|
||||
* rates. This function is kept for backwards compatibility but should not
|
||||
* be used in new code.
|
||||
*/
|
||||
export const humanFileSize = (size: number, concat = ""): string => {
|
||||
//64bit limit for Number stops at EiB
|
||||
const siRanges = ["B", "kiB", "MiB", "GiB", "TiB", "PiB", "EiB"];
|
||||
if (!Number.isInteger(size)) {
|
||||
console.warn(
|
||||
"Invalid use of the humanFileSize function with a float, please report this and what integration this is impacting.",
|
||||
);
|
||||
//Not an Integer
|
||||
return "NaI";
|
||||
}
|
||||
let count = 0;
|
||||
while (count < siRanges.length) {
|
||||
const tempSize = size / Math.pow(1024, count);
|
||||
if (tempSize < 1024) {
|
||||
return tempSize.toFixed(Math.min(count, 1)) + siRanges[count] + concat;
|
||||
}
|
||||
count++;
|
||||
}
|
||||
return "∞";
|
||||
};
|
||||
|
||||
const BINARY_UNITS = ["B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB"] as const;
|
||||
const DECIMAL_UNITS = ["B", "KB", "MB", "GB", "TB", "PB", "EB"] as const;
|
||||
|
||||
export const defaultByteUnitSystem = "decimal" as const;
|
||||
|
||||
export type ByteUnitSystem = "binary" | "decimal";
|
||||
|
||||
export interface FormatBytesOptions {
|
||||
/**
|
||||
* Unit system to use. "binary" uses 1024 as the base and KiB/MiB/GiB/TiB suffixes,
|
||||
* "decimal" uses 1000 as the base and KB/MB/GB/TB suffixes. Defaults to "binary".
|
||||
* "decimal" uses 1000 as the base and KB/MB/GB/TB suffixes. Defaults to "decimal".
|
||||
*/
|
||||
unit?: ByteUnitSystem;
|
||||
}
|
||||
@@ -78,10 +42,17 @@ const pickUnitIndex = (bytes: number, base: number, lastIndex: number): number =
|
||||
return index;
|
||||
};
|
||||
|
||||
const pickRoundedUnitIndex = (value: number, base: number, lastIndex: number, fractionDigits: number): number => {
|
||||
const index = pickUnitIndex(value, base, lastIndex);
|
||||
if (index >= lastIndex) return index;
|
||||
const scaled = value / base ** index;
|
||||
return Number(scaled.toFixed(fractionDigits)) >= base ? index + 1 : index;
|
||||
};
|
||||
|
||||
const sanitizeBytes = (bytes: number): number => (Number.isFinite(bytes) && bytes > 0 ? bytes : 0);
|
||||
|
||||
const resolveUnitConfig = (options: FormatBytesOptions) => {
|
||||
const { unit = "binary" } = options;
|
||||
const { unit = defaultByteUnitSystem } = options;
|
||||
return {
|
||||
units: unit === "binary" ? BINARY_UNITS : DECIMAL_UNITS,
|
||||
base: unit === "binary" ? 1024 : 1000,
|
||||
@@ -92,45 +63,45 @@ const resolveUnitConfig = (options: FormatBytesOptions) => {
|
||||
* Format a byte value as a human-readable string with a unit suffix.
|
||||
*
|
||||
* Picks the largest unit that keeps the scaled value below the base. Use
|
||||
* `formatBytesPair` when two related values (e.g. used and available) should
|
||||
* `formatBytesPair` when two related values (e.g. used and total) should
|
||||
* share a common unit.
|
||||
*
|
||||
* @example
|
||||
* formatBytes(0); // "0.0 B"
|
||||
* formatBytes(1024); // "1.0 KiB"
|
||||
* formatBytes(985828802560); // "918.1 GiB"
|
||||
* formatBytes(985828802560, { unit: "decimal" }); // "985.8 GB"
|
||||
* formatBytes(1000); // "1.0 KB"
|
||||
* formatBytes(985828802560); // "985.8 GB"
|
||||
* formatBytes(985828802560, { unit: "binary" }); // "918.1 GiB"
|
||||
*/
|
||||
export const formatBytes = (bytes: number, options: FormatBytesOptions = {}): string => {
|
||||
const { units, base } = resolveUnitConfig(options);
|
||||
const safe = sanitizeBytes(bytes);
|
||||
const index = pickUnitIndex(safe, base, units.length - 1);
|
||||
const index = pickRoundedUnitIndex(safe, base, units.length - 1, 1);
|
||||
const scaled = safe / base ** index;
|
||||
return `${scaled.toFixed(1)} ${units[index]}`;
|
||||
};
|
||||
|
||||
/**
|
||||
* Format two related byte values (typically `used` and `available`) with a
|
||||
* shared unit. The unit is picked from the sum of the two values so the
|
||||
* combined display stays consistent.
|
||||
* Format two related byte values (typically `used` and `total`) with a shared
|
||||
* unit. The unit is picked from the larger displayed value so the pair stays
|
||||
* consistent without promoting both values before either crosses a boundary.
|
||||
*
|
||||
* @example
|
||||
* formatBytesPair(985828802560, 2858736793190);
|
||||
* // { used: "0.9 TiB", available: "2.6 TiB" }
|
||||
* // { used: "1.0 TB", total: "2.9 TB" }
|
||||
*/
|
||||
export const formatBytesPair = (
|
||||
used: number,
|
||||
available: number,
|
||||
total: number,
|
||||
options: FormatBytesOptions = {},
|
||||
): { used: string; available: string } => {
|
||||
): { used: string; total: string } => {
|
||||
const { units, base } = resolveUnitConfig(options);
|
||||
const safeUsed = sanitizeBytes(used);
|
||||
const safeAvailable = sanitizeBytes(available);
|
||||
const index = pickUnitIndex(safeUsed + safeAvailable, base, units.length - 1);
|
||||
const safeTotal = sanitizeBytes(total);
|
||||
const index = pickRoundedUnitIndex(Math.max(safeUsed, safeTotal), base, units.length - 1, 1);
|
||||
const suffix = units[index];
|
||||
return {
|
||||
used: `${(safeUsed / base ** index).toFixed(1)} ${suffix}`,
|
||||
available: `${(safeAvailable / base ** index).toFixed(1)} ${suffix}`,
|
||||
total: `${(safeTotal / base ** index).toFixed(1)} ${suffix}`,
|
||||
};
|
||||
};
|
||||
|
||||
@@ -141,13 +112,40 @@ export const formatBytesPair = (
|
||||
*
|
||||
* @example
|
||||
* formatByteRate(0); // "0.0 B/s"
|
||||
* formatByteRate(1024); // "1.0 KiB/s"
|
||||
* formatByteRate(985828802560, { unit: "decimal" }); // "985.8 GB/s"
|
||||
* formatByteRate(1000); // "1.0 KB/s"
|
||||
* formatByteRate(985828802560, { unit: "binary" }); // "918.1 GiB/s"
|
||||
*/
|
||||
export const formatByteRate = (bytes: number, options: FormatBytesOptions = {}): string =>
|
||||
`${formatBytes(bytes, options)}/s`;
|
||||
|
||||
const BIT_RATE_UNITS = ["b/s", "Kb/s", "Mb/s", "Gb/s", "Tb/s", "Pb/s", "Eb/s"] as const;
|
||||
|
||||
export interface FormatBitRateOptions {
|
||||
/** Maximum number of fractional digits. Trailing zeroes are omitted. Defaults to 1. */
|
||||
maximumFractionDigits?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Format a bit-per-second rate using decimal SI units.
|
||||
*
|
||||
* Inputs are always bits per second. Callers whose upstream contract uses
|
||||
* kilobits must normalize explicitly before calling this function.
|
||||
*
|
||||
* @example
|
||||
* formatBitRate(999); // "999 b/s"
|
||||
* formatBitRate(1_000); // "1 Kb/s"
|
||||
* formatBitRate(1_500_000); // "1.5 Mb/s"
|
||||
*/
|
||||
export const formatBitRate = (bitsPerSecond: number, options: FormatBitRateOptions = {}): string => {
|
||||
const safeRate = Number.isFinite(bitsPerSecond) && bitsPerSecond > 0 ? bitsPerSecond : 0;
|
||||
const requestedDigits = options.maximumFractionDigits ?? 1;
|
||||
const maximumFractionDigits = Math.max(0, Math.min(20, Math.trunc(requestedDigits)));
|
||||
const index = pickRoundedUnitIndex(safeRate, 1000, BIT_RATE_UNITS.length - 1, maximumFractionDigits);
|
||||
const scaled = safeRate / 1000 ** index;
|
||||
const formatted = Number(scaled.toFixed(maximumFractionDigits)).toString();
|
||||
return `${formatted} ${BIT_RATE_UNITS[index]}`;
|
||||
};
|
||||
|
||||
const IMPERIAL_MULTIPLIER = 1.609344;
|
||||
|
||||
export const metricToImperial = (metricValue: number) => metricValue / IMPERIAL_MULTIPLIER;
|
||||
export const imperialToMetric = (imperialValue: number) => imperialValue * IMPERIAL_MULTIPLIER;
|
||||
@@ -1,5 +1,8 @@
|
||||
import { hashKey } from "@tanstack/query-core";
|
||||
|
||||
export const isRecord = (value: unknown): value is Record<string, unknown> =>
|
||||
value !== null && typeof value === "object" && !Array.isArray(value);
|
||||
|
||||
export function objectKeys<O extends object>(obj: O): (keyof O)[] {
|
||||
return Object.keys(obj) as (keyof O)[];
|
||||
}
|
||||
|
||||
@@ -1,35 +1,35 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { formatByteRate, formatBytes, formatBytesPair } from "../number";
|
||||
import { formatBitRate, formatByteRate, formatBytes, formatBytesPair } from "../number";
|
||||
|
||||
describe("formatBytes", () => {
|
||||
it("returns bytes for small values", () => {
|
||||
expect(formatBytes(0)).toBe("0.0 B");
|
||||
expect(formatBytes(1)).toBe("1.0 B");
|
||||
expect(formatBytes(1023)).toBe("1023.0 B");
|
||||
expect(formatBytes(999)).toBe("999.0 B");
|
||||
});
|
||||
|
||||
it("scales binary units correctly", () => {
|
||||
expect(formatBytes(1024)).toBe("1.0 KiB");
|
||||
expect(formatBytes(1024 ** 2)).toBe("1.0 MiB");
|
||||
expect(formatBytes(1024 ** 3)).toBe("1.0 GiB");
|
||||
expect(formatBytes(1024 ** 4)).toBe("1.0 TiB");
|
||||
it("scales decimal units by default", () => {
|
||||
expect(formatBytes(1000)).toBe("1.0 KB");
|
||||
expect(formatBytes(1000 ** 2)).toBe("1.0 MB");
|
||||
expect(formatBytes(1000 ** 3)).toBe("1.0 GB");
|
||||
expect(formatBytes(1000 ** 4)).toBe("1.0 TB");
|
||||
});
|
||||
|
||||
it("scales decimal units when requested", () => {
|
||||
expect(formatBytes(1000, { unit: "decimal" })).toBe("1.0 KB");
|
||||
expect(formatBytes(1000 ** 2, { unit: "decimal" })).toBe("1.0 MB");
|
||||
expect(formatBytes(1000 ** 3, { unit: "decimal" })).toBe("1.0 GB");
|
||||
expect(formatBytes(1000 ** 4, { unit: "decimal" })).toBe("1.0 TB");
|
||||
it("scales binary units when requested", () => {
|
||||
expect(formatBytes(1024, { unit: "binary" })).toBe("1.0 KiB");
|
||||
expect(formatBytes(1024 ** 2, { unit: "binary" })).toBe("1.0 MiB");
|
||||
expect(formatBytes(1024 ** 3, { unit: "binary" })).toBe("1.0 GiB");
|
||||
expect(formatBytes(1024 ** 4, { unit: "binary" })).toBe("1.0 TiB");
|
||||
});
|
||||
|
||||
it("formats a typical storage value with one decimal", () => {
|
||||
expect(formatBytes(985828802560)).toBe("918.1 GiB");
|
||||
expect(formatBytes(985828802560, { unit: "decimal" })).toBe("985.8 GB");
|
||||
expect(formatBytes(985828802560)).toBe("985.8 GB");
|
||||
expect(formatBytes(985828802560, { unit: "binary" })).toBe("918.1 GiB");
|
||||
});
|
||||
|
||||
it("caps at the largest unit to avoid overflow", () => {
|
||||
expect(formatBytes(Number.MAX_SAFE_INTEGER)).toMatch(/PiB$/);
|
||||
expect(formatBytes(Number.MAX_SAFE_INTEGER)).toMatch(/PB$/);
|
||||
});
|
||||
|
||||
it("returns the zero value for negative or non-finite input", () => {
|
||||
@@ -40,47 +40,53 @@ describe("formatBytes", () => {
|
||||
});
|
||||
|
||||
describe("formatBytesPair", () => {
|
||||
it("picks the unit of the larger total and applies it to both values", () => {
|
||||
const { used, available } = formatBytesPair(985828802560, 2858736793190);
|
||||
expect(used).toBe("0.9 TiB");
|
||||
expect(available).toBe("2.6 TiB");
|
||||
it("picks the unit of the larger value and applies it to both values", () => {
|
||||
const { used, total } = formatBytesPair(985828802560, 2858736793190);
|
||||
expect(used).toBe("1.0 TB");
|
||||
expect(total).toBe("2.9 TB");
|
||||
});
|
||||
|
||||
it("uses a smaller unit when both values fit in it", () => {
|
||||
const { used, available } = formatBytesPair(1024 * 1024 * 100, 1024 * 1024 * 200);
|
||||
expect(used).toBe("100.0 MiB");
|
||||
expect(available).toBe("200.0 MiB");
|
||||
const { used, total } = formatBytesPair(1024 * 1024 * 100, 1024 * 1024 * 200);
|
||||
expect(used).toBe("104.9 MB");
|
||||
expect(total).toBe("209.7 MB");
|
||||
});
|
||||
|
||||
it("does not promote the pair when only their sum crosses a unit boundary", () => {
|
||||
const { used, total } = formatBytesPair(700 * 1024, 700 * 1024);
|
||||
expect(used).toBe("716.8 KB");
|
||||
expect(total).toBe("716.8 KB");
|
||||
});
|
||||
|
||||
it("falls back to zero when both inputs are invalid", () => {
|
||||
const { used, available } = formatBytesPair(Number.NaN, -1);
|
||||
const { used, total } = formatBytesPair(Number.NaN, -1);
|
||||
expect(used).toBe("0.0 B");
|
||||
expect(available).toBe("0.0 B");
|
||||
expect(total).toBe("0.0 B");
|
||||
});
|
||||
|
||||
it("uses the same unit across both values when one is invalid", () => {
|
||||
const { used, available } = formatBytesPair(Number.NaN, 1024 ** 4);
|
||||
expect(used).toBe("0.0 TiB");
|
||||
expect(available).toBe("1.0 TiB");
|
||||
const { used, total } = formatBytesPair(Number.NaN, 1024 ** 4);
|
||||
expect(used).toBe("0.0 TB");
|
||||
expect(total).toBe("1.1 TB");
|
||||
});
|
||||
|
||||
it("honours the decimal unit option", () => {
|
||||
const { used, available } = formatBytesPair(500_000_000_000, 1_500_000_000_000, { unit: "decimal" });
|
||||
const { used, total } = formatBytesPair(500_000_000_000, 1_500_000_000_000, { unit: "decimal" });
|
||||
expect(used).toBe("0.5 TB");
|
||||
expect(available).toBe("1.5 TB");
|
||||
expect(total).toBe("1.5 TB");
|
||||
});
|
||||
});
|
||||
|
||||
describe("formatByteRate", () => {
|
||||
it("appends a /s suffix to the formatted value", () => {
|
||||
expect(formatByteRate(0)).toBe("0.0 B/s");
|
||||
expect(formatByteRate(1024)).toBe("1.0 KiB/s");
|
||||
expect(formatByteRate(1024 ** 3)).toBe("1.0 GiB/s");
|
||||
expect(formatByteRate(1000)).toBe("1.0 KB/s");
|
||||
expect(formatByteRate(1000 ** 3)).toBe("1.0 GB/s");
|
||||
});
|
||||
|
||||
it("honours the decimal unit option", () => {
|
||||
expect(formatByteRate(1000, { unit: "decimal" })).toBe("1.0 KB/s");
|
||||
expect(formatByteRate(1000 ** 2, { unit: "decimal" })).toBe("1.0 MB/s");
|
||||
it("honours the binary unit option", () => {
|
||||
expect(formatByteRate(1024, { unit: "binary" })).toBe("1.0 KiB/s");
|
||||
expect(formatByteRate(1024 ** 2, { unit: "binary" })).toBe("1.0 MiB/s");
|
||||
});
|
||||
|
||||
it("returns zero for invalid input", () => {
|
||||
@@ -88,3 +94,21 @@ describe("formatByteRate", () => {
|
||||
expect(formatByteRate(Number.NaN)).toBe("0.0 B/s");
|
||||
});
|
||||
});
|
||||
|
||||
describe("formatBitRate", () => {
|
||||
it("uses decimal SI units with one optional fractional digit", () => {
|
||||
expect(formatBitRate(999)).toBe("999 b/s");
|
||||
expect(formatBitRate(1_000)).toBe("1 Kb/s");
|
||||
expect(formatBitRate(1_000_000)).toBe("1 Mb/s");
|
||||
expect(formatBitRate(1_500_000)).toBe("1.5 Mb/s");
|
||||
expect(formatBitRate(1_000_000_000)).toBe("1 Gb/s");
|
||||
expect(formatBitRate(1_234_567)).toBe("1.2 Mb/s");
|
||||
});
|
||||
|
||||
it("returns zero for non-positive or non-finite rates", () => {
|
||||
expect(formatBitRate(0)).toBe("0 b/s");
|
||||
expect(formatBitRate(-1)).toBe("0 b/s");
|
||||
expect(formatBitRate(Number.NaN)).toBe("0 b/s");
|
||||
expect(formatBitRate(Number.POSITIVE_INFINITY)).toBe("0 b/s");
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user