@jmruthers/pace-core 0.2.4

package/src/utils/debugLogger.ts

@@ -0,0 +1,46 @@
+/**
+ * @file Debug Logger Utility
+ * @package @jmruthers/pace-core
+ * @module Utils/DebugLogger
+ * @since 0.4.76
+ */
+
+/**
+ * Debug logger that respects environment settings
+ * Only logs in development mode to prevent production console spam
+ */
+export class DebugLogger {
+  private static isDevelopment = process.env.NODE_ENV === 'development';
+
+  /**
+   * Log debug information only in development mode
+   */
+  static log(component: string, message: string, ...args: any[]): void {
+    if (this.isDevelopment) {
+      console.log(`[${component}] ${message}`, ...args);
+    }
+  }
+
+  /**
+   * Log error information (always logged)
+   */
+  static error(component: string, message: string, ...args: any[]): void {
+    console.error(`[${component}] ${message}`, ...args);
+  }
+
+  /**
+   * Log warning information (always logged)
+   */
+  static warn(component: string, message: string, ...args: any[]): void {
+    console.warn(`[${component}] ${message}`, ...args);
+  }
+
+  /**
+   * Log info information only in development mode
+   */
+  static info(component: string, message: string, ...args: any[]): void {
+    if (this.isDevelopment) {
+      console.info(`[${component}] ${message}`, ...args);
+    }
+  }
+}

package/src/utils/deviceFingerprint.ts

@@ -0,0 +1,215 @@
+/**
+ * @file Secure Device Fingerprinting
+ * @description Enhanced device fingerprinting with encryption and security measures
+ */
+
+import { secureStorage } from './secureStorage';
+
+export interface DeviceFingerprint {
+  hash: string;
+  timestamp: number;
+  components: {
+    userAgent: string;
+    language: string;
+    platform: string;
+    screen: string;
+    timezone: string;
+    canvas?: string;
+    webgl?: string;
+  };
+  entropy: number;
+}
+
+/**
+ * Generate a secure device fingerprint (synchronous)
+ */
+export function generateDeviceFingerprint(): DeviceFingerprint {
+  try {
+    const components = {
+      userAgent: getHashedUserAgent(),
+      language: navigator.language || 'unknown',
+      platform: navigator.platform || 'unknown',
+      screen: `${screen.width}x${screen.height}x${screen.colorDepth}`,
+      timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || 'unknown',
+      canvas: getCanvasFingerprint(),
+      webgl: getWebGLFingerprint(),
+    };
+
+    // Calculate entropy (uniqueness score)
+    const entropy = calculateEntropy(components);
+    
+    // Create a hash from all components
+    const fingerprintData = JSON.stringify(components);
+    const hash = hashStringSync(fingerprintData);
+
+    const fingerprint: DeviceFingerprint = {
+      hash,
+      timestamp: Date.now(),
+      components,
+      entropy,
+    };
+
+    // Store fingerprint asynchronously
+    secureStorage.setItem('device_fingerprint', JSON.stringify(fingerprint));
+    
+    return fingerprint;
+  } catch (error) {
+    return generateFallbackFingerprint();
+  }
+}
+
+/**
+ * Validate device fingerprint with security checks
+ */
+export function validateDeviceFingerprint(
+  storedFingerprint: DeviceFingerprint,
+  currentFingerprint: DeviceFingerprint
+): {
+  isValid: boolean;
+  confidence: number;
+  reasons: string[];
+} {
+  const reasons: string[] = [];
+  let matchingComponents = 0;
+  const totalComponents = Object.keys(storedFingerprint.components).length;
+
+  // Check each component
+  Object.entries(storedFingerprint.components).forEach(([key, value]) => {
+    if (currentFingerprint.components[key as keyof typeof currentFingerprint.components] === value) {
+      matchingComponents++;
+    } else {
+      reasons.push(`Component mismatch: ${key}`);
+    }
+  });
+
+  // Calculate confidence score
+  const confidence = (matchingComponents / totalComponents) * 100;
+
+  // Security thresholds
+  const isValid = confidence >= 80; // Require 80% match
+  
+  // Additional security checks
+  const timeDiff = currentFingerprint.timestamp - storedFingerprint.timestamp;
+  const maxAge = 30 * 24 * 60 * 60 * 1000; // 30 days
+  
+  if (timeDiff > maxAge) {
+    reasons.push('Fingerprint too old');
+    return { isValid: false, confidence, reasons };
+  }
+
+  if (confidence < 60) {
+    reasons.push('Device signature changed significantly');
+  }
+
+  return { isValid, confidence, reasons };
+}
+
+/**
+ * Generate canvas fingerprint for enhanced uniqueness
+ */
+function getCanvasFingerprint(): string {
+  try {
+    const canvas = document.createElement('canvas');
+    const ctx = canvas.getContext('2d');
+    
+    if (!ctx) return 'canvas-unavailable';
+
+    // Draw complex pattern for fingerprinting
+    ctx.textBaseline = 'top';
+    ctx.font = '14px Arial';
+    ctx.fillStyle = '#f60';
+    ctx.fillRect(125, 1, 62, 20);
+    ctx.fillStyle = '#069';
+    ctx.fillText('Device fingerprint 🔒', 2, 15);
+    ctx.fillStyle = 'rgba(102, 204, 0, 0.2)';
+    ctx.fillText('Device fingerprint 🔒', 4, 17);
+
+    const dataURL = canvas.toDataURL();
+    return hashStringSync(dataURL);
+  } catch (error) {
+    return 'canvas-error';
+  }
+}
+
+/**
+ * Get WebGL fingerprint
+ */
+function getWebGLFingerprint(): string {
+  try {
+    const canvas = document.createElement('canvas');
+    const gl = canvas.getContext('webgl') || canvas.getContext('experimental-webgl') as WebGLRenderingContext | null;
+    
+    if (!gl) return 'webgl-unavailable';
+
+    const debugInfo = gl.getExtension('WEBGL_debug_renderer_info');
+    if (!debugInfo) return 'webgl-no-debug';
+
+    const vendor = gl.getParameter(debugInfo.UNMASKED_VENDOR_WEBGL);
+    const renderer = gl.getParameter(debugInfo.UNMASKED_RENDERER_WEBGL);
+    
+    return `${vendor}|${renderer}`;
+  } catch (error) {
+    return 'webgl-error';
+  }
+}
+
+/**
+ * Hash user agent to prevent direct exposure
+ */
+function getHashedUserAgent(): string {
+  const ua = navigator.userAgent;
+  return hashStringSync(ua).substring(0, 16); // Shorter hash for storage
+}
+
+/**
+ * Calculate entropy of fingerprint components
+ */
+function calculateEntropy(components: Record<string, string>): number {
+  const values = Object.values(components).join('');
+  const charCounts = new Map<string, number>();
+  
+  for (const char of values) {
+    charCounts.set(char, (charCounts.get(char) || 0) + 1);
+  }
+  
+  let entropy = 0;
+  for (const count of charCounts.values()) {
+    const probability = count / values.length;
+    entropy -= probability * Math.log2(probability);
+  }
+  
+  return entropy;
+}
+
+/**
+ * Synchronous hash function for device fingerprinting
+ */
+function hashStringSync(str: string): string {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash).toString(36);
+}
+
+/**
+ * Generate fallback fingerprint for error cases
+ */
+function generateFallbackFingerprint(): DeviceFingerprint {
+  const components = {
+    userAgent: 'fallback',
+    language: 'unknown',
+    platform: 'unknown',
+    screen: 'unknown',
+    timezone: 'unknown',
+  };
+
+  return {
+    hash: `fallback_${Date.now()}_${Math.random().toString(36)}`,
+    timestamp: Date.now(),
+    components,
+    entropy: 1, // Low entropy for fallback
+  };
+}

package/src/utils/dynamicUtils.ts

@@ -0,0 +1,105 @@
+
+/**
+ * Dynamic utility loader to reduce initial bundle size
+ * Heavy utilities are loaded on-demand
+ */
+
+// Type definitions for dynamic imports
+type DebounceFunction = <T extends (...args: unknown[]) => unknown>(
+  func: T,
+  wait?: number,
+  options?: { leading?: boolean; maxWait?: number; trailing?: boolean }
+) => T & { cancel(): void; flush(): void };
+
+type ThrottleFunction = <T extends (...args: unknown[]) => unknown>(
+  func: T,
+  wait?: number,
+  options?: { leading?: boolean; trailing?: boolean }
+) => T & { cancel(): void; flush(): void };
+
+// Dynamic lodash utilities
+export const loadLodash = async (): Promise<{
+  debounce: DebounceFunction;
+  throttle: ThrottleFunction;
+}> => {
+  const [debounceModule, throttleModule] = await Promise.all([
+    import('lodash.debounce' as any),
+    import('lodash.throttle' as any)
+  ]);
+  
+  return {
+    debounce: (debounceModule.default || debounceModule) as DebounceFunction,
+    throttle: (throttleModule.default || throttleModule) as ThrottleFunction
+  };
+};
+
+// Dynamic date utilities
+export const loadDateUtils = async (): Promise<typeof import('date-fns')> => {
+  const dateFns = await import('date-fns');
+  return dateFns;
+};
+
+// Dynamic chart utilities - using unknown type to avoid Recharts type issues
+export const loadChartUtils = async (): Promise<unknown> => {
+  const recharts = await import('recharts');
+  return recharts;
+};
+
+// Dynamic form utilities
+export const loadFormUtils = async (): Promise<{
+  useForm: unknown;
+  useController: unknown;
+  Controller: unknown;
+  FormProvider: unknown;
+  useFormContext: unknown;
+  useWatch: unknown;
+  useFormState: unknown;
+  useFieldArray: unknown;
+  zodResolver: unknown;
+}> => {
+  const [reactHookForm, zodResolvers] = await Promise.all([
+    import('react-hook-form'),
+    import('@hookform/resolvers/zod')
+  ]);
+  
+  return {
+    ...reactHookForm,
+    zodResolver: zodResolvers.zodResolver
+  };
+};
+
+// Dynamic CSV utilities
+export const loadCSVUtils = async (): Promise<unknown> => {
+  const papaparse = await import('papaparse');
+  return papaparse.default;
+};
+
+// Utility function to create lazy utility hooks
+export function createLazyUtility<T>(loader: () => Promise<T>) {
+  let cached: T | null = null;
+  let loading: Promise<T> | null = null;
+
+  return {
+    load: async (): Promise<T> => {
+      if (cached) return cached;
+      if (loading) return loading;
+
+      loading = loader().then(result => {
+        cached = result;
+        loading = null;
+        return result;
+      });
+
+      return loading;
+    },
+    getCached: (): T | null => cached,
+    isLoaded: (): boolean => cached !== null
+  };
+}
+
+// Pre-configured lazy utilities with explicit types
+export const lazyLodash: ReturnType<typeof createLazyUtility<Awaited<ReturnType<typeof loadLodash>>>> = createLazyUtility(loadLodash);
+export const lazyDateUtils: ReturnType<typeof createLazyUtility<Awaited<ReturnType<typeof loadDateUtils>>>> = createLazyUtility(loadDateUtils);
+export const lazyChartUtils: ReturnType<typeof createLazyUtility<unknown>> = createLazyUtility(loadChartUtils);
+export const lazyFormUtils: ReturnType<typeof createLazyUtility<Awaited<ReturnType<typeof loadFormUtils>>>> = createLazyUtility(loadFormUtils);
+export const lazyCSVUtils: ReturnType<typeof createLazyUtility<unknown>> = createLazyUtility(loadCSVUtils);

package/src/utils/formatting.ts

@@ -0,0 +1,77 @@
+/**
+ * Utility functions for formatting data in the application
+ */
+
+/**
+ * Format a date as a readable string
+ */
+export function formatDate(date: Date | string | number): string {
+  const dateObj = typeof date === 'string' || typeof date === 'number' 
+    ? new Date(date) 
+    : date;
+  
+  return dateObj.toLocaleDateString(undefined, {
+    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
+ */
+export function formatPercent(
+  value: number,
+  locale: string = 'en-US',
+  decimals: number = 1
+): string {
+  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

@@ -0,0 +1,145 @@
+/**
+ * @file Utility functions exports
+ * @package @jmruthers/pace-core
+ * @module Utils
+ * @since 0.1.0
+ */
+
+// Core utilities
+export { cn } from './cn';
+export { DebugLogger } from './debugLogger';
+
+// App configuration utilities
+export * from './appNameResolver';
+export * from './appConfig';
+
+// Validation and sanitization
+export * from './validation';
+export * from './validationUtils';
+export * from './sanitization';
+
+// Security utilities
+export { 
+  getSecurityHeaders, 
+  validateSecurityHeaders
+} from './security';
+
+// Note: Accessibility testing utilities are only available in test environments
+// They are not exported in production builds to avoid including test dependencies
+
+// Performance utilities
+export { useComponentPerformance } from '../hooks/useComponentPerformance';
+export { PERFORMANCE_THRESHOLDS } from '../constants/performance';
+export { createPerformanceBenchmark, measureRenderPerformance } from './performanceBenchmark';
+export type { PerformanceMetrics } from './performanceBenchmark';
+
+// Bundle analysis utilities
+export { 
+  bundleAnalyzer, 
+  validateImportPattern, 
+  trackDynamicImport 
+} from './bundleAnalysis';
+
+// Dynamic utility loaders
+export { 
+  loadLodash, 
+  loadDateUtils, 
+  loadChartUtils,
+  loadFormUtils,
+  loadCSVUtils,
+  createLazyUtility,
+  lazyLodash,
+  lazyDateUtils,
+  lazyChartUtils,
+  lazyFormUtils,
+  lazyCSVUtils
+} from './dynamicUtils';
+
+// Performance budget utilities
+export { 
+  performanceBudgetMonitor, 
+  PERFORMANCE_BUDGETS 
+} from './performanceBudgets';
+
+// Lazy loading utilities
+export { createLazyComponent, LazyDataTable } from './lazyLoad';
+
+// App configuration utilities
+export { 
+  setAppConfig, 
+  getAppConfig, 
+  getCurrentAppName, 
+  getCurrentAppId 
+} from './appConfig';
+export type { AppConfig } from './appConfig';
+
+// Permission utilities
+export { 
+  transformPermissionMapToBoolean, 
+  hasPermission, 
+  hasAnyPermission, 
+  hasAllPermissions 
+} from './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';
+
+// Session tracking utilities
+export { 
+  useSessionTracking 
+} from './sessionTracking';
+
+// Audit utilities
+export { 
+  auditLogger, 
+  auditLog,
+  logAuthEvent,
+  logPermissionEvent,
+  logSecurityEvent,
+  logAuditEvent
+} from './audit';
+
+// Device fingerprinting utilities
+export { 
+  generateDeviceFingerprint, 
+  validateDeviceFingerprint 
+} from './deviceFingerprint';
+
+
+// Formatting utilities
+export { 
+  formatDate, 
+  formatCurrency, 
+  formatNumber,
+  formatPercent,
+  formatCompactNumber,
+  formatFileSize
+} from './formatting';
+
+// Organisation context utilities
+export { 
+  setOrganisationContext, 
+  clearOrganisationContext, 
+  getOrganisationContext, 
+  isOrganisationContextAvailable 
+} from './organisationContext';
+
+// Re-export types for convenience
+export type { 
+  SecurityEvent
+} from './security';

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'
+);