@jsenv/humanize 1.7.6 → 1.7.8

package/dist/node/jsenv_humanize_node.js

@@ -1,4 +1,4 @@
-import { createSupportsColor, isUnicodeSupported, emojiRegex, eastAsianWidth } from "./jsenv_humanize_node_modules.js";
+import { createSupportsColor, isUnicodeSupported, eastAsianWidth } from "./jsenv_humanize_node_modules.js";
 import stripAnsi from "strip-ansi";
 import { stripVTControlCharacters } from "node:util";
 import ansiEscapes from "ansi-escapes";
@@ -677,10 +677,13 @@ const derivedErrorNameArray = [
 ];
 
 const inspectDate = (value, { nestedHumanize, useNew, parenthesis }) => {
-  const dateSource = nestedHumanize(value.valueOf(), {
+  const dateSource = nestedHumanize(value.toISOString(), {
     numericSeparator: false,
   });
-  return inspectConstructor(`Date(${dateSource})`, { useNew, parenthesis });
+  return inspectConstructor(`Date(${dateSource})`, {
+    useNew,
+    parenthesis,
+  });
 };
 
 const inspectFunction = (
@@ -1014,29 +1017,16 @@ const TIME_DICTIONARY_EN = {
   second: { long: "second", plural: "seconds", short: "s" },
   joinDuration: (primary, remaining) => `${primary} and ${remaining}`,
 };
-const TIME_DICTIONARY_FR = {
-  year: { long: "an", plural: "ans", short: "a" },
-  month: { long: "mois", plural: "mois", short: "m" },
-  week: { long: "semaine", plural: "semaines", short: "s" },
-  day: { long: "jour", plural: "jours", short: "j" },
-  hour: { long: "heure", plural: "heures", short: "h" },
-  minute: { long: "minute", plural: "minutes", short: "m" },
-  second: { long: "seconde", plural: "secondes", short: "s" },
-  joinDuration: (primary, remaining) => `${primary} et ${remaining}`,
-};
 
 const humanizeEllapsedTime = (
   ms,
-  {
-    short,
-    lang = "en",
-    timeDictionnary = lang === "fr" ? TIME_DICTIONARY_FR : TIME_DICTIONARY_EN,
-  } = {},
+  { short, timeDictionnary = TIME_DICTIONARY_EN } = {},
 ) => {
   if (ms < 1000) {
-    return short
-      ? `0${timeDictionnary.second.short}`
-      : `0 ${timeDictionnary.second.long}`;
+    if (short) {
+      return `0${timeDictionnary.second.short}`;
+    }
+    return `0 ${timeDictionnary.second.long}`;
   }
   const { primary, remaining } = parseMs(ms);
   if (!remaining) {
@@ -1068,33 +1058,52 @@ const inspectEllapsedUnit = (unit, { short, timeDictionnary }) => {
   return `${count} ${unitText}`;
 };
 
+/**
+ * Converts a duration in milliseconds into a human-readable string intended for display in
+ * CLI output — where readability matters more than precision.
+ *
+ * - Values below 1ms are displayed as "0 second". Sub-millisecond durations are not
+ *   meaningful at human scale, and showing "0.0001 second" (or switching to a "millisecond"
+ *   unit) would hurt readability. The chosen trade-off is to always use "second" as the
+ *   smallest unit and accept the loss of precision for very small values.
+ * - Values below 1s are displayed in fractional seconds (e.g. "0.05 second").
+ * - Values are expressed using the two most significant units (e.g. "1 hour and 23 minutes").
+ * - Rounding never causes a value to display as the next unit boundary
+ *   (e.g. 59_999ms → "59.9 seconds", never "60 seconds").
+ *
+ * @param {number} ms - Duration in milliseconds.
+ * @param {object} [options]
+ * @param {boolean} [options.short=false] - Use compact unit symbols (e.g. "1h and 23m").
+ * @param {boolean} [options.rounded=true] - Round the last displayed digit. When false, truncates instead.
+ * @param {number} [options.decimals] - Override the number of decimal places shown.
+ * @returns {string}
+ */
 const humanizeDuration = (
   ms,
   {
     short,
     rounded = true,
     decimals,
-    lang = "en",
-    timeDictionnary = lang === "fr" ? TIME_DICTIONARY_FR : TIME_DICTIONARY_EN,
+    timeDictionnary = TIME_DICTIONARY_EN,
   } = {},
 ) => {
-  // 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
-      ? `0${timeDictionnary.second.short}`
-      : `0 ${timeDictionnary.second.long}`;
+    if (short) {
+      return `0${timeDictionnary.second.short}`;
+    }
+    return `0 ${timeDictionnary.second.long}`;
   }
   const { primary, remaining } = parseMs(ms);
   if (!remaining) {
+    const primaryUnitIndex = UNIT_KEYS.indexOf(primary.name);
+    const nextUnitName = UNIT_KEYS[primaryUnitIndex - 1];
+    const maxCount = nextUnitName
+      ? UNIT_MS[nextUnitName] / UNIT_MS[primary.name]
+      : null;
     return humanizeDurationUnit(primary, {
       decimals:
         decimals === undefined ? (primary.name === "second" ? 1 : 0) : decimals,
+      maxCount,
       short,
       rounded,
       timeDictionnary,
@@ -1112,15 +1121,23 @@ const humanizeDuration = (
     rounded,
     timeDictionnary,
   });
+  if (short) {
+    return `${primaryText}${remainingText}`;
+  }
   return timeDictionnary.joinDuration(primaryText, remainingText);
 };
 const humanizeDurationUnit = (
   unit,
-  { decimals, short, rounded, timeDictionnary },
+  { decimals, maxCount, short, rounded, timeDictionnary },
 ) => {
-  const count = rounded
+  let count = rounded
     ? setRoundedPrecision(unit.count, { decimals })
     : setPrecision(unit.count, { decimals });
+  if (maxCount !== null && maxCount !== undefined && count >= maxCount) {
+    // Prevent rounding up to the next unit boundary (e.g. 59.999s → 60s → cap to 59.9s)
+    const factor = Math.pow(10, decimals ?? 0);
+    count = Math.floor(unit.count * factor) / factor;
+  }
   const name = unit.name;
   if (short) {
     const unitText = timeDictionnary[name].short;
@@ -1173,6 +1190,17 @@ const parseMs = (ms) => {
       },
     };
   }
+  // When remaining rounds up to a full next-unit (e.g. 59.999s rounds to 60s = 1min),
+  // drop the remaining to avoid displaying "59 minutes and 60 seconds".
+  const remainingUnitMs = UNIT_MS[remainingUnitName];
+  const nextUnitMs = UNIT_MS[firstUnitName];
+  const maxRemainingCount = nextUnitMs / remainingUnitMs; // e.g. 60 for seconds-in-a-minute
+  // Cap remaining so it never rounds up to the next unit boundary
+  // (e.g. 59.5s stays as 59s instead of rounding to 60s = 1min)
+  const cappedRemainingCount =
+    remainingUnitCount >= maxRemainingCount - 1
+      ? maxRemainingCount - 1
+      : remainingUnitCount;
   // - 1 year and 1 month is great
   return {
     primary: {
@@ -1181,7 +1209,7 @@ const parseMs = (ms) => {
     },
     remaining: {
       name: remainingUnitName,
-      count: remainingUnitCount,
+      count: cappedRemainingCount,
     },
   };
 };
@@ -1701,23 +1729,122 @@ const error = (...args) => console.error(...args);
 
 const errorDisabled = () => {};
 
+// Whole-cluster zero-width: Default_Ignorable, Control, Format, Mark, Surrogate
+const zeroWidthClusterRegex =
+  /^[\p{Default_Ignorable_Code_Point}\p{Control}\p{Format}\p{Mark}\p{Surrogate}]+$/v;
+
+// Strip leading non-printing chars to get the first visible scalar of a cluster
+const leadingNonPrintingRegex =
+  /^[\p{Default_Ignorable_Code_Point}\p{Control}\p{Format}\p{Mark}\p{Surrogate}]+/v;
+
+// RGI emoji sequences (e.g. flag sequences, ZWJ families, keycap+VS16)
+const rgiEmojiRegex = /^\p{RGI_Emoji}$/v;
+
+// Unqualified keycap: digit/# /* + combining enclosing keycap (no VS16)
+const unqualifiedKeycapRegex = /^[\d#*]\u20E3$/;
+const extendedPictographicRegex = /\p{Extended_Pictographic}/gv;
+
+const isDoubleWidthNonRgiEmojiSequence = (segment) => {
+  if (segment.length > 50) {
+    return false;
+  }
+  if (unqualifiedKeycapRegex.test(segment)) {
+    return true;
+  }
+  // ZWJ sequences with 2+ Extended_Pictographic
+  if (segment.includes("\u200D")) {
+    const pictographics = segment.match(extendedPictographicRegex);
+    return pictographics !== null && pictographics.length >= 2;
+  }
+  return false;
+};
+
+const baseVisible = (segment) => {
+  return segment.replace(leadingNonPrintingRegex, "");
+};
+
+const isHangulLeadingJamo = (cp) => {
+  return (cp >= 0x11_00 && cp <= 0x11_5f) || (cp >= 0xa9_60 && cp <= 0xa9_7c);
+};
+const isHangulVowelJamo = (cp) => {
+  return (cp >= 0x11_60 && cp <= 0x11_a7) || (cp >= 0xd7_b0 && cp <= 0xd7_c6);
+};
+const isHangulTrailingJamo = (cp) => {
+  return (cp >= 0x11_a8 && cp <= 0x11_ff) || (cp >= 0xd7_cb && cp <= 0xd7_fb);
+};
+const isHangulJamo = (cp) => {
+  return (
+    isHangulLeadingJamo(cp) || isHangulVowelJamo(cp) || isHangulTrailingJamo(cp)
+  );
+};
+
+const hangulClusterWidth = (visibleSegment, eastAsianWidthOptions) => {
+  const codePoints = [];
+  for (const character of visibleSegment) {
+    if (zeroWidthClusterRegex.test(character)) {
+      continue;
+    }
+    codePoints.push(character.codePointAt(0));
+  }
+  if (codePoints.length === 0) {
+    return undefined;
+  }
+  let width = 0;
+  for (let index = 0; index < codePoints.length; index++) {
+    const codePoint = codePoints[index];
+    if (!isHangulJamo(codePoint)) {
+      if (width === 0) {
+        return undefined;
+      }
+      for (let remaining = index; remaining < codePoints.length; remaining++) {
+        width += eastAsianWidth(codePoints[remaining], eastAsianWidthOptions);
+      }
+      return width;
+    }
+    if (
+      isHangulLeadingJamo(codePoint) &&
+      isHangulVowelJamo(codePoints[index + 1])
+    ) {
+      width += 2;
+      index += isHangulTrailingJamo(codePoints[index + 2]) ? 2 : 1;
+      continue;
+    }
+    width += eastAsianWidth(codePoint, eastAsianWidthOptions);
+  }
+  return width;
+};
+
+const trailingHalfwidthWidth = (visibleSegment, eastAsianWidthOptions) => {
+  let extra = 0;
+  let first = true;
+  for (const character of visibleSegment) {
+    if (first) {
+      first = false;
+      continue;
+    }
+    if (character >= "\uFF00" && character <= "\uFFEF") {
+      extra += eastAsianWidth(character.codePointAt(0), eastAsianWidthOptions);
+    }
+  }
+  return extra;
+};
+
 const createMeasureTextWidth = ({ stripAnsi }) => {
   const segmenter = new Intl.Segmenter();
-  const defaultIgnorableCodePointRegex = /^\p{Default_Ignorable_Code_Point}$/u;
 
   const measureTextWidth = (
     string,
-    {
-      ambiguousIsNarrow = true,
-      countAnsiEscapeCodes = false,
-      skipEmojis = false,
-    } = {},
+    { ambiguousIsNarrow = true, countAnsiEscapeCodes = false } = {},
   ) => {
     if (typeof string !== "string" || string.length === 0) {
       return 0;
     }
 
-    if (!countAnsiEscapeCodes) {
+    // Only strip ANSI when escape codes are actually present
+    if (
+      !countAnsiEscapeCodes &&
+      (string.includes("\u001B") || string.includes("\u009B"))
+    ) {
       string = stripAnsi(string);
     }
 
@@ -1725,70 +1852,54 @@ const createMeasureTextWidth = ({ stripAnsi }) => {
       return 0;
     }
 
+    // Fast path: printable ASCII needs no segmenter or EAW lookup
+    if (/^[\u0020-\u007E]*$/.test(string)) {
+      return string.length;
+    }
+
     let width = 0;
     const eastAsianWidthOptions = { ambiguousAsWide: !ambiguousIsNarrow };
 
-    for (const { segment: character } of segmenter.segment(string)) {
-      const codePoint = character.codePointAt(0);
-
-      // Ignore control characters
-      if (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f)) {
+    for (const { segment } of segmenter.segment(string)) {
+      if (zeroWidthClusterRegex.test(segment)) {
         continue;
       }
 
-      // Ignore zero-width characters
+      // RGI emoji + unqualified emoji sequences are double-width
       if (
-        (codePoint >= 0x20_0b && codePoint <= 0x20_0f) || // Zero-width space, non-joiner, joiner, left-to-right mark, right-to-left mark
-        codePoint === 0xfe_ff // Zero-width no-break space
+        rgiEmojiRegex.test(segment) ||
+        isDoubleWidthNonRgiEmojiSequence(segment)
       ) {
+        if (process.env.CAPTURING_SIDE_EFFECTS && segment === "✔️") {
+          width += 2;
+          continue;
+        }
+        width += 2;
         continue;
       }
 
-      // Ignore combining characters
-      if (
-        (codePoint >= 0x3_00 && codePoint <= 0x3_6f) || // Combining diacritical marks
-        (codePoint >= 0x1a_b0 && codePoint <= 0x1a_ff) || // Combining diacritical marks extended
-        (codePoint >= 0x1d_c0 && codePoint <= 0x1d_ff) || // Combining diacritical marks supplement
-        (codePoint >= 0x20_d0 && codePoint <= 0x20_ff) || // Combining diacritical marks for symbols
-        (codePoint >= 0xfe_20 && codePoint <= 0xfe_2f) // Combining half marks
-      ) {
-        continue;
-      }
-
-      // Ignore surrogate pairs
-      if (codePoint >= 0xd8_00 && codePoint <= 0xdf_ff) {
-        continue;
-      }
-
-      // Ignore variation selectors
-      if (codePoint >= 0xfe_00 && codePoint <= 0xfe_0f) {
-        continue;
-      }
-
-      // This covers some of the above cases, but we still keep them for performance reasons.
-      if (defaultIgnorableCodePointRegex.test(character)) {
-        continue;
-      }
+      const visibleSegment = baseVisible(segment);
 
-      if (!skipEmojis && emojiRegex().test(character)) {
-        if (process.env.CAPTURING_SIDE_EFFECTS) {
-          if (character === "✔️") {
-            width += 2;
-            continue;
-          }
-        }
-        width += measureTextWidth(character, {
-          skipEmojis: true,
-          countAnsiEscapeCodes: true, // to skip call to stripAnsi
-        });
+      const hangulWidth = hangulClusterWidth(
+        visibleSegment,
+        eastAsianWidthOptions,
+      );
+      if (hangulWidth !== undefined) {
+        width += hangulWidth;
         continue;
       }
 
+      // EAW of the cluster's first visible scalar
+      const codePoint = visibleSegment.codePointAt(0);
       width += eastAsianWidth(codePoint, eastAsianWidthOptions);
+
+      // Add width for trailing Halfwidth/Fullwidth Forms (e.g. ﾞ, ﾟ, ｰ)
+      width += trailingHalfwidthWidth(visibleSegment, eastAsianWidthOptions);
     }
 
     return width;
   };
+
   return measureTextWidth;
 };