@opendata-ai/openchart-engine 6.25.4 → 6.26.0

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;
+}