indusagi-coding-agent 0.1.28 → 0.1.30

package/docs/UTILS-USAGE-GUIDE.md

@@ -1,1419 +0,0 @@
-# Utils Module Usage Guide
-
-**Version**: 1.0.0  
-**Last Updated**: February 2024  
-**Contains**: 40+ Real-World Examples
-
----
-
-## Table of Contents
-
-1. [Array Utilities Usage](#array-utilities-usage)
-2. [Error Handling Patterns](#error-handling-patterns)
-3. [Logging Usage Examples](#logging-usage-examples)
-4. [File Operations Workflows](#file-operations-workflows)
-5. [String & Date Formatting](#string--date-formatting)
-6. [JSON Processing](#json-processing)
-7. [Image Processing](#image-processing)
-8. [Git Operations](#git-operations)
-9. [Data Transformation Pipelines](#data-transformation-pipelines)
-10. [Integration Patterns](#integration-patterns)
-11. [Performance Optimization](#performance-optimization)
-12. [Dependency Management](#dependency-management)
-13. [Debugging Techniques](#debugging-techniques)
-14. [Common Gotchas](#common-gotchas)
-
----
-
-## Array Utilities Usage
-
-### 1. Grouping and Categorizing Data
-
-```typescript
-import { groupBy, partition, unique } from './utils/array';
-
-// Example 1: Group users by role
-const users = [
-  { id: 1, name: 'Alice', role: 'admin' },
-  { id: 2, name: 'Bob', role: 'user' },
-  { id: 3, name: 'Charlie', role: 'admin' },
-  { id: 4, name: 'Diana', role: 'user' }
-];
-
-const grouped = groupBy(users, user => user.role);
-// Result:
-// {
-//   admin: [{ id: 1, ... }, { id: 3, ... }],
-//   user: [{ id: 2, ... }, { id: 4, ... }]
-// }
-
-// Use case: Create permission groups
-const permissions = {
-  admin: ['read', 'write', 'delete'],
-  user: ['read']
-};
-
-for (const [role, members] of Object.entries(grouped)) {
-  applyPermissions(members, permissions[role]);
-}
-```
-
-### 2. Partitioning Arrays
-
-```typescript
-import { partition, unique } from './utils/array';
-
-// Example 2: Separate active and inactive users
-const [activeUsers, inactiveUsers] = partition(
-  users,
-  user => user.isActive
-);
-
-// Example 3: Separate even and odd numbers
-const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9];
-const [even, odd] = partition(numbers, n => n % 2 === 0);
-// even: [2, 4, 6, 8]
-// odd: [1, 3, 5, 7, 9]
-
-// Practical: Split data for parallel processing
-const [largeOrders, smallOrders] = partition(
-  orders,
-  order => order.total > 1000
-);
-
-processLargeOrdersWithPriority(largeOrders);
-processSmallOrdersInBatch(smallOrders);
-```
-
-### 3. Deduplication and Unique Values
-
-```typescript
-import { unique } from './utils/array';
-
-// Example 1: Remove duplicate IDs while preserving order
-const records = [
-  { id: 1, name: 'A' },
-  { id: 2, name: 'B' },
-  { id: 1, name: 'A' }, // duplicate
-  { id: 3, name: 'C' }
-];
-
-const unique_ = unique(records, r => r.id);
-// Result: [{ id: 1 }, { id: 2 }, { id: 3 }]
-
-// Example 2: Get unique tags from multiple arrays
-const tags1 = ['javascript', 'react', 'node'];
-const tags2 = ['react', 'typescript', 'node'];
-
-const allTags = unique([...tags1, ...tags2]);
-// Result: ['javascript', 'react', 'node', 'typescript']
-```
-
-### 4. Flattening Nested Arrays
-
-```typescript
-import { flatten, chunk } from './utils/array';
-
-// Example 1: Flatten directory structure
-const fileStructure = [
-  'README.md',
-  ['src/', 
-    ['utils.ts', 'index.ts'],
-    ['tests/', ['utils.test.ts']]
-  ],
-  'package.json'
-];
-
-const allFiles = flatten(fileStructure);
-// Result: ['README.md', 'src/', 'utils.ts', 'index.ts', 'tests/', 'utils.test.ts', 'package.json']
-
-// Example 2: Flatten with depth limit
-const result = flatten(fileStructure, 2);
-// Only flattens 2 levels deep
-```
-
-### 5. Chunking for Batch Processing
-
-```typescript
-import { chunk } from './utils/array';
-
-// Example 1: Process large arrays in batches
-const data = Array.from({ length: 1000 }, (_, i) => i);
-const batchSize = 100;
-
-for (const batch of chunk(data, batchSize)) {
-  await processBatch(batch);
-  // Prevents memory issues with large datasets
-}
-
-// Example 2: Create pagination
-const itemsPerPage = 20;
-const allItems = [...items];
-const pages = chunk(allItems, itemsPerPage);
-
-pages.forEach((page, index) => {
-  renderPage(page, index + 1); // Page numbers start at 1
-});
-```
-
-### 6. Sorting Custom Objects
-
-```typescript
-import { sortBy } from './utils/array';
-
-// Example: Sort users by age, then by name
-const users = [
-  { name: 'Charlie', age: 30 },
-  { name: 'Alice', age: 25 },
-  { name: 'Bob', age: 25 }
-];
-
-const sorted = sortBy(users, (a, b) => {
-  if (a.age !== b.age) return a.age - b.age;
-  return a.name.localeCompare(b.name);
-});
-
-// Result:
-// [
-//   { name: 'Alice', age: 25 },
-//   { name: 'Bob', age: 25 },
-//   { name: 'Charlie', age: 30 }
-// ]
-```
-
-### 7. Set Operations
-
-```typescript
-import { union, intersection, difference } from './utils/array';
-
-// Example: Compare user permissions
-const adminPermissions = ['read', 'write', 'delete', 'admin'];
-const userPermissions = ['read', 'write'];
-const guestPermissions = ['read'];
-
-// All unique permissions
-const allPermissions = union(adminPermissions, userPermissions, guestPermissions);
-
-// Common permissions across all groups
-const commonPermissions = intersection(adminPermissions, userPermissions, guestPermissions);
-// Result: ['read']
-
-// Exclusive admin permissions
-const adminOnly = difference(adminPermissions, userPermissions, guestPermissions);
-// Result: ['delete', 'admin']
-```
-
-### 8. Finding Min/Max and Aggregations
-
-```typescript
-import { minBy, maxBy, sum, average } from './utils/array';
-
-// Example: Sales analytics
-const sales = [
-  { product: 'A', amount: 1500 },
-  { product: 'B', amount: 2300 },
-  { product: 'C', amount: 800 }
-];
-
-const bestProduct = maxBy(sales, s => s.amount);
-const worstProduct = minBy(sales, s => s.amount);
-const totalSales = sum(sales, s => s.amount);
-const avgSale = average(sales, s => s.amount);
-
-console.log(`Best: ${bestProduct.product} ($${bestProduct.amount})`);
-console.log(`Worst: ${worstProduct.product} ($${worstProduct.amount})`);
-console.log(`Total: $${totalSales}`);
-console.log(`Average: $${avgSale.toFixed(2)}`);
-```
-
-### 9. Zipping Arrays Together
-
-```typescript
-import { zip, unzip } from './utils/array';
-
-// Example 1: Combine related arrays
-const names = ['Alice', 'Bob', 'Charlie'];
-const ages = [25, 30, 35];
-const cities = ['NYC', 'LA', 'Chicago'];
-
-const combined = zip(names, ages, cities);
-// Result: [
-//   ['Alice', 25, 'NYC'],
-//   ['Bob', 30, 'LA'],
-//   ['Charlie', 35, 'Chicago']
-// ]
-
-// Example 2: Create objects from zipped data
-const people = combined.map(([name, age, city]) => ({
-  name, age, city
-}));
-
-// Example 3: Unzip to separate arrays
-const [unzippedNames, unzippedAges, unzippedCities] = unzip(combined);
-```
-
-### 10. Sampling and Shuffling
-
-```typescript
-import { shuffle, sample, sampleSize } from './utils/array';
-
-// Example 1: Random selection
-const questions = [/* 100 questions */];
-const quiz = sampleSize(questions, 10); // Select 10 random questions
-
-// Example 2: Shuffle for randomization
-const shuffledCards = shuffle(deck); // Shuffle deck for card game
-
-// Example 3: Pick single random item
-const randomUser = sample(users);
-```
-
----
-
-## Error Handling Patterns
-
-### 1. Basic Error Formatting
-
-```typescript
-import { formatErrorForUser, ErrorCode } from './utils/error-handler';
-
-// Pattern 1: Standard error handling
-async function loadConfig() {
-  try {
-    const content = await fs.readFile('./config.json', 'utf-8');
-    return JSON.parse(content);
-  } catch (error) {
-    const formatted = formatErrorForUser(error);
-    console.error(`Error: ${formatted.message}`);
-    console.error('Try this:', formatted.suggestions[0]);
-    throw formatted.originalError;
-  }
-}
-```
-
-### 2. API Error Response
-
-```typescript
-import { formatErrorForUser } from './utils/error-handler';
-
-// Express error middleware
-app.use((err, req, res, next) => {
-  const formatted = formatErrorForUser(err);
-  
-  // Log internally
-  internalLogger.error(formatted.technicalDetails);
-  
-  // Return user-friendly response
-  res.status(500).json({
-    success: false,
-    error: formatted.message,
-    code: formatted.code,
-    suggestions: formatted.suggestions
-  });
-});
-```
-
-### 3. Promise Error Wrapper
-
-```typescript
-import { handlePromise } from './utils/error-handler';
-
-async function fetchUserData(userId) {
-  const [user, error] = await handlePromise(
-    fetch(`/api/users/${userId}`).then(r => r.json())
-  );
-  
-  if (error) {
-    return {
-      success: false,
-      error: formatErrorForUser(error).message
-    };
-  }
-  
-  return { success: true, data: user };
-}
-```
-
-### 4. Retry with Exponential Backoff
-
-```typescript
-import { retryWithBackoff, formatErrorForUser } from './utils/error-handler';
-
-// Resilient database connection
-async function connectWithRetry() {
-  try {
-    return await retryWithBackoff(
-      async () => {
-        const conn = await db.connect();
-        console.log('Connected successfully');
-        return conn;
-      },
-      5,    // Max 5 attempts
-      1000  // Start with 1s delay, doubles each attempt
-    );
-  } catch (error) {
-    const formatted = formatErrorForUser(error, { code: 'NETWORK' });
-    console.error(formatted.message);
-    // Fallback strategy
-    return await createOfflineCache();
-  }
-}
-```
-
-### 5. Error Categorization
-
-```typescript
-import { categorizeError, getRecoverySuggestions } from './utils/error-handler';
-
-function handleError(error) {
-  const errorType = categorizeError(error);
-  const suggestions = getRecoverySuggestions(error);
-  
-  switch (errorType) {
-    case 'TypeError':
-      showTypeErrorUI(suggestions);
-      break;
-    case 'ReferenceError':
-      showReferenceErrorUI(suggestions);
-      break;
-    case 'SyntaxError':
-      showSyntaxErrorUI(suggestions);
-      break;
-    default:
-      showGenericErrorUI(suggestions);
-  }
-}
-```
-
-### 6. Sanitized Error Messages
-
-```typescript
-import { sanitizeErrorMessage, extractErrorMessage } from './utils/error-handler';
-
-// Before sending to client
-const rawError = error.message;
-// Raw: "Error reading /home/user/secret.key: EACCES"
-
-const safe = sanitizeErrorMessage(rawError);
-// Safe: "Error reading file: Permission denied"
-
-// Send to client
-res.json({ error: safe });
-
-// But log the technical details internally
-internalLog.error(rawError);
-```
-
----
-
-## Logging Usage Examples
-
-### 1. Basic Module Logging
-
-```typescript
-import { createLogger, setLogLevel } from './utils/logger';
-
-// Create logger for module
-const log = createLogger('UserService');
-
-// Set global log level
-setLogLevel('debug');
-
-// Use in functions
-export async function getUser(id: string) {
-  log.debug('Fetching user', { userId: id });
-  
-  try {
-    const user = await db.users.findById(id);
-    log.info('User fetched successfully', { userId: id, name: user.name });
-    return user;
-  } catch (error) {
-    log.error('Failed to fetch user', { userId: id, error: String(error) });
-    throw error;
-  }
-}
-```
-
-### 2. Performance Monitoring
-
-```typescript
-const log = createLogger('Database');
-
-async function complexQuery() {
-  const timer = log.time('complex-query');
-  
-  try {
-    const result = await db.query(`
-      SELECT u.*, c.count FROM users u
-      LEFT JOIN (SELECT userId, count(*) as count FROM orders GROUP BY userId) c
-      ON u.id = c.userId
-      WHERE u.status = 'active'
-    `);
-    
-    timer(); // Automatically logs: "complex-query: 234.50ms"
-    return result;
-  } catch (error) {
-    timer(); // Still logs timing even on error
-    log.error('Query failed', { error: String(error) });
-    throw error;
-  }
-}
-```
-
-### 3. Scoped Logging with Context
-
-```typescript
-import { createScopedLogger } from './utils/logger';
-
-// In request handler
-app.post('/api/users', async (req, res) => {
-  const requestId = generateRequestId();
-  const requestLog = createScopedLogger(log, `req-${requestId}`, {
-    method: 'POST',
-    path: '/api/users',
-    ip: req.ip
-  });
-  
-  requestLog.info('Processing request');
-  
-  try {
-    const user = await createUser(req.body);
-    requestLog.info('User created', { userId: user.id });
-    res.json(user);
-  } catch (error) {
-    requestLog.error('User creation failed', { error: String(error) });
-    res.status(400).json({ error: 'Failed to create user' });
-  }
-});
-```
-
-### 4. Batch Logging
-
-```typescript
-import { logBatch } from './utils/logger';
-
-async function processBatch(items) {
-  const log = createLogger('BatchProcessor');
-  const results = [];
-  
-  for (const item of items) {
-    try {
-      const result = await processItem(item);
-      results.push(`Processed: ${item.id}`);
-    } catch (error) {
-      results.push(`Failed: ${item.id}`);
-    }
-  }
-  
-  // Log all results as group
-  logBatch('Batch Processing Complete', results, log);
-}
-```
-
-### 5. Performance Monitor
-
-```typescript
-import { createPerformanceMonitor } from './utils/logger';
-
-const log = createLogger('API');
-const monitor = createPerformanceMonitor(log, 200); // 200ms threshold
-
-// Any operation over 200ms triggers warning instead of debug
-await monitor('user-lookup', async () => {
-  return await db.users.find({ active: true });
-});
-
-// Result: "user-lookup completed { duration: 245.30ms }"
-// Log level: WARN (because 245ms > 200ms threshold)
-```
-
----
-
-## File Operations Workflows
-
-### 1. Safe File Reading with Validation
-
-```typescript
-import {
-  readFile,
-  exists,
-  getSize,
-  formatErrorForUser
-} from './utils/file-operations';
-import { parseJSON } from './utils/json-formatter';
-
-async function loadConfig(path: string) {
-  try {
-    // Check existence first
-    if (!await exists(path)) {
-      console.log('Config not found, creating default...');
-      return getDefaultConfig();
-    }
-    
-    // Check file size to prevent memory issues
-    const size = await getSize(path);
-    if (size > 1000000) { // 1MB limit
-      throw new Error('Config file too large');
-    }
-    
-    // Read and parse
-    const content = await readFile(path);
-    const [config, error] = parseJSON(content);
-    
-    if (error) {
-      throw new Error(`Invalid JSON: ${error.message}`);
-    }
-    
-    return config;
-  } catch (error) {
-    const formatted = formatErrorForUser(error);
-    console.error(formatted.message);
-    return getDefaultConfig();
-  }
-}
-```
-
-### 2. Batch File Processing
-
-```typescript
-import {
-  batchProcessFiles,
-  readFile,
-  writeFile,
-  createLogger
-} from './utils/file-operations';
-
-const log = createLogger('FileProcessor');
-
-async function convertFilesToUTF8() {
-  let converted = 0;
-  
-  const count = await batchProcessFiles(
-    './data',
-    async (filePath) => {
-      const content = await readFile(filePath, { encoding: 'latin1' });
-      const utf8Content = Buffer.from(content, 'latin1').toString('utf-8');
-      await writeFile(filePath, utf8Content);
-      converted++;
-      log.debug('Converted', { file: filePath });
-    },
-    { extension: '.txt', recursive: true }
-  );
-  
-  log.info('Conversion complete', { processed: converted, total: count });
-}
-```
-
-### 3. Safe File Deletion with Backup
-
-```typescript
-import { deleteFile, exists } from './utils/file-operations';
-
-async function safeDelete(filePath: string) {
-  try {
-    if (!await exists(filePath)) {
-      throw new Error('File not found');
-    }
-    
-    const backupPath = await deleteFile(filePath, true);
-    console.log(`Deleted: ${filePath}`);
-    console.log(`Backup: ${backupPath}`);
-    
-    return { success: true, backup: backupPath };
-  } catch (error) {
-    console.error('Failed to delete:', error.message);
-    return { success: false };
-  }
-}
-```
-
-### 4. Directory Listing and Filtering
-
-```typescript
-import { listFiles, isFile, isDirectory } from './utils/file-operations';
-
-async function analyzeProjectStructure() {
-  // Get all TypeScript files
-  const tsFiles = await listFiles('./src', {
-    extension: '.ts',
-    recursive: true,
-    filesOnly: true
-  });
-  
-  // Get all test files
-  const testFiles = await listFiles('./src', {
-    extension: '.test.ts',
-    recursive: true
-  });
-  
-  // Get all directories
-  const dirs = await listFiles('./src', {
-    recursive: true,
-    filesOnly: false
-  });
-  
-  console.log(`Found ${tsFiles.length} TypeScript files`);
-  console.log(`Found ${testFiles.length} test files`);
-  console.log(`Found ${dirs.length} directories`);
-}
-```
-
-### 5. File Metadata and Integrity
-
-```typescript
-import { getMetadata, copyFile } from './utils/file-operations';
-
-async function backupWithVerification() {
-  const original = './important.json';
-  const backup = './important.json.backup';
-  
-  // Get hash before copying
-  const originalMeta = await getMetadata(original, true);
-  console.log(`Original hash: ${originalMeta.hash}`);
-  
-  // Copy with verification
-  await copyFile(original, backup, true);
-  
-  // Verify copy
-  const backupMeta = await getMetadata(backup, true);
-  if (originalMeta.hash === backupMeta.hash) {
-    console.log('Backup verified - files are identical');
-  } else {
-    console.error('Backup verification failed - files differ!');
-  }
-}
-```
-
-### 6. Line-by-Line Processing
-
-```typescript
-import { readLinesSync, appendFile } from './utils/file-operations';
-
-async function processLogFile() {
-  let errorCount = 0;
-  let warningCount = 0;
-  
-  await readLinesSync('./app.log', (line, index) => {
-    if (line.includes('[ERROR]')) {
-      errorCount++;
-      console.log(`Line ${index}: ${line}`);
-    } else if (line.includes('[WARN]')) {
-      warningCount++;
-    }
-  });
-  
-  // Write summary
-  await appendFile('./summary.log', 
-    `Errors: ${errorCount}, Warnings: ${warningCount}\n`);
-}
-```
-
----
-
-## String & Date Formatting
-
-### 1. String Case Conversions
-
-```typescript
-import {
-  capitalize,
-  toCamelCase,
-  toSnakeCase,
-  toKebabCase
-} from './utils/string-formatter';
-
-const text = 'hello world';
-
-console.log(capitalize(text));     // 'Hello world'
-console.log(toCamelCase('hello-world-example')); // 'helloWorldExample'
-console.log(toSnakeCase('helloWorld'));         // 'hello_world'
-console.log(toKebabCase('HelloWorld'));         // 'hello-world'
-
-// Practical: URL slug generation
-const title = 'Hello World Example!';
-const slug = toKebabCase(title.toLowerCase());
-// Result: 'hello-world-example'
-```
-
-### 2. Date Formatting and Manipulation
-
-```typescript
-import {
-  formatDate,
-  addDays,
-  getDuration,
-  getWeekNumber
-} from './utils/date-formatter';
-
-// Example 1: Format dates for display
-const now = new Date();
-console.log(formatDate(now, 'yyyy-MM-dd'));        // '2024-02-15'
-console.log(formatDate(now, 'yyyy-MM-dd HH:mm')); // '2024-02-15 14:30'
-console.log(formatDate(now, 'MMMM d, yyyy'));     // 'February 15, 2024'
-
-// Example 2: Date arithmetic
-const deadline = addDays(now, 7);
-console.log(`Deadline: ${formatDate(deadline, 'yyyy-MM-dd')}`);
-
-// Example 3: Duration calculation
-const start = new Date('2024-02-01');
-const end = new Date('2024-02-15');
-const duration = getDuration(start, end);
-console.log(`Duration: ${duration.days} days, ${duration.hours} hours`);
-
-// Example 4: Week number for reporting
-const weekNum = getWeekNumber(now);
-console.log(`Current week: ${weekNum}`);
-```
-
----
-
-## JSON Processing
-
-### 1. Safe JSON Parsing
-
-```typescript
-import { parseJSON, validateJSON } from './utils/json-formatter';
-
-// Example: API response handling
-async function handleApiResponse(response) {
-  const text = await response.text();
-  
-  // Validate first
-  const isValid = validateJSON(text);
-  if (!isValid) {
-    console.error('Invalid JSON response');
-    return null;
-  }
-  
-  // Safe parse
-  const [data, error] = parseJSON(text);
-  if (error) {
-    console.error('Parse error:', error.message);
-    return null;
-  }
-  
-  return data;
-}
-```
-
-### 2. Flatten/Unflatten for APIs
-
-```typescript
-import { flattenJSON, unflattenJSON } from './utils/json-formatter';
-
-// Flatten for form submission
-const user = {
-  name: 'John',
-  address: {
-    street: '123 Main St',
-    city: 'New York',
-    zip: {
-      code: '10001'
-    }
-  }
-};
-
-const flat = flattenJSON(user);
-// Result:
-// {
-//   'name': 'John',
-//   'address.street': '123 Main St',
-//   'address.city': 'New York',
-//   'address.zip.code': '10001'
-// }
-
-// Send form data...
-
-// Unflatten for storage
-const restored = unflattenJSON(flat);
-// Result: Same as original user object
-```
-
-### 3. JSON Merging
-
-```typescript
-import { mergeJSON } from './utils/json-formatter';
-
-// Merge configuration files
-const baseConfig = {
-  port: 3000,
-  timeout: 30000,
-  features: { auth: true, logging: true }
-};
-
-const envConfig = {
-  port: 8080,
-  features: { cache: true }
-};
-
-const merged = mergeJSON(baseConfig, envConfig);
-// Result:
-// {
-//   port: 8080,  // Overridden
-//   timeout: 30000,  // From base
-//   features: { auth: true, logging: true, cache: true }  // Deep merged
-// }
-```
-
----
-
-## Image Processing
-
-### 1. Image Resizing Workflow
-
-```typescript
-import {
-  resizeImage,
-  getImageDimensions,
-  createLogger
-} from './utils/image-operations';
-
-const log = createLogger('ImageResize');
-
-async function optimizeImage(inputPath, outputPath) {
-  try {
-    // Get original dimensions
-    const dims = await getImageDimensions(inputPath);
-    log.info('Original dimensions', dims);
-    
-    // Resize to fit in 1920x1080
-    const resized = await resizeImage(inputPath, {
-      width: 1920,
-      height: 1080,
-      fit: 'inside'
-    });
-    
-    log.info('Image resized', { path: outputPath });
-    return resized;
-  } catch (error) {
-    log.error('Resize failed', { error: String(error) });
-    throw error;
-  }
-}
-```
-
-### 2. Image Format Conversion
-
-```typescript
-import {
-  convertFormat,
-  detectFormat
-} from './utils/image-operations';
-
-async function convertToWebP(inputPath, outputPath) {
-  // Detect original format
-  const format = detectFormat(inputPath);
-  console.log(`Original format: ${format}`);
-  
-  // Convert to WebP with compression
-  const result = await convertFormat(inputPath, 'webp', {
-    quality: 0.8
-  });
-  
-  // Save result
-  const fs = require('fs').promises;
-  await fs.writeFile(outputPath, result);
-  console.log(`Converted to WebP: ${outputPath}`);
-}
-```
-
-### 3. Batch Image Processing
-
-```typescript
-import {
-  resizeImage,
-  batchProcessFiles
-} from './utils/file-operations';
-
-async function createThumbnails() {
-  let created = 0;
-  
-  const count = await batchProcessFiles(
-    './images',
-    async (imagePath) => {
-      const outputPath = imagePath.replace('.', '_thumb.');
-      await resizeImage(imagePath, outputPath, {
-        width: 200,
-        height: 200,
-        fit: 'cover'
-      });
-      created++;
-    },
-    { extension: '.jpg', recursive: true }
-  );
-  
-  console.log(`Created ${created} thumbnails out of ${count} images`);
-}
-```
-
----
-
-## Git Operations
-
-### 1. Repository Status Check
-
-```typescript
-import {
-  checkIsRepository,
-  getGitStatus,
-  getCurrentBranch,
-  createLogger
-} from './utils/git';
-
-const log = createLogger('Git');
-
-async function checkRepoStatus() {
-  try {
-    if (!await checkIsRepository()) {
-      log.error('Not a git repository');
-      return;
-    }
-    
-    const branch = await getCurrentBranch();
-    const status = await getGitStatus();
-    
-    log.info('Repository status', {
-      branch,
-      modified: status.modified.length,
-      untracked: status.untracked.length,
-      staged: status.staged.length
-    });
-    
-    if (status.modified.length > 0) {
-      log.warn('Uncommitted changes:', status.modified);
-    }
-  } catch (error) {
-    log.error('Failed to check status', { error: String(error) });
-  }
-}
-```
-
-### 2. Commit History Analysis
-
-```typescript
-import { getCommitHistory, formatDate } from './utils/git';
-
-async function analyzeCommits() {
-  const commits = await getCommitHistory(50);
-  
-  // Group by author
-  const byAuthor = {};
-  for (const commit of commits) {
-    if (!byAuthor[commit.author]) {
-      byAuthor[commit.author] = [];
-    }
-    byAuthor[commit.author].push(commit);
-  }
-  
-  // Show statistics
-  for (const [author, commits] of Object.entries(byAuthor)) {
-    console.log(`${author}: ${commits.length} commits`);
-  }
-}
-```
-
----
-
-## Data Transformation Pipelines
-
-### 1. Multi-Step Transformation
-
-```typescript
-import { transform } from './utils/data-transformer';
-
-async function processUserData(users) {
-  const result = await transform(users)
-    .pipe(filter(u => u.status === 'active'))
-    .pipe(map(u => ({
-      ...u,
-      email: u.email.toLowerCase(),
-      joinedYear: new Date(u.joinDate).getFullYear()
-    })))
-    .pipe(sortBy((a, b) => b.joinedYear - a.joinedYear))
-    .pipe(chunk(10))
-    .execute();
-  
-  return result; // Array of arrays, grouped by year
-}
-```
-
-### 2. Parallel Processing
-
-```typescript
-async function processLargeDataset(items) {
-  const result = await transform(items)
-    .pipe(parallel(async (item) => {
-      return await expensiveOperation(item);
-    }, 4)) // Process 4 items in parallel
-    .execute();
-  
-  return result;
-}
-```
-
----
-
-## Integration Patterns
-
-### 1. Complete API Handler
-
-```typescript
-import {
-  createLogger,
-  formatErrorForUser,
-  retryWithBackoff,
-  handlePromise
-} from './utils';
-
-const log = createLogger('API');
-
-app.get('/api/data/:id', async (req, res) => {
-  const requestLog = createScopedLogger(log, `req-${req.id}`, {
-    path: req.path,
-    method: req.method
-  });
-  
-  requestLog.info('Request started');
-  const timer = requestLog.time('total');
-  
-  try {
-    // Fetch with retries
-    const [data, error] = await handlePromise(
-      retryWithBackoff(
-        () => fetchFromDatabase(req.params.id),
-        3,
-        1000
-      )
-    );
-    
-    if (error) {
-      const formatted = formatErrorForUser(error);
-      requestLog.error('Database error', { error: formatted.code });
-      return res.status(500).json({
-        error: formatted.message,
-        code: formatted.code
-      });
-    }
-    
-    requestLog.info('Data retrieved', { size: JSON.stringify(data).length });
-    timer();
-    res.json(data);
-  } catch (error) {
-    const formatted = formatErrorForUser(error);
-    requestLog.error('Unexpected error', { error: formatted.message });
-    timer();
-    res.status(500).json({ error: 'Internal server error' });
-  }
-});
-```
-
-### 2. CLI Command Implementation
-
-```typescript
-import {
-  createLogger,
-  readFile,
-  writeFile,
-  formatErrorForUser
-} from './utils';
-
-async function processCommand(input, output) {
-  const log = createLogger('CLI');
-  
-  try {
-    log.info('Starting process', { input, output });
-    
-    const timer = log.time('process');
-    
-    // Read input
-    const content = await readFile(input);
-    log.debug('File read', { size: content.length });
-    
-    // Process
-    const processed = await processContent(content);
-    log.debug('Content processed', { resultSize: processed.length });
-    
-    // Write output
-    await writeFile(output, processed, { createDirs: true });
-    log.info('Process complete', { output });
-    
-    timer();
-  } catch (error) {
-    const formatted = formatErrorForUser(error);
-    log.error(formatted.message);
-    console.error(`Error: ${formatted.message}`);
-    process.exit(1);
-  }
-}
-```
-
----
-
-## Performance Optimization
-
-### 1. Batch Operations
-
-```typescript
-// BAD: Individual operations
-for (const file of files) {
-  const content = await readFile(file);
-  const processed = processContent(content);
-  await writeFile(file, processed);
-}
-
-// GOOD: Batch processing
-const count = await batchProcessFiles(
-  dir,
-  async (file) => {
-    const content = await readFile(file);
-    const processed = processContent(content);
-    await writeFile(file, processed);
-  }
-);
-```
-
-### 2. Efficient Array Handling
-
-```typescript
-// BAD: Multiple iterations
-const active = data.filter(x => x.isActive);
-const mapped = active.map(x => transform(x));
-const sorted = mapped.sort((a, b) => a.id - b.id);
-
-// GOOD: Single pipeline
-const result = await transform(data)
-  .pipe(filter(x => x.isActive))
-  .pipe(map(x => transform(x)))
-  .pipe(sortBy((a, b) => a.id - b.id))
-  .execute();
-```
-
----
-
-## Dependency Management
-
-### 1. Import Organization
-
-```typescript
-// Organize imports by category
-
-// Node.js modules
-import * as path from 'path';
-import { promises as fs } from 'fs';
-
-// Utilities
-import {
-  readFile,
-  writeFile,
-  listFiles,
-  formatErrorForUser
-} from './utils/file-operations';
-
-import {
-  createLogger,
-  setLogLevel
-} from './utils/logger';
-
-import {
-  groupBy,
-  unique,
-  chunk
-} from './utils/array';
-
-// Application code
-import { processData } from './processor';
-```
-
-### 2. Avoiding Circular Dependencies
-
-```typescript
-// BAD: Direct circular dependency
-// file-a.ts
-import { funcB } from './file-b';
-export const funcA = () => funcB();
-
-// file-b.ts
-import { funcA } from './file-a';
-export const funcB = () => funcA();
-
-// GOOD: Use shared interface
-// types.ts
-export interface Processor {
-  process(data: any): any;
-}
-
-// file-a.ts
-import type { Processor } from './types';
-export class ProcessorA implements Processor {
-  process(data) { /* ... */ }
-}
-
-// file-b.ts
-import type { Processor } from './types';
-export class ProcessorB implements Processor {
-  process(data) { /* ... */ }
-}
-```
-
----
-
-## Debugging Techniques
-
-### 1. Structured Logging for Debugging
-
-```typescript
-const log = createLogger('MyModule');
-setLogLevel('debug'); // Enable debug messages
-
-// Example: Track variable changes
-const value = initialValue;
-log.debug('Initial value', { value });
-
-// Process
-const processed = await process(value);
-log.debug('After processing', { value: processed });
-
-// Conditional debugging
-if (getLogLevel() <= LogLevel.DEBUG) {
-  log.debug('Expensive operation', {
-    ...hugeObject,
-    timestamp: Date.now()
-  });
-}
-```
-
-### 2. Error Context for Debugging
-
-```typescript
-try {
-  const result = await operation();
-} catch (error) {
-  const formatted = formatErrorForUser(error);
-  
-  // Log full context
-  internalLog.error('Operation failed', {
-    operation: 'fetchUserData',
-    input: userId,
-    stack: formatted.technicalDetails,
-    timestamp: new Date().toISOString()
-  });
-  
-  // Show user-friendly message
-  showError(formatted.message);
-}
-```
-
----
-
-## Common Gotchas
-
-### 1. Array Modification
-
-```typescript
-// Gotcha: Modifying original array
-const original = [1, 2, 3];
-const sorted = sortBy(original, (a, b) => b - a);
-
-// safe - sortBy returns new array
-console.log(original); // [1, 2, 3] - unchanged
-console.log(sorted);   // [3, 2, 1] - new array
-
-// But this modifies original:
-const mapped = original.map(x => x * 2);
-original[0] = 999; // Changes affect mapped? No, primitives are safe.
-```
-
-### 2. Async Gotchas
-
-```typescript
-// Gotcha: Forgetting await
-const file = readFile('file.txt'); // Returns Promise!
-const content = file; // This is a Promise, not string
-
-// Correct:
-const content = await readFile('file.txt');
-
-// Gotcha: Promise.all vs sequential
-// Sequential (slow)
-const file1 = await readFile('f1.txt');
-const file2 = await readFile('f2.txt');
-
-// Parallel (fast)
-const [file1, file2] = await Promise.all([
-  readFile('f1.txt'),
-  readFile('f2.txt')
-]);
-```
-
-### 3. Logging Level Gotcha
-
-```typescript
-// Gotcha: Debug log always evaluates expression
-log.debug('User: ' + JSON.stringify(hugeObject)); // String created even if debug disabled!
-
-// Better:
-if (getLogLevel() <= LogLevel.DEBUG) {
-  log.debug('User', hugeObject); // Only if debug is enabled
-}
-
-// Or use lazy evaluation (if supported)
-log.debug(() => `User: ${JSON.stringify(hugeObject)}`);
-```
-
-### 4. File Path Gotcha
-
-```typescript
-// Gotcha: Relative paths from wrong directory
-const content = await readFile('./data.json');
-// Works when run from project root
-// Fails when run from subdirectory!
-
-// Better:
-const content = await readFile(
-  path.resolve(__dirname, '../../data.json')
-);
-// Or
-const content = await readFile(
-  validatePath('./data.json')
-);
-```
-
-### 5. Error Message Gotcha
-
-```typescript
-// Gotcha: Showing sensitive information
-catch (error) {
-  console.error(error.message);
-  // Client sees: "/home/user/app/config/db.ts line 42"
-}
-
-// Correct:
-catch (error) {
-  const safe = sanitizeErrorMessage(error.message);
-  console.error(safe);
-  // Client sees: "Database connection failed"
-}
-```
-
----
-
-## Best Practices Summary
-
-1. **Always handle errors**: Use formatErrorForUser for user-facing errors
-2. **Use appropriate log levels**: Don't log everything at INFO
-3. **Batch file operations**: Process multiple files together
-4. **Validate inputs**: Use type guards and path validators
-5. **Create new arrays**: Functions like sortBy return new arrays
-6. **Use pipelines**: Chain transformations with transform()
-7. **Scope loggers**: Create scoped loggers with context for requests
-8. **Check before deleting**: Verify file exists before operations
-9. **Sanitize errors**: Always sanitize before showing to users
-10. **Test edge cases**: Handle empty arrays, null values, etc.
-
----
-
-**Last Updated**: February 2024  
-**Maintained By**: Indusagi Core Team  
-**License**: MIT
-