Data Transformers

Centralized transformation logic for consistent data shaping across API routes.

When to Use This Skill

• Data transformation is scattered across routes

• Need consistent output formats across endpoints

• Want testable, reusable transformation functions

• Building dashboards with aggregated data

Core Concepts

Centralize all transformation logic in one place:

• Aggregators (category totals, counts)

• Rankers (top-N by score)

• Trend calculators (comparing periods)

• Sanitizers (validate and clean data)

┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ Raw Data │────▶│ Transformers │────▶│ API Output │ └─────────────┘ └──────────────┘ └─────────────┘

Implementation

TypeScript

// lib/transformers.ts

// ============================================ // Category Aggregation // ============================================

interface CategoryTotals { [category: string]: number; }

function aggregateCategories( items: Array<{ category: string; count?: number }> ): CategoryTotals { const totals: CategoryTotals = {};

for (const item of items) { const category = item.category?.toUpperCase() || 'OTHER'; totals[category] = (totals[category] || 0) + (item.count ?? 1); }

return totals; }

function categoriesToBreakdown( totals: CategoryTotals, previousTotals?: CategoryTotals ): Array<{ category: string; count: number; percentage: number; trend: string }> { const total = Object.values(totals).reduce((sum, count) => sum + count, 0);

return Object.entries(totals) .map(([category, count]) => { let trend: 'increasing' | 'stable' | 'decreasing' = 'stable';

  if (previousTotals) {
    const prevCount = previousTotals[category] ?? 0;
    const change = count - prevCount;
    if (change > prevCount * 0.1) trend = 'increasing';
    else if (change < -prevCount * 0.1) trend = 'decreasing';
  }

  return {
    category,
    count,
    percentage: total > 0 ? count / total : 0,
    trend,
  };
})
.sort((a, b) => b.count - a.count);

}

// ============================================ // Ranking // ============================================

interface Rankable { score: number; count: number; }

function rankItems<T extends Rankable>( items: T[], limit = 5 ): (T & { rank: number })[] { return items .sort((a, b) => { if (b.score !== a.score) return b.score - a.score; return b.count - a.count; }) .slice(0, limit) .map((item, index) => ({ ...item, rank: index + 1 })); }

// ============================================ // Trend Calculation // ============================================

type SimpleTrend = 'increasing' | 'stable' | 'decreasing';

function calculateTrend(current: number, previous: number): SimpleTrend { if (previous === 0) return 'stable'; const change = (current - previous) / previous;

if (change > 0.1) return 'increasing'; if (change < -0.1) return 'decreasing'; return 'stable'; }

function calculateRollingAverage(values: number[], window = 7): number { if (values.length === 0) return 0; const slice = values.slice(-window); return slice.reduce((sum, v) => sum + v, 0) / slice.length; }

function calculatePercentChange(current: number, previous: number): number { if (previous === 0) return current > 0 ? 100 : 0; return ((current - previous) / previous) * 100; }

// ============================================ // Data Sanitization // ============================================

interface Hotspot { country: string; countryCode: string; lat: number; lon: number; riskScore: number; eventCount: number; }

function sanitizeHotspot(raw: Partial<Hotspot>): Hotspot | null { if (!raw.country || !raw.countryCode) return null;

return { country: raw.country, countryCode: raw.countryCode, lat: raw.lat ?? 0, lon: raw.lon ?? 0, riskScore: Math.min(100, Math.max(0, raw.riskScore ?? 0)), eventCount: Math.max(0, raw.eventCount ?? 0), }; }

function filterValidHotspots(hotspots: Partial<Hotspot>[]): Hotspot[] { return hotspots .map(sanitizeHotspot) .filter((h): h is Hotspot => h !== null); }

// ============================================ // String Utilities // ============================================

function truncate(str: string, maxLen: number): string { if (!str) return ''; return str.length > maxLen ? str.slice(0, maxLen - 3) + '...' : str; }

function slugify(str: string): string { return str .toLowerCase() .replace(/[^\w\s-]/g, '') .replace(/\s+/g, '-') .replace(/-+/g, '-') .trim(); }

// ============================================ // Date Utilities // ============================================

function formatRelativeTime(date: Date): string { const now = new Date(); const diffMs = now.getTime() - date.getTime(); const diffMins = Math.floor(diffMs / 60000); const diffHours = Math.floor(diffMs / 3600000); const diffDays = Math.floor(diffMs / 86400000);

if (diffMins < 1) return 'just now'; if (diffMins < 60) return ${diffMins}m ago; if (diffHours < 24) return ${diffHours}h ago; if (diffDays < 7) return ${diffDays}d ago; return date.toLocaleDateString(); }

export { aggregateCategories, categoriesToBreakdown, rankItems, calculateTrend, calculateRollingAverage, calculatePercentChange, sanitizeHotspot, filterValidHotspots, truncate, slugify, formatRelativeTime, };

Usage Examples

API Route

// api/dashboard/route.ts import { aggregateCategories, rankItems, filterValidHotspots } from '@/lib/transformers';

export async function GET() { const rawData = await fetchFromDatabase();

return Response.json({ categories: aggregateCategories(rawData.predictions), topHotspots: rankItems(filterValidHotspots(rawData.hotspots), 5), trend: calculateTrend(rawData.todayCount, rawData.yesterdayCount), }); }

Dashboard Component

const breakdown = categoriesToBreakdown( currentTotals, previousTotals );

// Returns: // [ // { category: 'MILITARY', count: 150, percentage: 0.45, trend: 'increasing' }, // { category: 'POLITICAL', count: 100, percentage: 0.30, trend: 'stable' }, // ... // ]

Best Practices

• One file for all transformers - easy to find and test

• Pure functions - no side effects, predictable output

• Handle edge cases - empty arrays, missing fields, null values

• Type safety - use TypeScript generics where appropriate

• Export from types package - share across frontend and backend

Common Mistakes

• Scattering transformation logic across routes

• Not handling edge cases (empty arrays, null values)

• Mutating input data instead of returning new objects

• Missing type guards for nullable returns

• Not testing transformers in isolation

Related Patterns

• api-client - Use transformers in API responses

• validation-quarantine - Validate before transforming

• snapshot-aggregation - Aggregate data for dashboards