@jmruthers/pace-core 0.5.136 → 0.5.137

package/src/utils/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.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

@@ -18,6 +18,13 @@ export * from './app/appIdResolver';
 
 // Validation and sanitization
 export * from './validation';
+// 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 { 

package/src/utils/lazyLoad.tsx

@@ -0,0 +1,44 @@
+import React, { Suspense, ComponentType, lazy } from 'react';
+import { LoadingSpinner } from '../components/LoadingSpinner/LoadingSpinner';
+
+interface LazyLoadOptions {
+  fallback?: React.ReactNode;
+  errorBoundary?: ComponentType<{ children: React.ReactNode }>;
+}
+
+/**
+ * Create a lazy-loaded component with error boundary and loading fallback
+ */
+export function createLazyComponent<T extends ComponentType<any>>(
+  importFn: () => Promise<{ default: T }>,
+  componentName: string,
+  options: LazyLoadOptions = {}
+): T {
+  const LazyComponent = lazy(importFn);
+  
+  const WrappedComponent = (props: any) => {
+    const content = (
+      <Suspense fallback={options.fallback || <LoadingSpinner />}>
+        <LazyComponent {...props} />
+      </Suspense>
+    );
+
+    if (options.errorBoundary) {
+      const ErrorBoundary = options.errorBoundary;
+      return <ErrorBoundary>{content}</ErrorBoundary>;
+    }
+
+    return content;
+  };
+  
+  WrappedComponent.displayName = `Lazy${componentName}`;
+  return WrappedComponent as T;
+}
+
+/**
+ * Lazy-loaded DataTable component
+ */
+export const LazyDataTable = createLazyComponent(
+  () => import('../components/DataTable').then(module => ({ default: module.DataTable })),
+  'DataTable'
+);

package/src/utils/logger.ts

@@ -0,0 +1,179 @@
+/**
+ * @file Production-Safe Logger Utility
+ * @package @jmruthers/pace-core
+ * @module Utils/Logger
+ * @since 0.4.76
+ */
+
+/**
+ * Logger levels for different types of messages
+ */
+export enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+}
+
+/**
+ * Logger configuration interface
+ */
+export interface LoggerConfig {
+  /** Minimum log level to output */
+  level: LogLevel;
+  /** Whether to include timestamps */
+  includeTimestamp: boolean;
+  /** Whether to include component names */
+  includeComponent: boolean;
+  /** Custom prefix for all log messages */
+  prefix?: string;
+}
+
+/**
+ * Production-safe logger that no-ops in production builds
+ * Only outputs logs in development mode to prevent production console spam
+ */
+export class Logger {
+  private static config: LoggerConfig = {
+    level: LogLevel.DEBUG,
+    includeTimestamp: false,
+    includeComponent: true,
+  };
+
+  /**
+   * Check if we're in development mode
+   */
+  private static get isDevelopment(): boolean {
+    return import.meta.env.MODE === 'development';
+  }
+
+  /**
+   * Configure the logger
+   */
+  static configure(config: Partial<LoggerConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  /**
+   * Format a log message with optional timestamp and component
+   */
+  private static formatMessage(
+    level: LogLevel,
+    component: string,
+    message: string
+  ): string {
+    const parts: string[] = [];
+
+    if (this.config.prefix) {
+      parts.push(`[${this.config.prefix}]`);
+    }
+
+    if (this.config.includeTimestamp) {
+      parts.push(`[${new Date().toISOString()}]`);
+    }
+
+    parts.push(`[${LogLevel[level]}]`);
+
+    if (this.config.includeComponent && component) {
+      parts.push(`[${component}]`);
+    }
+
+    parts.push(message);
+
+    return parts.join(' ');
+  }
+
+  /**
+   * Check if a log level should be output
+   */
+  private static shouldLog(level: LogLevel): boolean {
+    return this.isDevelopment && level >= this.config.level;
+  }
+
+  /**
+   * Log debug information (development only)
+   */
+  static debug(component: string, message: string, ...args: any[]): void {
+    if (this.shouldLog(LogLevel.DEBUG)) {
+      try {
+        console.debug(this.formatMessage(LogLevel.DEBUG, component, message), ...args);
+      } catch (e) {
+        // Gracefully handle console method errors
+      }
+    }
+  }
+
+  /**
+   * Log info information (development only)
+   */
+  static info(component: string, message: string, ...args: any[]): void {
+    if (this.shouldLog(LogLevel.INFO)) {
+      try {
+        console.info(this.formatMessage(LogLevel.INFO, component, message), ...args);
+      } catch (e) {
+        // Gracefully handle console method errors
+      }
+    }
+  }
+
+  /**
+   * Log warning information (development only)
+   */
+  static warn(component: string, message: string, ...args: any[]): void {
+    if (this.shouldLog(LogLevel.WARN)) {
+      try {
+        console.warn(this.formatMessage(LogLevel.WARN, component, message), ...args);
+      } catch (e) {
+        // Gracefully handle console method errors
+      }
+    }
+  }
+
+  /**
+   * Log error information (development only)
+   */
+  static error(component: string, message: string, ...args: any[]): void {
+    if (this.shouldLog(LogLevel.ERROR)) {
+      try {
+        console.error(this.formatMessage(LogLevel.ERROR, component, message), ...args);
+      } catch (e) {
+        // Gracefully handle console method errors
+      }
+    }
+  }
+
+  /**
+   * Create a scoped logger for a specific component
+   */
+  static createScopedLogger(component: string) {
+    return {
+      debug: (message: string, ...args: any[]) => this.debug(component, message, ...args),
+      info: (message: string, ...args: any[]) => this.info(component, message, ...args),
+      warn: (message: string, ...args: any[]) => this.warn(component, message, ...args),
+      error: (message: string, ...args: any[]) => this.error(component, message, ...args),
+    };
+  }
+}
+
+/**
+ * Default logger instance for convenience
+ */
+export const logger = {
+  debug: (component: string, message: string, ...args: any[]) => 
+    Logger.debug(component, message, ...args),
+  info: (component: string, message: string, ...args: any[]) => 
+    Logger.info(component, message, ...args),
+  warn: (component: string, message: string, ...args: any[]) => 
+    Logger.warn(component, message, ...args),
+  error: (component: string, message: string, ...args: any[]) => 
+    Logger.error(component, message, ...args),
+  createScopedLogger: (component: string) => Logger.createScopedLogger(component),
+  configure: (config: Partial<LoggerConfig>) => Logger.configure(config),
+};
+
+/**
+ * Convenience function to create a scoped logger
+ */
+export function createLogger(component: string) {
+  return Logger.createScopedLogger(component);
+}