@lightdash/common 2.15.0 → 2.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,7 +3,8 @@ import moment from 'moment';
3
3
  import momentTz from 'moment-timezone';
4
4
  import { Compact, CustomFormatType, DimensionType, FieldType, Format, MetricType, NumberSeparator, TableCalculationType, } from '../types/field';
5
5
  import { TimeFrames } from '../types/timeFrames';
6
- import { applyCustomFormat, applyDefaultFormat, convertCustomFormatToFormatExpression, currencies, formatDate, formatItemValue, formatNumberValue, formatTemporalCellForSpreadsheet, formatTimestamp, formatValueWithExpression, getCustomFormatFromLegacy, getEffectiveSeparator, getFieldFormatOverrideProps, getFormatExpressionLocale, getFormatterTimezone, isCalendarValueItem, isItemTimezoneAffected, isMomentInput, isTimestampString, isUnambiguousTemporalString, parseCalendarValueUTC, parseTimestampValueUTC, shouldShiftItemTimezone, toIsoWithProjectOffset, } from './formatting';
6
+ import { convertCustomMetricToDbt } from './convertCustomMetricsToYaml';
7
+ import { applyCustomFormat, applyDefaultFormat, convertCustomFormatToFormatExpression, currencies, formatDate, formatItemValue, formatNumberValue, formatTemporalCellForSpreadsheet, formatTimestamp, formatValueWithExpression, getCustomFormatFromLegacy, getEffectiveSeparator, getFieldFormatOverrideProps, getFormatExpression, getFormatExpressionLocale, getFormatterTimezone, isCalendarValueItem, isItemTimezoneAffected, isMomentInput, isTimestampString, isUnambiguousTemporalString, parseCalendarValueUTC, parseTimestampValueUTC, separatorToNumfmtLocale, shouldShiftItemTimezone, toIsoWithProjectOffset, } from './formatting';
7
8
  import { additionalMetric, dimension, metric, tableCalculation, } from './formatting.mock';
8
9
  describe('Formatting', () => {
9
10
  describe('getFormatterTimezone (unified shift decision)', () => {
@@ -1544,15 +1545,18 @@ describe('Formatting', () => {
1544
1545
  type: CustomFormatType.BYTES_IEC,
1545
1546
  compact: Compact.KIBIBYTES,
1546
1547
  });
1547
- expect(kibibyteExpression).toEqual('#,##0.00"KiB"');
1548
- expect(formatValueWithExpression(kibibyteExpression, 2048)).toEqual('2.00KiB');
1548
+ // No round → up to 3 trailing-dropped decimals, matching the
1549
+ // structured applyCustomFormat path (G4 alignment).
1550
+ expect(kibibyteExpression).toEqual('#,##0.###"KiB"');
1551
+ expect(formatValueWithExpression(kibibyteExpression, 2048)).toEqual('2KiB');
1552
+ expect(formatValueWithExpression(kibibyteExpression, 1536)).toEqual('1.5KiB');
1549
1553
  // Test MEBIBYTES (should divide by 1048576)
1550
1554
  const mebibyteExpression = convertCustomFormatToFormatExpression({
1551
1555
  type: CustomFormatType.BYTES_IEC,
1552
1556
  compact: Compact.MEBIBYTES,
1553
1557
  });
1554
- expect(mebibyteExpression).toEqual('#,##0.00"MiB"');
1555
- expect(formatValueWithExpression(mebibyteExpression, 2097152)).toEqual('2.00MiB');
1558
+ expect(mebibyteExpression).toEqual('#,##0.###"MiB"');
1559
+ expect(formatValueWithExpression(mebibyteExpression, 2097152)).toEqual('2MiB');
1556
1560
  // Test with rounding
1557
1561
  const roundedExpression = convertCustomFormatToFormatExpression({
1558
1562
  type: CustomFormatType.BYTES_IEC,
@@ -1571,7 +1575,7 @@ describe('Formatting', () => {
1571
1575
  };
1572
1576
  // Backend calls convertCustomFormatToFormatExpression
1573
1577
  const formatExpression = convertCustomFormatToFormatExpression(formatOptions);
1574
- expect(formatExpression).toEqual('#,##0.00"KiB"');
1578
+ expect(formatExpression).toEqual('#,##0.###"KiB"');
1575
1579
  // Mock metric with format expression set by backend
1576
1580
  const mockMetric = {
1577
1581
  fieldType: FieldType.METRIC,
@@ -1587,10 +1591,10 @@ describe('Formatting', () => {
1587
1591
  };
1588
1592
  // Frontend uses formatItemValue which should call formatValueWithExpression
1589
1593
  const result = formatItemValue(mockMetric, 2048);
1590
- expect(result).toEqual('2.00KiB'); // Should be correctly divided by 1024
1594
+ expect(result).toEqual('2KiB'); // Should be correctly divided by 1024
1591
1595
  // Test larger values
1592
- expect(formatItemValue(mockMetric, 1024)).toEqual('1.00KiB');
1593
- expect(formatItemValue(mockMetric, 3072)).toEqual('3.00KiB');
1596
+ expect(formatItemValue(mockMetric, 1024)).toEqual('1KiB');
1597
+ expect(formatItemValue(mockMetric, 3072)).toEqual('3KiB');
1594
1598
  });
1595
1599
  test('formatValueWithExpression ignores the incidental runtime timezone for date expressions (#19759)', () => {
1596
1600
  const previousTz = process.env.TZ;
@@ -2322,4 +2326,291 @@ describe('isUnambiguousTemporalString', () => {
2322
2326
  expect(isUnambiguousTemporalString(value)).toBe(false);
2323
2327
  });
2324
2328
  });
2329
+ // Converter gap fixes (docs/composer-viz-plan/01-design.md §2): the format
2330
+ // expression produced for a CustomFormat must render identically to the
2331
+ // structured applyCustomFormat path, or return null when no ECMA-376 form
2332
+ // exists (the formatOptions escape hatch).
2333
+ describe('convertCustomFormatToFormatExpression gap fixes', () => {
2334
+ const gridValues = [-9876543.21, 0, 0.1234, 1234567, 12345.1235];
2335
+ const gridRounds = [undefined, 0, 2, -2];
2336
+ const gridSeparators = [undefined, ...Object.values(NumberSeparator)];
2337
+ const gridTypes = [
2338
+ { type: CustomFormatType.DEFAULT },
2339
+ { type: CustomFormatType.ID },
2340
+ { type: CustomFormatType.PERCENT },
2341
+ { type: CustomFormatType.NUMBER },
2342
+ { type: CustomFormatType.CURRENCY, currency: Format.USD },
2343
+ { type: CustomFormatType.BYTES_SI },
2344
+ { type: CustomFormatType.BYTES_IEC },
2345
+ ];
2346
+ const magnitudeRoundTypes = [
2347
+ CustomFormatType.PERCENT,
2348
+ CustomFormatType.NUMBER,
2349
+ CustomFormatType.CURRENCY,
2350
+ CustomFormatType.BYTES_SI,
2351
+ CustomFormatType.BYTES_IEC,
2352
+ ];
2353
+ // Documented G10 divergences we do not attempt to close:
2354
+ // - DEFAULT ignores the separator in the structured path (host locale),
2355
+ // while the expression render localises it.
2356
+ // - PERIOD_COMMA currency moves the symbol after the number in de-DE.
2357
+ const isDocumentedDivergence = (type, separator) => (type === CustomFormatType.DEFAULT &&
2358
+ separator !== undefined &&
2359
+ separator !== NumberSeparator.DEFAULT &&
2360
+ separator !== NumberSeparator.COMMA_PERIOD) ||
2361
+ (type === CustomFormatType.CURRENCY &&
2362
+ separator === NumberSeparator.PERIOD_COMMA);
2363
+ test('round-trip grid: expression render matches applyCustomFormat', () => {
2364
+ gridTypes.forEach((baseFormat) => {
2365
+ gridRounds.forEach((round) => {
2366
+ gridSeparators.forEach((separator) => {
2367
+ const customFormat = {
2368
+ ...baseFormat,
2369
+ round,
2370
+ separator,
2371
+ };
2372
+ const expression = convertCustomFormatToFormatExpression(customFormat);
2373
+ if (expression === null) {
2374
+ // The only legitimate null in this grid is magnitude
2375
+ // rounding (negative round), which has no ECMA-376 form.
2376
+ expect({ customFormat, expression }).toEqual({
2377
+ customFormat,
2378
+ expression: round !== undefined &&
2379
+ round < 0 &&
2380
+ magnitudeRoundTypes.includes(baseFormat.type)
2381
+ ? null
2382
+ : expect.anything(),
2383
+ });
2384
+ return;
2385
+ }
2386
+ if (isDocumentedDivergence(baseFormat.type, separator)) {
2387
+ return;
2388
+ }
2389
+ gridValues.forEach((value) => {
2390
+ const structured = applyCustomFormat(value, customFormat);
2391
+ const viaExpression = formatValueWithExpression(expression, value, separatorToNumfmtLocale(separator));
2392
+ expect({
2393
+ customFormat,
2394
+ value,
2395
+ formatted: viaExpression,
2396
+ }).toEqual({
2397
+ customFormat,
2398
+ value,
2399
+ formatted: structured,
2400
+ });
2401
+ });
2402
+ });
2403
+ });
2404
+ });
2405
+ });
2406
+ test('magnitude rounding (negative round) returns null — formatOptions escape hatch', () => {
2407
+ magnitudeRoundTypes.forEach((type) => {
2408
+ expect(convertCustomFormatToFormatExpression({
2409
+ type,
2410
+ round: -2,
2411
+ ...(type === CustomFormatType.CURRENCY && {
2412
+ currency: Format.USD,
2413
+ }),
2414
+ })).toBeNull();
2415
+ });
2416
+ });
2417
+ test('dynamic AUTO compact returns null for bytes too', () => {
2418
+ expect(convertCustomFormatToFormatExpression({
2419
+ type: CustomFormatType.BYTES_SI,
2420
+ compact: Compact.AUTO,
2421
+ })).toBeNull();
2422
+ expect(convertCustomFormatToFormatExpression({
2423
+ type: CustomFormatType.BYTES_IEC,
2424
+ compact: Compact.AUTO,
2425
+ })).toBeNull();
2426
+ });
2427
+ test('DEFAULT emits the applyDefaultFormat equivalent', () => {
2428
+ expect(convertCustomFormatToFormatExpression({
2429
+ type: CustomFormatType.DEFAULT,
2430
+ })).toBe('#,##0.###');
2431
+ // round and separator are ignored by applyDefaultFormat, so the
2432
+ // expression must not encode them either.
2433
+ expect(convertCustomFormatToFormatExpression({
2434
+ type: CustomFormatType.DEFAULT,
2435
+ round: 2,
2436
+ separator: NumberSeparator.NO_SEPARATOR_PERIOD,
2437
+ })).toBe('#,##0.###');
2438
+ });
2439
+ test('ID emits the verbatim text format', () => {
2440
+ expect(convertCustomFormatToFormatExpression({
2441
+ type: CustomFormatType.ID,
2442
+ })).toBe('@');
2443
+ // Large numeric IDs must render verbatim, not in scientific notation.
2444
+ expect(formatValueWithExpression('@', 1234567890123456)).toBe('1234567890123456');
2445
+ expect(formatValueWithExpression('@', 'ID-123')).toBe('ID-123');
2446
+ expect(formatValueWithExpression('@', 12345)).toBe(applyCustomFormat(12345, { type: CustomFormatType.ID }));
2447
+ });
2448
+ test('DATE emits per-grain expressions; QUARTER stays renderer-side', () => {
2449
+ expect(convertCustomFormatToFormatExpression({
2450
+ type: CustomFormatType.DATE,
2451
+ timeInterval: TimeFrames.YEAR,
2452
+ })).toBe('yyyy');
2453
+ expect(convertCustomFormatToFormatExpression({
2454
+ type: CustomFormatType.DATE,
2455
+ timeInterval: TimeFrames.MONTH,
2456
+ })).toBe('yyyy-mm');
2457
+ expect(convertCustomFormatToFormatExpression({
2458
+ type: CustomFormatType.DATE,
2459
+ timeInterval: TimeFrames.DAY,
2460
+ })).toBe('yyyy-mm-dd');
2461
+ expect(convertCustomFormatToFormatExpression({
2462
+ type: CustomFormatType.DATE,
2463
+ timeInterval: TimeFrames.WEEK,
2464
+ })).toBe('yyyy-mm-dd');
2465
+ expect(convertCustomFormatToFormatExpression({
2466
+ type: CustomFormatType.DATE,
2467
+ })).toBe('yyyy-mm-dd');
2468
+ // No ECMA-376 quarter token; renderer resolves it via timeInterval.
2469
+ expect(convertCustomFormatToFormatExpression({
2470
+ type: CustomFormatType.DATE,
2471
+ timeInterval: TimeFrames.QUARTER,
2472
+ })).toBeNull();
2473
+ });
2474
+ test('DATE expressions render like the structured path', () => {
2475
+ const date = new Date(Date.UTC(2024, 0, 2, 3, 4, 5));
2476
+ [
2477
+ [TimeFrames.YEAR, '2024'],
2478
+ [TimeFrames.MONTH, '2024-01'],
2479
+ [TimeFrames.DAY, '2024-01-02'],
2480
+ ].forEach(([timeInterval, expected]) => {
2481
+ const customFormat = {
2482
+ type: CustomFormatType.DATE,
2483
+ timeInterval,
2484
+ };
2485
+ const expression = convertCustomFormatToFormatExpression(customFormat);
2486
+ expect(formatValueWithExpression(expression, date, undefined, 'UTC')).toBe(expected);
2487
+ expect(applyCustomFormat(date, customFormat, 'UTC')).toBe(expected);
2488
+ });
2489
+ });
2490
+ test('TIMESTAMP emits sub-day expressions to the second; the (Z) offset suffix stays renderer-side', () => {
2491
+ expect(convertCustomFormatToFormatExpression({
2492
+ type: CustomFormatType.TIMESTAMP,
2493
+ timeInterval: TimeFrames.HOUR,
2494
+ })).toBe('yyyy-mm-dd, hh');
2495
+ expect(convertCustomFormatToFormatExpression({
2496
+ type: CustomFormatType.TIMESTAMP,
2497
+ timeInterval: TimeFrames.MINUTE,
2498
+ })).toBe('yyyy-mm-dd, hh:mm');
2499
+ expect(convertCustomFormatToFormatExpression({
2500
+ type: CustomFormatType.TIMESTAMP,
2501
+ timeInterval: TimeFrames.SECOND,
2502
+ })).toBe('yyyy-mm-dd, hh:mm:ss');
2503
+ // Milliseconds (the default grain) render as `:SSS (Z)` in the
2504
+ // structured path — no ECMA-376 form, stays renderer-side.
2505
+ expect(convertCustomFormatToFormatExpression({
2506
+ type: CustomFormatType.TIMESTAMP,
2507
+ })).toBeNull();
2508
+ expect(convertCustomFormatToFormatExpression({
2509
+ type: CustomFormatType.TIMESTAMP,
2510
+ timeInterval: TimeFrames.MILLISECOND,
2511
+ })).toBeNull();
2512
+ const date = new Date(Date.UTC(2024, 0, 2, 3, 4, 5));
2513
+ // The structured equivalent is '2024-01-02, 03:04:05 (+00:00)'; the
2514
+ // expression carries everything except the offset suffix.
2515
+ expect(formatValueWithExpression('yyyy-mm-dd, hh:mm:ss', date, undefined, 'UTC')).toBe('2024-01-02, 03:04:05');
2516
+ });
2517
+ test('quotes in prefix/suffix are escaped', () => {
2518
+ const customFormat = {
2519
+ type: CustomFormatType.NUMBER,
2520
+ prefix: 'ab"cd',
2521
+ suffix: ' un"it',
2522
+ round: 0,
2523
+ };
2524
+ const expression = convertCustomFormatToFormatExpression(customFormat);
2525
+ expect(expression).toBe('"ab"\\""cd"#,##0" un"\\""it"');
2526
+ expect(formatValueWithExpression(expression, 5)).toBe(applyCustomFormat(5, customFormat));
2527
+ expect(formatValueWithExpression(expression, 5)).toBe('ab"cd5 un"it');
2528
+ });
2529
+ test('all-optional decimals never leave a dangling separator', () => {
2530
+ expect(formatValueWithExpression('#,##0.###', 1234567)).toBe('1,234,567');
2531
+ expect(formatValueWithExpression('#,##0.###', 0)).toBe('0');
2532
+ expect(formatValueWithExpression('#,##0.###,"K"', 1000000)).toBe('1,000K');
2533
+ expect(formatValueWithExpression('#,##0.###', 1234567, separatorToNumfmtLocale(NumberSeparator.PERIOD_COMMA))).toBe('1.234.567');
2534
+ // Fixed decimals are untouched.
2535
+ expect(formatValueWithExpression('0.00', 5)).toBe('5.00');
2536
+ });
2537
+ });
2538
+ describe('getFormatExpression year-number guard', () => {
2539
+ const yearNumDimension = {
2540
+ ...dimension,
2541
+ type: DimensionType.NUMBER,
2542
+ timeInterval: TimeFrames.YEAR_NUM,
2543
+ };
2544
+ test('emits no expression for YEAR_NUM dimensions', () => {
2545
+ // formatItemValue renders year numbers as plain unseparated values,
2546
+ // short-circuiting before applyCustomFormat — the expression must not
2547
+ // reintroduce digit grouping (2021, never 2,021).
2548
+ expect(getFormatExpression(yearNumDimension)).toBeUndefined();
2549
+ expect(getFormatExpression({ ...yearNumDimension, round: 0 })).toBeUndefined();
2550
+ expect(formatItemValue(yearNumDimension, 2021)).toBe('2021');
2551
+ });
2552
+ });
2553
+ // Blast-radius pins (docs/composer-viz-plan/01-design.md §2): existing
2554
+ // consumers of the converter whose output changes with the gap fixes.
2555
+ describe('converter gap fixes blast radius', () => {
2556
+ describe('getFieldFormatOverrideProps', () => {
2557
+ test('DEFAULT/ID/DATE overrides now encode as expressions', () => {
2558
+ expect(getFieldFormatOverrideProps({
2559
+ type: CustomFormatType.DEFAULT,
2560
+ })).toEqual({ format: '#,##0.###', separator: undefined });
2561
+ expect(getFieldFormatOverrideProps({ type: CustomFormatType.ID })).toEqual({ format: '@', separator: undefined });
2562
+ expect(getFieldFormatOverrideProps({
2563
+ type: CustomFormatType.DATE,
2564
+ timeInterval: TimeFrames.MONTH,
2565
+ })).toEqual({ format: 'yyyy-mm', separator: undefined });
2566
+ });
2567
+ test('non-expressible overrides keep structured formatOptions', () => {
2568
+ const quarterDate = {
2569
+ type: CustomFormatType.DATE,
2570
+ timeInterval: TimeFrames.QUARTER,
2571
+ };
2572
+ expect(getFieldFormatOverrideProps(quarterDate)).toEqual({
2573
+ format: undefined,
2574
+ formatOptions: quarterDate,
2575
+ separator: undefined,
2576
+ });
2577
+ const millisecondTimestamp = {
2578
+ type: CustomFormatType.TIMESTAMP,
2579
+ };
2580
+ expect(getFieldFormatOverrideProps(millisecondTimestamp)).toEqual({
2581
+ format: undefined,
2582
+ formatOptions: millisecondTimestamp,
2583
+ separator: undefined,
2584
+ });
2585
+ const magnitudeRound = {
2586
+ type: CustomFormatType.NUMBER,
2587
+ round: -2,
2588
+ };
2589
+ expect(getFieldFormatOverrideProps(magnitudeRound)).toEqual({
2590
+ format: undefined,
2591
+ formatOptions: magnitudeRound,
2592
+ separator: undefined,
2593
+ });
2594
+ });
2595
+ });
2596
+ describe('convertCustomMetricToDbt writeback output', () => {
2597
+ test('unformatted numeric metrics keep the pre-existing default expression', () => {
2598
+ expect(convertCustomMetricToDbt(additionalMetric).format).toBe('#,##0.###');
2599
+ });
2600
+ test('legacy percent metrics emit trailing-dropped decimals (G4 alignment)', () => {
2601
+ // Was '#,##0.00%' before the round-default fix.
2602
+ expect(convertCustomMetricToDbt({
2603
+ ...additionalMetric,
2604
+ format: Format.PERCENT,
2605
+ }).format).toBe('#,##0.###%');
2606
+ });
2607
+ test('legacy id metrics now emit the text format', () => {
2608
+ // Was undefined before the ID fix.
2609
+ expect(convertCustomMetricToDbt({
2610
+ ...additionalMetric,
2611
+ format: Format.ID,
2612
+ }).format).toBe('@');
2613
+ });
2614
+ });
2615
+ });
2325
2616
  //# sourceMappingURL=formatting.test.js.map