@jmruthers/pace-core 0.2.4

package/dist/utils.d.ts

@@ -0,0 +1,639 @@
+export { A as AppConfig, S as SecureDataAccess, a as cn, g as getAppConfig, d as getCurrentAppId, b as getCurrentAppName, s as setAppConfig } from './appConfig-BVGyuvI7.js';
+import { z } from 'zod';
+export { u as useComponentPerformance } from './useComponentPerformance-DE9l5RkL.js';
+import * as date_fns from 'date-fns';
+import { D as DataTable } from './DataTable-BHlzyKZP.js';
+import React__default, { ComponentType } from 'react';
+import { SupabaseClient } from '@supabase/supabase-js';
+import './organisation-CO3Sh3_D.js';
+import 'clsx';
+import 'react/jsx-runtime';
+import './types-CInEi-ng.js';
+import '@tanstack/react-table';
+
+/**
+ * @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
+ */
+declare class DebugLogger {
+    private static isDevelopment;
+    /**
+     * Log debug information only in development mode
+     */
+    static log(component: string, message: string, ...args: any[]): void;
+    /**
+     * Log error information (always logged)
+     */
+    static error(component: string, message: string, ...args: any[]): void;
+    /**
+     * Log warning information (always logged)
+     */
+    static warn(component: string, message: string, ...args: any[]): void;
+    /**
+     * Log info information only in development mode
+     */
+    static info(component: string, message: string, ...args: any[]): void;
+}
+
+/**
+ * Utility to resolve the current app name from various sources
+ * Priority: package.json > environment variables > fallback
+ */
+/**
+ * Get the app name from package.json at build time
+ * This works by reading package.json during the build process
+ */
+declare function getAppNameFromPackageJson(): string | null;
+/**
+ * Get the app name from build-time injected variables
+ * This is the preferred method for browser environments
+ */
+declare function getAppNameFromBuildTime(): string | null;
+/**
+ * Get the app name from a global variable set by the consuming app
+ * This is the simplest approach for browser environments
+ */
+declare function getAppNameFromGlobal(): string | null;
+/**
+ * Get the app name from environment variables
+ * Fallback method for when package.json is not available
+ */
+declare function getAppNameFromEnvironment(): string | null;
+/**
+ * Set the app name globally for RBAC resolution
+ * Call this in your app's main entry point (e.g., main.tsx, index.tsx)
+ *
+ * @param appName - The app name from your package.json
+ *
+ * @example
+ * ```tsx
+ * // In your main.tsx or index.tsx
+ * import { setRBACAppName } from '@jmruthers/pace-core/utils';
+ *
+ * // Set the app name from package.json
+ * setRBACAppName('CAKE');
+ *
+ * // Rest of your app setup...
+ * ```
+ */
+declare function setRBACAppName(appName: string): void;
+/**
+ * Get the app name with fallback to a default
+ * Useful when you need a guaranteed app name
+ */
+declare function getCurrentAppNameWithFallback(fallback?: string): string;
+
+/**
+ * @file Internal utilities for validation module
+ * @internal This file contains implementation details that should not be used directly
+ */
+/**
+ * Utility functions for validating data in the application
+ */
+/**
+ * Check if a string is a valid email
+ */
+declare function isValidEmail(email: string): boolean;
+/**
+ * Check if a string is empty (either null, undefined, or just whitespace)
+ */
+declare function isEmpty(value: string | null | undefined): boolean;
+/**
+ * Check if a password meets minimum requirements
+ */
+declare function isStrongPassword(password: string): boolean;
+/**
+ * Check if a URL is valid
+ */
+declare function isValidUrl(url: string): boolean;
+/**
+ * Check if a date string is valid
+ */
+declare function isValidDate(dateStr: string): boolean;
+/**
+ * Check if a value is within a range
+ */
+declare function isWithinRange(value: number, min: number, max: number): boolean;
+/**
+ * Check if a value matches a specific pattern
+ */
+declare function matchesPattern(value: string, pattern: RegExp): boolean;
+/**
+ * Utility function to deep merge objects for schema combination
+ * @internal
+ */
+declare function deepMerge<T extends Record<string, unknown>>(target: T, source: Record<string, unknown>): T;
+/**
+ * Type guard to check if a value is a plain object
+ * @internal
+ */
+declare function isObject(item: unknown): item is Record<string, unknown>;
+
+/**
+ * @file Input Sanitization Layer
+ * @package @jmruthers/pace-core
+ * @module Security
+ * @since 0.1.0
+ *
+ * Comprehensive input sanitization utilities to prevent XSS, injection attacks,
+ * and other security vulnerabilities.
+ */
+
+/**
+ * Sanitization options for different contexts
+ */
+interface SanitizationOptions {
+    allowHtml?: boolean;
+    allowedTags?: string[];
+    maxLength?: number;
+    trim?: boolean;
+    removeScripts?: boolean;
+    removeEvents?: boolean;
+}
+/**
+ * Sanitizes user input by removing potentially dangerous characters and patterns
+ */
+declare function sanitizeUserInput(input: string, options?: SanitizationOptions): string;
+/**
+ * Sanitizes email addresses
+ */
+declare function sanitizeEmail(email: string): string;
+/**
+ * Sanitizes phone numbers
+ */
+declare function sanitizePhoneNumber(phone: string): string;
+/**
+ * Sanitizes URLs
+ */
+declare function sanitizeUrl(url: string): string;
+/**
+ * Sanitizes file names
+ */
+declare function sanitizeFileName(fileName: string): string;
+/**
+ * Sanitizes SQL input to prevent injection
+ */
+declare function sanitizeSqlInput(input: string): string;
+/**
+ * Validates and sanitizes form data using Zod schemas
+ */
+declare function sanitizeFormData<T>(data: unknown, schema: z.ZodSchema<T>, sanitizationRules?: Record<string, SanitizationOptions>): {
+    success: boolean;
+    data?: T;
+    error?: string;
+};
+/**
+ * Content Security Policy (CSP) utilities
+ */
+declare const CSP_DIRECTIVES: {
+    default: string;
+    script: string;
+    style: string;
+    img: string;
+    font: string;
+    connect: string;
+    frame: string;
+};
+declare function generateCSPHeader(customDirectives?: Partial<typeof CSP_DIRECTIVES>): string;
+/**
+ * Rate limiting utilities
+ */
+declare class RateLimiter {
+    private maxAttempts;
+    private windowMs;
+    private attempts;
+    constructor(maxAttempts?: number, windowMs?: number);
+    isAllowed(identifier: string): boolean;
+    getRemainingAttempts(identifier: string): number;
+    reset(identifier: string): void;
+}
+
+/**
+ * @file Validation utilities
+ *
+ * Shared validation utilities with enhanced security
+ */
+
+/**
+ * Validates user input against a schema with automatic sanitization
+ */
+declare function validateUserInput<T>(schema: z.ZodSchema<T>, data: unknown, sanitizationRules?: Record<string, SanitizationOptions>): {
+    success: boolean;
+    data?: T;
+    error?: string;
+};
+/**
+ * Sanitizes user input by removing potentially dangerous characters
+ * @deprecated Use sanitizeUserInput from lib/sanitization instead
+ */
+declare function sanitizeUserInput_deprecated(input: string): string;
+/**
+ * Enhanced email validation with sanitization
+ */
+declare const emailSchema: z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodString>;
+/**
+ * Enhanced password validation
+ */
+declare const passwordSchema: z.ZodString;
+/**
+ * Username validation with sanitization
+ */
+declare const usernameSchema: z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodString>;
+/**
+ * Name validation with sanitization
+ */
+declare const nameSchema: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+/**
+ * Phone number validation with sanitization
+ */
+declare const phoneSchema: z.ZodEffects<z.ZodString, string, string>;
+/**
+ * URL validation with sanitization
+ */
+declare const urlSchema: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+
+interface SecurityEvent$1 {
+    type: string;
+    timestamp: Date;
+    userId?: string;
+    details: Record<string, unknown>;
+}
+declare function getSecurityHeaders(): Record<string, string>;
+declare function validateSecurityHeaders(headers: Record<string, string>): boolean;
+
+/**
+ * Performance thresholds and constants
+ */
+declare const PERFORMANCE_THRESHOLDS: {
+    readonly RENDER_TIME: 16;
+    readonly INTERACTION_TIME: 100;
+    readonly ANIMATION_TIME: 300;
+    readonly LOAD_TIME: 1000;
+    readonly MEMORY_USAGE: number;
+    readonly BUNDLE_SIZE: number;
+};
+
+/**
+ * Performance benchmarking utilities
+ */
+interface PerformanceMetrics$1 {
+    renderTime: number;
+    interactionTime: number;
+    memoryUsage: number;
+    bundleSize: number;
+}
+declare function createPerformanceBenchmark(name: string): {
+    end: () => PerformanceMetrics$1;
+};
+declare function measureRenderPerformance(componentName: string, renderFn: () => void): PerformanceMetrics$1;
+
+interface BundleStats {
+    totalSize: number;
+    gzippedSize: number;
+    chunks: ChunkInfo[];
+    treeshakingEffectiveness: number;
+}
+interface ChunkInfo {
+    name: string;
+    size: number;
+    modules: string[];
+    dynamicallyImported: boolean;
+}
+declare class BundleAnalyzer {
+    private enabled;
+    analyzeBundle(): BundleStats | null;
+    checkTreeshaking(): void;
+    validateExports(): void;
+    generateReport(): string;
+}
+declare const bundleAnalyzer: BundleAnalyzer;
+declare function validateImportPattern(moduleId: string, importedItems: string[]): void;
+declare function trackDynamicImport(moduleName: string): void;
+
+/**
+ * Dynamic utility loader to reduce initial bundle size
+ * Heavy utilities are loaded on-demand
+ */
+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;
+};
+declare const loadLodash: () => Promise<{
+    debounce: DebounceFunction;
+    throttle: ThrottleFunction;
+}>;
+declare const loadDateUtils: () => Promise<typeof date_fns>;
+declare const loadChartUtils: () => Promise<unknown>;
+declare const loadFormUtils: () => Promise<{
+    useForm: unknown;
+    useController: unknown;
+    Controller: unknown;
+    FormProvider: unknown;
+    useFormContext: unknown;
+    useWatch: unknown;
+    useFormState: unknown;
+    useFieldArray: unknown;
+    zodResolver: unknown;
+}>;
+declare const loadCSVUtils: () => Promise<unknown>;
+declare function createLazyUtility<T>(loader: () => Promise<T>): {
+    load: () => Promise<T>;
+    getCached: () => T | null;
+    isLoaded: () => boolean;
+};
+declare const lazyLodash: ReturnType<typeof createLazyUtility<Awaited<ReturnType<typeof loadLodash>>>>;
+declare const lazyDateUtils: ReturnType<typeof createLazyUtility<Awaited<ReturnType<typeof loadDateUtils>>>>;
+declare const lazyChartUtils: ReturnType<typeof createLazyUtility<unknown>>;
+declare const lazyFormUtils: ReturnType<typeof createLazyUtility<Awaited<ReturnType<typeof loadFormUtils>>>>;
+declare const lazyCSVUtils: ReturnType<typeof createLazyUtility<unknown>>;
+
+interface PerformanceBudget {
+    metric: string;
+    budget: number;
+    actual: number;
+    threshold: 'error' | 'warning' | 'info';
+}
+interface PerformanceMetrics {
+    bundleSize: number;
+    chunkCount: number;
+    treeshakingEffectiveness: number;
+    dynamicImportUsage: number;
+}
+interface MeasurementResult {
+    passed: boolean;
+    value: number;
+    threshold: number;
+}
+declare const PERFORMANCE_BUDGETS: {
+    [key: string]: {
+        threshold: number;
+    };
+};
+declare class PerformanceBudgetMonitor {
+    private metrics;
+    private budgets;
+    measure(metric: string, value: number, metadata?: Record<string, unknown>): MeasurementResult;
+    setBudget(metric: string, budget: number, threshold?: 'error' | 'warning' | 'info'): void;
+    checkBudgets(): PerformanceBudget[];
+    getMetrics(): PerformanceMetrics;
+    reset(): void;
+}
+declare const performanceBudgetMonitor: PerformanceBudgetMonitor;
+
+interface LazyLoadOptions {
+    fallback?: React__default.ReactNode;
+    errorBoundary?: ComponentType<{
+        children: React__default.ReactNode;
+    }>;
+}
+/**
+ * Create a lazy-loaded component with error boundary and loading fallback
+ */
+declare function createLazyComponent<T extends ComponentType<any>>(importFn: () => Promise<{
+    default: T;
+}>, componentName: string, options?: LazyLoadOptions): T;
+/**
+ * Lazy-loaded DataTable component
+ */
+declare const LazyDataTable: typeof DataTable;
+
+/**
+ * Permission utilities for transforming and managing permissions
+ */
+declare function transformPermissionMapToBoolean(permissions: Record<string, unknown>): Record<string, boolean>;
+declare function hasPermission(permissions: Record<string, boolean>, permission: string): boolean;
+declare function hasAnyPermission(permissions: Record<string, boolean>, permissionList: string[]): boolean;
+declare function hasAllPermissions(permissions: Record<string, boolean>, permissionList: string[]): boolean;
+
+/**
+ * @file Permission type definitions and utilities
+ */
+declare enum PermissionType {
+    READ = "read",
+    WRITE = "write",
+    DELETE = "delete",
+    ADMIN = "admin"
+}
+/**
+ * Parse a permission string into components
+ */
+declare function parsePermission(permission: string): {
+    resource: string;
+    action: string;
+} | null;
+
+/**
+ * Creates a subset schema from a larger schema
+ *
+ * @param schema - Original Zod schema
+ * @param keys - Array of keys to pick from the schema
+ * @returns New schema with only the selected fields
+ */
+declare function pickSchema<T extends z.ZodObject<any, any, any>, K extends keyof z.infer<T>>(schema: T, keys: K[]): z.ZodObject<any>;
+/**
+ * Combines multiple Zod schemas into one
+ *
+ * @param schemas - Array of Zod schemas to combine
+ * @returns Combined schema
+ */
+declare function combineSchemas<T extends z.ZodObject<any, any, any>[]>(schemas: T): z.ZodObject<any>;
+
+interface SecurityEvent {
+    id?: string;
+    action: string;
+    details: Record<string, any>;
+    timestamp?: number;
+}
+interface SecurityAlert {
+    id: string;
+    type: string;
+    message: string;
+    timestamp: Date;
+}
+declare class SecurityMonitor {
+    private events;
+    logEvent(event: SecurityEvent): void;
+    getEvents(): SecurityEvent[];
+    clearEvents(): void;
+    createAlert(alert: Omit<SecurityAlert, 'id' | 'timestamp'>): SecurityAlert;
+}
+declare const securityMonitor: SecurityMonitor;
+
+/**
+ * Hook for tracking user sessions and event interactions using the new RBAC system
+ * @param supabaseClient - Supabase client instance
+ * @param appName - Optional application name for tracking
+ * @returns Object containing tracking functions
+ */
+declare function useSessionTracking(supabaseClient: SupabaseClient, appName?: string): {
+    trackLogin: (eventId?: string) => Promise<void>;
+    trackEventSwitch: (eventId: string) => Promise<void>;
+    trackLogout: () => Promise<void>;
+    trackSessionExpired: () => Promise<void>;
+};
+
+/**
+ * @file Audit Logger - General Utility
+ *
+ * Moved from shared/auditLogger to lib for better organization
+ */
+interface AuditEvent {
+    type: 'auth' | 'permission' | 'security';
+    action?: string;
+    event?: string;
+    user?: string;
+    userId?: string;
+    details?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+    timestamp?: number;
+    severity?: 'low' | 'medium' | 'high' | 'critical';
+    source?: string;
+}
+declare class AuditLogger {
+    private events;
+    log(event: AuditEvent): void;
+    logPermissionEvent(event: {
+        event: string;
+        userId: string;
+        data?: Record<string, unknown>;
+    }): Promise<void>;
+    logSecurityEvent(event: {
+        event: string;
+        data?: Record<string, unknown>;
+    }): Promise<void>;
+    logAuthEvent(event: {
+        event: string;
+        userId?: string;
+        data?: Record<string, unknown>;
+    }): Promise<void>;
+    getSecurityEvents(): Promise<AuditEvent[]>;
+    getEvents(): AuditEvent[];
+    clearEvents(): void;
+}
+declare const auditLogger: AuditLogger;
+declare const auditLog: AuditLogger;
+declare function logAuthEvent(action: string, user?: string, details?: Record<string, unknown>): void;
+declare function logPermissionEvent(action: string, user?: string, details?: Record<string, unknown>): void;
+declare function logSecurityEvent(action: string, user?: string, details?: Record<string, unknown>): void;
+declare function logAuditEvent(action: string, user?: string, details?: Record<string, unknown>): void;
+
+/**
+ * @file Secure Device Fingerprinting
+ * @description Enhanced device fingerprinting with encryption and security measures
+ */
+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)
+ */
+declare function generateDeviceFingerprint(): DeviceFingerprint;
+/**
+ * Validate device fingerprint with security checks
+ */
+declare function validateDeviceFingerprint(storedFingerprint: DeviceFingerprint, currentFingerprint: DeviceFingerprint): {
+    isValid: boolean;
+    confidence: number;
+    reasons: string[];
+};
+
+/**
+ * Utility functions for formatting data in the application
+ */
+/**
+ * Format a date as a readable string
+ */
+declare function formatDate(date: Date | string | number): string;
+/**
+ * Format a number as a currency
+ */
+declare function formatCurrency(value: number, currencyCode?: string, locale?: string): string;
+/**
+ * Format a number with custom options
+ */
+declare function formatNumber(value: number, options?: Intl.NumberFormatOptions, locale?: string): string;
+/**
+ * Format a number as a percentage
+ */
+declare function formatPercent(value: number, locale?: string, decimals?: number): string;
+/**
+ * Format a large number with abbreviations (K, M, B)
+ */
+declare function formatCompactNumber(value: number, locale?: string): string;
+/**
+ * Format a file size in bytes to a human-readable string
+ */
+declare function formatFileSize(bytes: number): string;
+
+/**
+ * @file Organisation Context Utility
+ * @package @jmruthers/pace-core
+ * @module Utils/OrganisationContext
+ * @since 0.4.0
+ *
+ * Utility functions for managing organisation context in database sessions.
+ * Provides fallback mechanisms for when database functions are not available.
+ */
+
+/**
+ * Set organisation context in the database session
+ *
+ * This function attempts to set the organisation context using a database function.
+ * If the function is not available, it falls back gracefully without throwing errors.
+ *
+ * @param supabase - Supabase client instance
+ * @param organisationId - The organisation ID to set as context
+ * @returns Promise that resolves when context is set (or falls back gracefully)
+ */
+declare function setOrganisationContext(supabase: SupabaseClient, organisationId: string): Promise<void>;
+/**
+ * Clear organisation context from the database session
+ *
+ * @param supabase - Supabase client instance
+ * @returns Promise that resolves when context is cleared
+ */
+declare function clearOrganisationContext(supabase: SupabaseClient): Promise<void>;
+/**
+ * Get current organisation context from the database session
+ *
+ * @param supabase - Supabase client instance
+ * @returns Promise that resolves to the current organisation ID or null
+ */
+declare function getOrganisationContext(supabase: SupabaseClient): Promise<string | null>;
+/**
+ * Check if organisation context functions are available in the database
+ *
+ * @param supabase - Supabase client instance
+ * @returns Promise that resolves to true if functions are available
+ */
+declare function isOrganisationContextAvailable(supabase: SupabaseClient): Promise<boolean>;
+
+export { CSP_DIRECTIVES, DebugLogger, LazyDataTable, PERFORMANCE_BUDGETS, PERFORMANCE_THRESHOLDS, type PerformanceMetrics$1 as PerformanceMetrics, PermissionType, RateLimiter, type SanitizationOptions, type SecurityEvent$1 as SecurityEvent, auditLog, auditLogger, bundleAnalyzer, clearOrganisationContext, combineSchemas, createLazyComponent, createLazyUtility, createPerformanceBenchmark, deepMerge, emailSchema, formatCompactNumber, formatCurrency, formatDate, formatFileSize, formatNumber, formatPercent, generateCSPHeader, generateDeviceFingerprint, getAppNameFromBuildTime, getAppNameFromEnvironment, getAppNameFromGlobal, getAppNameFromPackageJson, getCurrentAppNameWithFallback, getOrganisationContext, getSecurityHeaders, hasAllPermissions, hasAnyPermission, hasPermission, isEmpty, isObject, isOrganisationContextAvailable, isStrongPassword, isValidDate, isValidEmail, isValidUrl, isWithinRange, lazyCSVUtils, lazyChartUtils, lazyDateUtils, lazyFormUtils, lazyLodash, loadCSVUtils, loadChartUtils, loadDateUtils, loadFormUtils, loadLodash, logAuditEvent, logAuthEvent, logPermissionEvent, logSecurityEvent, matchesPattern, measureRenderPerformance, nameSchema, parsePermission, passwordSchema, performanceBudgetMonitor, phoneSchema, pickSchema, sanitizeEmail, sanitizeFileName, sanitizeFormData, sanitizePhoneNumber, sanitizeSqlInput, sanitizeUrl, sanitizeUserInput, sanitizeUserInput_deprecated, securityMonitor, setOrganisationContext, setRBACAppName, trackDynamicImport, transformPermissionMapToBoolean, urlSchema, useSessionTracking, usernameSchema, validateDeviceFingerprint, validateImportPattern, validateSecurityHeaders, validateUserInput };