@jmruthers/pace-core 0.5.135 → 0.5.137

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

@@ -0,0 +1,237 @@
+/**
+ * @file formatDate Utility Tests
+ * @description Comprehensive tests for the formatDate utility function
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { formatDate } from './formatting';
+
+describe('formatDate Utility', () => {
+  let originalLocale: string;
+  let originalTimezone: string;
+
+  beforeEach(() => {
+    // Store original values
+    originalLocale = Intl.DateTimeFormat().resolvedOptions().locale;
+    originalTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  });
+
+    describe('Date Object Input', () => {
+    it('formats a Date object correctly', () => {
+      const date = new Date('2024-01-15T10:30:00.000Z');
+      const result = formatDate(date);
+      
+      expect(result).toMatch(/^\d{1,2} [A-Za-z]{3} \d{4}$/);
+    });
+
+    it('formats different Date objects', () => {
+      const dates = [
+        new Date('2023-12-25T00:00:00.000Z'),
+        new Date('2024-06-15T12:00:00.000Z'),
+        new Date('2024-12-31T23:59:59.999Z')
+      ];
+      
+      dates.forEach(date => {
+        const result = formatDate(date);
+        expect(result).toMatch(/^\d{1,2} [A-Za-z]{3} \d{4}$/);
+      });
+    });
+  });
+
+  describe('String Input', () => {
+    it('formats ISO date strings correctly', () => {
+      const result = formatDate('2024-01-15T10:30:00.000Z');
+      expect(result).toMatch(/^\d{1,2} [A-Za-z]{3} \d{4}$/);
+    });
+
+    it('formats date-only strings correctly', () => {
+      const result = formatDate('2024-01-15');
+      expect(result).toMatch(/^\d{1,2} [A-Za-z]{3} \d{4}$/);
+    });
+
+    it('formats various date string formats', () => {
+      const dateStrings = [
+        '2024-01-15',
+        '2024-01-15T10:30:00Z',
+        '2024-01-15T10:30:00.000Z',
+        '2024-01-15T10:30:00+00:00'
+      ];
+      
+      dateStrings.forEach(dateString => {
+        const result = formatDate(dateString);
+        expect(result).toMatch(/^\d{1,2} [A-Za-z]{3} \d{4}$/);
+      });
+    });
+  });
+
+  describe('Number Input', () => {
+    it('formats timestamp numbers correctly', () => {
+      const timestamp = new Date('2024-01-15T10:30:00.000Z').getTime();
+      const result = formatDate(timestamp);
+      expect(result).toMatch(/^\d{1,2} [A-Za-z]{3} \d{4}$/);
+    });
+
+    it('formats Unix timestamps correctly', () => {
+      const unixTimestamp = Math.floor(new Date('2024-01-15T10:30:00.000Z').getTime() / 1000);
+      const result = formatDate(unixTimestamp * 1000); // Convert back to milliseconds
+      expect(result).toMatch(/^\d{1,2} [A-Za-z]{3} \d{4}$/);
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('handles invalid date strings gracefully', () => {
+      const invalidDates = [
+        'invalid-date',
+        'not-a-date',
+        '2024-13-45', // Invalid month and day
+        '2024-02-30'  // Invalid day for February
+      ];
+      
+      invalidDates.forEach(invalidDate => {
+        const result = formatDate(invalidDate);
+        // Should return a string even for invalid dates (may be "Invalid Date")
+        expect(typeof result).toBe('string');
+        expect(result.length).toBeGreaterThan(0);
+      });
+    });
+
+    it('handles empty string input', () => {
+      const result = formatDate('');
+      expect(typeof result).toBe('string');
+    });
+
+    it('handles null and undefined input', () => {
+      // @ts-expect-error - Testing runtime behavior with invalid types
+      expect(() => formatDate(null)).toThrow();
+      // @ts-expect-error - Testing runtime behavior with invalid types
+      expect(() => formatDate(undefined)).toThrow();
+    });
+
+    it('handles very large numbers', () => {
+      const largeNumber = Number.MAX_SAFE_INTEGER;
+      const result = formatDate(largeNumber);
+      expect(typeof result).toBe('string');
+    });
+
+    it('handles negative numbers', () => {
+      const negativeNumber = -1000000;
+      const result = formatDate(negativeNumber);
+      expect(typeof result).toBe('string');
+    });
+
+    it('handles zero', () => {
+      const result = formatDate(0);
+      expect(typeof result).toBe('string');
+    });
+  });
+
+  describe('Format Consistency', () => {
+    it('returns consistent format for same date', () => {
+      const date = new Date('2024-01-15T10:30:00.000Z');
+      const result1 = formatDate(date);
+      const result2 = formatDate(date);
+      
+      expect(result1).toBe(result2);
+    });
+
+    it('returns consistent format across different input types for same date', () => {
+      const date = new Date('2024-01-15T10:30:00.000Z');
+      const dateString = '2024-01-15T10:30:00.000Z';
+      const timestamp = date.getTime();
+      
+      const result1 = formatDate(date);
+      const result2 = formatDate(dateString);
+      const result3 = formatDate(timestamp);
+      
+      expect(result1).toBe(result2);
+      expect(result2).toBe(result3);
+    });
+  });
+
+  describe('Locale Handling', () => {
+    it('uses default locale when no locale is specified', () => {
+      const date = new Date('2024-01-15T10:30:00.000Z');
+      const result = formatDate(date);
+      
+      // Should use the default locale format
+      expect(result).toMatch(/^\d{1,2} [A-Za-z]{3} \d{4}$/);
+    });
+
+    it('handles different locales correctly', () => {
+      const date = new Date('2024-01-15T10:30:00.000Z');
+      
+      const result = formatDate(date);
+      expect(result).toMatch(/^\d{1,2} [A-Za-z]{3} \d{4}$/);
+    });
+  });
+
+  describe('Time Zone Handling', () => {
+    it('handles different time zones correctly', () => {
+      const date = new Date('2024-01-15T10:30:00.000Z');
+      const result = formatDate(date);
+      
+      // Should format consistently regardless of timezone
+      expect(result).toMatch(/^\d{1,2} [A-Za-z]{3} \d{4}$/);
+    });
+  });
+
+  describe('Performance', () => {
+    it('handles large number of calls efficiently', () => {
+      const date = new Date('2024-01-15T10:30:00.000Z');
+      const startTime = performance.now();
+      
+      // Call formatDate many times
+      for (let i = 0; i < 1000; i++) {
+        formatDate(date);
+      }
+      
+      const endTime = performance.now();
+      const duration = endTime - startTime;
+      
+      // Should complete in reasonable time (less than 200ms for 1000 calls)
+      expect(duration).toBeLessThan(200);
+    });
+  });
+
+  describe('Type Safety', () => {
+    it('accepts valid Date types', () => {
+      const date = new Date();
+      expect(() => formatDate(date)).not.toThrow();
+    });
+
+    it('accepts valid string types', () => {
+      const dateString = '2024-01-15';
+      expect(() => formatDate(dateString)).not.toThrow();
+    });
+
+    it('accepts valid number types', () => {
+      const timestamp = Date.now();
+      expect(() => formatDate(timestamp)).not.toThrow();
+    });
+  });
+
+  describe('Return Value', () => {
+    it('returns a string', () => {
+      const date = new Date('2024-01-15T10:30:00.000Z');
+      const result = formatDate(date);
+      
+      expect(typeof result).toBe('string');
+    });
+
+    it('returns non-empty string for valid dates', () => {
+      const date = new Date('2024-01-15T10:30:00.000Z');
+      const result = formatDate(date);
+      
+      expect(result).toBeTruthy();
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    it('returns expected format pattern', () => {
+      const date = new Date('2024-01-15T10:30:00.000Z');
+      const result = formatDate(date);
+      
+      // Should match pattern: "MMM DD, YYYY"
+      expect(result).toMatch(/^\d{1,2} [A-Za-z]{3} \d{4}$/);
+    });
+  });
+});

package/src/utils/formatting/formatting.ts

@@ -0,0 +1,133 @@
+/**
+ * Utility functions for formatting data in the application
+ */
+
+/**
+ * Format a date as a readable string in "dd mmm yyyy" format (e.g., "15 Jun 2024")
+ */
+export function formatDate(date: Date | string | number): string {
+  const dateObj = typeof date === 'string' || typeof date === 'number' 
+    ? new Date(date) 
+    : date;
+  
+  // Use 'en-GB' locale to ensure "dd mmm yyyy" format (e.g., "15 Jun 2024")
+  return dateObj.toLocaleDateString('en-GB', {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric'
+  });
+}
+
+/**
+ * Format a number as a currency
+ */
+export function formatCurrency(value: number, currencyCode = 'USD', locale = 'en-US'): string {
+  return new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency: currencyCode,
+  }).format(value);
+}
+
+/**
+ * Format a number with custom options
+ */
+export function formatNumber(
+  value: number,
+  options: Intl.NumberFormatOptions = {},
+  locale = 'en-US'
+): string {
+  return new Intl.NumberFormat(locale, options).format(value);
+}
+
+/**
+ * Format a number as a percentage.
+ * 
+ * The third parameter can be either:
+ * - A number for fixed decimal places (backward compatible): `formatPercent(0.81, 'en-US', 2)`
+ * - An options object with:
+ *   - `decimals`: Fixed number of decimal places (default: 1)
+ *   - `preserveDecimals`: Auto-detect and preserve decimal places from the input value
+ *   - `maxDecimals`: Maximum decimal places when preserving (default: 10)
+ * 
+ * @param value - The percentage value as a decimal (e.g., 0.81 for 0.81%)
+ * @param locale - The locale string (default: 'en-US')
+ * @param decimalsOrOptions - Either a number for fixed decimals, or an options object with:
+ *   - `decimals` - Fixed number of decimal places (default: 1)
+ *   - `preserveDecimals` - Auto-detect and preserve decimal places from the input value
+ *   - `maxDecimals` - Maximum decimal places when preserving (default: 10)
+ * @returns Formatted percentage string (e.g., "0.81%", "81%")
+ * 
+ * @example
+ * ```ts
+ * // Fixed decimals (default behavior)
+ * formatPercent(0.5) // '0.5%'
+ * formatPercent(0.81, 'en-US', 1) // '0.8%' (loses precision)
+ * 
+ * // Preserve decimal places dynamically
+ * formatPercent(0.81, 'en-US', { preserveDecimals: true }) // '0.81%'
+ * formatPercent(0.8123, 'en-US', { preserveDecimals: true, maxDecimals: 2 }) // '0.81%'
+ * ```
+ */
+export function formatPercent(
+  value: number,
+  locale: string = 'en-US',
+  decimalsOrOptions?: number | {
+    decimals?: number;
+    preserveDecimals?: boolean;
+    maxDecimals?: number;
+  }
+): string {
+  let decimals: number;
+
+  // Backward compatibility: if decimalsOrOptions is a number, use it directly
+  if (typeof decimalsOrOptions === 'number') {
+    decimals = decimalsOrOptions;
+  } else if (decimalsOrOptions && typeof decimalsOrOptions === 'object') {
+    // New options object: check if we should preserve decimals
+    if (decimalsOrOptions.preserveDecimals) {
+      const valueStr = value.toString();
+      const decimalIndex = valueStr.indexOf('.');
+      
+      if (decimalIndex !== -1) {
+        const detectedDecimals = valueStr.length - decimalIndex - 1;
+        const maxDecimals = decimalsOrOptions.maxDecimals ?? 10;
+        decimals = Math.min(detectedDecimals, maxDecimals);
+      } else {
+        decimals = 0;
+      }
+    } else {
+      decimals = decimalsOrOptions.decimals ?? 1;
+    }
+  } else {
+    decimals = 1;
+  }
+
+  return new Intl.NumberFormat(locale, {
+    style: 'percent',
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  }).format(value / 100);
+}
+
+/**
+ * Format a large number with abbreviations (K, M, B)
+ */
+export function formatCompactNumber(value: number, locale = 'en-US'): string {
+  return new Intl.NumberFormat(locale, {
+    notation: 'compact',
+    compactDisplay: 'short'
+  }).format(value);
+}
+
+/**
+ * Format a file size in bytes to a human-readable string
+ */
+export function formatFileSize(bytes: number): string {
+  if (bytes === 0) return '0 Bytes';
+  
+  const k = 1024;
+  const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}

package/src/utils/index.ts

@@ -6,39 +6,57 @@
  */
 
 // Core utilities
-export { cn } from './cn';
-export { DebugLogger } from './debugLogger';
+export { cn } from './core/cn';
+export { DebugLogger } from './core/debugLogger';
+export { Logger, logger, createLogger, LogLevel } from './core/logger';
+export type { LoggerConfig } from './core/logger';
 
 // App configuration utilities
-export * from './appNameResolver';
-export * from './appConfig';
+export * from './app/appNameResolver';
+export { setAppConfig, getAppConfig, getCurrentAppId } from './app/appConfig';
+export * from './app/appIdResolver';
 
 // Validation and sanitization
 export * from './validation';
-export * from './validationUtils';
-export * from './sanitization';
+// Explicitly re-export commonly used validation utilities to ensure they're available
+// Import from source modules to avoid re-export issues
+export { validateUserInput, usernameSchema } from './validation/validationUtils';
+export { sanitizeUserInput, sanitizeFormData } from './validation/sanitization';
+export { emailSchema, nameSchema, phoneSchema, urlSchema } from './validation/common';
+export { passwordSchema } from './validation/passwordSchema';
+export { pickSchema, combineSchemas } from './validation/schema';
 
 // Security utilities
 export { 
   getSecurityHeaders, 
   validateSecurityHeaders
-} from './security';
+} from './security/security';
+export type { SecurityEvent } from './security/security';
 
-// Note: Accessibility testing utilities are only available in test environments
-// They are not exported in production builds to avoid including test dependencies
+// Security monitoring utilities
+export { 
+  securityMonitor 
+} from './security/securityMonitor';
+export type { SecureDataAccess } from './security/secureDataAccess';
 
 // Performance utilities
 export { useComponentPerformance } from '../hooks/useComponentPerformance';
 export { PERFORMANCE_THRESHOLDS } from '../constants/performance';
-export { createPerformanceBenchmark, measureRenderPerformance } from './performanceBenchmark';
-export type { PerformanceMetrics } from './performanceBenchmark';
+export { createPerformanceBenchmark, measureRenderPerformance } from './performance/performanceBenchmark';
+export type { PerformanceMetrics } from './performance/performanceBenchmark';
 
 // Bundle analysis utilities
 export { 
   bundleAnalyzer, 
   validateImportPattern, 
   trackDynamicImport 
-} from './bundleAnalysis';
+} from './performance/bundleAnalysis';
+
+// Performance budget utilities
+export { 
+  performanceBudgetMonitor, 
+  PERFORMANCE_BUDGETS 
+} from './performance/performanceBudgets';
 
 // Dynamic utility loaders
 export { 
@@ -53,25 +71,10 @@ export {
   lazyChartUtils,
   lazyFormUtils,
   lazyCSVUtils
-} from './dynamicUtils';
-
-// Performance budget utilities
-export { 
-  performanceBudgetMonitor, 
-  PERFORMANCE_BUDGETS 
-} from './performanceBudgets';
+} from './dynamic/dynamicUtils';
 
 // Lazy loading utilities
-export { createLazyComponent, LazyDataTable } from './lazyLoad';
-
-// App configuration utilities
-export { 
-  setAppConfig, 
-  getAppConfig, 
-  getCurrentAppName, 
-  getCurrentAppId 
-} from './appConfig';
-export type { AppConfig } from './appConfig';
+export { createLazyComponent, LazyDataTable } from './dynamic/lazyLoad';
 
 // Permission utilities
 export { 
@@ -79,30 +82,18 @@ export {
   hasPermission, 
   hasAnyPermission, 
   hasAllPermissions 
-} from './permissionUtils';
+} from './permissions/permissionUtils';
 
 // Permission types
 export { 
   PermissionType, 
   parsePermission 
-} from './permissionTypes';
-
-// Schema utilities
-export { 
-  pickSchema, 
-  combineSchemas 
-} from './schemaUtils';
-
-// Security monitoring utilities
-export { 
-  securityMonitor 
-} from './securityMonitor';
-export type { SecureDataAccess } from './secureDataAccess';
+} from './permissions/permissionTypes';
 
 // Session tracking utilities
 export { 
   useSessionTracking 
-} from './sessionTracking';
+} from './context/sessionTracking';
 
 // Audit utilities
 export { 
@@ -112,14 +103,13 @@ export {
   logPermissionEvent,
   logSecurityEvent,
   logAuditEvent
-} from './audit';
+} from './audit/audit';
 
 // Device fingerprinting utilities
 export { 
   generateDeviceFingerprint, 
   validateDeviceFingerprint 
-} from './deviceFingerprint';
-
+} from './device/deviceFingerprint';
 
 // Formatting utilities
 export { 
@@ -129,7 +119,7 @@ export {
   formatPercent,
   formatCompactNumber,
   formatFileSize
-} from './formatting';
+} from './formatting/formatting';
 
 // Organisation context utilities
 export { 
@@ -137,9 +127,4 @@ export {
   clearOrganisationContext, 
   getOrganisationContext, 
   isOrganisationContextAvailable 
-} from './organisationContext';
-
-// Re-export types for convenience
-export type { 
-  SecurityEvent
-} from './security';
+} from './context/organisationContext';

package/src/utils/performance/bundleAnalysis.ts

@@ -0,0 +1,129 @@
+
+interface BundleStats {
+  totalSize: number;
+  gzippedSize: number;
+  chunks: ChunkInfo[];
+  treeshakingEffectiveness: number;
+}
+
+interface ChunkInfo {
+  name: string;
+  size: number;
+  modules: string[];
+  dynamicallyImported: boolean;
+}
+
+class BundleAnalyzer {
+  private enabled = import.meta.env.MODE === 'development';
+
+  analyzeBundle(): BundleStats | null {
+    if (!this.enabled) return null;
+
+    // In a real implementation, this would integrate with webpack-bundle-analyzer
+    // or similar tools. For now, we'll simulate analysis
+    
+    // TODO: Replace with proper logging service integration
+    // For now, we'll log to console for testing purposes
+    console.log('Bundle analysis would run here in development');
+    console.log('To enable real bundle analysis:');
+    console.log('1. Install webpack-bundle-analyzer');
+    console.log('2. Add bundle analysis to build scripts');
+    console.log('3. Integrate with performance budgets');
+
+    return {
+      totalSize: 0,
+      gzippedSize: 0,
+      chunks: [],
+      treeshakingEffectiveness: 0
+    };
+  }
+
+  checkTreeshaking(): void {
+    if (!this.enabled) return;
+
+    const potentialIssues = [
+      'Check for unused exports in index files',
+      'Verify side-effect free modules in package.json',
+      'Ensure proper ES module syntax',
+      'Check for circular dependencies'
+    ];
+
+    // TODO: Replace with proper logging service integration
+    // For now, we'll log to console for testing purposes
+    console.group('Tree-shaking Analysis');
+    potentialIssues.forEach(issue => console.log('- ' + issue));
+    console.groupEnd();
+  }
+
+  validateExports(): void {
+    if (!this.enabled) return;
+
+    // TODO: Replace with proper logging service integration
+    // For now, we'll log to console for testing purposes
+    console.group('Export Validation');
+    console.log('Checking for optimal export patterns...');
+    console.log('- Prefer named exports over default exports');
+    console.log('- Avoid barrel exports for large modules');
+    console.log('- Use dynamic imports for large dependencies');
+    console.groupEnd();
+  }
+
+  generateReport(): string {
+    const report = `
+# Bundle Analysis Report
+
+## Recommendations for @jmruthers/pace-core
+
+### 1. Code Splitting Opportunities
+- ✅ DataTable virtualization is lazy-loaded
+- ⚠️  Consider splitting auth providers by use case
+- ⚠️  Lazy load heavy UI components (charts, complex forms)
+
+### 2. Tree-shaking Optimization
+- ✅ Using ES modules throughout
+- ✅ Proper sideEffects configuration
+- ⚠️  Check for unused utility functions
+
+### 3. Bundle Size Targets
+- Core components: < 50KB gzipped
+- Auth module: < 30KB gzipped  
+- Utilities: < 20KB gzipped
+- Total package: < 150KB gzipped
+
+### 4. Performance Monitoring
+- Monitor component render times
+- Track bundle size changes
+- Validate tree-shaking effectiveness
+    `;
+
+    return report.trim();
+  }
+}
+
+export const bundleAnalyzer = new BundleAnalyzer();
+
+// Helper to check if imports are optimized
+export function validateImportPattern(moduleId: string, importedItems: string[]): void {
+  if (import.meta.env.MODE !== 'development') return;
+
+  const largeModules = ['lodash', 'moment', 'rxjs'];
+  const isLargeModule = largeModules.some(mod => moduleId.includes(mod));
+  
+  if (isLargeModule && importedItems.length > 5) {
+    // TODO: Replace with proper logging service integration
+    // For now, we'll log to console for testing purposes
+    console.warn(
+      'Large import detected: importing ' + importedItems.length + ' items from ' + moduleId + '. ' +
+      'Consider splitting imports or using more specific imports.'
+    );
+  }
+}
+
+// Monitor dynamic imports
+export function trackDynamicImport(moduleName: string): void {
+  if (import.meta.env.MODE !== 'development') return;
+  
+  // TODO: Replace with proper logging service integration
+  // For now, we'll log to console for testing purposes
+  console.log('Dynamic import: ' + moduleName + ' - Good for code splitting!');
+}