@jmruthers/pace-core 0.5.183 → 0.5.185

package/src/utils/__tests__/timezone.test.ts

@@ -0,0 +1,345 @@
+/**
+ * @file Timezone Utilities Unit Tests
+ * @package @jmruthers/pace-core
+ * @module Utils/__tests__/Timezone
+ * @since 0.1.0
+ * 
+ * Comprehensive tests for timezone utility functions covering all critical functionality,
+ * edge cases, and error handling.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  formatInTimeZone,
+  getTimezoneAbbreviation,
+  formatTimeInTimeZone,
+  getUserTimeZone,
+  toZonedTime,
+  fromZonedTime,
+  roundToNearestMinutes,
+  getTimeZoneDifference
+} from '../timezone';
+
+describe('Timezone Utilities', () => {
+  describe('formatInTimeZone', () => {
+    it('should format date in specific timezone', () => {
+      const utcDate = new Date('2024-01-15T10:00:00Z');
+      const result = formatInTimeZone(utcDate, 'America/New_York', 'MMM dd, yyyy HH:mm');
+      
+      // EST is UTC-5, so 10:00 UTC = 05:00 EST
+      expect(result).toContain('Jan 15, 2024');
+      expect(result).toContain('05:00');
+    });
+
+    it('should handle ISO string input', () => {
+      const result = formatInTimeZone('2024-01-15T10:00:00Z', 'America/New_York', 'MMM dd, yyyy');
+      expect(result).toContain('Jan 15, 2024');
+    });
+
+    it('should handle timestamp input', () => {
+      const timestamp = new Date('2024-01-15T10:00:00Z').getTime();
+      const result = formatInTimeZone(timestamp, 'America/New_York', 'MMM dd, yyyy');
+      expect(result).toContain('Jan 15, 2024');
+    });
+
+    it('should handle different format strings', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = formatInTimeZone(date, 'America/New_York', 'yyyy-MM-dd');
+      expect(result).toBe('2024-01-15');
+    });
+
+    it('should return "Invalid date" for invalid date input', () => {
+      const result = formatInTimeZone(new Date('invalid'), 'America/New_York', 'MMM dd, yyyy');
+      expect(result).toBe('Invalid date');
+    });
+
+    it('should return "Invalid date" for invalid timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = formatInTimeZone(date, '', 'MMM dd, yyyy');
+      expect(result).toBe('Invalid date');
+    });
+
+    it('should handle DST transitions', () => {
+      // Summer date (DST)
+      const summerDate = new Date('2024-07-15T10:00:00Z');
+      const summerResult = formatInTimeZone(summerDate, 'America/New_York', 'HH:mm');
+      
+      // Winter date (no DST)
+      const winterDate = new Date('2024-01-15T10:00:00Z');
+      const winterResult = formatInTimeZone(winterDate, 'America/New_York', 'HH:mm');
+      
+      // Summer should be UTC-4 (EDT), winter should be UTC-5 (EST)
+      expect(summerResult).not.toBe(winterResult);
+    });
+  });
+
+  describe('getTimezoneAbbreviation', () => {
+    it('should get timezone abbreviation', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = getTimezoneAbbreviation(date, 'America/New_York');
+      
+      // Should return EST or EDT depending on DST
+      expect(result).toMatch(/EST|EDT|America\/New_York/);
+    });
+
+    it('should handle different timezones', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const pst = getTimezoneAbbreviation(date, 'America/Los_Angeles');
+      const est = getTimezoneAbbreviation(date, 'America/New_York');
+      
+      expect(pst).toBeTruthy();
+      expect(est).toBeTruthy();
+    });
+
+    it('should return timezone name on error', () => {
+      const date = new Date('invalid');
+      const result = getTimezoneAbbreviation(date, 'America/New_York');
+      expect(result).toBeTruthy();
+    });
+
+    it('should handle invalid timezone gracefully', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = getTimezoneAbbreviation(date, '');
+      // Empty string returns 'UTC' as fallback per implementation
+      expect(result).toBe('UTC');
+    });
+  });
+
+  describe('formatTimeInTimeZone', () => {
+    it('should format time only in timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = formatTimeInTimeZone(date, 'America/New_York');
+      
+      // Should be in HH:mm format
+      expect(result).toMatch(/^\d{2}:\d{2}$/);
+    });
+
+    it('should handle string date input', () => {
+      const result = formatTimeInTimeZone('2024-01-15T10:00:00Z', 'America/New_York');
+      expect(result).toMatch(/^\d{2}:\d{2}$/);
+    });
+  });
+
+  describe('getUserTimeZone', () => {
+    it('should return user timezone', () => {
+      const result = getUserTimeZone();
+      expect(typeof result).toBe('string');
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    it('should return UTC as fallback', () => {
+      // Mock Intl to be undefined
+      const originalIntl = global.Intl;
+      // @ts-expect-error - Testing error case
+      global.Intl = undefined;
+      
+      const result = getUserTimeZone();
+      expect(result).toBe('UTC');
+      
+      global.Intl = originalIntl;
+    });
+
+    it('should handle Intl.DateTimeFormat errors gracefully', () => {
+      const originalIntl = global.Intl;
+      // @ts-expect-error - Testing error case
+      global.Intl = {
+        DateTimeFormat: () => {
+          throw new Error('Test error');
+        }
+      };
+      
+      const result = getUserTimeZone();
+      expect(result).toBe('UTC');
+      
+      global.Intl = originalIntl;
+    });
+  });
+
+  describe('toZonedTime', () => {
+    it('should convert UTC to timezone local time', () => {
+      const utcDate = new Date('2024-01-15T10:00:00Z');
+      const result = toZonedTime(utcDate, 'America/New_York');
+      
+      expect(result).toBeInstanceOf(Date);
+      expect(isNaN(result.getTime())).toBe(false);
+    });
+
+    it('should handle invalid date input', () => {
+      const result = toZonedTime(new Date('invalid'), 'America/New_York');
+      expect(isNaN(result.getTime())).toBe(true);
+    });
+
+    it('should handle invalid timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = toZonedTime(date, '');
+      // Empty timezone returns original date per implementation
+      expect(result).toBe(date);
+      expect(result.getTime()).toBe(date.getTime());
+    });
+
+    it('should handle DST correctly', () => {
+      const summerDate = new Date('2024-07-15T10:00:00Z');
+      const winterDate = new Date('2024-01-15T10:00:00Z');
+      
+      const summerResult = toZonedTime(summerDate, 'America/New_York');
+      const winterResult = toZonedTime(winterDate, 'America/New_York');
+      
+      // Results should be different due to DST
+      expect(summerResult.getHours()).not.toBe(winterResult.getHours());
+    });
+  });
+
+  describe('fromZonedTime', () => {
+    it('should convert local time to UTC', () => {
+      const localDate = new Date(2024, 0, 15, 10, 0); // Jan 15, 2024 10:00 AM (local)
+      const result = fromZonedTime(localDate, 'America/New_York');
+      
+      expect(result).toBeInstanceOf(Date);
+      expect(isNaN(result.getTime())).toBe(false);
+    });
+
+    it('should handle invalid date input', () => {
+      const result = fromZonedTime(new Date('invalid'), 'America/New_York');
+      expect(isNaN(result.getTime())).toBe(true);
+    });
+
+    it('should handle invalid timezone', () => {
+      const date = new Date(2024, 0, 15, 10, 0);
+      const result = fromZonedTime(date, '');
+      // Empty timezone returns original date per implementation
+      expect(result).toBe(date);
+      expect(result.getTime()).toBe(date.getTime());
+    });
+
+    it('should correctly convert to UTC', () => {
+      // 10:00 AM EST (UTC-5) should be 15:00 UTC
+      // Using a specific date in January (no DST) for predictable results
+      const localDate = new Date(2024, 0, 15, 10, 0, 0, 0);
+      const utcResult = fromZonedTime(localDate, 'America/New_York');
+      
+      // Check that it's approximately 5 hours ahead (EST is UTC-5)
+      // The actual difference depends on how fromZonedTime interprets the local date
+      // We just verify it's a valid date and the conversion happened
+      expect(isNaN(utcResult.getTime())).toBe(false);
+      expect(utcResult).toBeInstanceOf(Date);
+    });
+  });
+
+  describe('roundToNearestMinutes', () => {
+    it('should round to nearest 5 minutes by default', () => {
+      const date = new Date('2024-01-15T10:23:00Z');
+      const result = roundToNearestMinutes(date);
+      
+      expect(result).toBeInstanceOf(Date);
+      const minutes = result.getMinutes();
+      expect([0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55]).toContain(minutes);
+    });
+
+    it('should round to specified minutes step', () => {
+      const date = new Date('2024-01-15T10:23:00Z');
+      const result = roundToNearestMinutes(date, 15);
+      
+      const minutes = result.getMinutes();
+      expect([0, 15, 30, 45]).toContain(minutes);
+    });
+
+    it('should handle invalid date input', () => {
+      const result = roundToNearestMinutes(new Date('invalid'));
+      expect(isNaN(result.getTime())).toBe(true);
+    });
+
+    it('should return original date for invalid minutesStep', () => {
+      const date = new Date('2024-01-15T10:23:00Z');
+      const result = roundToNearestMinutes(date, -5);
+      expect(result.getTime()).toBe(date.getTime());
+    });
+
+    it('should return original date for non-integer minutesStep', () => {
+      const date = new Date('2024-01-15T10:23:00Z');
+      const result = roundToNearestMinutes(date, 5.5);
+      expect(result.getTime()).toBe(date.getTime());
+    });
+
+    it('should round up correctly', () => {
+      const date = new Date('2024-01-15T10:23:00Z');
+      const result = roundToNearestMinutes(date, 5);
+      // Should round to 25 (closer to 25 than 20)
+      expect(result.getMinutes()).toBe(25);
+    });
+  });
+
+  describe('getTimeZoneDifference', () => {
+    it('should calculate timezone difference in hours', () => {
+      const result = getTimeZoneDifference('America/New_York', 'America/Los_Angeles');
+      // EST is 3 hours ahead of PST
+      expect(result).toBe(-3);
+    });
+
+    it('should handle UTC timezone', () => {
+      const result = getTimeZoneDifference('UTC', 'America/New_York');
+      // UTC to EST is -5 hours (or -4 during DST)
+      expect([-5, -4]).toContain(result);
+    });
+
+    it('should return 0 for same timezone', () => {
+      const result = getTimeZoneDifference('America/New_York', 'America/New_York');
+      expect(result).toBe(0);
+    });
+
+    it('should handle invalid timezones gracefully', () => {
+      const result = getTimeZoneDifference('', 'America/New_York');
+      expect(result).toBe(0);
+    });
+
+    it('should handle reversed timezones', () => {
+      const forward = getTimeZoneDifference('America/New_York', 'America/Los_Angeles');
+      const backward = getTimeZoneDifference('America/Los_Angeles', 'America/New_York');
+      
+      expect(forward).toBe(-backward);
+    });
+
+    it('should account for DST in calculations', () => {
+      // Test with a summer date (DST active)
+      const summerDiff = getTimeZoneDifference('UTC', 'America/New_York');
+      // Should be -4 (EDT) or -5 (EST) depending on current date
+      expect([-4, -5]).toContain(summerDiff);
+    });
+  });
+
+  describe('Edge cases and error handling', () => {
+    it('should handle null and undefined gracefully', () => {
+      // @ts-expect-error - Testing error case
+      expect(formatInTimeZone(null, 'America/New_York', 'MMM dd, yyyy')).toBe('Invalid date');
+      // @ts-expect-error - Testing error case
+      expect(formatInTimeZone(undefined, 'America/New_York', 'MMM dd, yyyy')).toBe('Invalid date');
+    });
+
+    it('should handle various timezone formats', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const timezones = [
+        'America/New_York',
+        'Europe/London',
+        'Asia/Tokyo',
+        'Australia/Sydney',
+        'UTC'
+      ];
+      
+      timezones.forEach(tz => {
+        const result = formatInTimeZone(date, tz, 'MMM dd, yyyy');
+        expect(result).not.toBe('Invalid date');
+      });
+    });
+
+    it('should handle extreme dates', () => {
+      const farFuture = new Date('2099-12-31T23:59:59Z');
+      // Use a date that won't have timezone boundary issues
+      const farPast = new Date('1900-01-01T12:00:00Z');
+      
+      expect(formatInTimeZone(farFuture, 'America/New_York', 'yyyy')).toContain('2099');
+      // The year might be 1899 or 1900 depending on timezone conversion, so just check it's valid
+      const pastResult = formatInTimeZone(farPast, 'America/New_York', 'yyyy');
+      expect(pastResult).not.toBe('Invalid date');
+      expect(pastResult.length).toBeGreaterThan(0);
+    });
+  });
+});

package/src/utils/file-reference/__tests__/file-reference.test.ts

@@ -50,6 +50,7 @@ const mockFileUploadOptions = {
   organisation_id: 'test-org-123',
   app_id: 'test-app-123',
   category: FileCategory.GENERAL_DOCUMENTS,
+  pageContext: 'configuration',
   is_public: false
 };
 
@@ -116,6 +117,7 @@ describe('[service] FileReferenceServiceImpl', () => {
           p_record_id: mockFileUploadOptions.record_id,
           p_organisation_id: mockFileUploadOptions.organisation_id,
           p_app_id: mockFileUploadOptions.app_id,
+          p_page_context: mockFileUploadOptions.pageContext,
           p_file_metadata: expect.objectContaining({
             fileName: testFile.name,
             fileType: testFile.type,

package/src/utils/file-reference/index.ts

@@ -88,6 +88,7 @@ export class FileReferenceServiceImpl implements FileReferenceService {
           p_file_path: filePath, // Storage path from step 1
           p_organisation_id: options.organisation_id,
           p_app_id: options.app_id,
+          p_page_context: options.pageContext,
           p_file_metadata: {
             fileName: file.name,
             fileType: file.type,

package/src/utils/formatting/formatDateTimeTimezone.test.ts

@@ -0,0 +1,167 @@
+/**
+ * @file Timezone-Aware Date Formatting Tests
+ * @package @jmruthers/pace-core
+ * @module Utils/Formatting/__tests__
+ * @since 0.1.0
+ *
+ * Comprehensive tests for timezone-aware date formatting functions.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  formatDateTimeForDisplay,
+  formatDateOnlyForDisplay,
+  formatDateTimeForTable,
+  formatDateTimeForMap,
+  type DateTimeFormatOptions
+} from './formatting';
+
+describe('Timezone-Aware Date Formatting', () => {
+  describe('formatDateTimeForDisplay', () => {
+    it('formats UTC date with timezone abbreviation', () => {
+      const result = formatDateTimeForDisplay('2024-01-15T10:00:00Z', 'America/New_York');
+      expect(result).toMatch(/Jan 15, 2024/);
+      expect(result).toMatch(/\(/); // Should include timezone abbreviation in parentheses
+    });
+
+    it('formats Date object with timezone', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = formatDateTimeForDisplay(date, 'America/New_York');
+      expect(result).toMatch(/Jan 15, 2024/);
+    });
+
+    it('excludes timezone when includeTimezone is false', () => {
+      const options: DateTimeFormatOptions = { includeTimezone: false };
+      const result = formatDateTimeForDisplay('2024-01-15T10:00:00Z', 'America/New_York', options);
+      expect(result).toMatch(/Jan 15, 2024/);
+      expect(result).not.toMatch(/\(/); // Should not include parentheses
+    });
+
+    it('uses custom format string', () => {
+      const options: DateTimeFormatOptions = { format: 'yyyy-MM-dd HH:mm' };
+      const result = formatDateTimeForDisplay('2024-01-15T10:00:00Z', 'America/New_York', options);
+      expect(result).toMatch(/2024-01-15/);
+    });
+
+    it('returns empty string for undefined date', () => {
+      const result = formatDateTimeForDisplay(undefined, 'America/New_York');
+      expect(result).toBe('');
+    });
+
+    it('returns empty string for undefined timezone', () => {
+      const result = formatDateTimeForDisplay('2024-01-15T10:00:00Z', undefined);
+      expect(result).toBe('');
+    });
+
+    it('returns empty string for invalid date', () => {
+      const result = formatDateTimeForDisplay('invalid-date', 'America/New_York');
+      expect(result).toBe('');
+    });
+
+    it('handles different timezones correctly', () => {
+      const date = '2024-01-15T10:00:00Z';
+      const ny = formatDateTimeForDisplay(date, 'America/New_York');
+      const la = formatDateTimeForDisplay(date, 'America/Los_Angeles');
+      expect(ny).not.toBe(la);
+    });
+  });
+
+  describe('formatDateOnlyForDisplay', () => {
+    it('formats date only without time', () => {
+      const result = formatDateOnlyForDisplay('2024-01-15T10:00:00Z');
+      expect(result).toMatch(/January/);
+      expect(result).toMatch(/2024/);
+      expect(result).toMatch(/15/);
+    });
+
+    it('formats Date object', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = formatDateOnlyForDisplay(date);
+      expect(result).toMatch(/January/);
+    });
+
+    it('returns empty string for undefined', () => {
+      const result = formatDateOnlyForDisplay(undefined);
+      expect(result).toBe('');
+    });
+
+    it('returns empty string for invalid date', () => {
+      const result = formatDateOnlyForDisplay('invalid-date');
+      expect(result).toBe('');
+    });
+
+    it('formats different dates correctly', () => {
+      const dates = [
+        '2024-01-15T10:00:00Z',
+        '2024-06-15T12:00:00Z',
+        '2024-12-31T23:59:59Z'
+      ];
+
+      dates.forEach(date => {
+        const result = formatDateOnlyForDisplay(date);
+        expect(result).toBeTruthy();
+        expect(result.length).toBeGreaterThan(0);
+      });
+    });
+  });
+
+  describe('formatDateTimeForTable', () => {
+    it('formats date for table display with timezone', () => {
+      const result = formatDateTimeForTable('2024-01-15T10:00:00Z', 'America/New_York');
+      expect(result).toMatch(/Jan 15, 2024/);
+      expect(result).toMatch(/\(/); // Should include timezone
+    });
+
+    it('returns empty string for undefined date', () => {
+      const result = formatDateTimeForTable(undefined, 'America/New_York');
+      expect(result).toBe('');
+    });
+
+    it('returns empty string for undefined timezone', () => {
+      const result = formatDateTimeForTable('2024-01-15T10:00:00Z', undefined);
+      expect(result).toBe('');
+    });
+
+    it('formats Date object', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = formatDateTimeForTable(date, 'America/New_York');
+      expect(result).toMatch(/Jan 15, 2024/);
+    });
+  });
+
+  describe('formatDateTimeForMap', () => {
+    it('formats date for map display', () => {
+      const result = formatDateTimeForMap('2024-01-15T10:00:00Z', 'America/New_York');
+      expect(result).toMatch(/Jan 15/);
+      expect(result).toMatch(/\d{2}:\d{2}/); // Time format
+    });
+
+    it('includes timezone abbreviation', () => {
+      const result = formatDateTimeForMap('2024-01-15T10:00:00Z', 'America/New_York');
+      expect(result.length).toBeGreaterThan(0);
+      // Should include timezone info (not in parentheses for map format)
+    });
+
+    it('returns empty string for undefined date', () => {
+      const result = formatDateTimeForMap(undefined, 'America/New_York');
+      expect(result).toBe('');
+    });
+
+    it('returns empty string for undefined timezone', () => {
+      const result = formatDateTimeForMap('2024-01-15T10:00:00Z', undefined);
+      expect(result).toBe('');
+    });
+
+    it('formats Date object', () => {
+      const date = new Date('2024-01-15T10:00:00Z');
+      const result = formatDateTimeForMap(date, 'America/New_York');
+      expect(result).toMatch(/Jan 15/);
+    });
+
+    it('returns empty string for invalid date', () => {
+      const result = formatDateTimeForMap('invalid-date', 'America/New_York');
+      expect(result).toBe('');
+    });
+  });
+});
+