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

package/lib/utils/formatting/numbers.js

@@ -0,0 +1,187 @@
+/*
+ * 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 number formatting utilities for CLI display output.
+ *
+ * All functions are pure (no side effects, no external state) and handle
+ * edge cases including 0, negative numbers, NaN, Infinity, and null/undefined.
+ *
+ * @module utils/formatting/numbers
+ */
+/**
+ * Fixed locale for deterministic output across environments.
+ */
+const LOCALE = 'en-US';
+/**
+ * Compact notation thresholds and suffixes, ordered from largest to smallest.
+ */
+const COMPACT_THRESHOLDS = [
+    { divisor: 1_000_000_000_000, suffix: 'T' },
+    { divisor: 1_000_000_000, suffix: 'B' },
+    { divisor: 1_000_000, suffix: 'M' },
+    { divisor: 1000, suffix: 'K' },
+];
+/**
+ * Byte unit thresholds using binary (IEC) units, ordered from largest to smallest.
+ */
+const BYTE_UNITS = [
+    { threshold: 1024 ** 4, unit: 'TB' },
+    { threshold: 1024 ** 3, unit: 'GB' },
+    { threshold: 1024 ** 2, unit: 'MB' },
+    { threshold: 1024, unit: 'KB' },
+];
+/**
+ * Sentinel value returned for non-finite or nullish inputs.
+ */
+const INVALID_DISPLAY = '--';
+/**
+ * Coerces a value to a number, returning NaN for null/undefined.
+ *
+ * @param value - The value to coerce
+ * @returns The numeric value, or NaN if null/undefined
+ */
+function toNumber(value) {
+    if (value === null || value === undefined) {
+        return NaN;
+    }
+    return value;
+}
+/**
+ * Checks whether a number is displayable (finite and not NaN).
+ *
+ * @param n - The number to check
+ * @returns true if the number can be formatted for display
+ */
+function isDisplayable(n) {
+    return Number.isFinite(n);
+}
+/**
+ * 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 function formatNumber(value) {
+    const n = toNumber(value);
+    if (!isDisplayable(n)) {
+        return INVALID_DISPLAY;
+    }
+    // Normalize negative zero to positive zero for display
+    const normalized = Object.is(n, -0) ? 0 : n;
+    return normalized.toLocaleString(LOCALE);
+}
+/**
+ * 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 function formatCompact(value) {
+    const n = toNumber(value);
+    if (!isDisplayable(n)) {
+        return INVALID_DISPLAY;
+    }
+    const abs = Math.abs(n);
+    const sign = n < 0 ? '-' : '';
+    for (const { divisor, suffix } of COMPACT_THRESHOLDS) {
+        if (abs >= divisor) {
+            const divided = abs / divisor;
+            const formatted = divided.toFixed(1);
+            return `${sign}${formatted}${suffix}`;
+        }
+    }
+    // Below 1,000: use locale formatting for consistency
+    return n.toLocaleString(LOCALE);
+}
+/**
+ * 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 function formatPercent(numerator, total, precision = 1) {
+    const num = toNumber(numerator);
+    const den = toNumber(total);
+    if (!isDisplayable(num) || !isDisplayable(den) || den === 0) {
+        return INVALID_DISPLAY;
+    }
+    const percentage = (num / den) * 100;
+    if (!isDisplayable(percentage)) {
+        return INVALID_DISPLAY;
+    }
+    return `${percentage.toFixed(precision)}%`;
+}
+/**
+ * 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 function formatBytes(value) {
+    const n = toNumber(value);
+    if (!isDisplayable(n) || n < 0) {
+        return INVALID_DISPLAY;
+    }
+    if (n === 0) {
+        return '0 B';
+    }
+    for (const { threshold, unit } of BYTE_UNITS) {
+        if (n >= threshold) {
+            const scaled = n / threshold;
+            return `${scaled.toFixed(1)} ${unit}`;
+        }
+    }
+    // Below 1 KB: display as whole bytes
+    return `${Math.round(n)} B`;
+}
+//# sourceMappingURL=numbers.js.map

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

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

package/lib/utils/formatting/object-describe-display.d.ts

@@ -0,0 +1,114 @@
+import type { ObjectResult } from '../../models/object-describe-types.js';
+import type { OrgIdentity } from '../../services/OrgInfoService.js';
+/**
+ * Displays a single object result in table format.
+ *
+ * Orchestrates all display sub-sections: header, summary, record age,
+ * record types, business processes, field summary, field type distribution,
+ * namespaces, relationships, lookups, and fields.
+ *
+ * @param log - The logging function (typically `this.log.bind(this)`)
+ * @param result - The object result data to display
+ * @param index - The 1-based index of this object in the results
+ * @param total - The total number of objects being described
+ */
+export declare function displayObjectResult(log: (msg: string) => void, result: ObjectResult, index: number, total: number): void;
+/**
+ * Displays the Org Identity block.
+ *
+ * @param log - The logging function
+ * @param identity - The org identity data from OrgInfoService
+ * @param instanceUrl - The Salesforce instance URL
+ */
+export declare function displayOrgIdentity(log: (msg: string) => void, identity: OrgIdentity, instanceUrl: string): void;
+/**
+ * Displays the header for an object result.
+ * Only shown when describing multiple objects.
+ *
+ * @param log - The logging function
+ * @param result - The object result data
+ * @param index - The 1-based index of this object
+ * @param total - The total number of objects
+ */
+export declare function displayHeader(log: (msg: string) => void, result: ObjectResult, index: number, total: number): void;
+/**
+ * Displays the summary section with object metadata.
+ *
+ * @param log - The logging function
+ * @param result - The object result data
+ */
+export declare function displaySummarySection(log: (msg: string) => void, result: ObjectResult): void;
+/**
+ * Displays the record types section with optional per-record-type age distribution.
+ *
+ * @param log - The logging function
+ * @param result - The object result data
+ */
+export declare function displayRecordTypesSection(log: (msg: string) => void, result: ObjectResult): void;
+/**
+ * Displays the business processes section using the business-process-grid renderer.
+ * Hidden when no business processes exist for the object.
+ *
+ * @param log - The logging function
+ * @param result - The object result data
+ */
+export declare function displayBusinessProcessesSection(log: (msg: string) => void, result: ObjectResult): void;
+/**
+ * Displays the field summary section as a summary box.
+ *
+ * @param log - The logging function
+ * @param result - The object result data
+ */
+export declare function displayFieldSummarySection(log: (msg: string) => void, result: ObjectResult): void;
+/**
+ * Displays the field type distribution table.
+ *
+ * @param log - The logging function
+ * @param result - The object result data
+ */
+export declare function displayFieldTypeDistributionSection(log: (msg: string) => void, result: ObjectResult): void;
+/**
+ * Displays the namespaces table.
+ *
+ * @param log - The logging function
+ * @param result - The object result data
+ */
+export declare function displayNamespacesSection(log: (msg: string) => void, result: ObjectResult): void;
+/**
+ * Displays the referenced-by relationships section.
+ *
+ * @param log - The logging function
+ * @param result - The object result data
+ */
+export declare function displayReferencedBySection(log: (msg: string) => void, result: ObjectResult): void;
+/**
+ * Displays the lookups section.
+ *
+ * @param log - The logging function
+ * @param result - The object result data
+ */
+export declare function displayLookupsSection(log: (msg: string) => void, result: ObjectResult): void;
+/**
+ * Displays the record age distribution table.
+ *
+ * @param log - The logging function
+ * @param result - The object result data
+ */
+export declare function displayRecordAgeSection(log: (msg: string) => void, result: ObjectResult): void;
+/**
+ * Displays the profiling status section.
+ *
+ * Shows existing profiling definitions and their last profiled dates.
+ * Hidden when no definitions exist for the object.
+ *
+ * @param log - The logging function
+ * @param result - The object result data
+ */
+export declare function displayProfilingStatusSection(log: (msg: string) => void, result: ObjectResult): void;
+/**
+ * Displays the fields listing table.
+ *
+ * @param log - The logging function
+ * @param result - The object result data
+ */
+export declare function displayFieldsSection(log: (msg: string) => void, result: ObjectResult): void;