@jmruthers/pace-core 0.2.4

package/src/utils/print/PrintDataProcessor.ts

@@ -0,0 +1,390 @@
+/**
+ * @file Print Data Processor
+ * @package @jmruthers/pace-core
+ * @module PrintDataProcessor
+ * @since 0.4.38
+ * 
+ * Data processing utilities for print optimization.
+ */
+
+import { 
+  PrintDataProcessorOptions, 
+  PrintDataProcessorResult, 
+  PrintDataProcessorConfig,
+  PrintDataProcessor 
+} from './types';
+
+export class PrintDataProcessorImpl implements PrintDataProcessor {
+  private config: PrintDataProcessorConfig;
+
+  constructor(config?: Partial<PrintDataProcessorConfig>) {
+    this.config = {
+      defaultOptions: {
+        maxItemsPerPage: 50,
+        maxCharactersPerLine: 80,
+        maxLinesPerPage: 60,
+        pageBreakStrategy: 'auto',
+        groupingStrategy: 'auto',
+        truncationStrategy: 'word',
+        optimizationLevel: 'basic',
+        pageSize: 'A4',
+        orientation: 'portrait',
+        fontSize: 12,
+        lineHeight: 1.4,
+        margins: {
+          top: 0.5,
+          right: 0.5,
+          bottom: 0.5,
+          left: 0.5
+        }
+      },
+      pageSizes: {
+        A4: {
+          width: 8.27,
+          height: 11.69,
+          margin: { top: 0.5, right: 0.5, bottom: 0.5, left: 0.5 }
+        },
+        A3: {
+          width: 11.69,
+          height: 16.53,
+          margin: { top: 0.5, right: 0.5, bottom: 0.5, left: 0.5 }
+        },
+        A5: {
+          width: 5.83,
+          height: 8.27,
+          margin: { top: 0.5, right: 0.5, bottom: 0.5, left: 0.5 }
+        },
+        Letter: {
+          width: 8.5,
+          height: 11,
+          margin: { top: 0.5, right: 0.5, bottom: 0.5, left: 0.5 }
+        },
+        Legal: {
+          width: 8.5,
+          height: 14,
+          margin: { top: 0.5, right: 0.5, bottom: 0.5, left: 0.5 }
+        }
+      },
+      fonts: {
+        small: { size: 10, lineHeight: 1.2, charactersPerLine: 100 },
+        medium: { size: 12, lineHeight: 1.4, charactersPerLine: 80 },
+        large: { size: 14, lineHeight: 1.6, charactersPerLine: 60 }
+      },
+      presets: {
+        basic: {
+          maxItemsPerPage: 50,
+          maxCharactersPerLine: 80,
+          maxLinesPerPage: 60,
+          pageBreakStrategy: 'auto',
+          groupingStrategy: 'auto',
+          truncationStrategy: 'word',
+          optimizationLevel: 'basic'
+        },
+        compact: {
+          maxItemsPerPage: 100,
+          maxCharactersPerLine: 100,
+          maxLinesPerPage: 80,
+          pageBreakStrategy: 'force',
+          groupingStrategy: 'auto',
+          truncationStrategy: 'character',
+          optimizationLevel: 'advanced'
+        },
+        readable: {
+          maxItemsPerPage: 30,
+          maxCharactersPerLine: 60,
+          maxLinesPerPage: 40,
+          pageBreakStrategy: 'avoid',
+          groupingStrategy: 'smart',
+          truncationStrategy: 'word',
+          optimizationLevel: 'maximum'
+        }
+      },
+      ...config
+    };
+  }
+
+  process<T>(data: T[], options: Partial<PrintDataProcessorOptions> = {}): PrintDataProcessorResult<T> {
+    const mergedOptions = { ...this.config.defaultOptions, ...options };
+    const warnings: string[] = [];
+    const suggestions: string[] = [];
+
+    // Validate data
+    const validation = this.validate(data, mergedOptions);
+    if (!validation.isValid) {
+      warnings.push(...validation.errors);
+    }
+    warnings.push(...validation.warnings);
+
+    // Process data based on options
+    let processedData = [...data];
+    
+    // Apply optimization
+    if (mergedOptions.optimizationLevel !== 'none') {
+      processedData = this.optimize(processedData, mergedOptions);
+    }
+
+    // Calculate pagination
+    const pagination = this.getPagination(processedData, mergedOptions);
+
+    // Calculate grouping
+    const grouping = this.getGrouping(processedData, 'id' as keyof T, mergedOptions);
+
+    // Calculate optimization metrics
+    const optimization = this.getPreview(processedData, mergedOptions);
+
+    // Generate suggestions
+    if (optimization.estimatedPages > 10) {
+      suggestions.push('Consider using a more compact layout or smaller font size');
+    }
+    if (optimization.readabilityScore < 0.7) {
+      suggestions.push('Consider improving text formatting for better readability');
+    }
+    if (optimization.compressionRatio < 0.8) {
+      suggestions.push('Consider optimizing content to reduce page count');
+    }
+
+    return {
+      data: processedData,
+      pagination,
+      grouping,
+      optimization,
+      warnings,
+      suggestions
+    };
+  }
+
+  getPagination<T>(data: T[], options: Partial<PrintDataProcessorOptions> = {}): {
+    totalPages: number;
+    currentPage: number;
+    itemsPerPage: number;
+    totalItems: number;
+  } {
+    const mergedOptions = { ...this.config.defaultOptions, ...options };
+    const itemsPerPage = mergedOptions.maxItemsPerPage || 50;
+    const totalItems = data.length;
+    const totalPages = Math.ceil(totalItems / itemsPerPage);
+
+    return {
+      totalPages,
+      currentPage: 1,
+      itemsPerPage,
+      totalItems
+    };
+  }
+
+  getGrouping<T>(data: T[], groupBy: keyof T, options: Partial<PrintDataProcessorOptions> = {}): {
+    groups: Array<{
+      key: string;
+      items: T[];
+      startPage: number;
+      endPage: number;
+    }>;
+    totalGroups: number;
+  } {
+    const mergedOptions = { ...this.config.defaultOptions, ...options };
+    const itemsPerPage = mergedOptions.maxItemsPerPage || 50;
+    
+    // Group data by the specified key
+    const groups = new Map<string, T[]>();
+    data.forEach(item => {
+      const key = String(item[groupBy] || 'Unknown');
+      if (!groups.has(key)) {
+        groups.set(key, []);
+      }
+      groups.get(key)!.push(item);
+    });
+
+    // Calculate page information for each group
+    const groupArray = Array.from(groups.entries()).map(([key, items]) => {
+      const startPage = Math.floor(data.indexOf(items[0]) / itemsPerPage) + 1;
+      const endPage = Math.floor(data.indexOf(items[items.length - 1]) / itemsPerPage) + 1;
+      
+      return {
+        key,
+        items,
+        startPage,
+        endPage
+      };
+    });
+
+    return {
+      groups: groupArray,
+      totalGroups: groupArray.length
+    };
+  }
+
+  optimize<T>(data: T[], options: Partial<PrintDataProcessorOptions> = {}): T[] {
+    const mergedOptions = { ...this.config.defaultOptions, ...options };
+    let optimizedData = [...data];
+
+    // Apply text truncation if needed
+    if (mergedOptions.truncationStrategy !== 'none') {
+      optimizedData = this.applyTextTruncation(optimizedData, mergedOptions);
+    }
+
+    // Apply grouping optimization
+    if (mergedOptions.groupingStrategy !== 'none') {
+      optimizedData = this.applyGroupingOptimization(optimizedData, mergedOptions);
+    }
+
+    // Apply page break optimization
+    if (mergedOptions.pageBreakStrategy !== 'auto') {
+      optimizedData = this.applyPageBreakOptimization(optimizedData, mergedOptions);
+    }
+
+    return optimizedData;
+  }
+
+  validate<T>(data: T[], options: Partial<PrintDataProcessorOptions> = {}): {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+  } {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    // Check if data is empty
+    if (!data || data.length === 0) {
+      errors.push('Data array is empty');
+    }
+
+    // Check data types
+    if (data.some(item => typeof item !== 'object' || item === null)) {
+      warnings.push('Some items in data array are not objects or are null');
+    }
+
+    // Check for very large datasets
+    if (data.length > 10000) {
+      warnings.push('Large dataset detected. Consider pagination or filtering.');
+    }
+
+    // Check for very long text content
+    const longTextItems = data.filter(item => 
+      typeof item === 'object' && 
+      item !== null && 
+      Object.values(item).some(value => 
+        typeof value === 'string' && value.length > 1000
+      )
+    );
+    
+    if (longTextItems.length > 0) {
+      warnings.push('Some items contain very long text. Consider truncation.');
+    }
+
+    return {
+      isValid: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+
+  getPreview<T>(data: T[], options: Partial<PrintDataProcessorOptions> = {}): {
+    estimatedPages: number;
+    estimatedPrintTime: number;
+    compressionRatio: number;
+    readabilityScore: number;
+  } {
+    const mergedOptions = { ...this.config.defaultOptions, ...options };
+    const pagination = this.getPagination(data, mergedOptions);
+    
+    // Calculate estimated print time (in minutes)
+    const estimatedPrintTime = pagination.totalPages * 0.5; // 30 seconds per page
+    
+    // Calculate compression ratio
+    const originalSize = JSON.stringify(data).length;
+    const optimizedData = this.optimize(data, mergedOptions);
+    const optimizedSize = JSON.stringify(optimizedData).length;
+    const compressionRatio = optimizedSize / originalSize;
+    
+    // Calculate readability score (0-1)
+    const readabilityScore = this.calculateReadabilityScore(data, mergedOptions);
+    
+    return {
+      estimatedPages: pagination.totalPages,
+      estimatedPrintTime,
+      compressionRatio,
+      readabilityScore
+    };
+  }
+
+  private applyTextTruncation<T>(data: T[], options: PrintDataProcessorOptions): T[] {
+    const maxLength = options.maxCharactersPerLine || 80;
+    
+    return data.map(item => {
+      if (typeof item === 'object' && item !== null) {
+        const truncatedItem = { ...item } as Record<string, any>;
+        
+        Object.keys(truncatedItem).forEach(key => {
+          const value = truncatedItem[key];
+          if (typeof value === 'string' && value.length > maxLength) {
+            switch (options.truncationStrategy) {
+              case 'ellipsis':
+                truncatedItem[key] = value.substring(0, maxLength - 3) + '...';
+                break;
+              case 'word':
+                const words = value.split(' ');
+                let truncated = '';
+                for (const word of words) {
+                  const testLength = truncated ? truncated.length + 1 + word.length : word.length;
+                  if (testLength > maxLength) {
+                    if (truncated.length + 3 <= maxLength) {
+                      truncated += '...';
+                    }
+                    break;
+                  }
+                  truncated += (truncated ? ' ' : '') + word;
+                }
+                truncatedItem[key] = truncated;
+                break;
+              case 'character':
+                truncatedItem[key] = value.substring(0, maxLength);
+                break;
+            }
+          }
+        });
+        
+        return truncatedItem as T;
+      }
+      
+      return item;
+    });
+  }
+
+  private applyGroupingOptimization<T>(data: T[], options: PrintDataProcessorOptions): T[] {
+    // This is a simplified grouping optimization
+    // In a real implementation, this would be more sophisticated
+    return data;
+  }
+
+  private applyPageBreakOptimization<T>(data: T[], options: PrintDataProcessorOptions): T[] {
+    // This is a simplified page break optimization
+    // In a real implementation, this would analyze content and add page breaks
+    return data;
+  }
+
+  private calculateReadabilityScore<T>(data: T[], options: PrintDataProcessorOptions): number {
+    // Simplified readability score calculation
+    // In a real implementation, this would use more sophisticated algorithms
+    let score = 1.0;
+    
+    // Penalize very long lines
+    if (options.maxCharactersPerLine && options.maxCharactersPerLine > 100) {
+      score -= 0.1;
+    }
+    
+    // Penalize very dense layouts
+    if (options.maxLinesPerPage && options.maxLinesPerPage > 80) {
+      score -= 0.1;
+    }
+    
+    // Reward good font sizes
+    if (options.fontSize && options.fontSize >= 12) {
+      score += 0.1;
+    }
+    
+    return Math.max(0, Math.min(1, score));
+  }
+}
+
+// Export singleton instance
+export const printDataProcessor = new PrintDataProcessorImpl();

package/src/utils/print/__tests__/PrintDataProcessor.unit.test.ts

@@ -0,0 +1,219 @@
+/**
+ * @file PrintDataProcessor Unit Tests
+ * @package @jmruthers/pace-core
+ * @module PrintDataProcessor
+ * @since 0.4.38
+ * 
+ * Unit tests for PrintDataProcessor class.
+ */
+
+import { PrintDataProcessorImpl } from '../PrintDataProcessor';
+import { testDataGenerators } from '../../../__tests__/shared';
+
+describe('PrintDataProcessor', () => {
+  let processor: PrintDataProcessorImpl;
+  const sampleData = [
+    { id: 1, name: 'John Doe', email: 'john@example.com', department: 'Engineering' },
+    { id: 2, name: 'Jane Smith', email: 'jane@example.com', department: 'Marketing' },
+    { id: 3, name: 'Bob Johnson', email: 'bob@example.com', department: 'Engineering' },
+    { id: 4, name: 'Alice Brown', email: 'alice@example.com', department: 'Sales' },
+    { id: 5, name: 'Charlie Wilson', email: 'charlie@example.com', department: 'Marketing' }
+  ];
+
+  beforeEach(() => {
+    processor = new PrintDataProcessorImpl();
+  });
+
+  describe('process', () => {
+    it('processes data with default options', () => {
+      const result = processor.process(sampleData);
+      
+      expect(result).toBeDefined();
+      expect(result.data).toHaveLength(5);
+      expect(result.pagination.totalPages).toBe(1);
+      expect(result.pagination.itemsPerPage).toBe(50);
+      expect(result.pagination.totalItems).toBe(5);
+      expect(result.grouping.totalGroups).toBe(5);
+      expect(result.optimization.estimatedPages).toBe(1);
+      expect(result.warnings).toBeDefined();
+      expect(result.suggestions).toBeDefined();
+    });
+
+    it('processes data with custom options', () => {
+      const options = {
+        maxItemsPerPage: 2,
+        maxCharactersPerLine: 50,
+        optimizationLevel: 'advanced' as const
+      };
+      
+      const result = processor.process(sampleData, options);
+      
+      expect(result.pagination.totalPages).toBe(3);
+      expect(result.pagination.itemsPerPage).toBe(2);
+    });
+
+    it('handles empty data array', () => {
+      const result = processor.process([]);
+      
+      expect(result.data).toHaveLength(0);
+      expect(result.pagination.totalPages).toBe(0);
+      expect(result.warnings).toContain('Data array is empty');
+    });
+
+    it('applies text truncation when enabled', () => {
+      const longTextData = [
+        { id: 1, description: 'This is a very long description that should be truncated because it exceeds the maximum character limit' }
+      ];
+      
+      const options = {
+        maxCharactersPerLine: 50,
+        truncationStrategy: 'ellipsis' as const
+      };
+      
+      const result = processor.process(longTextData, options);
+      
+      expect(result.data[0].description).toContain('...');
+      expect(result.data[0].description.length).toBeLessThanOrEqual(50);
+    });
+  });
+
+  describe('getPagination', () => {
+    it('calculates pagination correctly', () => {
+      const result = processor.getPagination(sampleData);
+      
+      expect(result.totalPages).toBe(1);
+      expect(result.itemsPerPage).toBe(50);
+      expect(result.totalItems).toBe(5);
+    });
+
+    it('calculates pagination with custom items per page', () => {
+      const result = processor.getPagination(sampleData, { maxItemsPerPage: 2 });
+      
+      expect(result.totalPages).toBe(3);
+      expect(result.itemsPerPage).toBe(2);
+      expect(result.totalItems).toBe(5);
+    });
+  });
+
+  describe('getGrouping', () => {
+    it('groups data by specified key', () => {
+      const result = processor.getGrouping(sampleData, 'department');
+      
+      expect(result.totalGroups).toBe(3);
+      expect(result.groups).toHaveLength(3);
+      
+      const engineeringGroup = result.groups.find(g => g.key === 'Engineering');
+      expect(engineeringGroup).toBeDefined();
+      expect(engineeringGroup!.items).toHaveLength(2);
+    });
+
+    it('handles missing group keys', () => {
+      const dataWithMissingKeys = [
+        { id: 1, name: 'John' },
+        { id: 2, name: 'Jane', department: 'Engineering' }
+      ];
+      
+      const result = processor.getGrouping(dataWithMissingKeys, 'department');
+      
+      expect(result.totalGroups).toBe(2);
+      const unknownGroup = result.groups.find(g => g.key === 'Unknown');
+      expect(unknownGroup).toBeDefined();
+    });
+  });
+
+  describe('optimize', () => {
+    it('optimizes data without changing structure', () => {
+      const result = processor.optimize(sampleData);
+      
+      expect(result).toHaveLength(5);
+      expect(result[0]).toHaveProperty('id');
+      expect(result[0]).toHaveProperty('name');
+    });
+
+    it('applies text truncation optimization', () => {
+      const longTextData = [
+        { id: 1, description: 'Very long text that should be truncated' }
+      ];
+      
+      const options = {
+        maxCharactersPerLine: 20,
+        truncationStrategy: 'word' as const
+      };
+      
+      const result = processor.optimize(longTextData, options);
+      
+      expect(result[0].description.length).toBeLessThanOrEqual(20);
+    });
+  });
+
+  describe('validate', () => {
+    it('validates valid data', () => {
+      const result = processor.validate(sampleData);
+      
+      expect(result.isValid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it('validates empty data array', () => {
+      const result = processor.validate([]);
+      
+      expect(result.isValid).toBe(false);
+      expect(result.errors).toContain('Data array is empty');
+    });
+
+    it('validates data with null items', () => {
+      const dataWithNulls = [null, { id: 1, name: 'John' }];
+      
+      const result = processor.validate(dataWithNulls);
+      
+      expect(result.isValid).toBe(true);
+      expect(result.warnings).toContain('Some items in data array are not objects or are null');
+    });
+
+    it('validates large datasets', () => {
+      const largeData = Array.from({ length: 15000 }, (_, i) => ({ id: i, name: `Item ${i}` }));
+      
+      const result = processor.validate(largeData);
+      
+      expect(result.isValid).toBe(true);
+      expect(result.warnings).toContain('Large dataset detected. Consider pagination or filtering.');
+    });
+
+    it('validates data with long text content', () => {
+      const longTextData = [
+        { id: 1, description: 'a'.repeat(2000) }
+      ];
+      
+      const result = processor.validate(longTextData);
+      
+      expect(result.isValid).toBe(true);
+      expect(result.warnings).toContain('Some items contain very long text. Consider truncation.');
+    });
+  });
+
+  describe('getPreview', () => {
+    it('calculates preview metrics', () => {
+      const result = processor.getPreview(sampleData);
+      
+      expect(result.estimatedPages).toBe(1);
+      expect(result.estimatedPrintTime).toBeGreaterThan(0);
+      expect(result.compressionRatio).toBeGreaterThan(0);
+      expect(result.compressionRatio).toBeLessThanOrEqual(1);
+      expect(result.readabilityScore).toBeGreaterThan(0);
+      expect(result.readabilityScore).toBeLessThanOrEqual(1);
+    });
+
+    it('calculates preview with custom options', () => {
+      const options = {
+        maxItemsPerPage: 2,
+        fontSize: 14,
+        maxCharactersPerLine: 60
+      };
+      
+      const result = processor.getPreview(sampleData, options);
+      
+      expect(result.estimatedPages).toBe(3);
+      expect(result.readabilityScore).toBeGreaterThan(0.8);
+    });
+  });
+});