@jsenv/humanize 1.0.0

package/src/log/dynamic_log.js

@@ -0,0 +1,185 @@
+/*
+ * see also https://github.com/vadimdemedes/ink
+ */
+
+import stringWidth from "string-width";
+import ansiEscapes from "ansi-escapes";
+
+export const createDynamicLog = ({
+  stream = process.stdout,
+  clearTerminalAllowed,
+  onVerticalOverflow = () => {},
+  onWriteFromOutside = () => {},
+} = {}) => {
+  const { columns = 80, rows = 24 } = stream;
+  const dynamicLog = {
+    destroyed: false,
+    onVerticalOverflow,
+    onWriteFromOutside,
+  };
+
+  let lastOutput = "";
+  let lastOutputFromOutside = "";
+  let clearAttemptResult;
+  let writing = false;
+
+  const getErasePreviousOutput = () => {
+    // nothing to clear
+    if (!lastOutput) {
+      return "";
+    }
+    if (clearAttemptResult !== undefined) {
+      return "";
+    }
+
+    const logLines = lastOutput.split(/\r\n|\r|\n/);
+    let visualLineCount = 0;
+    for (const logLine of logLines) {
+      const width = stringWidth(logLine);
+      if (width === 0) {
+        visualLineCount++;
+      } else {
+        visualLineCount += Math.ceil(width / columns);
+      }
+    }
+
+    if (visualLineCount > rows) {
+      if (clearTerminalAllowed) {
+        clearAttemptResult = true;
+        return ansiEscapes.clearTerminal;
+      }
+      // the whole log cannot be cleared because it's vertically to long
+      // (longer than terminal height)
+      // readline.moveCursor cannot move cursor higher than screen height
+      // it means we would only clear the visible part of the log
+      // better keep the log untouched
+      clearAttemptResult = false;
+      dynamicLog.onVerticalOverflow();
+      return "";
+    }
+
+    clearAttemptResult = true;
+    return ansiEscapes.eraseLines(visualLineCount);
+  };
+
+  const update = (string) => {
+    if (dynamicLog.destroyed) {
+      throw new Error("Cannot write log after destroy");
+    }
+    let stringToWrite = string;
+    if (lastOutput) {
+      if (lastOutputFromOutside) {
+        // We don't want to clear logs written by other code,
+        // it makes output unreadable and might erase precious information
+        // To detect this we put a spy on the stream.
+        // The spy is required only if we actually wrote something in the stream
+        // something else than this code has written in the stream
+        // so we just write without clearing (append instead of replacing)
+        lastOutput = "";
+        lastOutputFromOutside = "";
+      } else {
+        stringToWrite = `${getErasePreviousOutput()}${string}`;
+      }
+    }
+    writing = true;
+    stream.write(stringToWrite);
+    lastOutput = string;
+    writing = false;
+    clearAttemptResult = undefined;
+  };
+
+  const clearDuringFunctionCall = (callback) => {
+    // 1. Erase the current log
+    // 2. Call callback (expected to write something on stdout)
+    // 3. Restore the current log
+    // During step 2. we expect a "write from outside" so we uninstall
+    // the stream spy during function call
+    const currentOutput = lastOutput;
+    update("");
+
+    writing = true;
+    callback();
+    writing = false;
+
+    update(currentOutput);
+  };
+
+  const writeFromOutsideEffect = (value) => {
+    if (!lastOutput) {
+      // we don't care if the log never wrote anything
+      // or if last update() wrote an empty string
+      return;
+    }
+    if (writing) {
+      return;
+    }
+    lastOutputFromOutside = value;
+    dynamicLog.onWriteFromOutside(value);
+  };
+
+  let removeStreamSpy;
+  if (stream === process.stdout) {
+    const removeStdoutSpy = spyStreamOutput(
+      process.stdout,
+      writeFromOutsideEffect,
+    );
+    const removeStderrSpy = spyStreamOutput(
+      process.stderr,
+      writeFromOutsideEffect,
+    );
+    removeStreamSpy = () => {
+      removeStdoutSpy();
+      removeStderrSpy();
+    };
+  } else {
+    removeStreamSpy = spyStreamOutput(stream, writeFromOutsideEffect);
+  }
+
+  const destroy = () => {
+    dynamicLog.destroyed = true;
+    if (removeStreamSpy) {
+      removeStreamSpy();
+      removeStreamSpy = null;
+      lastOutput = "";
+      lastOutputFromOutside = "";
+    }
+  };
+
+  Object.assign(dynamicLog, {
+    update,
+    destroy,
+    stream,
+    clearDuringFunctionCall,
+  });
+  return dynamicLog;
+};
+
+// maybe https://github.com/gajus/output-interceptor/tree/v3.0.0 ?
+// the problem with listening data on stdout
+// is that node.js will later throw error if stream gets closed
+// while something listening data on it
+const spyStreamOutput = (stream, callback) => {
+  const originalWrite = stream.write;
+
+  let output = "";
+  let installed = true;
+
+  stream.write = function (...args /* chunk, encoding, callback */) {
+    output += args;
+    callback(output);
+    return originalWrite.call(stream, ...args);
+  };
+
+  const uninstall = () => {
+    if (!installed) {
+      return;
+    }
+    stream.write = originalWrite;
+    installed = false;
+  };
+
+  return () => {
+    uninstall();
+    return output;
+  };
+};

package/src/log/logger.js

@@ -0,0 +1,85 @@
+import {
+  LOG_LEVEL_DEBUG,
+  LOG_LEVEL_INFO,
+  LOG_LEVEL_WARN,
+  LOG_LEVEL_ERROR,
+  LOG_LEVEL_OFF,
+} from "./LOG_LEVELS.js";
+
+export const createLogger = ({ logLevel = LOG_LEVEL_INFO } = {}) => {
+  if (logLevel === LOG_LEVEL_DEBUG) {
+    return {
+      level: "debug",
+      levels: { debug: true, info: true, warn: true, error: true },
+      debug,
+      info,
+      warn,
+      error,
+    };
+  }
+  if (logLevel === LOG_LEVEL_INFO) {
+    return {
+      level: "info",
+      levels: { debug: false, info: true, warn: true, error: true },
+      debug: debugDisabled,
+      info,
+      warn,
+      error,
+    };
+  }
+  if (logLevel === LOG_LEVEL_WARN) {
+    return {
+      level: "warn",
+      levels: { debug: false, info: false, warn: true, error: true },
+      debug: debugDisabled,
+      info: infoDisabled,
+      warn,
+      error,
+    };
+  }
+  if (logLevel === LOG_LEVEL_ERROR) {
+    return {
+      level: "error",
+      levels: { debug: false, info: false, warn: false, error: true },
+      debug: debugDisabled,
+      info: infoDisabled,
+      warn: warnDisabled,
+      error,
+    };
+  }
+  if (logLevel === LOG_LEVEL_OFF) {
+    return {
+      level: "off",
+      levels: { debug: false, info: false, warn: false, error: false },
+      debug: debugDisabled,
+      info: infoDisabled,
+      warn: warnDisabled,
+      error: errorDisabled,
+    };
+  }
+  throw new Error(`unexpected logLevel.
+--- logLevel ---
+${logLevel}
+--- allowed log levels ---
+${LOG_LEVEL_OFF}
+${LOG_LEVEL_ERROR}
+${LOG_LEVEL_WARN}
+${LOG_LEVEL_INFO}
+${LOG_LEVEL_DEBUG}`);
+};
+
+const debug = (...args) => console.debug(...args);
+
+const debugDisabled = () => {};
+
+const info = (...args) => console.info(...args);
+
+const infoDisabled = () => {};
+
+const warn = (...args) => console.warn(...args);
+
+const warnDisabled = () => {};
+
+const error = (...args) => console.error(...args);
+
+const errorDisabled = () => {};

package/src/log/spinner.js

@@ -0,0 +1,72 @@
+import { ANSI } from "./ansi.js";
+
+export const startSpinner = ({
+  dynamicLog,
+  frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+  fps = 20,
+  keepProcessAlive = false,
+  stopOnWriteFromOutside = true,
+  stopOnVerticalOverflow = true,
+  render = () => "",
+  effect = () => {},
+  animated = dynamicLog.stream.isTTY,
+}) => {
+  let frameIndex = 0;
+  let interval;
+  let running = true;
+
+  const spinner = {
+    message: undefined,
+  };
+
+  const update = (message) => {
+    spinner.message = running
+      ? `${frames[frameIndex]} ${message}\n`
+      : `${message}\n`;
+    return spinner.message;
+  };
+  spinner.update = update;
+
+  let cleanup;
+  if (animated && ANSI.supported) {
+    running = true;
+    cleanup = effect();
+    dynamicLog.update(update(render()));
+
+    interval = setInterval(() => {
+      frameIndex = frameIndex === frames.length - 1 ? 0 : frameIndex + 1;
+      dynamicLog.update(update(render()));
+    }, 1000 / fps);
+    if (!keepProcessAlive) {
+      interval.unref();
+    }
+  } else {
+    dynamicLog.update(update(render()));
+  }
+
+  const stop = (message) => {
+    running = false;
+    if (interval) {
+      clearInterval(interval);
+      interval = null;
+    }
+    if (cleanup) {
+      cleanup();
+      cleanup = null;
+    }
+    if (dynamicLog && message) {
+      dynamicLog.update(update(message));
+      dynamicLog = null;
+    }
+  };
+  spinner.stop = stop;
+
+  if (stopOnVerticalOverflow) {
+    dynamicLog.onVerticalOverflow = stop;
+  }
+  if (stopOnWriteFromOutside) {
+    dynamicLog.onWriteFromOutside = stop;
+  }
+
+  return spinner;
+};

package/src/log/task_log.js

@@ -0,0 +1,46 @@
+import { humanizeDuration } from "../time/time.js";
+import { UNICODE } from "./unicode.js";
+import { createDynamicLog } from "./dynamic_log.js";
+import { startSpinner } from "./spinner.js";
+
+export const createTaskLog = (
+  label,
+  { disabled = false, animated = true, stopOnWriteFromOutside } = {},
+) => {
+  if (disabled) {
+    return {
+      setRightText: () => {},
+      done: () => {},
+      happen: () => {},
+      fail: () => {},
+    };
+  }
+  const startMs = Date.now();
+  const dynamicLog = createDynamicLog();
+  let message = label;
+  const taskSpinner = startSpinner({
+    dynamicLog,
+    render: () => message,
+    stopOnWriteFromOutside,
+    animated,
+  });
+  return {
+    setRightText: (value) => {
+      message = `${label} ${value}`;
+    },
+    done: () => {
+      const msEllapsed = Date.now() - startMs;
+      taskSpinner.stop(
+        `${UNICODE.OK} ${label} (done in ${humanizeDuration(msEllapsed)})`,
+      );
+    },
+    happen: (message) => {
+      taskSpinner.stop(
+        `${UNICODE.INFO} ${message} (at ${new Date().toLocaleTimeString()})`,
+      );
+    },
+    fail: (message = `failed to ${label}`) => {
+      taskSpinner.stop(`${UNICODE.FAILURE} ${message}`);
+    },
+  };
+};

package/src/log/unicode.js

@@ -0,0 +1,52 @@
+// see also https://github.com/sindresorhus/figures
+
+import isUnicodeSupported from "is-unicode-supported";
+
+import { ANSI } from "./ansi.js";
+
+export const UNICODE = {
+  supported: isUnicodeSupported(),
+
+  get COMMAND_RAW() {
+    return UNICODE.supported ? `❯` : `>`;
+  },
+  get OK_RAW() {
+    return UNICODE.supported ? `✔` : `√`;
+  },
+  get FAILURE_RAW() {
+    return UNICODE.supported ? `✖` : `×`;
+  },
+  get DEBUG_RAW() {
+    return UNICODE.supported ? `◆` : `♦`;
+  },
+  get INFO_RAW() {
+    return UNICODE.supported ? `ℹ` : `i`;
+  },
+  get WARNING_RAW() {
+    return UNICODE.supported ? `⚠` : `‼`;
+  },
+  get CIRCLE_CROSS_RAW() {
+    return UNICODE.supported ? `ⓧ` : `(×)`;
+  },
+  get COMMAND() {
+    return ANSI.color(UNICODE.COMMAND_RAW, ANSI.GREY); // ANSI_MAGENTA)
+  },
+  get OK() {
+    return ANSI.color(UNICODE.OK_RAW, ANSI.GREEN);
+  },
+  get FAILURE() {
+    return ANSI.color(UNICODE.FAILURE_RAW, ANSI.RED);
+  },
+  get DEBUG() {
+    return ANSI.color(UNICODE.DEBUG_RAW, ANSI.GREY);
+  },
+  get INFO() {
+    return ANSI.color(UNICODE.INFO_RAW, ANSI.BLUE);
+  },
+  get WARNING() {
+    return ANSI.color(UNICODE.WARNING_RAW, ANSI.YELLOW);
+  },
+  get CIRCLE_CROSS() {
+    return ANSI.color(UNICODE.CIRCLE_CROSS_RAW, ANSI.RED);
+  },
+};

package/src/main_browser.js

@@ -0,0 +1,10 @@
+export { createDetailedMessage } from "./log/detailed_message.js";
+
+export { humanize, humanizeMethodSymbol } from "./js_value/humanize.js";
+export { determineQuote, inspectChar } from "./js_value/string.js";
+
+export { humanizeDuration, humanizeEllapsedTime } from "./time/time.js";
+export { humanizeFileSize, humanizeMemoryUsage } from "./byte/byte.js";
+export { distributePercentages } from "./percentage/distribute_percentages.js";
+
+export { generateContentFrame } from "./content_frame/content_frame.js";

package/src/main_node.js

@@ -0,0 +1,18 @@
+// node only
+export { createLogger } from "./log/logger.js";
+export { createDynamicLog } from "./log/dynamic_log.js";
+export { startSpinner } from "./log/spinner.js";
+export { createTaskLog } from "./log/task_log.js";
+export { createDetailedMessage } from "./log/detailed_message.js";
+
+export { ANSI } from "./log/ansi.js";
+export { UNICODE } from "./log/unicode.js";
+
+export { humanize, humanizeMethodSymbol } from "./js_value/humanize.js";
+export { determineQuote, inspectChar } from "./js_value/string.js";
+
+export { humanizeDuration, humanizeEllapsedTime } from "./time/time.js";
+export { humanizeFileSize, humanizeMemoryUsage } from "./byte/byte.js";
+export { distributePercentages } from "./percentage/distribute_percentages.js";
+
+export { generateContentFrame } from "./content_frame/content_frame.js";

package/src/percentage/distribute_percentages.js

@@ -0,0 +1,53 @@
+import { getPrecision, setRoundedPrecision } from "../utils/decimals.js";
+
+export const distributePercentages = (
+  namedNumbers,
+  { maxPrecisionHint = 2 } = {},
+) => {
+  const numberNames = Object.keys(namedNumbers);
+  if (numberNames.length === 0) {
+    return {};
+  }
+  if (numberNames.length === 1) {
+    const firstNumberName = numberNames[0];
+    return { [firstNumberName]: "100 %" };
+  }
+  const numbers = numberNames.map((name) => namedNumbers[name]);
+  const total = numbers.reduce((sum, value) => sum + value, 0);
+  const ratios = numbers.map((number) => number / total);
+  const percentages = {};
+  ratios.pop();
+  ratios.forEach((ratio, index) => {
+    const percentage = ratio * 100;
+    percentages[numberNames[index]] = percentage;
+  });
+  const lowestPercentage = (1 / Math.pow(10, maxPrecisionHint)) * 100;
+  let precision = 0;
+  Object.keys(percentages).forEach((name) => {
+    const percentage = percentages[name];
+    if (percentage < lowestPercentage) {
+      // check the amout of meaningful decimals
+      // and that what we will use
+      const percentageRounded = setRoundedPrecision(percentage);
+      const percentagePrecision = getPrecision(percentageRounded);
+      if (percentagePrecision > precision) {
+        precision = percentagePrecision;
+      }
+    }
+  });
+  let remainingPercentage = 100;
+
+  Object.keys(percentages).forEach((name) => {
+    const percentage = percentages[name];
+    const percentageAllocated = setRoundedPrecision(percentage, {
+      decimals: precision,
+    });
+    remainingPercentage -= percentageAllocated;
+    percentages[name] = percentageAllocated;
+  });
+  const lastName = numberNames[numberNames.length - 1];
+  percentages[lastName] = setRoundedPrecision(remainingPercentage, {
+    decimals: precision,
+  });
+  return percentages;
+};

package/src/time/time.js

@@ -0,0 +1,151 @@
+import { setPrecision, setRoundedPrecision } from "../utils/decimals.js";
+
+export const humanizeEllapsedTime = (ms, { short } = {}) => {
+  if (ms < 1000) {
+    return short ? "0s" : "0 second";
+  }
+  const { primary, remaining } = parseMs(ms);
+  if (!remaining) {
+    return inspectEllapsedUnit(primary, short);
+  }
+  return `${inspectEllapsedUnit(primary, short)} and ${inspectEllapsedUnit(
+    remaining,
+    short,
+  )}`;
+};
+const inspectEllapsedUnit = (unit, short) => {
+  const count =
+    unit.name === "second" ? Math.floor(unit.count) : Math.round(unit.count);
+  let name = unit.name;
+  if (short) {
+    name = unitShort[name];
+    if (count <= 1) {
+      return `${count}${name}`;
+    }
+    return `${count}${name}s`;
+  }
+  if (count <= 1) {
+    return `${count} ${name}`;
+  }
+  return `${count} ${name}s`;
+};
+const unitShort = {
+  year: "y",
+  month: "m",
+  week: "w",
+  day: "d",
+  hour: "h",
+  minute: "m",
+  second: "s",
+};
+
+export const humanizeDuration = (
+  ms,
+  { short, rounded = true, decimals } = {},
+) => {
+  // ignore ms below meaningfulMs so that:
+  // humanizeDuration(0.5) -> "0 second"
+  // humanizeDuration(1.1) -> "0.001 second" (and not "0.0011 second")
+  // This tool is meant to be read by humans and it would be barely readable to see
+  // "0.0001 second" (stands for 0.1 millisecond)
+  // yes we could return "0.1 millisecond" but we choosed consistency over precision
+  // so that the prefered unit is "second" (and does not become millisecond when ms is super small)
+  if (ms < 1) {
+    return short ? "0s" : "0 second";
+  }
+  const { primary, remaining } = parseMs(ms);
+  if (!remaining) {
+    return humanizeDurationUnit(primary, {
+      decimals:
+        decimals === undefined ? (primary.name === "second" ? 1 : 0) : decimals,
+      short,
+      rounded,
+    });
+  }
+  return `${humanizeDurationUnit(primary, {
+    decimals: decimals === undefined ? 0 : decimals,
+    short,
+    rounded,
+  })} and ${humanizeDurationUnit(remaining, {
+    decimals: decimals === undefined ? 0 : decimals,
+    short,
+    rounded,
+  })}`;
+};
+const humanizeDurationUnit = (unit, { decimals, short, rounded }) => {
+  const count = rounded
+    ? setRoundedPrecision(unit.count, { decimals })
+    : setPrecision(unit.count, { decimals });
+  let name = unit.name;
+  if (short) {
+    name = unitShort[name];
+    return `${count}${name}`;
+  }
+  if (count <= 1) {
+    return `${count} ${name}`;
+  }
+  return `${count} ${name}s`;
+};
+const MS_PER_UNITS = {
+  year: 31_557_600_000,
+  month: 2_629_000_000,
+  week: 604_800_000,
+  day: 86_400_000,
+  hour: 3_600_000,
+  minute: 60_000,
+  second: 1000,
+};
+
+const parseMs = (ms) => {
+  const unitNames = Object.keys(MS_PER_UNITS);
+  const smallestUnitName = unitNames[unitNames.length - 1];
+  let firstUnitName = smallestUnitName;
+  let firstUnitCount = ms / MS_PER_UNITS[smallestUnitName];
+  const firstUnitIndex = unitNames.findIndex((unitName) => {
+    if (unitName === smallestUnitName) {
+      return false;
+    }
+    const msPerUnit = MS_PER_UNITS[unitName];
+    const unitCount = Math.floor(ms / msPerUnit);
+    if (unitCount) {
+      firstUnitName = unitName;
+      firstUnitCount = unitCount;
+      return true;
+    }
+    return false;
+  });
+  if (firstUnitName === smallestUnitName) {
+    return {
+      primary: {
+        name: firstUnitName,
+        count: firstUnitCount,
+      },
+    };
+  }
+  const remainingMs = ms - firstUnitCount * MS_PER_UNITS[firstUnitName];
+  const remainingUnitName = unitNames[firstUnitIndex + 1];
+  const remainingUnitCount = remainingMs / MS_PER_UNITS[remainingUnitName];
+  // - 1 year and 1 second is too much information
+  //   so we don't check the remaining units
+  // - 1 year and 0.0001 week is awful
+  //   hence the if below
+  if (Math.round(remainingUnitCount) < 1) {
+    return {
+      primary: {
+        name: firstUnitName,
+        count: firstUnitCount,
+      },
+    };
+  }
+  // - 1 year and 1 month is great
+  return {
+    primary: {
+      name: firstUnitName,
+      count: firstUnitCount,
+    },
+    remaining: {
+      name: remainingUnitName,
+      count: remainingUnitCount,
+    },
+  };
+};