@jsenv/humanize 1.0.0

package/src/_tests/percentage/percentage_distribution.test.mjs

@@ -0,0 +1,89 @@
+import { assert } from "@jsenv/assert";
+
+import { distributePercentages } from "@jsenv/humanize";
+
+const test = (namedNumbers, expected) => {
+  const actual = distributePercentages(namedNumbers);
+  assert({ actual, expected });
+};
+
+test(
+  {
+    css: 24,
+    html: 707,
+    js: 6367,
+    json: 0,
+    other: 9997,
+  },
+  {
+    css: 0.1,
+    html: 4.1,
+    js: 37.2,
+    json: 0,
+    other: 58.6,
+  },
+);
+test(
+  {
+    a: 1,
+    b: 999,
+  },
+  {
+    a: 0.1,
+    b: 99.9,
+  },
+);
+test(
+  {
+    a: 1,
+    b: 9_999,
+  },
+  {
+    a: 0.01,
+    b: 99.99,
+  },
+);
+test(
+  {
+    a: 1,
+    b: 99_999,
+  },
+  {
+    a: 0.001,
+    b: 99.999,
+  },
+);
+test(
+  {
+    a: 56_052,
+    b: 222_878,
+  },
+  {
+    a: 20,
+    b: 80,
+  },
+);
+test(
+  {
+    a: 10,
+    b: 90,
+  },
+  {
+    a: 10,
+    b: 90,
+  },
+);
+test(
+  {
+    a: 1,
+    b: 10,
+    c: 100,
+    d: 889,
+  },
+  {
+    a: 0.1,
+    b: 1,
+    c: 10,
+    d: 88.9,
+  },
+);

package/src/_tests/time/decimals.test.js

@@ -0,0 +1,119 @@
+import { assert } from "@jsenv/assert";
+
+import {
+  setRoundedPrecision,
+  setCeiledPrecision,
+  setFlooredPrecision,
+  setPrecision,
+} from "@jsenv/humanize/src/utils/decimals.js";
+
+/* numbers between -1 and 1 */
+// rounds last decimal
+{
+  const actual = setRoundedPrecision(0.54);
+  const expected = 0.5;
+  assert({ actual, expected });
+}
+{
+  const actual = setRoundedPrecision(0.55);
+  const expected = 0.6;
+  assert({ actual, expected });
+}
+// floor last decimal
+{
+  const actual = setFlooredPrecision(0.54);
+  const expected = 0.5;
+  assert({ actual, expected });
+}
+{
+  const actual = setFlooredPrecision(0.55);
+  const expected = 0.5;
+  assert({ actual, expected });
+}
+{
+  const actual = setFlooredPrecision(0.501);
+  const expected = 0.5;
+  assert({ actual, expected });
+}
+// ceil last decimal
+{
+  const actual = setCeiledPrecision(0.54);
+  const expected = 0.6;
+  assert({ actual, expected });
+}
+{
+  const actual = setCeiledPrecision(0.54);
+  const expected = 0.6;
+  assert({ actual, expected });
+}
+{
+  const actual = setCeiledPrecision(0.501);
+  const expected = 0.6;
+  assert({ actual, expected });
+}
+// truncate last decimal
+{
+  const actual = setPrecision(0.501);
+  const expected = 0.5;
+  assert({ actual, expected });
+}
+{
+  const actual = setPrecision(0.56);
+  const expected = 0.5;
+  assert({ actual, expected });
+}
+// rounded tests
+{
+  const actual = setRoundedPrecision(0.0101);
+  const expected = 0.01;
+  assert({ actual, expected });
+}
+{
+  const actual = setRoundedPrecision(0.012);
+  const expected = 0.01;
+  assert({ actual, expected });
+}
+{
+  const actual = setRoundedPrecision(0.016);
+  const expected = 0.02;
+  assert({ actual, expected });
+}
+{
+  const actual = setRoundedPrecision(0.016556, {
+    decimals: 3,
+  });
+  const expected = 0.0166;
+  assert({ actual, expected });
+}
+{
+  const actual = setRoundedPrecision(0);
+  const expected = 0;
+  assert({ actual, expected });
+}
+{
+  const actual = setRoundedPrecision(-0.0015);
+  const expected = -0.002;
+  assert({ actual, expected });
+}
+
+/* numbers above 1 */
+{
+  const actual = setRoundedPrecision(37.04);
+  const expected = 37;
+  assert({ actual, expected });
+}
+{
+  const actual = setRoundedPrecision(37.05);
+  const expected = 37.1;
+  assert({ actual, expected });
+}
+{
+  const actual = setCeiledPrecision(37.01);
+  const expected = 37.1;
+  assert({ actual, expected });
+}
+{
+  const actual = setFlooredPrecision(37.01);
+  const expected = 37;
+  assert({ actual, expected });
+}

package/src/_tests/time/duration.test.js

@@ -0,0 +1,20 @@
+import { assert } from "@jsenv/assert";
+
+import { humanizeDuration } from "@jsenv/humanize";
+
+const test = (durationInMs, expected) => {
+  const actual = humanizeDuration(durationInMs);
+  assert({ actual, expected });
+};
+
+test(0.1, "0 second");
+test(1.02, "0.001 second");
+test(1.52, "0.002 second");
+test(52, "0.05 second");
+test(55, "0.06 second");
+test(99, "0.1 second");
+test(999, "1 second");
+test(1_421, "1.4 seconds");
+test(61_421, "1 minute and 1 second");
+test(3_601_200, "1 hour");
+test(7_651_200, "2 hours and 8 minutes");

package/src/_tests/time/ellapsed.test.js

@@ -0,0 +1,10 @@
+import { assert } from "@jsenv/assert";
+
+import { humanizeEllapsedTime } from "@jsenv/humanize";
+
+const test = (durationInMs, expected) => {
+  const actual = humanizeEllapsedTime(durationInMs);
+  assert({ actual, expected });
+};
+
+test(2200, "2 seconds");

package/src/byte/byte.js

@@ -0,0 +1,44 @@
+import { setRoundedPrecision } from "../utils/decimals.js";
+
+export const humanizeFileSize = (numberOfBytes, { decimals, short } = {}) => {
+  return inspectBytes(numberOfBytes, { decimals, short });
+};
+
+export const humanizeMemoryUsage = (metricValue, { decimals, short } = {}) => {
+  return inspectBytes(metricValue, { decimals, fixedDecimals: true, short });
+};
+
+const inspectBytes = (
+  number,
+  { fixedDecimals = false, decimals, short } = {},
+) => {
+  if (number === 0) {
+    return `0 B`;
+  }
+  const exponent = Math.min(
+    Math.floor(Math.log10(number) / 3),
+    BYTE_UNITS.length - 1,
+  );
+  const unitNumber = number / Math.pow(1000, exponent);
+  const unitName = BYTE_UNITS[exponent];
+  if (decimals === undefined) {
+    if (unitNumber < 100) {
+      decimals = 1;
+    } else {
+      decimals = 0;
+    }
+  }
+  const unitNumberRounded = setRoundedPrecision(unitNumber, {
+    decimals,
+    decimalsWhenSmall: 1,
+  });
+  const value = fixedDecimals
+    ? unitNumberRounded.toFixed(decimals)
+    : unitNumberRounded;
+  if (short) {
+    return `${value}${unitName}`;
+  }
+  return `${value} ${unitName}`;
+};
+
+const BYTE_UNITS = ["B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"];

package/src/content_frame/content_frame.js

@@ -0,0 +1,157 @@
+const formatDefault = (v) => v;
+
+export const generateContentFrame = ({
+  content,
+  line,
+  column,
+
+  linesAbove = 3,
+  linesBelow = 0,
+  lineMaxWidth = 120,
+  lineNumbersOnTheLeft = true,
+  lineMarker = true,
+  columnMarker = true,
+  format = formatDefault,
+} = {}) => {
+  const lineStrings = content.split(/\r?\n/);
+  if (line === 0) line = 1;
+  if (column === undefined) {
+    columnMarker = false;
+    column = 1;
+  }
+  if (column === 0) column = 1;
+
+  let lineStartIndex = line - 1 - linesAbove;
+  if (lineStartIndex < 0) {
+    lineStartIndex = 0;
+  }
+  let lineEndIndex = line - 1 + linesBelow;
+  if (lineEndIndex > lineStrings.length - 1) {
+    lineEndIndex = lineStrings.length - 1;
+  }
+  if (columnMarker) {
+    // human reader deduce the line when there is a column marker
+    lineMarker = false;
+  }
+  if (line - 1 === lineEndIndex) {
+    lineMarker = false; // useless because last line
+  }
+  let lineIndex = lineStartIndex;
+
+  let columnsBefore;
+  let columnsAfter;
+  if (column > lineMaxWidth) {
+    columnsBefore = column - Math.ceil(lineMaxWidth / 2);
+    columnsAfter = column + Math.floor(lineMaxWidth / 2);
+  } else {
+    columnsBefore = 0;
+    columnsAfter = lineMaxWidth;
+  }
+  let columnMarkerIndex = column - 1 - columnsBefore;
+
+  let source = "";
+  while (lineIndex <= lineEndIndex) {
+    const lineString = lineStrings[lineIndex];
+    const lineNumber = lineIndex + 1;
+    const isLastLine = lineIndex === lineEndIndex;
+    const isMainLine = lineNumber === line;
+    lineIndex++;
+
+    write_aside: {
+      if (lineMarker) {
+        if (isMainLine) {
+          source += `${format(">", "marker_line")} `;
+        } else {
+          source += "  ";
+        }
+      }
+      if (lineNumbersOnTheLeft) {
+        // fill with spaces to ensure if line moves from 7,8,9 to 10 the display is still great
+        const asideSource = `${fillLeft(lineNumber, lineEndIndex + 1)} |`;
+        source += `${format(asideSource, "line_number_aside")} `;
+      }
+    }
+    write_line: {
+      source += truncateLine(lineString, {
+        start: columnsBefore,
+        end: columnsAfter,
+        prefix: "…",
+        suffix: "…",
+        format,
+      });
+    }
+    write_column_marker: {
+      if (columnMarker && isMainLine) {
+        source += `\n`;
+        if (lineMarker) {
+          source += "  ";
+        }
+        if (lineNumbersOnTheLeft) {
+          const asideSpaces = `${fillLeft(lineNumber, lineEndIndex + 1)} | `
+            .length;
+          source += " ".repeat(asideSpaces);
+        }
+        source += " ".repeat(columnMarkerIndex);
+        source += format("^", "marker_column");
+      }
+    }
+    if (!isLastLine) {
+      source += "\n";
+    }
+  }
+  return source;
+};
+
+const truncateLine = (line, { start, end, prefix, suffix, format }) => {
+  const lastIndex = line.length;
+
+  if (line.length === 0) {
+    // don't show any ellipsis if the line is empty
+    // because it's not truncated in that case
+    return "";
+  }
+
+  const startTruncated = start > 0;
+  const endTruncated = lastIndex > end;
+
+  let from = startTruncated ? start + prefix.length : start;
+  let to = endTruncated ? end - suffix.length : end;
+  if (to > lastIndex) to = lastIndex;
+
+  if (start >= lastIndex || from === to) {
+    return "";
+  }
+  let result = "";
+  while (from < to) {
+    result += format(line[from], "char");
+    from++;
+  }
+  if (result.length === 0) {
+    return "";
+  }
+  if (startTruncated && endTruncated) {
+    return `${format(prefix, "marker_overflow_left")}${result}${format(
+      suffix,
+      "marker_overflow_right",
+    )}`;
+  }
+  if (startTruncated) {
+    return `${format(prefix, "marker_overflow_left")}${result}`;
+  }
+  if (endTruncated) {
+    return `${result}${format(suffix, "marker_overflow_right")}`;
+  }
+  return result;
+};
+
+const fillLeft = (value, biggestValue, char = " ") => {
+  const width = String(value).length;
+  const biggestWidth = String(biggestValue).length;
+  let missingWidth = biggestWidth - width;
+  let padded = "";
+  while (missingWidth--) {
+    padded += char;
+  }
+  padded += value;
+  return padded;
+};

package/src/js_value/array.js

@@ -0,0 +1,58 @@
+import {
+  preNewLineAndIndentation,
+  wrapNewLineAndIndentation,
+} from "../utils/indentation.js";
+import { inspectConstructor } from "./constructor.js";
+
+export const inspectArray = (
+  value,
+  {
+    seen = [],
+    nestedHumanize,
+    depth,
+    indentUsingTab,
+    indentSize,
+    parenthesis,
+    useNew,
+  },
+) => {
+  if (seen.indexOf(value) > -1) {
+    return "Symbol.for('circular')";
+  }
+  seen.push(value);
+
+  let valuesSource = "";
+  let i = 0;
+  const j = value.length;
+
+  while (i < j) {
+    const valueSource = value.hasOwnProperty(i)
+      ? nestedHumanize(value[i], { seen })
+      : "";
+    if (i === 0) {
+      valuesSource += valueSource;
+    } else {
+      valuesSource += `,${preNewLineAndIndentation(valueSource, {
+        depth,
+        indentUsingTab,
+        indentSize,
+      })}`;
+    }
+    i++;
+  }
+
+  let arraySource;
+  if (valuesSource.length) {
+    arraySource = wrapNewLineAndIndentation(valuesSource, {
+      depth,
+      indentUsingTab,
+      indentSize,
+    });
+  } else {
+    arraySource = "";
+  }
+
+  arraySource = `[${arraySource}]`;
+
+  return inspectConstructor(arraySource, { parenthesis, useNew });
+};

package/src/js_value/bigint.js

@@ -0,0 +1,3 @@
+export const inspectBigInt = (value) => {
+  return `${value}n`;
+};

package/src/js_value/bigint_object.js

@@ -0,0 +1,5 @@
+export const inspectBigIntObject = (value, { nestedHumanize }) => {
+  const bigIntSource = nestedHumanize(value.valueOf());
+
+  return `BigInt(${bigIntSource})`;
+};

package/src/js_value/boolean.js

@@ -0,0 +1 @@
+export const inspectBoolean = (value) => value.toString();

package/src/js_value/boolean_object.js

@@ -0,0 +1,12 @@
+import { inspectConstructor } from "./constructor.js";
+
+export const inspectBooleanObject = (
+  value,
+  { nestedHumanize, useNew, parenthesis },
+) => {
+  const booleanSource = nestedHumanize(value.valueOf());
+  return inspectConstructor(`Boolean(${booleanSource})`, {
+    useNew,
+    parenthesis,
+  });
+};

package/src/js_value/constructor.js

@@ -0,0 +1,10 @@
+export const inspectConstructor = (value, { parenthesis, useNew }) => {
+  let formattedString = value;
+  if (parenthesis) {
+    formattedString = `(${value})`;
+  }
+  if (useNew) {
+    formattedString = `new ${formattedString}`;
+  }
+  return formattedString;
+};

package/src/js_value/date.js

@@ -0,0 +1,8 @@
+import { inspectConstructor } from "./constructor.js";
+
+export const inspectDate = (value, { nestedHumanize, useNew, parenthesis }) => {
+  const dateSource = nestedHumanize(value.valueOf(), {
+    numericSeparator: false,
+  });
+  return inspectConstructor(`Date(${dateSource})`, { useNew, parenthesis });
+};

package/src/js_value/error.js

@@ -0,0 +1,34 @@
+import { inspectConstructor } from "./constructor.js";
+
+export const inspectError = (
+  error,
+  { nestedHumanize, useNew, parenthesis },
+) => {
+  const messageSource = nestedHumanize(error.message);
+
+  const errorSource = inspectConstructor(
+    `${errorToConstructorName(error)}(${messageSource})`,
+    {
+      useNew,
+      parenthesis,
+    },
+  );
+  return errorSource;
+};
+
+const errorToConstructorName = ({ name }) => {
+  if (derivedErrorNameArray.includes(name)) {
+    return name;
+  }
+  return "Error";
+};
+
+// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#Error_types
+const derivedErrorNameArray = [
+  "EvalError",
+  "RangeError",
+  "ReferenceError",
+  "SyntaxError",
+  "TypeError",
+  "URIError",
+];

package/src/js_value/function.js

@@ -0,0 +1,20 @@
+export const inspectFunction = (
+  value,
+  { showFunctionBody, parenthesis, depth },
+) => {
+  let functionSource;
+  if (showFunctionBody) {
+    functionSource = value.toString();
+  } else {
+    const isArrowFunction = value.prototype === undefined;
+    const head = isArrowFunction
+      ? "() =>"
+      : `function ${depth === 0 ? value.name : ""}()`;
+    functionSource = `${head} {/* hidden */}`;
+  }
+
+  if (parenthesis) {
+    return `(${functionSource})`;
+  }
+  return functionSource;
+};