agentsqripts/lib/utils/patterns/groupBy.js

Comprehensive static code analysis toolkit for identifying technical debt, security vulnerabilities, performance issues, and code quality problems

/**
 * @file Group items by key with flexible key extraction
 * @description Single responsibility: Organize items into groups based on key
 * 
 * This utility implements the classic "group by" functional programming pattern,
 * organizing array items into groups based on a shared key. It provides flexible
 * key extraction and is essential for data analysis, reporting, and batch processing
 * operations throughout the AgentSqripts platform.
 * 
 * Design rationale:
 * - Supports both string property names and custom functions for key extraction
 * - Uses reduce for efficient single-pass grouping algorithm
 * - Lazy array initialization optimizes memory usage
 * - Object structure provides O(1) group lookup for performance
 */

/**
 * Group array items by specified key extraction method
 * 
 * Technical function: Organizes items into groups based on key extraction strategy
 * 
 * Implementation rationale:
 * - Type checking (typeof) enables dual interface for convenience and flexibility
 * - Arrow function property accessor provides clean syntax for common use case
 * - reduce() with object accumulator enables efficient single-pass grouping
 * - Lazy array initialization avoids creating empty arrays unnecessarily
 * 
 * Key extraction strategy:
 * - String keyFn: Creates property accessor function (item) => item[keyFn]
 * - Function keyFn: Uses provided function directly for complex grouping logic
 * - Supports any key type that can be used as object property
 * - Handles missing properties by creating 'undefined' group
 * 
 * Grouping algorithm:
 * - Single pass through items array using reduce
 * - Object accumulator for O(1) group lookup and access
 * - Lazy initialization: arrays created only when first item added to group
 * - Items preserved in original order within each group
 * 
 * Memory optimization:
 * - Arrays created on-demand to avoid empty group arrays
 * - Object structure more memory efficient than Map for serialization
 * - No deep copying - original item references preserved
 * - Garbage collection friendly with proper reference management
 * 
 * Performance considerations:
 * - O(n) time complexity for single pass through items
 * - O(n) space complexity for storing all items in groups
 * - Object property access is O(1) for group operations
 * - No sorting required - maintains insertion order
 * 
 * Edge cases handled:
 * - Empty items array: Returns empty object {}
 * - Missing property access: Creates 'undefined' group
 * - Function returning null/undefined: Creates groups for those values
 * - Single item per group: Creates arrays with single elements
 * 
 * Alternative approaches considered:
 * - Map data structure: Rejected as objects serialize better for JSON
 * - Pre-initializing all possible groups: Rejected as memory inefficient
 * - Separate functions for property vs function modes: Rejected for API simplicity
 * 
 * @param {Array<any>} items - Array of items to group and organize
 * @param {Function|string} keyFn - Key extraction method:
 *   - String: Property name to extract from each item
 *   - Function: Custom function that takes item and returns grouping key
 * @returns {Object<string, Array>} Object mapping keys to arrays of grouped items
 *   Example: { "HIGH": [issue1, issue3], "LOW": [issue2, issue4] }
 */
function groupBy(items, keyFn) {
  const getKey = typeof keyFn === 'string' 
    ? (item) => item[keyFn]
    : keyFn;
    
  return items.reduce((groups, item) => {
    const key = getKey(item);
    if (!groups[key]) groups[key] = [];
    groups[key].push(item);
    return groups;
  }, {});
}

module.exports = groupBy;