@allternit/gizzi-code 1.0.0

package/src/utils/format.js

@@ -0,0 +1,230 @@
+/**
+ * @fileoverview Format utilities for gizzi-code integration
+ * @module utils/format
+ *
+ * Provides formatting utilities for durations, byte sizes, and numbers.
+ * These functions are commonly used in CLI output and display components.
+ */
+/**
+ * Time unit definitions for duration formatting
+ * @constant {Record<string, number>}
+ */
+const TIME_UNITS = {
+    millisecond: 1,
+    second: 1000,
+    minute: 60 * 1000,
+    hour: 60 * 60 * 1000,
+    day: 24 * 60 * 60 * 1000,
+    week: 7 * 24 * 60 * 60 * 1000,
+    month: 30 * 24 * 60 * 60 * 1000,
+    year: 365 * 24 * 60 * 60 * 1000,
+};
+/**
+ * Byte unit definitions for size formatting
+ * @constant {string[]}
+ */
+const BYTE_UNITS = ['B', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB'];
+/**
+ * Formats a duration in milliseconds to a human-readable string
+ *
+ * @param {number} ms - Duration in milliseconds
+ * @param {DurationFormatOptions} [options] - Format options
+ * @returns {string} Formatted duration string
+ * @example
+ * ```typescript
+ * formatDuration(5000); // "5s"
+ * formatDuration(65000); // "1m 5s"
+ * formatDuration(3600000); // "1h"
+ * formatDuration(90000, { style: 'long' }); // "1 minute 30 seconds"
+ * ```
+ */
+export function formatDuration(ms, options = {}) {
+    const { style = 'auto', maxUnits = 2, includeMs = false, round = false, } = options;
+    // Handle edge cases
+    if (!Number.isFinite(ms) || ms < 0) {
+        return style === 'long' ? 'unknown duration' : '--';
+    }
+    if (ms === 0) {
+        return style === 'long' ? '0 seconds' : '0s';
+    }
+    // Round if requested
+    const duration = round ? Math.round(ms) : ms;
+    // Determine appropriate units
+    const units = [
+        { value: TIME_UNITS.year, short: 'y', long: 'year' },
+        { value: TIME_UNITS.month, short: 'mo', long: 'month' },
+        { value: TIME_UNITS.week, short: 'w', long: 'week' },
+        { value: TIME_UNITS.day, short: 'd', long: 'day' },
+        { value: TIME_UNITS.hour, short: 'h', long: 'hour' },
+        { value: TIME_UNITS.minute, short: 'm', long: 'minute' },
+        { value: TIME_UNITS.second, short: 's', long: 'second' },
+    ];
+    // Add milliseconds if requested
+    if (includeMs || duration < TIME_UNITS.second) {
+        units.push({ value: TIME_UNITS.millisecond, short: 'ms', long: 'millisecond' });
+    }
+    const parts = [];
+    let remaining = Math.abs(duration);
+    for (const unit of units) {
+        if (remaining >= unit.value) {
+            const count = Math.floor(remaining / unit.value);
+            remaining %= unit.value;
+            const useLong = style === 'long';
+            const unitStr = useLong
+                ? `${unit.long}${count !== 1 ? 's' : ''}`
+                : unit.short;
+            parts.push(useLong ? `${count} ${unitStr}` : `${count}${unitStr}`);
+            if (parts.length >= maxUnits) {
+                break;
+            }
+        }
+    }
+    if (parts.length === 0) {
+        return style === 'long' ? '0 seconds' : '0s';
+    }
+    return parts.join(style === 'long' ? ' ' : ' ');
+}
+/**
+ * Formats a byte size to a human-readable string
+ *
+ * @param {number} bytes - Size in bytes
+ * @param {ByteFormatOptions} [options] - Format options
+ * @returns {string} Formatted size string
+ * @example
+ * ```typescript
+ * formatBytes(1024); // "1 KB"
+ * formatBytes(1536); // "1.50 KB"
+ * formatBytes(1048576); // "1 MB"
+ * formatBytes(1024, { binary: true }); // "1 KiB"
+ * ```
+ */
+export function formatBytes(bytes, options = {}) {
+    const { decimals = 2, binary = false, space = true } = options;
+    // Handle edge cases
+    if (!Number.isFinite(bytes)) {
+        return '0 B';
+    }
+    const absBytes = Math.abs(bytes);
+    if (absBytes === 0) {
+        return '0 B';
+    }
+    // Use 1024 for binary (KiB, MiB) or 1000 for decimal (KB, MB)
+    const base = binary ? 1024 : 1000;
+    const binarySuffix = binary ? 'i' : '';
+    // Find appropriate unit
+    const exponent = Math.min(Math.floor(Math.log(absBytes) / Math.log(base)), BYTE_UNITS.length - 1);
+    const value = bytes / Math.pow(base, exponent);
+    const unit = BYTE_UNITS[exponent] + (exponent > 0 ? binarySuffix : '');
+    // Format with specified decimal places
+    const formattedValue = value.toFixed(decimals);
+    const trimmedValue = parseFloat(formattedValue).toString();
+    return space ? `${trimmedValue} ${unit}` : `${trimmedValue}${unit}`;
+}
+/**
+ * Formats a number with locale-aware formatting
+ *
+ * @param {number} num - Number to format
+ * @param {NumberFormatOptions} [options] - Format options
+ * @returns {string} Formatted number string
+ * @example
+ * ```typescript
+ * formatNumber(1234567); // "1,234,567"
+ * formatNumber(1234.5678, { maximumFractionDigits: 2 }); // "1,234.57"
+ * formatNumber(0.001234, { minimumFractionDigits: 6 }); // "0.001234"
+ * ```
+ */
+export function formatNumber(num, options = {}) {
+    const { minimumFractionDigits, maximumFractionDigits = 2, useGrouping = true, locale = 'en-US', } = options;
+    // Handle edge cases
+    if (!Number.isFinite(num)) {
+        if (Number.isNaN(num))
+            return 'NaN';
+        return num > 0 ? '∞' : '-∞';
+    }
+    try {
+        return new Intl.NumberFormat(locale, {
+            minimumFractionDigits,
+            maximumFractionDigits,
+            useGrouping,
+        }).format(num);
+    }
+    catch {
+        // Fallback for environments without Intl support
+        const absNum = Math.abs(num);
+        const sign = num < 0 ? '-' : '';
+        // Handle integer part with grouping
+        const integerPart = Math.floor(absNum);
+        const fractionPart = absNum - integerPart;
+        let result = useGrouping
+            ? integerPart.toLocaleString(locale)
+            : integerPart.toString();
+        // Add fraction part if needed
+        const minDecimals = minimumFractionDigits ?? 0;
+        const maxDecimals = maximumFractionDigits ?? 2;
+        if (fractionPart > 0 || minDecimals > 0) {
+            const fractionStr = fractionPart
+                .toFixed(maxDecimals)
+                .slice(2)
+                .padEnd(minDecimals, '0');
+            // Trim trailing zeros if no minimum required
+            const trimmedFraction = minDecimals === 0
+                ? fractionStr.replace(/0+$/, '')
+                : fractionStr;
+            if (trimmedFraction.length > 0) {
+                result += '.' + trimmedFraction;
+            }
+        }
+        return sign + result;
+    }
+}
+/**
+ * Formats a number as a percentage
+ *
+ * @param {number} value - Value to format (0.5 = 50%)
+ * @param {number} [decimals=1] - Number of decimal places
+ * @returns {string} Formatted percentage string
+ * @example
+ * ```typescript
+ * formatPercentage(0.5); // "50%"
+ * formatPercentage(0.1234, 2); // "12.34%"
+ * ```
+ */
+export function formatPercentage(value, decimals = 1) {
+    if (!Number.isFinite(value)) {
+        return '--%';
+    }
+    return `${(value * 100).toFixed(decimals)}%`;
+}
+/**
+ * Formats a number as compact notation (1K, 1M, etc.)
+ *
+ * @param {number} num - Number to format
+ * @param {number} [decimals=1] - Number of decimal places
+ * @returns {string} Compact formatted string
+ * @example
+ * ```typescript
+ * formatCompact(1234); // "1.2K"
+ * formatCompact(1000000); // "1M"
+ * formatCompact(1234567890); // "1.2B"
+ * ```
+ */
+export function formatCompact(num, decimals = 1) {
+    if (!Number.isFinite(num) || num === 0) {
+        return '0';
+    }
+    const absNum = Math.abs(num);
+    const sign = num < 0 ? '-' : '';
+    const units = ['', 'K', 'M', 'B', 'T'];
+    const unitIndex = Math.min(Math.floor(Math.log10(absNum) / 3), units.length - 1);
+    const value = absNum / Math.pow(1000, unitIndex);
+    const formatted = value.toFixed(decimals).replace(/\.0+$|(\.[0-9]*[1-9])0+$/, '$1');
+    return `${sign}${formatted}${units[unitIndex]}`;
+}
+// Default export
+export default {
+    formatDuration,
+    formatBytes,
+    formatNumber,
+    formatPercentage,
+    formatCompact,
+};

package/src/utils/format.ts

@@ -0,0 +1,336 @@
+/**
+ * @fileoverview Format utilities for gizzi-code integration
+ * @module utils/format
+ *
+ * Provides formatting utilities for durations, byte sizes, and numbers.
+ * These functions are commonly used in CLI output and display components.
+ */
+
+/**
+ * Time unit definitions for duration formatting
+ * @constant {Record<string, number>}
+ */
+const TIME_UNITS = {
+  millisecond: 1,
+  second: 1000,
+  minute: 60 * 1000,
+  hour: 60 * 60 * 1000,
+  day: 24 * 60 * 60 * 1000,
+  week: 7 * 24 * 60 * 60 * 1000,
+  month: 30 * 24 * 60 * 60 * 1000,
+  year: 365 * 24 * 60 * 60 * 1000,
+};
+
+/**
+ * Byte unit definitions for size formatting
+ * @constant {string[]}
+ */
+const BYTE_UNITS = ['B', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB'];
+
+/**
+ * Number format options
+ * @interface NumberFormatOptions
+ */
+export interface NumberFormatOptions {
+  /** Minimum number of decimal places */
+  readonly minimumFractionDigits?: number;
+  /** Maximum number of decimal places */
+  readonly maximumFractionDigits?: number;
+  /** Use thousands separator */
+  readonly useGrouping?: boolean;
+  /** Locale for formatting (default: 'en-US') */
+  readonly locale?: string;
+}
+
+/**
+ * Duration format options
+ * @interface DurationFormatOptions
+ */
+export interface DurationFormatOptions {
+  /** Format style (default: 'auto') */
+  readonly style?: 'short' | 'long' | 'narrow' | 'auto';
+  /** Maximum number of units to display (default: 2) */
+  readonly maxUnits?: number;
+  /** Include milliseconds in output */
+  readonly includeMs?: boolean;
+  /** Round to nearest unit */
+  readonly round?: boolean;
+}
+
+/**
+ * Byte format options
+ * @interface ByteFormatOptions
+ */
+export interface ByteFormatOptions {
+  /** Number of decimal places (default: 2) */
+  readonly decimals?: number;
+  /** Use binary units (KiB, MiB) instead of decimal (KB, MB) */
+  readonly binary?: boolean;
+  /** Include space between value and unit */
+  readonly space?: boolean;
+}
+
+/**
+ * Formats a duration in milliseconds to a human-readable string
+ *
+ * @param {number} ms - Duration in milliseconds
+ * @param {DurationFormatOptions} [options] - Format options
+ * @returns {string} Formatted duration string
+ * @example
+ * ```typescript
+ * formatDuration(5000); // "5s"
+ * formatDuration(65000); // "1m 5s"
+ * formatDuration(3600000); // "1h"
+ * formatDuration(90000, { style: 'long' }); // "1 minute 30 seconds"
+ * ```
+ */
+export function formatDuration(
+  ms: number,
+  options: DurationFormatOptions = {}
+): string {
+  const {
+    style = 'auto',
+    maxUnits = 2,
+    includeMs = false,
+    round = false,
+  } = options;
+
+  // Handle edge cases
+  if (!Number.isFinite(ms) || ms < 0) {
+    return style === 'long' ? 'unknown duration' : '--';
+  }
+
+  if (ms === 0) {
+    return style === 'long' ? '0 seconds' : '0s';
+  }
+
+  // Round if requested
+  const duration = round ? Math.round(ms) : ms;
+
+  // Determine appropriate units
+  const units: Array<{ value: number; short: string; long: string }> = [
+    { value: TIME_UNITS.year, short: 'y', long: 'year' },
+    { value: TIME_UNITS.month, short: 'mo', long: 'month' },
+    { value: TIME_UNITS.week, short: 'w', long: 'week' },
+    { value: TIME_UNITS.day, short: 'd', long: 'day' },
+    { value: TIME_UNITS.hour, short: 'h', long: 'hour' },
+    { value: TIME_UNITS.minute, short: 'm', long: 'minute' },
+    { value: TIME_UNITS.second, short: 's', long: 'second' },
+  ];
+
+  // Add milliseconds if requested
+  if (includeMs || duration < TIME_UNITS.second) {
+    units.push({ value: TIME_UNITS.millisecond, short: 'ms', long: 'millisecond' });
+  }
+
+  const parts: string[] = [];
+  let remaining = Math.abs(duration);
+
+  for (const unit of units) {
+    if (remaining >= unit.value) {
+      const count = Math.floor(remaining / unit.value);
+      remaining %= unit.value;
+
+      const useLong = style === 'long';
+      const unitStr = useLong
+        ? `${unit.long}${count !== 1 ? 's' : ''}`
+        : unit.short;
+
+      parts.push(useLong ? `${count} ${unitStr}` : `${count}${unitStr}`);
+
+      if (parts.length >= maxUnits) {
+        break;
+      }
+    }
+  }
+
+  if (parts.length === 0) {
+    return style === 'long' ? '0 seconds' : '0s';
+  }
+
+  return parts.join(style === 'long' ? ' ' : ' ');
+}
+
+/**
+ * Formats a byte size to a human-readable string
+ *
+ * @param {number} bytes - Size in bytes
+ * @param {ByteFormatOptions} [options] - Format options
+ * @returns {string} Formatted size string
+ * @example
+ * ```typescript
+ * formatBytes(1024); // "1 KB"
+ * formatBytes(1536); // "1.50 KB"
+ * formatBytes(1048576); // "1 MB"
+ * formatBytes(1024, { binary: true }); // "1 KiB"
+ * ```
+ */
+export function formatBytes(
+  bytes: number,
+  options: ByteFormatOptions = {}
+): string {
+  const { decimals = 2, binary = false, space = true } = options;
+
+  // Handle edge cases
+  if (!Number.isFinite(bytes)) {
+    return '0 B';
+  }
+
+  const absBytes = Math.abs(bytes);
+
+  if (absBytes === 0) {
+    return '0 B';
+  }
+
+  // Use 1024 for binary (KiB, MiB) or 1000 for decimal (KB, MB)
+  const base = binary ? 1024 : 1000;
+  const binarySuffix = binary ? 'i' : '';
+
+  // Find appropriate unit
+  const exponent = Math.min(
+    Math.floor(Math.log(absBytes) / Math.log(base)),
+    BYTE_UNITS.length - 1
+  );
+
+  const value = bytes / Math.pow(base, exponent);
+  const unit = BYTE_UNITS[exponent] + (exponent > 0 ? binarySuffix : '');
+
+  // Format with specified decimal places
+  const formattedValue = value.toFixed(decimals);
+  const trimmedValue = parseFloat(formattedValue).toString();
+
+  return space ? `${trimmedValue} ${unit}` : `${trimmedValue}${unit}`;
+}
+
+/**
+ * Formats a number with locale-aware formatting
+ *
+ * @param {number} num - Number to format
+ * @param {NumberFormatOptions} [options] - Format options
+ * @returns {string} Formatted number string
+ * @example
+ * ```typescript
+ * formatNumber(1234567); // "1,234,567"
+ * formatNumber(1234.5678, { maximumFractionDigits: 2 }); // "1,234.57"
+ * formatNumber(0.001234, { minimumFractionDigits: 6 }); // "0.001234"
+ * ```
+ */
+export function formatNumber(
+  num: number,
+  options: NumberFormatOptions = {}
+): string {
+  const {
+    minimumFractionDigits,
+    maximumFractionDigits = 2,
+    useGrouping = true,
+    locale = 'en-US',
+  } = options;
+
+  // Handle edge cases
+  if (!Number.isFinite(num)) {
+    if (Number.isNaN(num)) return 'NaN';
+    return num > 0 ? '∞' : '-∞';
+  }
+
+  try {
+    return new Intl.NumberFormat(locale, {
+      minimumFractionDigits,
+      maximumFractionDigits,
+      useGrouping,
+    }).format(num);
+  } catch {
+    // Fallback for environments without Intl support
+    const absNum = Math.abs(num);
+    const sign = num < 0 ? '-' : '';
+
+    // Handle integer part with grouping
+    const integerPart = Math.floor(absNum);
+    const fractionPart = absNum - integerPart;
+
+    let result = useGrouping
+      ? integerPart.toLocaleString(locale)
+      : integerPart.toString();
+
+    // Add fraction part if needed
+    const minDecimals = minimumFractionDigits ?? 0;
+    const maxDecimals = maximumFractionDigits ?? 2;
+
+    if (fractionPart > 0 || minDecimals > 0) {
+      const fractionStr = fractionPart
+        .toFixed(maxDecimals)
+        .slice(2)
+        .padEnd(minDecimals, '0');
+      // Trim trailing zeros if no minimum required
+      const trimmedFraction =
+        minDecimals === 0
+          ? fractionStr.replace(/0+$/, '')
+          : fractionStr;
+      if (trimmedFraction.length > 0) {
+        result += '.' + trimmedFraction;
+      }
+    }
+
+    return sign + result;
+  }
+}
+
+/**
+ * Formats a number as a percentage
+ *
+ * @param {number} value - Value to format (0.5 = 50%)
+ * @param {number} [decimals=1] - Number of decimal places
+ * @returns {string} Formatted percentage string
+ * @example
+ * ```typescript
+ * formatPercentage(0.5); // "50%"
+ * formatPercentage(0.1234, 2); // "12.34%"
+ * ```
+ */
+export function formatPercentage(value: number, decimals: number = 1): string {
+  if (!Number.isFinite(value)) {
+    return '--%';
+  }
+  return `${(value * 100).toFixed(decimals)}%`;
+}
+
+/**
+ * Formats a number as compact notation (1K, 1M, etc.)
+ *
+ * @param {number} num - Number to format
+ * @param {number} [decimals=1] - Number of decimal places
+ * @returns {string} Compact formatted string
+ * @example
+ * ```typescript
+ * formatCompact(1234); // "1.2K"
+ * formatCompact(1000000); // "1M"
+ * formatCompact(1234567890); // "1.2B"
+ * ```
+ */
+export function formatCompact(num: number, decimals: number = 1): string {
+  if (!Number.isFinite(num) || num === 0) {
+    return '0';
+  }
+
+  const absNum = Math.abs(num);
+  const sign = num < 0 ? '-' : '';
+
+  const units = ['', 'K', 'M', 'B', 'T'];
+  const unitIndex = Math.min(
+    Math.floor(Math.log10(absNum) / 3),
+    units.length - 1
+  );
+
+  const value = absNum / Math.pow(1000, unitIndex);
+  const formatted = value.toFixed(decimals).replace(/\.0+$|(\.[0-9]*[1-9])0+$/, '$1');
+
+  return `${sign}${formatted}${units[unitIndex]}`;
+}
+
+// Default export
+export default {
+  formatDuration,
+  formatBytes,
+  formatNumber,
+  formatPercentage,
+  formatCompact,
+};