@opendata-ai/openchart-engine 6.0.0 → 6.1.0

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

@@ -0,0 +1,129 @@
+import { describe, expect, it } from 'vitest';
+import { runTimeUnit } from '../timeunit';
+
+describe('runTimeUnit', () => {
+  // Use a specific date: 2024-03-15 14:30:45.123 (Friday)
+  const testDate = new Date(2024, 2, 15, 14, 30, 45, 123);
+  const data = [{ ts: testDate }];
+
+  describe('single time units', () => {
+    it('extracts year', () => {
+      const result = runTimeUnit(data, { timeUnit: 'year', field: 'ts', as: 'y' });
+      expect(result[0].y).toBe(2024);
+    });
+
+    it('extracts quarter', () => {
+      const result = runTimeUnit(data, { timeUnit: 'quarter', field: 'ts', as: 'q' });
+      expect(result[0].q).toBe(1); // March is Q1
+    });
+
+    it('extracts month (0-indexed)', () => {
+      const result = runTimeUnit(data, { timeUnit: 'month', field: 'ts', as: 'm' });
+      expect(result[0].m).toBe(2); // March = 2
+    });
+
+    it('extracts day of week', () => {
+      const result = runTimeUnit(data, { timeUnit: 'day', field: 'ts', as: 'd' });
+      expect(result[0].d).toBe(5); // Friday
+    });
+
+    it('extracts date (day of month)', () => {
+      const result = runTimeUnit(data, { timeUnit: 'date', field: 'ts', as: 'd' });
+      expect(result[0].d).toBe(15);
+    });
+
+    it('extracts hours', () => {
+      const result = runTimeUnit(data, { timeUnit: 'hours', field: 'ts', as: 'h' });
+      expect(result[0].h).toBe(14);
+    });
+
+    it('extracts minutes', () => {
+      const result = runTimeUnit(data, { timeUnit: 'minutes', field: 'ts', as: 'min' });
+      expect(result[0].min).toBe(30);
+    });
+
+    it('extracts seconds', () => {
+      const result = runTimeUnit(data, { timeUnit: 'seconds', field: 'ts', as: 's' });
+      expect(result[0].s).toBe(45);
+    });
+
+    it('extracts milliseconds', () => {
+      const result = runTimeUnit(data, { timeUnit: 'milliseconds', field: 'ts', as: 'ms' });
+      expect(result[0].ms).toBe(123);
+    });
+
+    it('extracts week number', () => {
+      const result = runTimeUnit(data, { timeUnit: 'week', field: 'ts', as: 'w' });
+      expect(typeof result[0].w).toBe('number');
+      expect(result[0].w).toBeGreaterThan(0);
+      expect(result[0].w).toBeLessThanOrEqual(53);
+    });
+
+    it('extracts dayofyear', () => {
+      const result = runTimeUnit(data, { timeUnit: 'dayofyear', field: 'ts', as: 'doy' });
+      expect(typeof result[0].doy).toBe('number');
+      // March 15 is day 75 in a leap year (2024)
+      expect(result[0].doy).toBe(75);
+    });
+  });
+
+  describe('compound time units', () => {
+    it('extracts yearmonth', () => {
+      const result = runTimeUnit(data, { timeUnit: 'yearmonth', field: 'ts', as: 'ym' });
+      expect(result[0].ym).toBe('2024-03');
+    });
+
+    it('extracts yearmonthdate', () => {
+      const result = runTimeUnit(data, { timeUnit: 'yearmonthdate', field: 'ts', as: 'ymd' });
+      expect(result[0].ymd).toBe('2024-03-15');
+    });
+
+    it('extracts monthdate', () => {
+      const result = runTimeUnit(data, { timeUnit: 'monthdate', field: 'ts', as: 'md' });
+      expect(result[0].md).toBe('03-15');
+    });
+
+    it('extracts hoursminutes', () => {
+      const result = runTimeUnit(data, { timeUnit: 'hoursminutes', field: 'ts', as: 'hm' });
+      expect(result[0].hm).toBe('14:30');
+    });
+  });
+
+  describe('date parsing', () => {
+    it('parses ISO string dates', () => {
+      const stringData = [{ ts: '2024-03-15T14:30:00Z' }];
+      const result = runTimeUnit(stringData, { timeUnit: 'year', field: 'ts', as: 'y' });
+      expect(result[0].y).toBe(2024);
+    });
+
+    it('parses numeric timestamps', () => {
+      const numData = [{ ts: testDate.getTime() }];
+      const result = runTimeUnit(numData, { timeUnit: 'year', field: 'ts', as: 'y' });
+      expect(result[0].y).toBe(2024);
+    });
+
+    it('returns null for unparseable dates', () => {
+      const badData = [{ ts: 'not-a-date' }];
+      const result = runTimeUnit(badData, { timeUnit: 'year', field: 'ts', as: 'y' });
+      expect(result[0].y).toBeNull();
+    });
+
+    it('returns null for null values', () => {
+      const nullData = [{ ts: null }];
+      const result = runTimeUnit(nullData, { timeUnit: 'year', field: 'ts', as: 'y' });
+      expect(result[0].y).toBeNull();
+    });
+  });
+
+  it('preserves existing fields', () => {
+    const extraData = [{ ts: testDate, label: 'test' }];
+    const result = runTimeUnit(extraData, { timeUnit: 'year', field: 'ts', as: 'y' });
+    expect(result[0].label).toBe('test');
+    expect(result[0].ts).toBe(testDate);
+  });
+
+  it('handles empty data', () => {
+    const result = runTimeUnit([], { timeUnit: 'year', field: 'ts', as: 'y' });
+    expect(result).toHaveLength(0);
+  });
+});

package/src/transforms/bin.ts

@@ -0,0 +1,87 @@
+/**
+ * Bin transform: discretizes a continuous field into bins.
+ *
+ * Adds bin start (and optionally bin end) fields to each row.
+ */
+
+import type { BinParams, BinTransform, DataRow } from '@opendata-ai/openchart-core';
+
+/**
+ * Compute a nice step size for binning.
+ */
+function computeStep(extent: [number, number], maxbins: number, nice: boolean): number {
+  const span = extent[1] - extent[0];
+  if (span === 0) return 1;
+
+  let step = span / maxbins;
+
+  if (nice) {
+    // Round to a nice step: 1, 2, 5, 10, 20, 50, etc.
+    const magnitude = 10 ** Math.floor(Math.log10(step));
+    const residual = step / magnitude;
+
+    if (residual <= 1.5) {
+      step = magnitude;
+    } else if (residual <= 3.5) {
+      step = 2 * magnitude;
+    } else if (residual <= 7.5) {
+      step = 5 * magnitude;
+    } else {
+      step = 10 * magnitude;
+    }
+  }
+
+  return step;
+}
+
+/**
+ * Apply a bin transform to data rows.
+ *
+ * Adds one or two fields to each row:
+ * - If `as` is a string: adds `as` with the bin start value.
+ * - If `as` is [start, end]: adds both bin start and bin end fields.
+ *
+ * @param data - Input rows.
+ * @param transform - Bin transform definition.
+ * @returns New rows with binned field(s) added.
+ */
+export function runBin(data: DataRow[], transform: BinTransform): DataRow[] {
+  const params: BinParams = transform.bin === true ? {} : transform.bin;
+  const maxbins = params.maxbins ?? 10;
+  const nice = params.nice ?? true;
+  const field = transform.field;
+
+  // Compute extent from data if not provided
+  let extent = params.extent;
+  if (!extent) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (const row of data) {
+      const v = Number(row[field]);
+      if (Number.isFinite(v)) {
+        if (v < min) min = v;
+        if (v > max) max = v;
+      }
+    }
+    extent = [min === Infinity ? 0 : min, max === -Infinity ? 0 : max];
+  }
+
+  const step = params.step ?? computeStep(extent, maxbins, nice);
+  const [startAs, endAs] = Array.isArray(transform.as) ? transform.as : [transform.as, undefined];
+
+  return data.map((row) => {
+    const v = Number(row[field]);
+    const newRow = { ...row };
+
+    if (!Number.isFinite(v)) {
+      newRow[startAs] = null;
+      if (endAs) newRow[endAs] = null;
+    } else {
+      const binStart = Math.floor((v - extent![0]) / step) * step + extent![0];
+      newRow[startAs] = binStart;
+      if (endAs) newRow[endAs] = binStart + step;
+    }
+
+    return newRow;
+  });
+}

package/src/transforms/calculate.ts

@@ -0,0 +1,60 @@
+/**
+ * Calculate transform: adds a computed field to each row.
+ *
+ * Supports arithmetic operations on fields and constant values.
+ */
+
+import type { CalculateExpression, CalculateTransform, DataRow } from '@opendata-ai/openchart-core';
+
+/**
+ * Evaluate a calculate expression against a datum.
+ */
+function evaluateExpression(datum: DataRow, expr: CalculateExpression): number {
+  const fieldValue = Number(datum[expr.field]);
+
+  // Unary operations (single field)
+  switch (expr.op) {
+    case 'abs':
+      return Math.abs(fieldValue);
+    case 'round':
+      return Math.round(fieldValue);
+    case 'floor':
+      return Math.floor(fieldValue);
+    case 'ceil':
+      return Math.ceil(fieldValue);
+    case 'log':
+      return Math.log(fieldValue);
+    case 'sqrt':
+      return Math.sqrt(fieldValue);
+  }
+
+  // Binary operations (field + field2 or field + value)
+  const operand = expr.field2 !== undefined ? Number(datum[expr.field2]) : (expr.value ?? 0);
+
+  switch (expr.op) {
+    case '+':
+      return fieldValue + operand;
+    case '-':
+      return fieldValue - operand;
+    case '*':
+      return fieldValue * operand;
+    case '/':
+      return operand === 0 ? NaN : fieldValue / operand;
+  }
+}
+
+/**
+ * Apply a calculate transform to data rows.
+ *
+ * Adds a new field with the computed value to each row.
+ *
+ * @param data - Input rows.
+ * @param transform - Calculate transform definition.
+ * @returns New rows with the calculated field added.
+ */
+export function runCalculate(data: DataRow[], transform: CalculateTransform): DataRow[] {
+  return data.map((row) => ({
+    ...row,
+    [transform.as]: evaluateExpression(row, transform.calculate),
+  }));
+}

package/src/transforms/conditional.ts

@@ -0,0 +1,46 @@
+/**
+ * Conditional encoding evaluation.
+ *
+ * Resolves conditional value definitions per-datum by evaluating
+ * predicates and returning the first matching condition's value.
+ */
+
+import type { ConditionalValueDef, DataRow } from '@opendata-ai/openchart-core';
+import { evaluatePredicate } from './predicates';
+
+/**
+ * Resolve a conditional value definition for a datum.
+ *
+ * Evaluates conditions in order, returning the value from the first
+ * condition whose test passes. Falls back to the default value if
+ * no condition matches.
+ *
+ * @param datum - The data row to evaluate against.
+ * @param channelDef - The conditional value definition.
+ * @returns The resolved value, or undefined if no condition matches and no default.
+ */
+export function resolveConditionalValue(datum: DataRow, channelDef: ConditionalValueDef): unknown {
+  const conditions = Array.isArray(channelDef.condition)
+    ? channelDef.condition
+    : [channelDef.condition];
+
+  for (const cond of conditions) {
+    if (evaluatePredicate(datum, cond.test)) {
+      // If the condition specifies a field, return the datum's field value
+      if (cond.field !== undefined) {
+        return datum[cond.field];
+      }
+      return cond.value;
+    }
+  }
+
+  // No condition matched, return default
+  return channelDef.value;
+}
+
+/**
+ * Check if a channel definition is a ConditionalValueDef.
+ */
+export function isConditionalValueDef(def: unknown): def is ConditionalValueDef {
+  return def !== null && typeof def === 'object' && 'condition' in (def as Record<string, unknown>);
+}

package/src/transforms/filter.ts

@@ -0,0 +1,17 @@
+/**
+ * Filter transform: removes rows that don't match a predicate.
+ */
+
+import type { DataRow, FilterPredicate } from '@opendata-ai/openchart-core';
+import { evaluatePredicate } from './predicates';
+
+/**
+ * Filter data rows by a predicate.
+ *
+ * @param data - Input rows.
+ * @param predicate - Filter predicate to evaluate per row.
+ * @returns Rows that pass the predicate.
+ */
+export function runFilter(data: DataRow[], predicate: FilterPredicate): DataRow[] {
+  return data.filter((datum) => evaluatePredicate(datum, predicate));
+}

package/src/transforms/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Data transform pipeline.
+ *
+ * Runs an ordered sequence of transforms (filter, bin, calculate, timeUnit)
+ * against a data array. Each transform produces a new array, feeding into
+ * the next transform in sequence.
+ */
+
+import type { DataRow, Transform } from '@opendata-ai/openchart-core';
+import { runBin } from './bin';
+import { runCalculate } from './calculate';
+import { runFilter } from './filter';
+import { runTimeUnit } from './timeunit';
+
+export { runBin } from './bin';
+export { runCalculate } from './calculate';
+export { isConditionalValueDef, resolveConditionalValue } from './conditional';
+export { runFilter } from './filter';
+export { evaluatePredicate } from './predicates';
+export { runTimeUnit } from './timeunit';
+
+/**
+ * Run a sequence of transforms against a data array.
+ *
+ * Each transform is applied in order, producing a new data array
+ * that feeds into the next transform. The original data is not mutated.
+ *
+ * @param data - Input data rows.
+ * @param transforms - Ordered array of transform definitions.
+ * @returns Transformed data rows.
+ */
+export function runTransforms(data: DataRow[], transforms: Transform[]): DataRow[] {
+  let result = data;
+
+  for (const transform of transforms) {
+    if ('filter' in transform) {
+      result = runFilter(result, transform.filter);
+    } else if ('bin' in transform) {
+      result = runBin(result, transform);
+    } else if ('calculate' in transform) {
+      result = runCalculate(result, transform);
+    } else if ('timeUnit' in transform) {
+      result = runTimeUnit(result, transform);
+    }
+  }
+
+  return result;
+}

package/src/transforms/predicates.ts

@@ -0,0 +1,90 @@
+/**
+ * Predicate evaluation for filter transforms and conditional encoding.
+ *
+ * Supports field predicates (equal, lt, gt, range, oneOf, valid)
+ * and logical combinators (and, or, not).
+ */
+
+import type { DataRow, FieldPredicate, FilterPredicate } from '@opendata-ai/openchart-core';
+
+/**
+ * Check if a predicate is a FieldPredicate (has a 'field' property).
+ */
+function isFieldPredicate(pred: FilterPredicate): pred is FieldPredicate {
+  return 'field' in pred;
+}
+
+/**
+ * Evaluate a single field predicate against a datum.
+ */
+function evaluateFieldPredicate(datum: DataRow, pred: FieldPredicate): boolean {
+  const value = datum[pred.field];
+
+  // valid: check for non-null, non-undefined, non-NaN
+  if (pred.valid !== undefined) {
+    const isValid = value !== null && value !== undefined && !Number.isNaN(value);
+    return pred.valid ? isValid : !isValid;
+  }
+
+  // equal
+  if (pred.equal !== undefined) {
+    return value === pred.equal;
+  }
+
+  // Numeric comparisons
+  const numValue = Number(value);
+
+  if (pred.lt !== undefined) {
+    return numValue < pred.lt;
+  }
+  if (pred.lte !== undefined) {
+    return numValue <= pred.lte;
+  }
+  if (pred.gt !== undefined) {
+    return numValue > pred.gt;
+  }
+  if (pred.gte !== undefined) {
+    return numValue >= pred.gte;
+  }
+
+  // range: inclusive [min, max]
+  if (pred.range !== undefined) {
+    const [min, max] = pred.range;
+    return numValue >= min && numValue <= max;
+  }
+
+  // oneOf: value is in the set
+  if (pred.oneOf !== undefined) {
+    return pred.oneOf.includes(value);
+  }
+
+  // No condition specified, default to true
+  return true;
+}
+
+/**
+ * Evaluate a filter predicate (field predicate or logical combinator) against a datum.
+ *
+ * @param datum - The data row to test.
+ * @param predicate - The filter predicate to evaluate.
+ * @returns Whether the datum passes the predicate.
+ */
+export function evaluatePredicate(datum: DataRow, predicate: FilterPredicate): boolean {
+  if (isFieldPredicate(predicate)) {
+    return evaluateFieldPredicate(datum, predicate);
+  }
+
+  if ('and' in predicate) {
+    return predicate.and.every((p) => evaluatePredicate(datum, p));
+  }
+
+  if ('or' in predicate) {
+    return predicate.or.some((p) => evaluatePredicate(datum, p));
+  }
+
+  if ('not' in predicate) {
+    return !evaluatePredicate(datum, predicate.not);
+  }
+
+  return true;
+}

package/src/transforms/timeunit.ts

@@ -0,0 +1,88 @@
+/**
+ * Time unit transform: extracts temporal components from date fields.
+ *
+ * Follows Vega-Lite time unit conventions.
+ */
+
+import type { DataRow, TimeUnit, TimeUnitTransform } from '@opendata-ai/openchart-core';
+
+/**
+ * Extract a time unit value from a Date object.
+ */
+function extractTimeUnit(date: Date, unit: TimeUnit): number | string {
+  switch (unit) {
+    case 'year':
+      return date.getFullYear();
+    case 'quarter':
+      return Math.floor(date.getMonth() / 3) + 1;
+    case 'month':
+      return date.getMonth(); // 0-indexed like JS Date
+    case 'week': {
+      // ISO week number
+      const d = new Date(date.getTime());
+      d.setHours(0, 0, 0, 0);
+      d.setDate(d.getDate() + 3 - ((d.getDay() + 6) % 7));
+      const yearStart = new Date(d.getFullYear(), 0, 1);
+      return Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+    }
+    case 'day':
+      return date.getDay(); // 0 = Sunday
+    case 'dayofyear': {
+      const start = new Date(date.getFullYear(), 0, 0);
+      const diff = date.getTime() - start.getTime();
+      return Math.floor(diff / 86400000);
+    }
+    case 'date':
+      return date.getDate(); // 1-31
+    case 'hours':
+      return date.getHours();
+    case 'minutes':
+      return date.getMinutes();
+    case 'seconds':
+      return date.getSeconds();
+    case 'milliseconds':
+      return date.getMilliseconds();
+    // Compound units
+    case 'yearmonth':
+      return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`;
+    case 'yearmonthdate':
+      return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+    case 'monthdate':
+      return `${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+    case 'hoursminutes':
+      return `${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}`;
+  }
+}
+
+/**
+ * Parse a value into a Date object.
+ * Handles Date objects, ISO strings, and numeric timestamps.
+ */
+function toDate(value: unknown): Date | null {
+  if (value instanceof Date) return value;
+  if (typeof value === 'string' || typeof value === 'number') {
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? null : d;
+  }
+  return null;
+}
+
+/**
+ * Apply a time unit transform to data rows.
+ *
+ * Parses the field as a date and extracts the specified time unit,
+ * storing the result in a new field.
+ *
+ * @param data - Input rows.
+ * @param transform - Time unit transform definition.
+ * @returns New rows with the time unit field added.
+ */
+export function runTimeUnit(data: DataRow[], transform: TimeUnitTransform): DataRow[] {
+  return data.map((row) => {
+    const date = toDate(row[transform.field]);
+    return {
+      ...row,
+      [transform.as]: date ? extractTimeUnit(date, transform.timeUnit) : null,
+    };
+  });
+}