@opendata-ai/openchart-engine 6.12.0 → 6.15.0

package/src/transforms/__tests__/aggregate.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'vitest';
+import { runAggregate } from '../aggregate';
+
+describe('runAggregate', () => {
+  const data = [
+    { region: 'North', product: 'A', revenue: 100, qty: 10 },
+    { region: 'North', product: 'B', revenue: 200, qty: 20 },
+    { region: 'South', product: 'A', revenue: 150, qty: 15 },
+    { region: 'South', product: 'B', revenue: 250, qty: 25 },
+    { region: 'South', product: 'A', revenue: 50, qty: 5 },
+  ];
+
+  it('computes sum aggregate grouped by one field', () => {
+    const result = runAggregate(data, {
+      aggregate: [{ op: 'sum', field: 'revenue', as: 'total_revenue' }],
+      groupby: ['region'],
+    });
+
+    expect(result).toHaveLength(2);
+    const north = result.find((r) => r.region === 'North');
+    const south = result.find((r) => r.region === 'South');
+    expect(north?.total_revenue).toBe(300);
+    expect(south?.total_revenue).toBe(450);
+  });
+
+  it('computes mean aggregate', () => {
+    const result = runAggregate(data, {
+      aggregate: [{ op: 'mean', field: 'revenue', as: 'avg_revenue' }],
+      groupby: ['region'],
+    });
+
+    const north = result.find((r) => r.region === 'North');
+    const south = result.find((r) => r.region === 'South');
+    expect(north?.avg_revenue).toBe(150); // (100+200)/2
+    expect(south?.avg_revenue).toBe(150); // (150+250+50)/3
+  });
+
+  it('computes count aggregate', () => {
+    const result = runAggregate(data, {
+      aggregate: [{ op: 'count', field: 'revenue', as: 'num_rows' }],
+      groupby: ['region'],
+    });
+
+    const north = result.find((r) => r.region === 'North');
+    const south = result.find((r) => r.region === 'South');
+    expect(north?.num_rows).toBe(2);
+    expect(south?.num_rows).toBe(3);
+  });
+
+  it('computes median aggregate', () => {
+    const result = runAggregate(data, {
+      aggregate: [{ op: 'median', field: 'revenue', as: 'med_revenue' }],
+      groupby: ['region'],
+    });
+
+    const north = result.find((r) => r.region === 'North');
+    const south = result.find((r) => r.region === 'South');
+    expect(north?.med_revenue).toBe(150); // median of [100, 200]
+    expect(south?.med_revenue).toBe(150); // median of [50, 150, 250]
+  });
+
+  it('computes min and max aggregates', () => {
+    const result = runAggregate(data, {
+      aggregate: [
+        { op: 'min', field: 'revenue', as: 'min_rev' },
+        { op: 'max', field: 'revenue', as: 'max_rev' },
+      ],
+      groupby: ['region'],
+    });
+
+    const south = result.find((r) => r.region === 'South');
+    expect(south?.min_rev).toBe(50);
+    expect(south?.max_rev).toBe(250);
+  });
+
+  it('supports multiple groupby fields', () => {
+    const result = runAggregate(data, {
+      aggregate: [{ op: 'sum', field: 'revenue', as: 'total' }],
+      groupby: ['region', 'product'],
+    });
+
+    expect(result).toHaveLength(4);
+    const southA = result.find((r) => r.region === 'South' && r.product === 'A');
+    expect(southA?.total).toBe(200); // 150 + 50
+  });
+
+  it('supports multiple aggregate ops in one transform', () => {
+    const result = runAggregate(data, {
+      aggregate: [
+        { op: 'sum', field: 'revenue', as: 'total_rev' },
+        { op: 'mean', field: 'qty', as: 'avg_qty' },
+      ],
+      groupby: ['region'],
+    });
+
+    const north = result.find((r) => r.region === 'North');
+    expect(north?.total_rev).toBe(300);
+    expect(north?.avg_qty).toBe(15); // (10+20)/2
+  });
+
+  it('computes variance aggregate', () => {
+    const result = runAggregate(data, {
+      aggregate: [{ op: 'variance', field: 'revenue', as: 'var_rev' }],
+      groupby: ['region'],
+    });
+
+    const south = result.find((r) => r.region === 'South');
+    // South values: [150, 250, 50], mean=150, variance = ((0)^2 + (100)^2 + (-100)^2) / 3
+    expect(south?.var_rev).toBeCloseTo(6666.667, 0);
+  });
+
+  it('computes stdev aggregate', () => {
+    const result = runAggregate(data, {
+      aggregate: [{ op: 'stdev', field: 'revenue', as: 'sd_rev' }],
+      groupby: ['region'],
+    });
+
+    const south = result.find((r) => r.region === 'South');
+    // sqrt(6666.667) ≈ 81.65
+    expect(south?.sd_rev).toBeCloseTo(81.65, 1);
+  });
+
+  it('computes distinct aggregate (counts unique raw values)', () => {
+    const result = runAggregate(data, {
+      aggregate: [{ op: 'distinct', field: 'product', as: 'n_products' }],
+      groupby: ['region'],
+    });
+
+    const north = result.find((r) => r.region === 'North');
+    const south = result.find((r) => r.region === 'South');
+    expect(north?.n_products).toBe(2); // A, B
+    expect(south?.n_products).toBe(2); // A, B (A appears twice but distinct=2)
+  });
+
+  it('computes q1 and q3 aggregates', () => {
+    const result = runAggregate(data, {
+      aggregate: [
+        { op: 'q1', field: 'revenue', as: 'q1_rev' },
+        { op: 'q3', field: 'revenue', as: 'q3_rev' },
+      ],
+      groupby: ['region'],
+    });
+
+    const south = result.find((r) => r.region === 'South');
+    // South values sorted: [50, 150, 250]
+    // q1: index = (3-1)*0.25 = 0.5 -> 50 + 0.5*(150-50) = 100
+    // q3: index = (3-1)*0.75 = 1.5 -> 150 + 0.5*(250-150) = 200
+    expect(south?.q1_rev).toBe(100);
+    expect(south?.q3_rev).toBe(200);
+  });
+
+  it('handles empty data', () => {
+    const result = runAggregate([], {
+      aggregate: [{ op: 'sum', field: 'revenue', as: 'total' }],
+      groupby: ['region'],
+    });
+    expect(result).toHaveLength(0);
+  });
+});

package/src/transforms/__tests__/fold.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import { runFold } from '../fold';
+
+describe('runFold', () => {
+  const data = [
+    { country: 'US', gold: 10, silver: 20, bronze: 30 },
+    { country: 'UK', gold: 5, silver: 15, bronze: 25 },
+  ];
+
+  it('folds two columns with default key/value names', () => {
+    const result = runFold(data, {
+      fold: ['gold', 'silver'],
+    });
+
+    expect(result).toHaveLength(4); // 2 rows x 2 fold fields
+    expect(result[0]).toEqual({ country: 'US', bronze: 30, key: 'gold', value: 10 });
+    expect(result[1]).toEqual({ country: 'US', bronze: 30, key: 'silver', value: 20 });
+    expect(result[2]).toEqual({ country: 'UK', bronze: 25, key: 'gold', value: 5 });
+    expect(result[3]).toEqual({ country: 'UK', bronze: 25, key: 'silver', value: 15 });
+  });
+
+  it('folds three columns', () => {
+    const result = runFold(data, {
+      fold: ['gold', 'silver', 'bronze'],
+    });
+
+    expect(result).toHaveLength(6); // 2 rows x 3 fold fields
+    // First row's fold outputs
+    expect(result[0].key).toBe('gold');
+    expect(result[0].value).toBe(10);
+    expect(result[1].key).toBe('silver');
+    expect(result[1].value).toBe(20);
+    expect(result[2].key).toBe('bronze');
+    expect(result[2].value).toBe(30);
+  });
+
+  it('uses custom as names', () => {
+    const result = runFold(data, {
+      fold: ['gold', 'silver'],
+      as: ['medal', 'count'],
+    });
+
+    expect(result[0].medal).toBe('gold');
+    expect(result[0].count).toBe(10);
+    expect(result[1].medal).toBe('silver');
+    expect(result[1].count).toBe(20);
+    // Default key/value shouldn't be present
+    expect(result[0].key).toBeUndefined();
+    expect(result[0].value).toBeUndefined();
+  });
+
+  it('preserves non-fold fields', () => {
+    const result = runFold(data, {
+      fold: ['gold'],
+    });
+
+    // country and bronze are non-fold fields
+    expect(result[0].country).toBe('US');
+    expect(result[0].bronze).toBe(30);
+    // gold should not be a direct field (it's now key/value)
+    expect(result[0].gold).toBeUndefined();
+  });
+
+  it('handles undefined fold field values', () => {
+    const sparse = [{ name: 'test', a: 1 }]; // no 'b' field
+    const result = runFold(sparse, {
+      fold: ['a', 'b'],
+    });
+
+    expect(result).toHaveLength(2);
+    expect(result[0].value).toBe(1);
+    expect(result[1].value).toBeUndefined();
+  });
+
+  it('handles empty data', () => {
+    const result = runFold([], { fold: ['gold', 'silver'] });
+    expect(result).toHaveLength(0);
+  });
+});

package/src/transforms/aggregate.ts

@@ -0,0 +1,130 @@
+/**
+ * Aggregate transform: groups rows and computes summary statistics.
+ *
+ * Follows Vega-Lite aggregate transform conventions.
+ * Groups input data by the specified fields, then applies aggregate
+ * operations (sum, mean, count, etc.) to produce one row per group.
+ */
+
+import type { AggregateOp, AggregateTransform, DataRow } from '@opendata-ai/openchart-core';
+
+/**
+ * Compute a single aggregate operation over an array of numeric values.
+ */
+function computeAggregate(op: AggregateOp, values: number[]): number {
+  if (values.length === 0) return 0;
+
+  switch (op) {
+    case 'count':
+      return values.length;
+    case 'sum':
+      return values.reduce((a, b) => a + b, 0);
+    case 'mean': {
+      const sum = values.reduce((a, b) => a + b, 0);
+      return sum / values.length;
+    }
+    case 'median': {
+      const sorted = [...values].sort((a, b) => a - b);
+      const mid = Math.floor(sorted.length / 2);
+      return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+    }
+    case 'min':
+      return Math.min(...values);
+    case 'max':
+      return Math.max(...values);
+    case 'variance': {
+      if (values.length < 2) return 0;
+      const mean = values.reduce((a, b) => a + b, 0) / values.length;
+      return values.reduce((a, v) => a + (v - mean) ** 2, 0) / values.length;
+    }
+    case 'stdev': {
+      if (values.length < 2) return 0;
+      const m = values.reduce((a, b) => a + b, 0) / values.length;
+      return Math.sqrt(values.reduce((a, v) => a + (v - m) ** 2, 0) / values.length);
+    }
+    case 'q1': {
+      const s = [...values].sort((a, b) => a - b);
+      const i = (s.length - 1) * 0.25;
+      const lo = Math.floor(i);
+      const frac = i - lo;
+      return s[lo] + frac * ((s[lo + 1] ?? s[lo]) - s[lo]);
+    }
+    case 'q3': {
+      const s = [...values].sort((a, b) => a - b);
+      const i = (s.length - 1) * 0.75;
+      const lo = Math.floor(i);
+      const frac = i - lo;
+      return s[lo] + frac * ((s[lo + 1] ?? s[lo]) - s[lo]);
+    }
+    default:
+      return 0;
+  }
+}
+
+/**
+ * Build a composite group key from a row's groupby field values.
+ */
+function groupKey(row: DataRow, groupby: string[]): string {
+  return groupby.map((f) => String(row[f] ?? '')).join('\x00');
+}
+
+/**
+ * Apply an aggregate transform to data rows.
+ *
+ * Groups rows by the groupby fields, then computes each aggregate
+ * operation within each group. Returns one row per group containing
+ * the groupby field values plus computed aggregate fields.
+ *
+ * @param data - Input rows.
+ * @param transform - Aggregate transform definition.
+ * @returns Aggregated rows (one per group).
+ */
+export function runAggregate(data: DataRow[], transform: AggregateTransform): DataRow[] {
+  const { aggregate, groupby } = transform;
+
+  // Group rows by the groupby fields
+  const groups = new Map<string, DataRow[]>();
+  for (const row of data) {
+    const key = groupKey(row, groupby);
+    const existing = groups.get(key);
+    if (existing) {
+      existing.push(row);
+    } else {
+      groups.set(key, [row]);
+    }
+  }
+
+  // Compute aggregates for each group
+  const result: DataRow[] = [];
+  for (const rows of groups.values()) {
+    // Start with groupby field values from the first row in the group
+    const outRow: DataRow = {};
+    for (const field of groupby) {
+      outRow[field] = rows[0][field];
+    }
+
+    // Compute each aggregate operation
+    for (const agg of aggregate) {
+      // distinct counts unique raw values (not just numeric)
+      if (agg.op === 'distinct') {
+        outRow[agg.as] = new Set(rows.map((r) => r[agg.field])).size;
+        continue;
+      }
+
+      const values = rows
+        .map((r) => {
+          // For count, the field value doesn't matter, just count rows
+          if (agg.op === 'count') return 1;
+          const v = Number(r[agg.field]);
+          return Number.isFinite(v) ? v : NaN;
+        })
+        .filter((v) => !Number.isNaN(v));
+
+      outRow[agg.as] = computeAggregate(agg.op, values);
+    }
+
+    result.push(outRow);
+  }
+
+  return result;
+}

package/src/transforms/fold.ts

@@ -0,0 +1,49 @@
+/**
+ * Fold transform: unpivots wide-format data into long format.
+ *
+ * Follows Vega-Lite fold transform conventions.
+ * For each input row, creates N new rows (one per fold field),
+ * copying all non-fold fields and adding key/value columns.
+ */
+
+import type { DataRow, FoldTransform } from '@opendata-ai/openchart-core';
+
+/**
+ * Apply a fold transform to data rows.
+ *
+ * For each input row, creates one output row per fold field. Each output
+ * row contains all fields from the original row (except the fold fields),
+ * plus a key field (the fold field name) and a value field (the fold field value).
+ *
+ * @param data - Input rows.
+ * @param transform - Fold transform definition.
+ * @returns Folded rows (N rows per input row, where N = fold fields count).
+ */
+export function runFold(data: DataRow[], transform: FoldTransform): DataRow[] {
+  const { fold } = transform;
+  const [keyAs, valueAs] = transform.as ?? ['key', 'value'];
+  const foldSet = new Set(fold);
+
+  const result: DataRow[] = [];
+
+  for (const row of data) {
+    // Copy all non-fold fields
+    const base: DataRow = {};
+    for (const [k, v] of Object.entries(row)) {
+      if (!foldSet.has(k)) {
+        base[k] = v;
+      }
+    }
+
+    // Create one row per fold field
+    for (const field of fold) {
+      result.push({
+        ...base,
+        [keyAs]: field,
+        [valueAs]: row[field],
+      });
+    }
+  }
+
+  return result;
+}

package/src/transforms/index.ts

@@ -7,15 +7,19 @@
  */
 
 import type { DataRow, Transform } from '@opendata-ai/openchart-core';
+import { runAggregate } from './aggregate';
 import { runBin } from './bin';
 import { runCalculate } from './calculate';
 import { runFilter } from './filter';
+import { runFold } from './fold';
 import { runTimeUnit } from './timeunit';
 
+export { runAggregate } from './aggregate';
 export { runBin } from './bin';
 export { runCalculate } from './calculate';
 export { isConditionalValueDef, resolveConditionalValue } from './conditional';
 export { runFilter } from './filter';
+export { runFold } from './fold';
 export { evaluatePredicate } from './predicates';
 export { runTimeUnit } from './timeunit';
 
@@ -41,6 +45,10 @@ export function runTransforms(data: DataRow[], transforms: Transform[]): DataRow
       result = runCalculate(result, transform);
     } else if ('timeUnit' in transform) {
       result = runTimeUnit(result, transform);
+    } else if ('aggregate' in transform) {
+      result = runAggregate(result, transform);
+    } else if ('fold' in transform) {
+      result = runFold(result, transform);
     }
   }