@thoughtspot/ts-chart-sdk 0.0.2-alpha.24 → 0.0.2-alpha.26

package/src/utils/number-formatting/number-formatting-utils.ts

@@ -0,0 +1,260 @@
+/**
+ * @file: Formatting Utils
+ *
+ * @author Yashvardhan Nehra <yashvardhan.nehra@thoughtspot.com>
+ *
+ * Copyright: ThoughtSpot Inc. 2024
+ */
+
+import _ from 'lodash';
+import {
+    ColumnFormat,
+    CurrencyFormat,
+    CurrencyFormatType,
+} from '../../types/answer-column.types';
+import { Maybe } from '../../types/common.types';
+import {
+    CategoryType,
+    CurrencyFormatConfig,
+    FormatConfig,
+    NegativeValueFormat,
+    NumberFormatConfig,
+    Unit,
+} from '../../types/number-formatting.types';
+import { getDefaultCurrencyCode } from '../globalize-Initializer/globalize-utils';
+
+interface FormatterConfig {
+    unitDetails: Unit;
+    decimalDetails: number;
+    shouldRemoveTrailingZeros: boolean;
+}
+/**
+ * Constants for unit conversions and suffixes.
+ */
+export const UNITS_TO_DIVIDING_FACTOR: Record<Unit, number> = {
+    [Unit.None]: 1,
+    [Unit.Thousands]: 1000,
+    [Unit.Million]: 1000 * 1000,
+    [Unit.Billion]: 1000 * 1000 * 1000,
+    [Unit.Trillion]: 1000 * 1000 * 1000 * 1000,
+    [Unit.Auto]: 1,
+};
+
+/**
+ * Default strings for placeholders.
+ */
+let strings: Record<string, string> = {
+    NULL_VALUE_PLACEHOLDER_LABEL: '{Null}',
+    EMPTY_VALUE_PLACEHOLDER_LABEL: '{Empty}',
+};
+
+export const setLocaleBasedStringFormats = (
+    tsLocaleBasedStringsFormats?: Record<string, string>,
+) => {
+    if (tsLocaleBasedStringsFormats) {
+        strings = tsLocaleBasedStringsFormats;
+    }
+};
+
+export const getLocaleBasedStringFormats = () => strings;
+
+export const UNITS_TO_SUFFIX: Record<Unit, string> = {
+    [Unit.None]: '',
+    [Unit.Thousands]: 'K',
+    [Unit.Million]: 'M',
+    [Unit.Billion]: 'B',
+    [Unit.Trillion]: 'T',
+    [Unit.Auto]: '',
+};
+
+const DEFAULT_DECIMAL_PRECISION = 2;
+
+/**
+ * Formats negative values according to the specified format.
+ *
+ * @param formattedValue - The formatted value to modify.
+ * @param negativeFormat - The desired negative value format.
+ * @returns The formatted negative value.
+ */
+export const formatNegativeValue = (
+    formattedValue: string,
+    negativeFormat?: Maybe<NegativeValueFormat> | number,
+): string => {
+    switch (negativeFormat) {
+        case NegativeValueFormat.PrefixDash:
+            return `-${formattedValue}`;
+        case NegativeValueFormat.SuffixDash:
+            return `${formattedValue}-`;
+        case NegativeValueFormat.BracesNodash:
+            return `(${formattedValue})`;
+        default:
+            return `-${formattedValue}`;
+    }
+};
+
+/**
+ * Determines the appropriate unit for auto-scaling values.
+ *
+ * @param value - The numeric value to evaluate.
+ * @returns The appropriate unit (e.g., Thousand, Million, etc.).
+ */
+export const getAutoUnit = (value: number): Unit => {
+    if (value >= UNITS_TO_DIVIDING_FACTOR[Unit.Trillion]) {
+        return Unit.Trillion;
+    }
+    if (value >= UNITS_TO_DIVIDING_FACTOR[Unit.Billion]) {
+        return Unit.Billion;
+    }
+    if (value >= UNITS_TO_DIVIDING_FACTOR[Unit.Million]) {
+        return Unit.Million;
+    }
+    if (value >= UNITS_TO_DIVIDING_FACTOR[Unit.Thousands]) {
+        return Unit.Thousands;
+    }
+    return Unit.None;
+};
+
+/**
+ * Retrieves the locale name based on the provided currency format.
+ *
+ * @param currencyFormat - The currency format configuration.
+ * @returns The locale name as a string.
+ */
+export const getLocaleName = (currencyFormat: CurrencyFormat): string => {
+    if (currencyFormat.type === CurrencyFormatType.ISO_CODE) {
+        return currencyFormat.isoCode;
+    }
+
+    const locale = getDefaultCurrencyCode();
+    return locale;
+};
+
+/**
+ * Generates a default format configuration based on the column settings.
+ *
+ * @param columnFormatConfig - The column-specific formatting settings.
+ * @returns The default format configuration.
+ */
+export const defaultFormatConfig = (
+    columnFormatConfig?: ColumnFormat,
+): FormatConfig => {
+    if (columnFormatConfig?.pattern) {
+        return {
+            __typename: 'FormatConfig',
+            category: CategoryType.Custom,
+            isCategoryEditable: true,
+            customFormatConfig: {
+                __typename: 'CustomFormatConfig',
+                format: columnFormatConfig?.pattern,
+            },
+        };
+    }
+    if (columnFormatConfig?.currencyFormat) {
+        const locale = getLocaleName(columnFormatConfig?.currencyFormat);
+        const currencyFormatConfig: CurrencyFormatConfig = {
+            __typename: 'CurrencyFormatConfig',
+            decimals: 0,
+            locale,
+            removeTrailingZeroes: false,
+            toSeparateThousands: true,
+            unit: Unit.Auto,
+        };
+        const formatConfig: FormatConfig = {
+            __typename: 'FormatConfig',
+            category: CategoryType.Currency,
+            isCategoryEditable: true,
+            currencyFormatConfig,
+        };
+        return formatConfig;
+    }
+    const numberFormatConfig: NumberFormatConfig = {
+        __typename: 'NumberFormatConfig',
+        decimals: 0,
+        negativeValueFormat: NegativeValueFormat.PrefixDash,
+        removeTrailingZeroes: false,
+        toSeparateThousands: true,
+        unit: Unit.Auto,
+    };
+    const formatConfig: FormatConfig = {
+        __typename: 'FormatConfig',
+        category: CategoryType.Number,
+        isCategoryEditable: true,
+        numberFormatConfig,
+        percentageFormatConfig: null,
+    };
+    return formatConfig;
+};
+
+/**
+ * Maps configuration details to a formatter configuration object.
+ *
+ * @param absFloatValue - The absolute value of the number being formatted.
+ * @param configDetails - The number or currency format configuration.
+ * @returns A mapped formatter configuration.
+ */
+export const mapFormatterConfig = (
+    absFloatValue: number,
+    configDetails: NumberFormatConfig | CurrencyFormatConfig,
+): FormatterConfig => {
+    const isAutoFormatted = configDetails.unit === Unit.Auto;
+    let unitDetails = configDetails.unit || Unit.Auto;
+    let decimalDetails = configDetails.decimals || 0;
+
+    if (isAutoFormatted) {
+        unitDetails = getAutoUnit(absFloatValue);
+        if (unitDetails !== Unit.None) {
+            decimalDetails = DEFAULT_DECIMAL_PRECISION;
+        }
+    }
+    const shouldRemoveTrailingZeros =
+        configDetails.removeTrailingZeroes || isAutoFormatted;
+    return {
+        unitDetails,
+        decimalDetails,
+        shouldRemoveTrailingZeros,
+    };
+};
+
+/**
+ * Handles formatting of special data values (e.g., null, empty, NaN, Infinity).
+ *
+ * @param value - The value to check and format.
+ * @returns A formatted special value or null if not applicable.
+ */
+export function formatSpecialDataValue(value: any) {
+    if (
+        value === strings.NULL_VALUE_PLACEHOLDER_LABEL ||
+        value === strings.EMPTY_VALUE_PLACEHOLDER_LABEL
+    ) {
+        return value;
+    }
+
+    if (value === null || value === undefined) {
+        return strings.NULL_VALUE_PLACEHOLDER_LABEL;
+    }
+
+    if (value === Infinity || value === -Infinity || _.isNaN(value)) {
+        return value.toString();
+    }
+    // {Empty} placeholder is set for empty string or no characters
+    // other than spaces.
+    if (value === '') {
+        return strings.EMPTY_VALUE_PLACEHOLDER_LABEL;
+    }
+    if (value instanceof Array) {
+        if (_.isEmpty(value) || _.isNil(value[0])) {
+            return strings.NULL_VALUE_PLACEHOLDER_LABEL;
+        }
+
+        switch (value[0]) {
+            case 'NaN':
+                return 'NaN';
+            case 'Infinity':
+                return 'Infinity';
+            default:
+                return null;
+        }
+    }
+
+    return null;
+}

package/src/utils/number-formatting/number-formatting.spec.ts

@@ -0,0 +1,243 @@
+import { create, LogLevel, logMethods } from '../../main/logger';
+import {
+    ColumnFormat,
+    CurrencyFormatType,
+    FormatType,
+} from '../../types/answer-column.types';
+import {
+    CategoryType,
+    FormatConfig,
+    NegativeValueFormat,
+    Unit,
+} from '../../types/number-formatting.types';
+import { initGlobalize } from '../globalize-Initializer/globalize-utils';
+import * as globalizeUtils from '../globalize-Initializer/globalize-utils';
+import {
+    formatCurrencyWithCustomPattern,
+    getFormattedValue,
+} from './number-formatting';
+
+jest.mock('../../main/util', () => ({
+    getQueryParam: jest.fn().mockReturnValue('true'),
+}));
+
+describe('formatCurrencyWithCustomPattern', () => {
+    beforeAll(() => {
+        initGlobalize('en-US');
+    });
+    test('formats value with a custom pattern and currency symbol', () => {
+        const value = 12345.678;
+        const currencyCode = 'USD';
+        const formatPattern = '#,##0.00';
+
+        const result = formatCurrencyWithCustomPattern(
+            value,
+            currencyCode,
+            formatPattern,
+        );
+        expect(result).toBe('$12,345.68');
+    });
+});
+
+describe('getFormattedValue', () => {
+    beforeAll(() => {
+        initGlobalize('en-US');
+    });
+    const columnFormatConfig: ColumnFormat = {
+        type: FormatType.CURRENCY,
+        currencyFormat: {
+            type: CurrencyFormatType.ISO_CODE,
+            column: '',
+            isoCode: 'USD',
+        },
+    };
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    test('uses Number Fromatting as default configuration when formatConfigProp &  columnFormatConfig are null', () => {
+        const result = getFormattedValue(12345, {}, {} as ColumnFormat);
+        expect(result).toBe('12.35K');
+    });
+
+    test('use Custom Formatting as default configuration when only formatConfigProp is null', () => {
+        const result = getFormattedValue(12345, {}, columnFormatConfig);
+        expect(result).toBe('$12.35K');
+    });
+
+    test('formats special values (NaN, Infinity)', () => {
+        expect(getFormattedValue(NaN, {}, {} as ColumnFormat)).toBe('NaN');
+        expect(getFormattedValue(Infinity, {}, {} as ColumnFormat)).toBe(
+            'Infinity',
+        );
+        expect(getFormattedValue(-Infinity, {}, {} as ColumnFormat)).toBe(
+            '-Infinity',
+        );
+    });
+
+    test('formats number category values with units and trailing zeroes', () => {
+        const formatConfig: FormatConfig = {
+            category: CategoryType.Number,
+            numberFormatConfig: {
+                unit: Unit.Thousands,
+                decimals: 2,
+                toSeparateThousands: true,
+                negativeValueFormat: NegativeValueFormat.PrefixDash,
+            },
+        };
+        const result = getFormattedValue(
+            -12345,
+            formatConfig,
+            {} as ColumnFormat,
+        );
+        expect(result).toBe('-12.35K'); // Update based on actual expected output
+    });
+
+    test('formats percentage values correctly', () => {
+        const formatConfig: FormatConfig = {
+            category: CategoryType.Percentage,
+            percentageFormatConfig: { decimals: 2, removeTrailingZeroes: true },
+        };
+        const result = getFormattedValue(
+            0.1234,
+            formatConfig,
+            {} as ColumnFormat,
+        );
+        expect(result).toBe('12.34%');
+    });
+
+    test('formats currency values with compact units', () => {
+        const formatConfig: FormatConfig = {
+            category: CategoryType.Currency,
+            currencyFormatConfig: {
+                locale: 'USD',
+                toSeparateThousands: true,
+            },
+        };
+        const result = getFormattedValue(
+            12345.678,
+            formatConfig,
+            {} as ColumnFormat,
+        );
+        // eslint-disable-next-line security/detect-unsafe-regex
+        expect(result).toMatch(/^\$\d+,\d+(\.\d+)?$/); // Update expected value
+    });
+
+    test('formats currency values with user Locale', () => {
+        jest.spyOn(
+            globalizeUtils,
+            'getDefaultCurrencyCode',
+        ).mockImplementationOnce(() => 'INR');
+        const formatConfig: FormatConfig = {
+            category: CategoryType.Currency,
+            currencyFormatConfig: {
+                unit: Unit.Thousands,
+                decimals: 2,
+                locale: CurrencyFormatType.USER_LOCALE,
+                toSeparateThousands: true,
+            },
+        };
+        const result = getFormattedValue(
+            12345.678,
+            formatConfig,
+            {} as ColumnFormat,
+        );
+        expect(result).toMatch('₹12.35K'); // Update expected value
+    });
+
+    test('should normalize category to CategoryType.Number when it is a number', () => {
+        // Mock formatConfig with category as a number
+        const formatConfig: FormatConfig = {
+            category: CategoryType.Number,
+            numberFormatConfig: {
+                unit: Unit.Thousands,
+                decimals: 2,
+                toSeparateThousands: true,
+                negativeValueFormat: NegativeValueFormat.PrefixDash,
+            },
+        };
+
+        const result = getFormattedValue(
+            1000,
+            formatConfig,
+            {} as ColumnFormat,
+        );
+
+        expect(result).toBe('1.00K'); // Update based on actual expected output
+    });
+
+    test('falls back to default formatting for unsupported categories', () => {
+        const formatConfig: FormatConfig = { category: 'Unknown' as any };
+        const result = getFormattedValue(
+            12345.678,
+            formatConfig,
+            {} as ColumnFormat,
+        );
+        expect(result).toBe('12,345.678'); // Update based on fallback behavior
+    });
+
+    test('formats custom pattern correctly', () => {
+        const formatConfig: FormatConfig = {
+            category: CategoryType.Custom,
+            customFormatConfig: { format: '#,##0.00' },
+        };
+        const result = getFormattedValue(
+            12345.678,
+            formatConfig,
+            {} as ColumnFormat,
+        );
+        expect(result).toBe('12,345.68'); // Update based on actual output
+    });
+
+    test('formats custom pattern with valid customColumn format', () => {
+        const formatConfig: FormatConfig = {
+            category: CategoryType.Custom,
+            customFormatConfig: { format: '#,##0.00' },
+        };
+        const result = getFormattedValue(
+            12345.678,
+            formatConfig,
+            columnFormatConfig,
+        );
+        expect(result).toBe('$12,345.68'); // Update based on actual output
+    });
+
+    test('logs error for invalid custom format patterns', () => {
+        const formatConfig: FormatConfig = {
+            category: CategoryType.Custom,
+            customFormatConfig: { format: 'invalid-format' },
+        };
+        const error = jest.fn();
+        logMethods[LogLevel.ERROR] = error;
+        const logger = create('TestLogger');
+        logger.error = error;
+
+        getFormattedValue(12345.678, formatConfig, {} as ColumnFormat);
+        expect(logger.error).toHaveBeenCalled();
+
+        jest.restoreAllMocks();
+    });
+
+    test('handles currency formatting failure', () => {
+        const formatConfig: FormatConfig = {
+            category: CategoryType.Currency,
+        };
+        jest.spyOn(
+            globalizeUtils,
+            'globalizeCurrencyFormatter',
+        ).mockImplementationOnce(() => {
+            throw new Error('Currency format error');
+        });
+
+        const error = jest.fn();
+        logMethods[LogLevel.ERROR] = error;
+        const logger = create('TestLogger');
+        logger.error = error;
+
+        getFormattedValue(12345.678, formatConfig, {} as ColumnFormat);
+        expect(logger.error).toHaveBeenCalled();
+
+        jest.restoreAllMocks();
+    });
+});