@thoughtspot/ts-chart-sdk 0.0.2-alpha.8 → 1.0.0

package/src/utils/formatting-util.ts

@@ -0,0 +1,234 @@
+import _ from 'lodash';
+import { CustomChartContext } from '../main/custom-chart-context';
+import {
+    ChartColumn,
+    ColumnAggregationType,
+    ColumnTimeBucket,
+    ColumnType,
+    DataType,
+} from '../types/answer-column.types';
+import {
+    CustomCalendarDate,
+    dateFormatPresets,
+    formatDate,
+    formatDateNum,
+    getCustomCalendarGuidFromColumn,
+    getCustomCalendarValueFromEpoch,
+    getDisplayString,
+    getEffectiveDateNumDataType,
+    hasCustomCalendar,
+    isDateColumn,
+    isDateNumColumn,
+    isDateTimeColumn,
+} from './date-formatting';
+import {
+    getCustomCalendarGuid,
+    getFormatPatternForBucket,
+    showDateFinancialYearFormat,
+} from './date-utils';
+
+interface FormatOptionsType {
+    isMillisIncluded: boolean;
+}
+
+const getBucketization = (col: ChartColumn) => col.timeBucket;
+/**
+ * Retrieves the format pattern for a given column based on its bucketization or custom format.
+ *
+ * This function first checks the column's bucketization and attempts to retrieve a format pattern
+ * using `getFormatPatternForBucket`. If no format pattern is found for the bucketization, it falls
+ * back to the column's custom format pattern (if available).
+ *
+ * @param col - The column to retrieve the format pattern for, represented as a `ChartColumn`.
+ * @returns The format pattern as a string, either derived from the bucketization or the column's custom format.
+ */
+export const getFormatPattern = (col: ChartColumn): string =>
+    getFormatPatternForBucket(getBucketization(col)) || col.format?.pattern;
+
+/**
+ * Retrieves a formatter function for a column based on its type (e.g., date, date_number).
+ *
+ * This function returns a specialized formatter based on the column's type and format pattern.
+ * It first checks if the column is a date column and applies the appropriate date format,
+ * considering options like whether the fiscal year or milliseconds are included. If the column is
+ * a date number column, it applies date number formatting. For other types of columns, it returns
+ * the raw data value without formatting.
+ *
+ * @param col - The column for which the formatter is to be created, represented as a `ChartColumn`.
+ * @param options - The formatting options, including locale, fiscal settings, and custom calendar information.
+ *
+ * @returns A function that formats a data value based on the column type and format pattern.
+ *          This returned function takes in the data value and optional additional options.
+ *
+ * @example
+ *
+ * const dateFormatter = getBaseTypeFormatterInstance(column, options);
+ * const formattedValue = dateFormatter(dataValue, options);
+ * For more info in column
+ * @link ChartColumn
+ * To see how options are feched see src/example/custom-bar-chart
+ */
+export function getBaseTypeFormatterInstance(
+    col: ChartColumn,
+    options: FormatOptionsType,
+): any {
+    let formatPattern = getFormatPattern(col);
+    // TODO: add numberic formatter if the col is numeric.
+    if (isDateColumn(col)) {
+        const showFinancialFormat = showDateFinancialYearFormat(col);
+        const isDateTime = isDateTimeColumn(col);
+
+        if (!formatPattern) {
+            if (isDateTime) {
+                if (options.isMillisIncluded) {
+                    formatPattern =
+                        dateFormatPresets.DATETIME_SHORT_WITH_MILLIS;
+                } else {
+                    formatPattern =
+                        dateFormatPresets.DATETIME_SHORT_WITH_SECONDS;
+                }
+            }
+        }
+        return (dataValue: any, options?: any) => {
+            const customCalendarValueFromEpoch: CustomCalendarDate =
+                getCustomCalendarValueFromEpoch(
+                    col,
+                    dataValue,
+                    options?.displayToCustomCalendarValueMap,
+                );
+            const customCalendarDisplayStr = getDisplayString(
+                customCalendarValueFromEpoch,
+            );
+            if (customCalendarDisplayStr) {
+                return customCalendarDisplayStr;
+            }
+            const customCalendarOverridesFiscalOffset =
+                hasCustomCalendar(col) &&
+                getCustomCalendarGuidFromColumn(col) !==
+                    getCustomCalendarGuid(
+                        'fiscal',
+                        options.defaultDataSourceId,
+                        options.tsDefinedCustomCalenders,
+                    );
+            const optionsWithFiscalOffset = {
+                ...options,
+                customCalendarOverridesFiscalOffset:
+                    !!customCalendarOverridesFiscalOffset,
+            };
+            return formatDate(
+                dataValue,
+                formatPattern,
+                !showFinancialFormat,
+                optionsWithFiscalOffset,
+            );
+        };
+    }
+    if (isDateNumColumn(col)) {
+        return (dataValue: any, options?: any) => {
+            const customCalendarValueFromEpoch: CustomCalendarDate =
+                getCustomCalendarValueFromEpoch(
+                    col,
+                    dataValue,
+                    options?.displayToCustomCalendarValueMap,
+                );
+            const customCalendarDisplayStr = getDisplayString(
+                customCalendarValueFromEpoch,
+            );
+            if (customCalendarValueFromEpoch && customCalendarDisplayStr) {
+                return customCalendarDisplayStr;
+            }
+            return formatDateNum(
+                getEffectiveDateNumDataType(col),
+                dataValue,
+                formatPattern,
+                options,
+            );
+        };
+    }
+    return (dataValue: any) => {
+        return dataValue;
+    };
+}
+/**
+ * Retrieves the appropriate data formatter function for a specified column,
+ * based on its type, format options, and an optional aggregation type override.
+ *
+ *
+ * @param col - The column for which the formatter is to be created, represented as a `ChartColumn`.
+ * @param options - The formatting options, including settings such as locale, custom calendars, and date constants.
+ * @param aggrTypeOverride - Optional override for the column's aggregation type (e.g., `SUM`, `AVERAGE`),
+ *                            which could affect formatting behavior in future implementations.
+ *
+ * @returns A function to format data values based on the column type, format pattern, and options.
+ *          This returned function can be used to format individual data values within the column.
+ *
+ * @example
+ * const formatter = getDataFormatter(column, formatOptions, 'SUM');
+ * const formattedValue = formatter(dataValue);
+ */
+export const getDataFormatter = (
+    col: ChartColumn,
+    options: FormatOptionsType,
+    aggrTypeOverride?: ColumnAggregationType,
+) => {
+    // TODO: number formatter for column based on column type based on
+    // aggregation type
+
+    return getBaseTypeFormatterInstance(col, options);
+};
+
+/**
+ * Generates a configuration object with formatting and locale-based options for date handling,
+ * including custom calendar mapping for a specific column.
+ *
+ * This function builds an options object that includes locale settings, quarter start month,
+ * date formats, and a custom calendar map, which is populated when the column contains a
+ * custom calendar GUID. The custom calendar map links display values to custom calendar data
+ * for date formatting needs.
+ *
+ * @param appConfig - The application configuration containing locale, date format settings,
+ *                    and custom calendar definitions.
+ * @param col - The column to check for a custom calendar GUID, represented as a `ChartColumn`.
+ * @param data - The dataset, used to populate the custom calendar map if a custom calendar
+ *               GUID is associated with the column.
+ *
+ * @returns An options object with locale and date formatting details, including a custom
+ *          calendar map if applicable.
+ *
+ * @example
+ * const mapOptions = generateMapOptions(appConfig, column, data);
+ * const locale = mapOptions.locale;
+ */
+
+export const generateMapOptions = (
+    appConfig: any,
+    col: ChartColumn,
+    data: any,
+): any => {
+    let customCalenderMap = {};
+
+    if (!_.isEmpty(getCustomCalendarGuidFromColumn(col))) {
+        customCalenderMap = data.reduce(
+            (customCalenderMapAcc: any, dataValue: any) => {
+                return {
+                    ...customCalenderMapAcc,
+                    [dataValue.v.s]: dataValue,
+                };
+            },
+            {},
+        );
+    }
+    return {
+        locale: appConfig?.localeOptions?.locale,
+        quarterStartMonth: appConfig?.localeOptions?.quarterStartMonth,
+        tsLocaleBasedDateFormats:
+            appConfig?.dateFormatsConfig?.tsLocaleBasedDateFormats,
+        tsLocaleBasedStringsFormats:
+            appConfig?.dateFormatsConfig?.tsLocaleBasedStringsFormats,
+        tsDateConstants: appConfig?.dateFormatsConfig?.tsDateConstants,
+        tsDefinedCustomCalenders:
+            appConfig?.dateFormatsConfig?.tsDefinedCustomCalenders,
+        defaultDataSourceId: appConfig?.dateFormatsConfig?.defaultDataSourceId,
+        displayToCustomCalendarValueMap: customCalenderMap,
+    };
+};

package/src/utils/globalize-Initializer/globalize-utils.spec.ts

@@ -0,0 +1,192 @@
+import Globalize from 'globalize';
+import {
+    formatNumberSafely,
+    getCountryCode,
+    getCurrentCurrencyFormat,
+    getDefaultCurrencyCode,
+    getGlobalizeLocale,
+    globalizeCurrencyFormatter,
+    globalizeNumberFormatter,
+    initGlobalize,
+    loadCurrencyData,
+    loadGlobalizeData,
+    sanitizeFormat,
+    setCurrentCurrencyFormat,
+    setGlobalizeLocale,
+    validateNumberFormat,
+} from './globalize-utils';
+
+describe('Initialize Globalize', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+        initGlobalize('en-US');
+    });
+
+    describe('getCountryCode', () => {
+        it('should extract country code from locale with underscore', () => {
+            expect(getCountryCode('en_US')).toBe('US');
+        });
+
+        it('should extract country code from locale with hyphen', () => {
+            expect(getCountryCode('en-US')).toBe('US');
+        });
+
+        it('should return the input locale if no delimiter is found', () => {
+            expect(getCountryCode('en')).toBe('en');
+        });
+    });
+
+    describe('getDefaultCurrencyCode', () => {
+        it('should return the current currency format if set', () => {
+            setCurrentCurrencyFormat('EUR');
+            expect(getDefaultCurrencyCode()).toBe('EUR');
+        });
+
+        it('should return GBP if no currency data is found', () => {
+            setCurrentCurrencyFormat(null);
+            loadCurrencyData({});
+            expect(getDefaultCurrencyCode()).toBe('GBP');
+        });
+
+        it('should retrieve the default currency code from supplemental data', () => {
+            loadCurrencyData({
+                supplemental: {
+                    currencyData: {
+                        region: {
+                            US: [{ USD: {} }],
+                        },
+                    },
+                },
+            });
+            setGlobalizeLocale('en-US');
+            expect(getDefaultCurrencyCode()).toBe('USD');
+        });
+    });
+
+    describe('setGlobalizeLocale', () => {
+        it('should set the Globalize locale', () => {
+            setGlobalizeLocale('fr-FR');
+            expect(getGlobalizeLocale()).toBe('fr-FR');
+        });
+    });
+
+    describe('getGlobalizeLocale', () => {
+        it('should return the current locale', () => {
+            expect(getGlobalizeLocale()).toBe('en-US');
+        });
+    });
+
+    describe('setCurrentCurrencyFormat', () => {
+        it('should set the current currency format', () => {
+            setCurrentCurrencyFormat('JPY');
+            expect(getCurrentCurrencyFormat()).toBe('JPY');
+        });
+    });
+
+    describe('loadCurrencyData', () => {
+        it('should load supplemental currency data', () => {
+            const data = {
+                supplemental: {
+                    currencyData: {
+                        region: {
+                            US: [{ USD: {} }],
+                        },
+                    },
+                },
+            };
+            setCurrentCurrencyFormat(null);
+            loadCurrencyData(data);
+            expect(getDefaultCurrencyCode()).toBe('USD');
+        });
+    });
+
+    describe('loadGlobalizeData', () => {
+        it('should load CLDR data', () => {
+            jest.spyOn(Globalize, 'load').mockImplementationOnce((data) => {
+                return data;
+            });
+            const data = { key: 'value' };
+            loadGlobalizeData(data);
+            expect(Globalize.load).toHaveBeenCalledWith(data);
+            jest.clearAllMocks();
+        });
+    });
+
+    describe('globalizeNumberFormatter', () => {
+        it('should create a number formatter', () => {
+            const formatter = globalizeNumberFormatter({
+                minimumFractionDigits: 2,
+            });
+            expect(typeof formatter).toBe('function');
+        });
+    });
+
+    describe('globalizeCurrencyFormatter', () => {
+        it('should create a currency formatter', () => {
+            const formatter = globalizeCurrencyFormatter('USD', {
+                style: 'symbol',
+            });
+            expect(typeof formatter).toBe('function');
+        });
+    });
+
+    describe('formatNumberSafely', () => {
+        it('should format numbers safely', () => {
+            const formattedNumber = formatNumberSafely(
+                { maximumFractionDigits: 2, minimumFractionDigits: 2 },
+                123.456,
+            );
+            expect(formattedNumber).toBe('123.46');
+        });
+
+        it('should return 0 for very small numbers', () => {
+            jest.spyOn(Globalize, 'numberFormatter').mockImplementationOnce(
+                () => {
+                    throw new Error('Test Error');
+                },
+            );
+            const formattedNumber = formatNumberSafely({}, 1e-8);
+            expect(formattedNumber).toBe('0');
+            jest.clearAllMocks();
+        });
+
+        it('should return the string representation for errors', () => {
+            jest.spyOn(Globalize, 'numberFormatter').mockImplementationOnce(
+                () => {
+                    throw new Error('Test Error');
+                },
+            );
+            const formattedNumber = formatNumberSafely({}, 123);
+            expect(formattedNumber).toBe('123');
+            jest.clearAllMocks();
+        });
+    });
+
+    describe('sanitizeFormat', () => {
+        it('should add zero before decimal point', () => {
+            expect(sanitizeFormat('#.##')).toBe('0.##');
+        });
+
+        it('should add zero at the end if no decimal point', () => {
+            expect(sanitizeFormat('#%')).toBe('0%');
+        });
+
+        it('should return the same format if no changes are needed', () => {
+            expect(sanitizeFormat('0.##')).toBe('0.##');
+        });
+    });
+
+    describe('validateNumberFormat', () => {
+        it('should return true for valid number formats', () => {
+            expect(validateNumberFormat('#.##')).toBe(true);
+        });
+
+        it('should return false for invalid number formats', () => {
+            jest.spyOn(Globalize, 'numberFormatter').mockImplementation(() => {
+                throw new Error('Test Error');
+            });
+            expect(validateNumberFormat('#.#')).toBe(false);
+            jest.clearAllMocks();
+        });
+    });
+});

package/src/utils/globalize-Initializer/globalize-utils.ts

@@ -0,0 +1,216 @@
+/**
+ * @file: Initialize Globalize
+ *
+ * @author Yashvardhan Nehra <yashvardhan.nehra@thoughtspot.com>
+ *
+ * Copyright: ThoughtSpot Inc. 2024
+ */
+
+/* eslint-disable import/no-extraneous-dependencies */
+import enCaGregorian from 'cldr-data/main/en/ca-gregorian.json';
+import enCurrencies from 'cldr-data/main/en/currencies.json';
+import enNumbers from 'cldr-data/main/en/numbers.json';
+import currencyData from 'cldr-data/supplemental/currencyData.json';
+import supplemental from 'cldr-data/supplemental/likelySubtags.json';
+import enpluralJson from 'cldr-data/supplemental/plurals.json';
+import Globalize from 'globalize';
+import _ from 'lodash';
+import { create } from '../../main/logger';
+
+const logger = create('globalize-initializer');
+
+let currentLocale: string;
+let currentCurrencyFormat: any;
+let supplementalCurrencyDataJson: any;
+
+/**
+ * Extracts the country code from a locale string.
+ *
+ * @param locale - The locale string (e.g., 'en-US', 'en_US').
+ * @returns The country code (e.g., 'US') or the input locale if no delimiter is found.
+ */
+export const getCountryCode = (locale: string): string => {
+    let parts = locale.split('_'); //  // Split by '_'
+    if (parts.length === 2) {
+        return parts[1].toUpperCase();
+    }
+    parts = locale.split('-'); //  // Split by '-'
+    if (parts.length === 2) {
+        return parts[1].toUpperCase();
+    }
+    return locale;
+};
+
+/**
+ * Retrieves the default currency code for the current locale.
+ *
+ * @returns The default currency code (e.g., 'USD') or GBP if not found.
+ */
+export const getDefaultCurrencyCode = (): string => {
+    if (currentCurrencyFormat) {
+        return currentCurrencyFormat;
+    }
+
+    const countryCode = getCountryCode(currentLocale);
+    const regionData =
+        supplementalCurrencyDataJson?.supplemental?.currencyData?.region[
+            countryCode.toUpperCase()
+        ];
+    if (!regionData || regionData.length === 0) {
+        logger.warn('No currency data found for country:', countryCode);
+        return 'GBP';
+    }
+    return Object.keys(regionData[regionData.length - 1])[0];
+};
+
+/**
+ * Sets the current locale for Globalize and updates the global state.
+ *
+ * @param locale - The locale string to set (e.g., 'en-US').
+ */
+export const setGlobalizeLocale = (locale: string): void => {
+    Globalize.locale(locale);
+    currentLocale = locale;
+};
+
+/**
+ * Retrieves the current locale set in Globalize.
+ *
+ * @returns The current locale string (e.g., 'en-US').
+ */
+export const getGlobalizeLocale = () => currentLocale;
+
+/**
+ * Updates the current currency format.
+ *
+ * @param currencyFormat - The currency format to set.
+ */
+export const setCurrentCurrencyFormat = (currencyFormat: any): void => {
+    currentCurrencyFormat = currencyFormat;
+};
+
+/**
+ * Retrieves the current currency format.
+ *
+ * @returns The current currency format.
+ */
+export const getCurrentCurrencyFormat = () => currentCurrencyFormat;
+
+/**
+ * Loads supplemental currency data for Globalize.
+ *
+ * @param data - The supplemental currency data to load.
+ */
+export const loadCurrencyData = (data: any) => {
+    supplementalCurrencyDataJson = data;
+};
+
+/**
+ * Loads CLDR data into Globalize.
+ *
+ * @param data - The CLDR data to load.
+ */
+export const loadGlobalizeData = (data: any) => {
+    Globalize.load(data);
+};
+
+/**
+ * Initializes Globalize with CLDR data and sets the default locale.
+ *
+ * @param locale - The locale to initialize Globalize with (default: 'en-GB').
+ */
+export const initGlobalize = (locale = 'en-GB') => {
+    loadGlobalizeData(enNumbers);
+    loadGlobalizeData(enCaGregorian);
+    loadGlobalizeData(supplemental);
+    loadGlobalizeData(currencyData);
+    loadGlobalizeData(enpluralJson);
+    loadGlobalizeData(enCurrencies);
+
+    loadCurrencyData(currencyData);
+
+    setGlobalizeLocale(locale);
+};
+
+/**
+ * Creates a number formatter with the given options.
+ *
+ * @param format - The Globalize number formatter options.
+ * @returns A formatter function for numbers.
+ */
+export function globalizeNumberFormatter(
+    format: Globalize.NumberFormatterOptions,
+): (num: number) => string {
+    return Globalize.numberFormatter(format);
+}
+
+/**
+ * Creates a currency formatter with the given options.
+ *
+ * @param currencyCode - The ISO currency code (e.g., 'USD').
+ * @param format - The Globalize currency formatter options.
+ * @returns A formatter function for currency values.
+ */
+export function globalizeCurrencyFormatter(
+    currencyCode: string,
+    format: Globalize.CurrencyFormatterOptions,
+): (num: number) => string {
+    return Globalize.currencyFormatter(currencyCode, format);
+}
+
+/**
+ * Formats a number using Globalize, handling errors gracefully.
+ *
+ * @param format - Globalize number formatter options.
+ * @param num - The number to format.
+ * @returns The formatted number as a string.
+ */
+export function formatNumberSafely<
+    FormatOptions extends Globalize.NumberFormatterOptions,
+>(format: FormatOptions, num: number): string {
+    try {
+        const formatter = globalizeNumberFormatter(format);
+        const formattedNumber = formatter(num);
+        return formattedNumber;
+    } catch (e) {
+        logger.error('Error formatting pattern: ', format, num, e);
+        if (Math.abs(num) < 1e-7) {
+            return '0';
+        }
+        return String(num);
+    }
+}
+
+/**
+ * Sanitizes a number format to ensure compatibility with Globalize.
+ *
+ * @param format - The raw format string (e.g., '#.##').
+ * @returns A sanitized format string (e.g., '0.##').
+ */
+export const sanitizeFormat = (format: string): string => {
+    // Globalize needs to have a zero before the decimal point
+    // or at the end of format if no decimal point
+    let sanitizedFormat = format.replace(/#\./, '0.');
+    if (!sanitizedFormat.includes('.')) {
+        sanitizedFormat = sanitizedFormat.replace(/#(%?)$/, '0$1');
+    }
+    return sanitizedFormat;
+};
+
+/**
+ * Validates if a given number format is compatible with Globalize.
+ *
+ * @param format - The raw format string.
+ * @returns True if the format is valid; otherwise, false.
+ */
+export const validateNumberFormat = (format: string): boolean => {
+    try {
+        Globalize.numberFormatter({
+            ...({ raw: sanitizeFormat(format) } as any),
+        })(123); // Test the formatter with a dummy value
+    } catch (e) {
+        logger.error('Invalid number format:', format, e);
+        return false;
+    }
+    return true;
+};