@openmrs/esm-report-builder 0.1.1-pre.101

package/src/utils/etl-monitor/status-mapper.util.ts

@@ -0,0 +1,105 @@
+/**
+ * Status Mapper Utility
+ * Map status values to display colors and labels
+ */
+
+/**
+ * Get status color for a status value
+ */
+export function getStatusColor(status: string): string {
+  const normalizedStatus = status?.toLowerCase() || '';
+
+  const colorMap: Record<string, string> = {
+    // Success states
+    success: 'green',
+    completed: 'green',
+    complete: 'green',
+    finished: 'green',
+    done: 'green',
+    ok: 'green',
+    active: 'blue',
+    running: 'blue',
+    in_progress: 'blue',
+    started: 'blue',
+
+    // Warning states
+    warning: 'orange',
+    pending: 'orange',
+    waiting: 'orange',
+    queued: 'orange',
+    retry: 'orange',
+
+    // Error states
+    error: 'red',
+    failed: 'red',
+    failure: 'red',
+    stopped: 'red',
+    cancelled: 'gray',
+    canceled: 'gray',
+
+    // Information states
+    info: 'blue',
+    unknown: 'gray',
+  };
+
+  return colorMap[normalizedStatus] || 'gray';
+}
+
+/**
+ * Get status label (human-readable)
+ */
+export function getStatusLabel(status: string): string {
+  const normalizedStatus = status?.toLowerCase() || '';
+
+  const labelMap: Record<string, string> = {
+    success: 'Success',
+    completed: 'Completed',
+    complete: 'Complete',
+    finished: 'Finished',
+    done: 'Done',
+    ok: 'OK',
+    active: 'Active',
+    running: 'Running',
+    in_progress: 'In Progress',
+    started: 'Started',
+    warning: 'Warning',
+    pending: 'Pending',
+    waiting: 'Waiting',
+    queued: 'Queued',
+    retry: 'Retrying',
+    error: 'Error',
+    failed: 'Failed',
+    failure: 'Failure',
+    stopped: 'Stopped',
+    cancelled: 'Cancelled',
+    canceled: 'Cancelled',
+    info: 'Info',
+    unknown: 'Unknown',
+  };
+
+  return labelMap[normalizedStatus] || status || 'Unknown';
+}
+
+/**
+ * Check if status is successful
+ */
+export function isSuccessfulStatus(status: string): boolean {
+  const color = getStatusColor(status);
+  return color === 'green';
+}
+
+/**
+ * Check if status is error state
+ */
+export function isErrorStatus(status: string): boolean {
+  const color = getStatusColor(status);
+  return color === 'red';
+}
+
+/**
+ * Check if status is running
+ */
+export function isRunningStatus(status: string): boolean {
+  const color = getStatusColor(status);
+  return color === 'blue';
+}

package/src/utils/etl-monitor/value-formatters.util.ts

@@ -0,0 +1,167 @@
+/**
+ * Value Formatters Utility
+ * Format values for display based on type
+ */
+
+/**
+ * Format value based on type
+ */
+export function formatValue(value: any, type: string, options?: any): string {
+  if (value === null || value === undefined) {
+    return '—';
+  }
+
+  switch (type) {
+    case 'DATE':
+      return formatDate(value);
+    case 'DATETIME':
+      return formatDateTime(value);
+    case 'NUMBER':
+      return formatNumber(value, options?.decimals);
+    case 'PERCENTAGE':
+      return formatPercentage(value);
+    case 'CURRENCY':
+      return formatCurrency(value, options?.currency);
+    case 'BOOLEAN':
+      return value ? 'Yes' : 'No';
+    case 'DURATION':
+      return formatDuration(value);
+    case 'FILE_SIZE':
+      return formatFileSize(value);
+    default:
+      return String(value);
+  }
+}
+
+/**
+ * Format date
+ */
+export function formatDate(value: any): string {
+  if (!value) return '—';
+  const date = new Date(value);
+  if (isNaN(date.getTime())) return String(value);
+  return date.toLocaleDateString(undefined, {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  });
+}
+
+/**
+ * Format datetime
+ */
+export function formatDateTime(value: any): string {
+  if (!value) return '—';
+  const date = new Date(value);
+  if (isNaN(date.getTime())) return String(value);
+  return date.toLocaleString();
+}
+
+/**
+ * Format number
+ */
+export function formatNumber(value: any, decimals = 2): string {
+  if (typeof value !== 'number') return String(value);
+  return value.toLocaleString(undefined, {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  });
+}
+
+/**
+ * Format percentage
+ */
+export function formatPercentage(value: any): string {
+  if (typeof value !== 'number') return String(value);
+  return `${value.toFixed(1)}%`;
+}
+
+/**
+ * Format currency
+ */
+export function formatCurrency(value: any, currency = 'USD'): string {
+  if (typeof value !== 'number') return String(value);
+  return new Intl.NumberFormat(undefined, {
+    style: 'currency',
+    currency,
+  }).format(value);
+}
+
+/**
+ * Format duration (milliseconds)
+ */
+export function formatDuration(value: any): string {
+  if (typeof value !== 'number') return String(value);
+
+  const seconds = Math.floor(value / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (days > 0) {
+    return `${days}d ${hours % 24}h`;
+  }
+  if (hours > 0) {
+    return `${hours}h ${minutes % 60}m`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m ${seconds % 60}s`;
+  }
+  return `${seconds}s`;
+}
+
+/**
+ * Format file size
+ */
+export function formatFileSize(bytes: number): string {
+  if (typeof bytes !== 'number') return String(bytes);
+
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let size = bytes;
+  let unitIndex = 0;
+
+  while (size >= 1024 && unitIndex < units.length - 1) {
+    size /= 1024;
+    unitIndex++;
+  }
+
+  return `${size.toFixed(1)} ${units[unitIndex]}`;
+}
+
+/**
+ * Format a timestamp as a relative time string.
+ * Past: "5 minutes ago". Future: "in 51 minutes".
+ * With `pastOnly`, near-future timestamps (clock skew) render as "just now" —
+ * for "last updated"-style fields.
+ */
+export function formatRelativeTime(value: any, options?: { pastOnly?: boolean }): string {
+  if (value === null || value === undefined || value === '') return '—';
+  const date = new Date(value);
+  if (isNaN(date.getTime())) return String(value);
+
+  const diffMs = date.getTime() - Date.now();
+  const absMs = Math.abs(diffMs);
+
+  if (absMs < 60000) {
+    if (diffMs < 0 || options?.pastOnly) {
+      return 'just now';
+    }
+    return 'in less than a minute';
+  }
+
+  let unitValue: number;
+  let unit: string;
+  if (absMs < 3600000) {
+    unitValue = Math.floor(absMs / 60000);
+    unit = 'minute';
+  } else if (absMs < 86400000) {
+    unitValue = Math.floor(absMs / 3600000);
+    unit = 'hour';
+  } else {
+    unitValue = Math.floor(absMs / 86400000);
+    unit = 'day';
+  }
+
+  const plural = unitValue === 1 ? unit : `${unit}s`;
+  return diffMs >= 0 ? `in ${unitValue} ${plural}` : `${unitValue} ${plural} ago`;
+}

package/src/utils/etl-task/etl-task-card.util.test.ts

@@ -0,0 +1,240 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  computeNextRun,
+  countStatusEntries,
+  extractDurationFromMonitorData,
+  findMonitorByRef,
+  formatLastRun,
+  formatNextRun,
+  formatRepeatInterval,
+  parseLenientDate,
+  resolveProgressMonitors,
+  sumStatusCounts,
+} from './etl-task-card.util';
+import type { ETLMonitorDto } from '../../types/etl-monitor';
+
+const NOW = new Date('2026-09-04T12:00:00');
+
+function monitor(uuid: string, code?: string): ETLMonitorDto {
+  return { uuid, name: uuid, monitorType: 'STATUS_CARD', code } as ETLMonitorDto;
+}
+
+const monitors = [monitor('uuid-1', 'alpha-monitor'), monitor('uuid-2', 'Beta Monitor')];
+
+describe('etl-task-card.util', () => {
+  beforeEach(() => {
+    vi.useFakeTimers().setSystemTime(NOW);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('parseLenientDate', () => {
+    it('parses colon-less UTC offsets (OpenMRS serialization)', () => {
+      expect(parseLenientDate('2026-09-04T09:12:00+0300')).not.toBeNull();
+    });
+
+    it('returns null for unusable values', () => {
+      expect(parseLenientDate(null)).toBeNull();
+      expect(parseLenientDate('')).toBeNull();
+      expect(parseLenientDate('not-a-date')).toBeNull();
+    });
+  });
+
+  describe('formatLastRun', () => {
+    it('renders a dash for empty values', () => {
+      expect(formatLastRun(null)).toBe('—');
+      expect(formatLastRun(undefined)).toBe('—');
+      expect(formatLastRun('')).toBe('—');
+    });
+
+    it('labels today and yesterday', () => {
+      expect(formatLastRun('2026-09-04T09:12:00')).toBe('Today, 09:12');
+      expect(formatLastRun('2026-09-03T23:05:00')).toBe('Yesterday, 23:05');
+    });
+
+    it('formats older dates with day and month', () => {
+      expect(formatLastRun('2026-08-12T09:12:00')).toBe('12 Aug, 09:12');
+    });
+
+    it('passes garbage through as its string value', () => {
+      expect(formatLastRun('not-a-date')).toBe('not-a-date');
+    });
+  });
+
+  describe('computeNextRun', () => {
+    it('adds the repeat interval to the last execution time', () => {
+      expect(computeNextRun('2026-09-04T09:00:00', 1800)).toEqual(new Date('2026-09-04T09:30:00'));
+      expect(computeNextRun('2026-09-04T09:00:00', 21600)).toEqual(new Date('2026-09-04T15:00:00'));
+    });
+
+    it('returns null for one-shot or invalid intervals', () => {
+      expect(computeNextRun('2026-09-04T09:00:00', 0)).toBeNull();
+      expect(computeNextRun('2026-09-04T09:00:00', -5)).toBeNull();
+      expect(computeNextRun('2026-09-04T09:00:00', NaN)).toBeNull();
+      expect(computeNextRun('2026-09-04T09:00:00', undefined)).toBeNull();
+    });
+
+    it('returns null without a last execution time', () => {
+      expect(computeNextRun(null, 1800)).toBeNull();
+      expect(computeNextRun('not-a-date', 1800)).toBeNull();
+    });
+  });
+
+  describe('formatNextRun', () => {
+    it('reports unscheduled tasks', () => {
+      expect(formatNextRun(null)).toBe('Not scheduled');
+    });
+
+    it('formats a computed next run', () => {
+      expect(formatNextRun(new Date('2026-09-04T13:00:00'))).toBe('Today, 13:00');
+    });
+  });
+
+  describe('formatRepeatInterval', () => {
+    it('renders a dash for absent or one-shot intervals', () => {
+      expect(formatRepeatInterval(undefined)).toBe('—');
+      expect(formatRepeatInterval(null)).toBe('—');
+      expect(formatRepeatInterval(0)).toBe('—');
+    });
+
+    it('humanizes intervals', () => {
+      expect(formatRepeatInterval(30)).toBe('Every 30 s');
+      expect(formatRepeatInterval(1800)).toBe('Every 30 min');
+      expect(formatRepeatInterval(21600)).toBe('Every 6 h');
+      expect(formatRepeatInterval(172800)).toBe('Every 2 d');
+      expect(formatRepeatInterval(5400)).toBe('Every 1.5 h');
+    });
+  });
+
+  describe('findMonitorByRef', () => {
+    it('returns undefined for empty or invalid references', () => {
+      expect(findMonitorByRef(monitors, '')).toBeUndefined();
+      expect(findMonitorByRef(monitors, '   ')).toBeUndefined();
+      expect(findMonitorByRef(monitors, 5 as unknown as string)).toBeUndefined();
+      expect(findMonitorByRef(monitors, undefined)).toBeUndefined();
+    });
+
+    it('is null-safe', () => {
+      expect(findMonitorByRef(null, 'uuid-1')).toBeUndefined();
+      expect(findMonitorByRef([], 'uuid-1')).toBeUndefined();
+    });
+
+    it('matches by uuid exactly and case-insensitively', () => {
+      expect(findMonitorByRef(monitors, 'uuid-1')?.uuid).toBe('uuid-1');
+      expect(findMonitorByRef(monitors, 'UUID-1')?.uuid).toBe('uuid-1');
+    });
+
+    it('matches by code case-insensitively', () => {
+      expect(findMonitorByRef(monitors, 'beta monitor')?.uuid).toBe('uuid-2');
+    });
+
+    it('prefers uuid over code when both could match', () => {
+      const both = [...monitors, monitor('uuid-3', 'uuid-2')];
+      expect(findMonitorByRef(both, 'uuid-2')?.uuid).toBe('uuid-2');
+    });
+  });
+
+  describe('resolveProgressMonitors', () => {
+    it('returns an empty list for missing or empty refs', () => {
+      expect(resolveProgressMonitors(monitors, undefined)).toEqual([]);
+      expect(resolveProgressMonitors(monitors, [])).toEqual([]);
+      expect(resolveProgressMonitors(monitors, ['   ', ''])).toEqual([]);
+    });
+
+    it('resolves refs in config order', () => {
+      const resolved = resolveProgressMonitors(monitors, ['beta monitor', 'uuid-1']);
+      expect(resolved.map((entry) => entry.monitor?.uuid)).toEqual(['uuid-2', 'uuid-1']);
+    });
+
+    it('deduplicates refs that resolve to the same monitor', () => {
+      const resolved = resolveProgressMonitors(monitors, ['uuid-1', 'alpha-monitor']);
+      expect(resolved).toHaveLength(1);
+      expect(resolved[0].monitor?.uuid).toBe('uuid-1');
+    });
+
+    it('keeps unresolved refs visible for typos', () => {
+      const resolved = resolveProgressMonitors(monitors, ['uuid-1', 'nope-monitor']);
+      expect(resolved).toHaveLength(2);
+      expect(resolved[1].monitor).toBeUndefined();
+      expect(resolved[1].ref).toBe('nope-monitor');
+    });
+  });
+
+  describe('extractDurationFromMonitorData', () => {
+    it('returns null when nothing usable is found', () => {
+      expect(extractDurationFromMonitorData(null)).toBeNull();
+      expect(extractDurationFromMonitorData('string')).toBeNull();
+      expect(extractDurationFromMonitorData({})).toBeNull();
+      expect(extractDurationFromMonitorData({ status: 'ok', rows: 5 })).toBeNull();
+    });
+
+    it('formats top-level and nested durations as milliseconds', () => {
+      expect(extractDurationFromMonitorData({ duration: 48000 })).toBe('48s');
+      expect(extractDurationFromMonitorData({ summary: { durationMs: 48000 } })).toBe('48s');
+      expect(extractDurationFromMonitorData({ totalDurationMillis: 134000 })).toBe('2m 14s');
+    });
+
+    it('scales seconds-named fields', () => {
+      expect(extractDurationFromMonitorData({ durationSeconds: 48 })).toBe('48s');
+    });
+
+    it('passes pre-formatted strings through and parses numeric strings', () => {
+      expect(extractDurationFromMonitorData({ duration: '2m 14s' })).toBe('2m 14s');
+      expect(extractDurationFromMonitorData({ runtime: '48' })).toBe('48s');
+    });
+
+    it('skips null values and searches arrays', () => {
+      expect(extractDurationFromMonitorData({ duration: null, elapsedMs: 61000 })).toBe('1m 1s');
+      expect(extractDurationFromMonitorData([{ runtime: 65000 }])).toBe('1m 5s');
+    });
+
+    it('terminates on cyclic structures', () => {
+      const cyclic: Record<string, unknown> = { status: 'running' };
+      cyclic['self'] = cyclic;
+      expect(extractDurationFromMonitorData(cyclic)).toBeNull();
+    });
+  });
+
+  describe('countStatusEntries', () => {
+    const RUNNING = /running|in.?progress|processing/i;
+    const FAILED = /fail|error/i;
+
+    it('counts status entries in arrays of job objects', () => {
+      const raw = { jobs: [{ status: 'RUNNING' }, { status: 'COMPLETED' }, { status: 'Running' }] };
+      expect(countStatusEntries(raw, RUNNING)).toBe(2);
+      expect(countStatusEntries(raw, FAILED)).toBeUndefined();
+    });
+
+    it('reads numeric count fields keyed by the pattern', () => {
+      expect(countStatusEntries({ runningCount: 3 }, RUNNING)).toBe(3);
+      expect(countStatusEntries({ data: { failedCount: 2 } }, FAILED)).toBe(2);
+    });
+
+    it('returns undefined for empty or non-matching payloads', () => {
+      expect(countStatusEntries(null, RUNNING)).toBeUndefined();
+      expect(countStatusEntries('string', RUNNING)).toBeUndefined();
+      expect(countStatusEntries({ status: 'ok' }, RUNNING)).toBeUndefined();
+      expect(countStatusEntries({}, RUNNING)).toBeUndefined();
+    });
+
+    it('is cycle-safe', () => {
+      const cyclic: Record<string, unknown> = { status: 'RUNNING' };
+      cyclic['self'] = cyclic;
+      expect(countStatusEntries(cyclic, RUNNING)).toBe(1);
+    });
+  });
+
+  describe('sumStatusCounts', () => {
+    it('sums across responses and skips signal-less ones', () => {
+      const raws = [{ runningCount: 2 }, { jobs: [{ status: 'RUNNING' }] }, { nothing: 'here' }, null];
+      expect(sumStatusCounts(raws, /running/i)).toBe(3);
+    });
+
+    it('returns undefined when no response yields a signal', () => {
+      expect(sumStatusCounts([null, {}, 'x'], /running/i)).toBeUndefined();
+      expect(sumStatusCounts([], /running/i)).toBeUndefined();
+    });
+  });
+});