chore: release version 5.5.2 with new sign feature for number and percentage formatting

Author: ogroppo

CHANGELOG.md

@@ -1,5 +1,11 @@
 # deverything
 
+## 5.5.2
+
+### Patch Changes
+
+- sign
+
 ## 5.5.1
 
 ### Patch Changes
@@ -10,7 +16,7 @@
 
 ### Minor Changes
 
-- sortBySortdedKeys
+- sortBySortedKeys
 
 ## 5.4.0
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "deverything",
-  "version": "5.5.1",
+  "version": "5.5.2",
   "description": "Everything you need for Dev",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

src/formatters/formatNumber.test.ts

@@ -36,6 +36,32 @@ describe("formatNumber", () => {
     expect(formattedValue).toEqual("123,456.123");
   });
 
+  describe("sign", () => {
+    test("prefixes positive number with +", () => {
+      expect(formatNumber(1234, { sign: true })).toBe("+1,234");
+    });
+
+    test("no prefix for zero", () => {
+      expect(formatNumber(0, { sign: true })).toBe("0");
+    });
+
+    test("no prefix for negative", () => {
+      expect(formatNumber(-50, { sign: true })).toBe("-50");
+    });
+
+    test("prefixes positive compact value with +", () => {
+      expect(formatNumber(1500, { sign: true, compact: true })).toBe("+1.5K");
+    });
+
+    test("prefixes positive percentage with +", () => {
+      expect(formatNumber(0.25, { sign: true, percentage: true })).toBe("+25%");
+    });
+
+    test("no prefix for zero percentage", () => {
+      expect(formatNumber(0, { sign: true, percentage: true })).toBe("0%");
+    });
+  });
+
   describe("Percentage", () => {
     test("no digits", () => {
       const formattedValue = formatNumber(0.123456, { percentage: true });

src/formatters/formatNumber.ts

@@ -24,17 +24,25 @@ export const formatNumber = (
     maxDigits,
     percentage,
     unit = "",
+    sign = false,
   }: {
     compact?: boolean;
     maxDigits?: number;
     percentage?: boolean;
     unit?: string;
+    sign?: boolean;
   } = {}
 ): string => {
+  let prefix = "";
+
+  if (sign) {
+    prefix = value > 0 ? "+" : "";
+  }
+
   if (percentage) {
     const useValue = isNumber(value) ? value : 0;
     const number = (useValue * 100).toFixed(maxDigits || 0);
-    return `${number}%`;
+    return `${prefix}${number}%`;
   }
 
   // < 1 case
@@ -51,7 +59,7 @@ export const formatNumber = (
     const formatter = Intl.NumberFormat("en", {
       maximumSignificantDigits: maxDigits ?? 3,
     });
-    return `${formatter.format(scaled)}${tier.suffix}${unit}`;
+    return `${prefix}${formatter.format(scaled)}${tier.suffix}${unit}`;
   }
 
   // > 1 case
@@ -60,5 +68,5 @@ export const formatNumber = (
     maximumSignificantDigits: maxDigits,
   });
 
-  return `${formatter.format(value)}${unit}`;
+  return `${prefix}${formatter.format(value)}${unit}`;
 };

src/formatters/formatPercentage.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "vitest";
+import { formatPercentage, formatPercentageNumber } from "./formatPercentage";
+
+describe("formatPercentageNumber", () => {
+  test("converts ratio to percentage string", () => {
+    expect(formatPercentageNumber(0.5)).toBe("50");
+  });
+
+  test("respects digits option", () => {
+    expect(formatPercentageNumber(0.123456, { digits: 2 })).toBe("12.35");
+  });
+
+  test("clamps to -100 at minimum", () => {
+    expect(formatPercentageNumber(-0.5)).toBe("-50");
+    expect(formatPercentageNumber(-2)).toBe("-100");
+  });
+
+  test("clamps to 100 at maximum", () => {
+    expect(formatPercentageNumber(1.5)).toBe("100");
+  });
+
+  describe("sign", () => {
+    test("prefixes positive values with +", () => {
+      expect(formatPercentageNumber(0.25, { sign: true })).toBe("+25");
+    });
+
+    test("no prefix for zero", () => {
+      expect(formatPercentageNumber(0, { sign: true })).toBe("0");
+    });
+
+    test("negative value shows minus sign from the number", () => {
+      expect(formatPercentageNumber(-0.1, { sign: true })).toBe("-10");
+    });
+
+    test("respects digits alongside sign", () => {
+      expect(formatPercentageNumber(0.1234, { sign: true, digits: 2 })).toBe(
+        "+12.34"
+      );
+    });
+  });
+});
+
+describe("formatPercentage", () => {
+  test("appends % symbol", () => {
+    expect(formatPercentage(1)).toBe("100%");
+    expect(formatPercentage(0, { digits: 2 })).toBe("0.00%");
+  });
+
+  describe("sign", () => {
+    test("prefixes positive values with +", () => {
+      expect(formatPercentage(0.25, { sign: true })).toBe("+25%");
+    });
+
+    test("prefixes negative values with -", () => {
+      expect(formatPercentage(-0.25, { sign: true })).toBe("-25%");
+    });
+
+    test("no prefix for zero", () => {
+      expect(formatPercentage(0, { sign: true })).toBe("0%");
+    });
+
+    test("respects digits alongside sign", () => {
+      expect(formatPercentage(0.1234, { sign: true, digits: 2 })).toBe(
+        "+12.34%"
+      );
+    });
+  });
+});

src/formatters/formatPercentage.ts

@@ -8,13 +8,21 @@ export const formatPercentageNumber = (
   value: number,
   {
     digits,
+    sign,
   }: {
     digits?: number;
+    sign?: boolean;
   } = {}
 ): string => {
-  return `${clamp({
+  let prefix = "";
+
+  if (sign) {
+    prefix = value > 0 ? "+" : "";
+  }
+
+  return `${prefix}${clamp({
     number: value * 100,
-    min: 0,
+    min: -100,
     max: 100,
   }).toFixed(digits || 0)}`;
 };
@@ -28,9 +36,11 @@ export const formatPercentage = (
   value: number,
   {
     digits,
+    sign,
   }: {
     digits?: number;
+    sign?: boolean;
   } = {}
 ): string => {
-  return `${formatPercentageNumber(value, { digits })}%`;
+  return `${formatPercentageNumber(value, { digits, sign })}%`;
 };

src/formatters/formatProgress.ts

@@ -80,6 +80,26 @@ const calculateRemainingTime = (
   return formatRemainingTime(remainingSeconds);
 };
 
+/**
+ * Formats a progress indicator showing the current index, total, and completion percentage.
+ *
+ * When a `progressId` is provided, also estimates and appends the remaining time based on
+ * the rate of progress since the first call with that ID. Tracking state is automatically
+ * cleaned up once the final item is reached.
+ *
+ * @param index - Zero-based index of the current item being processed.
+ * @param total - Total number of items.
+ * @param options - Optional configuration.
+ * @param options.progressId - Stable identifier used to track throughput across calls and
+ *   compute a remaining-time estimate. Omit to skip time estimation.
+ * @returns A formatted string such as `"42/100 42.00%"` or `"42/100 42.00% (~3m 20s remaining)"`.
+ *
+ * @example
+ * for (const [i, item] of items.entries()) {
+ *   console.log(formatProgress(i, items.length, { progressId: "my-job" }));
+ *   await process(item);
+ * }
+ */
 export const formatProgress = (
   index: number,
   total: number,