@peernova/cuneiform-sf 1.0.2 → 1.0.4-beta.8

package/lib/utils/formatting/indicators.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Pure status indicator formatting utilities for CLI display output.
+ *
+ * All functions are pure (no side effects, no external state) and return
+ * formatted strings or labels for consistent status presentation across commands.
+ *
+ * @module utils/formatting/indicators
+ */
+/**
+ * Status types supported by the status symbol formatter.
+ */
+export type StatusType = 'success' | 'error' | 'warning' | 'info' | 'pending' | 'skip';
+/**
+ * Display style options for boolean formatting.
+ */
+export type BooleanDisplayStyle = 'yesNo' | 'enabledDisabled' | 'symbol';
+/**
+ * Options for controlling boolean display formatting.
+ */
+export type BooleanDisplayOptions = {
+    /** The display style to use. Default: 'yesNo'. */
+    readonly style?: BooleanDisplayStyle;
+};
+/**
+ * Volume level labels returned by the volume indicator.
+ */
+export type VolumeLevel = 'none' | 'low' | 'medium' | 'high';
+/**
+ * Configurable thresholds for volume classification.
+ */
+export type VolumeThresholds = {
+    /** Upper bound for 'low' volume (inclusive). Default: 100. */
+    readonly low?: number;
+    /** Upper bound for 'medium' volume (inclusive). Default: 10000. */
+    readonly medium?: number;
+};
+/**
+ * Returns a unicode symbol with a descriptive label for a given status.
+ *
+ * Maps each status type to a consistent symbol + text representation
+ * suitable for CLI output.
+ *
+ * @param status - The status type to display
+ * @returns A formatted status string, e.g. "✓ Success", "✗ Error"
+ *
+ * @example
+ * statusSymbol('success')   // "✓ Success"
+ * statusSymbol('error')     // "✗ Error"
+ * statusSymbol('warning')   // "! Warning"
+ * statusSymbol('info')      // "i Info"
+ * statusSymbol('pending')   // "○ Pending"
+ */
+export declare function statusSymbol(status: StatusType): string;
+/**
+ * Renders a boolean value as a human-readable display string.
+ *
+ * Supports multiple display styles: yes/no, enabled/disabled, and unicode symbols.
+ * Defaults to 'yesNo' style when no options are provided.
+ *
+ * @param value - The boolean value to display
+ * @param options - Display style options
+ * @returns A formatted boolean string, e.g. "Yes", "Disabled", "✓"
+ *
+ * @example
+ * booleanDisplay(true)                                // "Yes"
+ * booleanDisplay(false)                               // "No"
+ * booleanDisplay(true, { style: 'enabledDisabled' })  // "Enabled"
+ * booleanDisplay(false, { style: 'symbol' })          // "✗"
+ */
+export declare function booleanDisplay(value: boolean, options?: BooleanDisplayOptions): string;
+/**
+ * Classifies a count into a volume level based on configurable thresholds.
+ *
+ * Returns 'none' for zero, 'low' for counts up to the low threshold,
+ * 'medium' for counts up to the medium threshold, and 'high' for counts
+ * above the medium threshold.
+ *
+ * Negative counts are treated as 'none'.
+ *
+ * @param count - The count to classify
+ * @param thresholds - Optional custom thresholds (low default: 100, medium default: 10000)
+ * @returns The volume level: 'none', 'low', 'medium', or 'high'
+ *
+ * @example
+ * volumeIndicator(0)          // "none"
+ * volumeIndicator(50)         // "low"
+ * volumeIndicator(5000)       // "medium"
+ * volumeIndicator(50000)      // "high"
+ * volumeIndicator(50, { low: 10, medium: 100 })  // "medium"
+ */
+export declare function volumeIndicator(count: number, thresholds?: VolumeThresholds): VolumeLevel;
+/**
+ * Generates an ASCII progress bar with a percentage label.
+ *
+ * The bar is rendered using filled (█) and empty (░) block characters
+ * within square brackets, followed by the percentage. Handles edge cases:
+ * - 0/0 returns an empty bar at 0%
+ * - Negative values are clamped to 0%
+ * - Values exceeding total are clamped to 100%
+ *
+ * @param current - The current progress value
+ * @param total - The total/target value
+ * @param width - The bar width in characters (default: 20)
+ * @returns A formatted progress bar string, e.g. "[████████░░░░░░░░░░░░] 40%"
+ *
+ * @example
+ * completenessBar(40, 100)       // "[████████░░░░░░░░░░░░] 40%"
+ * completenessBar(100, 100)      // "[████████████████████] 100%"
+ * completenessBar(0, 100)        // "[░░░░░░░░░░░░░░░░░░░░] 0%"
+ * completenessBar(0, 0)          // "[░░░░░░░░░░░░░░░░░░░░] 0%"
+ * completenessBar(150, 100)      // "[████████████████████] 100%"
+ */
+export declare function completenessBar(current: number, total: number, width?: number): string;

package/lib/utils/formatting/indicators.js

@@ -0,0 +1,161 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+/**
+ * Mapping from status type to unicode symbol and label.
+ */
+const STATUS_MAP = {
+    success: { symbol: '\u2713', label: 'Success' },
+    error: { symbol: '\u2717', label: 'Error' },
+    warning: { symbol: '!', label: 'Warning' },
+    info: { symbol: 'i', label: 'Info' },
+    pending: { symbol: '\u25CB', label: 'Pending' },
+    skip: { symbol: '\u2192', label: 'Skip' },
+};
+/**
+ * Boolean display renderings indexed by style and truthiness.
+ */
+const BOOLEAN_DISPLAY_MAP = {
+    yesNo: { trueValue: 'Yes', falseValue: 'No' },
+    enabledDisabled: { trueValue: 'Enabled', falseValue: 'Disabled' },
+    symbol: { trueValue: '\u2713', falseValue: '\u2717' },
+};
+/**
+ * Default volume thresholds.
+ */
+const DEFAULT_VOLUME_THRESHOLDS = {
+    low: 100,
+    medium: 10_000,
+};
+/**
+ * Default progress bar width in characters.
+ */
+const DEFAULT_BAR_WIDTH = 20;
+/**
+ * Character used for the filled portion of the progress bar.
+ */
+const FILLED_CHAR = '\u2588';
+/**
+ * Character used for the empty portion of the progress bar.
+ */
+const EMPTY_CHAR = '\u2591';
+/**
+ * Returns a unicode symbol with a descriptive label for a given status.
+ *
+ * Maps each status type to a consistent symbol + text representation
+ * suitable for CLI output.
+ *
+ * @param status - The status type to display
+ * @returns A formatted status string, e.g. "✓ Success", "✗ Error"
+ *
+ * @example
+ * statusSymbol('success')   // "✓ Success"
+ * statusSymbol('error')     // "✗ Error"
+ * statusSymbol('warning')   // "! Warning"
+ * statusSymbol('info')      // "i Info"
+ * statusSymbol('pending')   // "○ Pending"
+ */
+export function statusSymbol(status) {
+    const entry = STATUS_MAP[status];
+    return `${entry.symbol} ${entry.label}`;
+}
+/**
+ * Renders a boolean value as a human-readable display string.
+ *
+ * Supports multiple display styles: yes/no, enabled/disabled, and unicode symbols.
+ * Defaults to 'yesNo' style when no options are provided.
+ *
+ * @param value - The boolean value to display
+ * @param options - Display style options
+ * @returns A formatted boolean string, e.g. "Yes", "Disabled", "✓"
+ *
+ * @example
+ * booleanDisplay(true)                                // "Yes"
+ * booleanDisplay(false)                               // "No"
+ * booleanDisplay(true, { style: 'enabledDisabled' })  // "Enabled"
+ * booleanDisplay(false, { style: 'symbol' })          // "✗"
+ */
+export function booleanDisplay(value, options) {
+    const style = options?.style ?? 'yesNo';
+    const mapping = BOOLEAN_DISPLAY_MAP[style];
+    return value ? mapping.trueValue : mapping.falseValue;
+}
+/**
+ * Classifies a count into a volume level based on configurable thresholds.
+ *
+ * Returns 'none' for zero, 'low' for counts up to the low threshold,
+ * 'medium' for counts up to the medium threshold, and 'high' for counts
+ * above the medium threshold.
+ *
+ * Negative counts are treated as 'none'.
+ *
+ * @param count - The count to classify
+ * @param thresholds - Optional custom thresholds (low default: 100, medium default: 10000)
+ * @returns The volume level: 'none', 'low', 'medium', or 'high'
+ *
+ * @example
+ * volumeIndicator(0)          // "none"
+ * volumeIndicator(50)         // "low"
+ * volumeIndicator(5000)       // "medium"
+ * volumeIndicator(50000)      // "high"
+ * volumeIndicator(50, { low: 10, medium: 100 })  // "medium"
+ */
+export function volumeIndicator(count, thresholds) {
+    if (count <= 0) {
+        return 'none';
+    }
+    const low = thresholds?.low ?? DEFAULT_VOLUME_THRESHOLDS.low;
+    const medium = thresholds?.medium ?? DEFAULT_VOLUME_THRESHOLDS.medium;
+    if (count <= low) {
+        return 'low';
+    }
+    if (count <= medium) {
+        return 'medium';
+    }
+    return 'high';
+}
+/**
+ * Generates an ASCII progress bar with a percentage label.
+ *
+ * The bar is rendered using filled (█) and empty (░) block characters
+ * within square brackets, followed by the percentage. Handles edge cases:
+ * - 0/0 returns an empty bar at 0%
+ * - Negative values are clamped to 0%
+ * - Values exceeding total are clamped to 100%
+ *
+ * @param current - The current progress value
+ * @param total - The total/target value
+ * @param width - The bar width in characters (default: 20)
+ * @returns A formatted progress bar string, e.g. "[████████░░░░░░░░░░░░] 40%"
+ *
+ * @example
+ * completenessBar(40, 100)       // "[████████░░░░░░░░░░░░] 40%"
+ * completenessBar(100, 100)      // "[████████████████████] 100%"
+ * completenessBar(0, 100)        // "[░░░░░░░░░░░░░░░░░░░░] 0%"
+ * completenessBar(0, 0)          // "[░░░░░░░░░░░░░░░░░░░░] 0%"
+ * completenessBar(150, 100)      // "[████████████████████] 100%"
+ */
+export function completenessBar(current, total, width = DEFAULT_BAR_WIDTH) {
+    const effectiveWidth = Math.max(1, Math.floor(width));
+    let ratio;
+    if (total <= 0 || current <= 0) {
+        ratio = 0;
+    }
+    else if (current >= total) {
+        ratio = 1;
+    }
+    else {
+        ratio = current / total;
+    }
+    const percentage = Math.round(ratio * 100);
+    const filledCount = Math.round(ratio * effectiveWidth);
+    const emptyCount = effectiveWidth - filledCount;
+    const filled = FILLED_CHAR.repeat(filledCount);
+    const empty = EMPTY_CHAR.repeat(emptyCount);
+    return `[${filled}${empty}] ${percentage}%`;
+}
+//# sourceMappingURL=indicators.js.map

package/lib/utils/formatting/indicators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indicators.js","sourceRoot":"","sources":["../../../src/utils/formatting/indicators.ts"],"names":[],"mappings":"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"}

package/lib/utils/formatting/loading-messages.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Pure loading message formatting utilities for CLI progress output.
+ *
+ * Generates contextual loading messages that describe what the CLI
+ * is doing, on what subject, and optionally in which org.
+ *
+ * All functions are pure (no side effects, no external state) and return
+ * formatted strings.
+ *
+ * @module utils/formatting/loading-messages
+ */
+/**
+ * Generates a contextual loading message for CLI progress display.
+ *
+ * Produces a human-readable string describing the current operation,
+ * suitable for use with spinners or progress indicators. The message
+ * follows the pattern: "Action Subject from OrgAlias..." or
+ * "Action Subject..." when no org is provided.
+ *
+ * @param action - The verb describing the operation (e.g. "Analyzing", "Fetching", "Exporting")
+ * @param subject - The target of the operation (e.g. "Account", "definitions", "field metadata")
+ * @param org - Optional org alias or username for context
+ * @returns A formatted loading message string ending with "..."
+ *
+ * @example
+ * loadingMessage('Analyzing', 'Account', 'myOrg')
+ * // "Analyzing Account from myOrg..."
+ *
+ * @example
+ * loadingMessage('Fetching', 'field metadata')
+ * // "Fetching field metadata..."
+ *
+ * @example
+ * loadingMessage('Exporting', '42 definitions', 'prod')
+ * // "Exporting 42 definitions from prod..."
+ */
+export declare function loadingMessage(action: string, subject: string, org?: string): string;

package/lib/utils/formatting/loading-messages.js

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+/**
+ * Pure loading message formatting utilities for CLI progress output.
+ *
+ * Generates contextual loading messages that describe what the CLI
+ * is doing, on what subject, and optionally in which org.
+ *
+ * All functions are pure (no side effects, no external state) and return
+ * formatted strings.
+ *
+ * @module utils/formatting/loading-messages
+ */
+/**
+ * Generates a contextual loading message for CLI progress display.
+ *
+ * Produces a human-readable string describing the current operation,
+ * suitable for use with spinners or progress indicators. The message
+ * follows the pattern: "Action Subject from OrgAlias..." or
+ * "Action Subject..." when no org is provided.
+ *
+ * @param action - The verb describing the operation (e.g. "Analyzing", "Fetching", "Exporting")
+ * @param subject - The target of the operation (e.g. "Account", "definitions", "field metadata")
+ * @param org - Optional org alias or username for context
+ * @returns A formatted loading message string ending with "..."
+ *
+ * @example
+ * loadingMessage('Analyzing', 'Account', 'myOrg')
+ * // "Analyzing Account from myOrg..."
+ *
+ * @example
+ * loadingMessage('Fetching', 'field metadata')
+ * // "Fetching field metadata..."
+ *
+ * @example
+ * loadingMessage('Exporting', '42 definitions', 'prod')
+ * // "Exporting 42 definitions from prod..."
+ */
+export function loadingMessage(action, subject, org) {
+    if (org !== undefined && org.trim() !== '') {
+        return `${action} ${subject} from ${org.trim()}...`;
+    }
+    return `${action} ${subject}...`;
+}
+//# sourceMappingURL=loading-messages.js.map

package/lib/utils/formatting/loading-messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading-messages.js","sourceRoot":"","sources":["../../../src/utils/formatting/loading-messages.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,OAAe,EAAE,GAAY;IAC1E,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC3C,OAAO,GAAG,MAAM,IAAI,OAAO,SAAS,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC;IACtD,CAAC;IACD,OAAO,GAAG,MAAM,IAAI,OAAO,KAAK,CAAC;AACnC,CAAC"}

package/lib/utils/formatting/namespace-display.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Options for controlling namespace display formatting.
+ */
+export type NamespaceDisplayOptions = {
+    /** Show the raw namespace prefix alongside the product name. Default: false. */
+    readonly showPrefix?: boolean;
+    /** Label to use for objects with no namespace (platform-native). Default: "Standard". */
+    readonly standardLabel?: string;
+};
+/**
+ * Formats a Salesforce namespace prefix into a human-readable display string.
+ *
+ * Resolves known namespace prefixes to their product names using the
+ * namespace constants map. Unknown namespaces are returned as-is.
+ * Null/undefined/empty namespaces return the standard label.
+ *
+ * @param namespace - The namespace prefix (with or without trailing underscores),
+ * or null/undefined for standard objects
+ * @param options - Display formatting options
+ * @returns A human-readable string representing the namespace
+ *
+ * @example
+ * formatNamespace('FinServ__')                         // "Financial Services Cloud"
+ * formatNamespace('SBQQ__')                            // "Salesforce CPQ"
+ * formatNamespace('SBQQ__', { showPrefix: true })      // "Salesforce CPQ (SBQQ__)"
+ * formatNamespace(null)                                // "Standard"
+ * formatNamespace('')                                  // "Standard"
+ * formatNamespace('Unknown__')                         // "Unknown__"
+ * formatNamespace(null, { standardLabel: 'Platform' }) // "Platform"
+ */
+export declare function formatNamespace(namespace: string | null | undefined, options?: NamespaceDisplayOptions): string;

package/lib/utils/formatting/namespace-display.js

@@ -0,0 +1,64 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+/**
+ * Pure namespace display formatting utilities for CLI output.
+ *
+ * Transforms raw Salesforce namespace prefixes into human-readable
+ * product names for display in CLI tables, summaries, and details views.
+ *
+ * Composes Phase A namespace-constants with display formatting.
+ *
+ * All functions are pure (no side effects, no external state) and return
+ * formatted strings.
+ *
+ * @module utils/formatting/namespace-display
+ */
+import { getProductName } from '../../services/namespace-constants.js';
+/**
+ * Default label for objects with no namespace prefix.
+ */
+const DEFAULT_STANDARD_LABEL = 'Standard';
+/**
+ * Formats a Salesforce namespace prefix into a human-readable display string.
+ *
+ * Resolves known namespace prefixes to their product names using the
+ * namespace constants map. Unknown namespaces are returned as-is.
+ * Null/undefined/empty namespaces return the standard label.
+ *
+ * @param namespace - The namespace prefix (with or without trailing underscores),
+ * or null/undefined for standard objects
+ * @param options - Display formatting options
+ * @returns A human-readable string representing the namespace
+ *
+ * @example
+ * formatNamespace('FinServ__')                         // "Financial Services Cloud"
+ * formatNamespace('SBQQ__')                            // "Salesforce CPQ"
+ * formatNamespace('SBQQ__', { showPrefix: true })      // "Salesforce CPQ (SBQQ__)"
+ * formatNamespace(null)                                // "Standard"
+ * formatNamespace('')                                  // "Standard"
+ * formatNamespace('Unknown__')                         // "Unknown__"
+ * formatNamespace(null, { standardLabel: 'Platform' }) // "Platform"
+ */
+export function formatNamespace(namespace, options) {
+    const standardLabel = options?.standardLabel ?? DEFAULT_STANDARD_LABEL;
+    // Null, undefined, or empty → standard
+    if (namespace == null || namespace.trim() === '') {
+        return standardLabel;
+    }
+    const trimmed = namespace.trim();
+    const productName = getProductName(trimmed);
+    if (productName === undefined) {
+        // Unknown namespace — return raw prefix
+        return trimmed;
+    }
+    if (options?.showPrefix === true) {
+        return `${productName} (${trimmed})`;
+    }
+    return productName;
+}
+//# sourceMappingURL=namespace-display.js.map

package/lib/utils/formatting/namespace-display.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace-display.js","sourceRoot":"","sources":["../../../src/utils/formatting/namespace-display.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAYvE;;GAEG;AACH,MAAM,sBAAsB,GAAG,UAAU,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAAC,SAAoC,EAAE,OAAiC;IACrG,MAAM,aAAa,GAAG,OAAO,EAAE,aAAa,IAAI,sBAAsB,CAAC;IAEvE,uCAAuC;IACvC,IAAI,SAAS,IAAI,IAAI,IAAI,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;IACjC,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IAE5C,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,wCAAwC;QACxC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,OAAO,EAAE,UAAU,KAAK,IAAI,EAAE,CAAC;QACjC,OAAO,GAAG,WAAW,KAAK,OAAO,GAAG,CAAC;IACvC,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/lib/utils/formatting/numbers.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Formats a number with locale-aware thousands separators.
+ *
+ * Uses a fixed 'en-US' locale for deterministic output. Returns '--' for
+ * non-finite values (NaN, Infinity, null, undefined).
+ *
+ * @param value - The number to format (accepts null/undefined)
+ * @returns Formatted string with thousands separators, e.g. "1,234,567"
+ *
+ * @example
+ * formatNumber(1234567)   // "1,234,567"
+ * formatNumber(0)         // "0"
+ * formatNumber(-42)       // "-42"
+ * formatNumber(NaN)       // "--"
+ * formatNumber(null)      // "--"
+ */
+export declare function formatNumber(value: number | null | undefined): string;
+/**
+ * Formats a number in compact abbreviated form.
+ *
+ * Numbers below 1,000 (in absolute value) are returned as-is with locale formatting.
+ * Larger numbers are abbreviated with K, M, B, or T suffixes with one decimal place.
+ * Returns '--' for non-finite values (NaN, Infinity, null, undefined).
+ *
+ * @param value - The number to format (accepts null/undefined)
+ * @returns Abbreviated string, e.g. "1.2M", "1.5K", "999"
+ *
+ * @example
+ * formatCompact(1234567)  // "1.2M"
+ * formatCompact(1500)     // "1.5K"
+ * formatCompact(999)      // "999"
+ * formatCompact(-2500)    // "-2.5K"
+ * formatCompact(0)        // "0"
+ * formatCompact(NaN)      // "--"
+ */
+export declare function formatCompact(value: number | null | undefined): string;
+/**
+ * Formats a ratio as a percentage string with configurable precision.
+ *
+ * Computes `(numerator / total) * 100` and formats with the specified decimal places.
+ * Returns '--' for non-finite inputs or when total is zero (division by zero).
+ *
+ * @param numerator - The numerator value (accepts null/undefined)
+ * @param total - The total/denominator value (accepts null/undefined)
+ * @param precision - Number of decimal places (default: 1)
+ * @returns Formatted percentage string, e.g. "45.0%"
+ *
+ * @example
+ * formatPercent(45, 100)      // "45.0%"
+ * formatPercent(1, 3, 2)      // "33.33%"
+ * formatPercent(0, 100)       // "0.0%"
+ * formatPercent(45, 0)        // "--"
+ * formatPercent(NaN, 100)     // "--"
+ */
+export declare function formatPercent(numerator: number | null | undefined, total: number | null | undefined, precision?: number): string;
+/**
+ * Formats a byte count as a human-readable size string.
+ *
+ * Uses binary (IEC) units: KB = 1024, MB = 1024^2, etc.
+ * Returns '--' for non-finite or negative values. Returns "0 B" for zero.
+ *
+ * @param value - The byte count to format (accepts null/undefined)
+ * @returns Human-readable byte string, e.g. "1.0 MB", "512 B"
+ *
+ * @example
+ * formatBytes(1048576)    // "1.0 MB"
+ * formatBytes(1536)       // "1.5 KB"
+ * formatBytes(500)        // "500 B"
+ * formatBytes(0)          // "0 B"
+ * formatBytes(-1)         // "--"
+ * formatBytes(NaN)        // "--"
+ */
+export declare function formatBytes(value: number | null | undefined): string;