@opendata-ai/openchart-engine 6.25.4 → 6.27.0

package/src/transforms/filter.ts

@@ -1,17 +1,122 @@
 /**
  * Filter transform: removes rows that don't match a predicate.
+ *
+ * Supports RelativeTimeRef values on comparison properties (lt, lte, gt, gte, range).
+ * These are resolved against the data extent before filtering.
+ */
+
+import type {
+  DataRow,
+  FieldPredicate,
+  FilterPredicate,
+  RelativeTimeRef,
+} from '@opendata-ai/openchart-core';
+import { evaluatePredicate, isRelativeTimeRef } from './predicates';
+
+/**
+ * Apply a time offset to a Date, returning the resulting timestamp.
+ */
+function applyOffset(anchor: Date, offset: number, unit: RelativeTimeRef['unit']): number {
+  const d = new Date(anchor.getTime());
+  switch (unit) {
+    case 'year':
+      d.setFullYear(d.getFullYear() + offset);
+      break;
+    case 'quarter':
+      d.setMonth(d.getMonth() + offset * 3);
+      break;
+    case 'month':
+      d.setMonth(d.getMonth() + offset);
+      break;
+    case 'week':
+      d.setDate(d.getDate() + offset * 7);
+      break;
+    case 'day':
+      d.setDate(d.getDate() + offset);
+      break;
+  }
+  return d.getTime();
+}
+
+/**
+ * Resolve a single RelativeTimeRef against a data array.
+ * Scans the field for min/max date values, then applies the offset.
+ */
+function resolveRef(data: DataRow[], field: string, ref: RelativeTimeRef): number {
+  let anchorMs = ref.anchor === 'max' ? -Infinity : Infinity;
+
+  for (const row of data) {
+    const val = row[field];
+    if (val == null) continue;
+    const ms = new Date(val as string | number).getTime();
+    if (Number.isNaN(ms)) continue;
+    if (ref.anchor === 'max' && ms > anchorMs) anchorMs = ms;
+    if (ref.anchor === 'min' && ms < anchorMs) anchorMs = ms;
+  }
+
+  if (!Number.isFinite(anchorMs)) return 0;
+
+  return applyOffset(new Date(anchorMs), ref.offset, ref.unit);
+}
+
+/**
+ * Walk a predicate tree and resolve any RelativeTimeRef values to concrete numbers.
+ * Returns a new predicate tree (does not mutate the original).
  */
+function resolveRelativeRefs(data: DataRow[], predicate: FilterPredicate): FilterPredicate {
+  if ('and' in predicate) {
+    return { and: predicate.and.map((p) => resolveRelativeRefs(data, p)) };
+  }
+  if ('or' in predicate) {
+    return { or: predicate.or.map((p) => resolveRelativeRefs(data, p)) };
+  }
+  if ('not' in predicate) {
+    return { not: resolveRelativeRefs(data, predicate.not) };
+  }
+
+  // FieldPredicate: check each comparison property for RelativeTimeRef
+  if ('field' in predicate) {
+    const fp = predicate as FieldPredicate;
+    let needsCopy = false;
+    const resolved: Partial<FieldPredicate> = {};
 
-import type { DataRow, FilterPredicate } from '@opendata-ai/openchart-core';
-import { evaluatePredicate } from './predicates';
+    for (const prop of ['lt', 'lte', 'gt', 'gte'] as const) {
+      if (isRelativeTimeRef(fp[prop])) {
+        resolved[prop] = resolveRef(data, fp.field, fp[prop] as RelativeTimeRef);
+        needsCopy = true;
+      }
+    }
+
+    if (fp.range) {
+      const [lo, hi] = fp.range;
+      const loResolved = isRelativeTimeRef(lo) ? resolveRef(data, fp.field, lo) : lo;
+      const hiResolved = isRelativeTimeRef(hi) ? resolveRef(data, fp.field, hi) : hi;
+      if (isRelativeTimeRef(lo) || isRelativeTimeRef(hi)) {
+        resolved.range = [loResolved as number, hiResolved as number];
+        needsCopy = true;
+      }
+    }
+
+    if (needsCopy) {
+      return { ...fp, ...resolved };
+    }
+  }
+
+  return predicate;
+}
 
 /**
  * Filter data rows by a predicate.
  *
+ * If the predicate contains RelativeTimeRef values, they are resolved
+ * against the data extent first, then the standard evaluatePredicate
+ * logic runs per-row.
+ *
  * @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));
+  const resolved = resolveRelativeRefs(data, predicate);
+  return data.filter((datum) => evaluatePredicate(datum, resolved));
 }

package/src/transforms/index.ts

@@ -13,6 +13,7 @@ import { runCalculate } from './calculate';
 import { runFilter } from './filter';
 import { runFold } from './fold';
 import { runTimeUnit } from './timeunit';
+import { runWindow } from './window';
 
 export { runAggregate } from './aggregate';
 export { runBin } from './bin';
@@ -20,8 +21,9 @@ export { runCalculate } from './calculate';
 export { isConditionalValueDef, resolveConditionalValue } from './conditional';
 export { runFilter } from './filter';
 export { runFold } from './fold';
-export { evaluatePredicate } from './predicates';
+export { evaluatePredicate, isRelativeTimeRef } from './predicates';
 export { runTimeUnit } from './timeunit';
+export { runWindow } from './window';
 
 /**
  * Run a sequence of transforms against a data array.
@@ -49,6 +51,8 @@ export function runTransforms(data: DataRow[], transforms: Transform[]): DataRow
       result = runAggregate(result, transform);
     } else if ('fold' in transform) {
       result = runFold(result, transform);
+    } else if ('window' in transform) {
+      result = runWindow(result, transform);
     }
   }
 

package/src/transforms/predicates.ts

@@ -5,7 +5,12 @@
  * and logical combinators (and, or, not).
  */
 
-import type { DataRow, FieldPredicate, FilterPredicate } from '@opendata-ai/openchart-core';
+import type {
+  DataRow,
+  FieldPredicate,
+  FilterPredicate,
+  RelativeTimeRef,
+} from '@opendata-ai/openchart-core';
 
 /**
  * Check if a predicate is a FieldPredicate (has a 'field' property).
@@ -14,6 +19,27 @@ function isFieldPredicate(pred: FilterPredicate): pred is FieldPredicate {
   return 'field' in pred;
 }
 
+/**
+ * Check if a value is a RelativeTimeRef (has anchor, offset, and unit properties).
+ */
+export function isRelativeTimeRef(value: unknown): value is RelativeTimeRef {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'anchor' in value &&
+    'offset' in value &&
+    'unit' in value
+  );
+}
+
+/**
+ * Coerce a comparison value to a number. RelativeTimeRef objects that weren't
+ * resolved upstream become NaN, which makes all comparisons return false (safe).
+ */
+function toNum(v: number | RelativeTimeRef): number {
+  return typeof v === 'number' ? v : NaN;
+}
+
 /**
  * Evaluate a single field predicate against a datum.
  */
@@ -33,26 +59,30 @@ function evaluateFieldPredicate(datum: DataRow, pred: FieldPredicate): boolean {
     return value == pred.equal;
   }
 
-  // Numeric comparisons
-  const numValue = Number(value);
+  // Numeric comparisons (with date string fallback)
+  let numValue = Number(value);
+  if (Number.isNaN(numValue) && value != null) {
+    const ms = new Date(value as string | number).getTime();
+    if (!Number.isNaN(ms)) numValue = ms;
+  }
 
   if (pred.lt !== undefined) {
-    return numValue < pred.lt;
+    return numValue < toNum(pred.lt);
   }
   if (pred.lte !== undefined) {
-    return numValue <= pred.lte;
+    return numValue <= toNum(pred.lte);
   }
   if (pred.gt !== undefined) {
-    return numValue > pred.gt;
+    return numValue > toNum(pred.gt);
   }
   if (pred.gte !== undefined) {
-    return numValue >= pred.gte;
+    return numValue >= toNum(pred.gte);
   }
 
   // range: inclusive [min, max]
   if (pred.range !== undefined) {
-    const [min, max] = pred.range;
-    return numValue >= min && numValue <= max;
+    const [lo, hi] = pred.range;
+    return numValue >= toNum(lo) && numValue <= toNum(hi);
   }
 
   // oneOf: use loose equality (same rationale as equal above)

package/src/transforms/window.ts

@@ -0,0 +1,185 @@
+/**
+ * Window transform: computes values relative to other rows in sort order
+ * within a partition (lag, lead, diff, pct_change, cumsum, rank, first_value).
+ *
+ * Follows the same grouping pattern as aggregate.ts, but preserves all
+ * input rows and appends computed fields rather than collapsing groups.
+ */
+
+import type { DataRow, WindowTransform } from '@opendata-ai/openchart-core';
+
+/**
+ * Build a composite group key from a row's groupby field values.
+ * Uses null-char delimiter (same convention as aggregate.ts).
+ */
+function groupKey(row: DataRow, groupby: string[]): string {
+  return groupby.map((f) => String(row[f] ?? '')).join('\x00');
+}
+
+/**
+ * Try to parse a value as a date, returning its timestamp if valid.
+ * Only recognizes ISO-8601 strings (must contain '-' or 'T') and numeric timestamps.
+ * Bare numeric strings like "9" or "100" are not treated as dates.
+ */
+function tryParseDate(val: unknown): number {
+  if (val == null) return NaN;
+  if (typeof val === 'number') return new Date(val).getTime();
+  if (typeof val === 'string' && (val.includes('-') || val.includes('T'))) {
+    const ms = new Date(val).getTime();
+    return ms;
+  }
+  return NaN;
+}
+
+/**
+ * Type-aware comparison for sorting:
+ * 1. Try ISO date parsing first
+ * 2. If both are numeric, compare as numbers
+ * 3. Otherwise lexicographic string comparison
+ */
+function compareValues(a: unknown, b: unknown, order: 'ascending' | 'descending'): number {
+  const dir = order === 'descending' ? -1 : 1;
+
+  // Try dates first
+  const dateA = tryParseDate(a);
+  const dateB = tryParseDate(b);
+  if (!Number.isNaN(dateA) && !Number.isNaN(dateB)) {
+    return dir * (dateA - dateB);
+  }
+
+  // Try numeric comparison
+  const numA = Number(a);
+  const numB = Number(b);
+  if (Number.isFinite(numA) && Number.isFinite(numB)) {
+    return dir * (numA - numB);
+  }
+
+  // Fallback to string comparison
+  return dir * String(a ?? '').localeCompare(String(b ?? ''));
+}
+
+/**
+ * Apply a window transform to data rows.
+ *
+ * Groups rows by the groupby fields, sorts within each group, computes
+ * window operations, then returns all rows in their original input order
+ * with computed fields appended.
+ *
+ * @param data - Input rows.
+ * @param transform - Window transform definition.
+ * @returns Rows with computed window fields appended.
+ */
+export function runWindow(data: DataRow[], transform: WindowTransform): DataRow[] {
+  if (data.length === 0) return [];
+
+  const { window: windowDefs, sort, groupby = [] } = transform;
+
+  // Track original indices so we can restore input order
+  const indexed = data.map((row, i) => ({ row, originalIndex: i }));
+
+  // Group rows by groupby fields
+  const groups = new Map<string, { row: DataRow; originalIndex: number }[]>();
+  for (const entry of indexed) {
+    const key = groupby.length > 0 ? groupKey(entry.row, groupby) : '';
+    const existing = groups.get(key);
+    if (existing) {
+      existing.push(entry);
+    } else {
+      groups.set(key, [entry]);
+    }
+  }
+
+  // Build result array indexed by original position
+  const result: DataRow[] = new Array(data.length);
+
+  for (const groupEntries of groups.values()) {
+    // Sort the group entries by the sort fields
+    const sorted = [...groupEntries].sort((a, b) => {
+      for (const s of sort) {
+        const cmp = compareValues(a.row[s.field], b.row[s.field], s.order ?? 'ascending');
+        if (cmp !== 0) return cmp;
+      }
+      return 0;
+    });
+
+    // Compute window operations for each row in sorted order
+    for (let i = 0; i < sorted.length; i++) {
+      const entry = sorted[i];
+      const outRow: DataRow = { ...entry.row };
+
+      for (const def of windowDefs) {
+        const offset = def.offset ?? 1;
+        let computed: unknown = null;
+
+        switch (def.op) {
+          case 'lag': {
+            const lagIdx = i - offset;
+            computed = lagIdx >= 0 ? (sorted[lagIdx].row[def.field] ?? null) : null;
+            break;
+          }
+          case 'lead': {
+            const leadIdx = i + offset;
+            computed = leadIdx < sorted.length ? (sorted[leadIdx].row[def.field] ?? null) : null;
+            break;
+          }
+          case 'diff': {
+            const lagIdx = i - offset;
+            if (lagIdx >= 0) {
+              const current = Number(entry.row[def.field]);
+              const lagged = Number(sorted[lagIdx].row[def.field]);
+              computed =
+                Number.isFinite(current) && Number.isFinite(lagged) ? current - lagged : null;
+            }
+            break;
+          }
+          case 'pct_change': {
+            const lagIdx = i - offset;
+            if (lagIdx >= 0) {
+              const current = Number(entry.row[def.field]);
+              const lagged = Number(sorted[lagIdx].row[def.field]);
+              if (Number.isFinite(current) && Number.isFinite(lagged) && lagged !== 0) {
+                computed = (current - lagged) / lagged;
+              }
+            }
+            break;
+          }
+          case 'cumsum': {
+            const val = Number(entry.row[def.field]);
+            const addend = Number.isFinite(val) ? val : 0;
+            if (i === 0) {
+              computed = addend;
+            } else {
+              const prev = Number(result[sorted[i - 1].originalIndex]?.[def.as] ?? 0);
+              computed = prev + addend;
+            }
+            break;
+          }
+          case 'rank': {
+            let rank = i + 1;
+            for (let j = 0; j < i; j++) {
+              const isTie = sort.every(
+                (s) => String(sorted[j].row[s.field]) === String(entry.row[s.field]),
+              );
+              if (isTie) {
+                rank = result[sorted[j].originalIndex]?.[def.as] as number;
+                break;
+              }
+            }
+            computed = rank;
+            break;
+          }
+          case 'first_value': {
+            computed = sorted[0].row[def.field] ?? null;
+            break;
+          }
+        }
+
+        outRow[def.as] = computed;
+      }
+
+      result[entry.originalIndex] = outRow;
+    }
+  }
+
+  return result;
+}