Views and Analytics

/**
 * Create view with query configuration
 * @param config - View configuration options
 * @returns Promise resolving to View instance
 */
view(config?: ViewConfigUpdate): Promise<View>;

interface ViewConfigUpdate {
  /** Columns to include in view */
  columns?: string[];
  /** Columns to group by (creates aggregated rows) */
  group_by?: string[];
  /** Columns to split by (creates column pivots) */
  split_by?: string[];
  /** Aggregation functions per column */
  aggregates?: Record<string, string>;
  /** Sort specifications */
  sort?: [string, "asc" | "desc"][];
  /** Filter conditions */
  filter?: [string, string, any][];
  /** Computed column expressions */
  expressions?: Record<string, string>;
}

// Basic view (no aggregation)
const basicView = await table.view();

// Aggregated view with grouping
const groupedView = await table.view({
  group_by: ["region", "category"],
  aggregates: {
    sales: "sum",
    count: "count",
    avg_price: "mean",
  },
});

// Filtered and sorted view
const filteredView = await table.view({
  columns: ["name", "age", "salary"],
  filter: [
    ["age", ">", 25],
    ["department", "in", ["Engineering", "Sales"]],
  ],
  sort: [["salary", "desc"]],
});

// Pivot table with expressions
const pivotView = await table.view({
  group_by: ["region"],
  split_by: ["quarter"],
  aggregates: { revenue: "sum" },
  expressions: {
    "growth_rate": "(revenue - lag(revenue)) / lag(revenue) * 100",
  },
});

interface View {
  /** Get view schema (may differ from table schema) */
  schema(): Promise<Schema>;
  
  /** Get schema for expressions only */
  expression_schema(): Promise<Schema>;
  
  /** Get view configuration */
  get_config(): Promise<ViewConfigUpdate>;
  
  /** Get dimensions (row/column counts for table and view) */
  dimensions(): Promise<Dimensions>;
  
  /** Get number of aggregated rows */
  num_rows(): Promise<number>;
  
  /** Get number of aggregated columns */
  num_columns(): Promise<number>;
  
  /** Get column paths after pivots */
  column_paths(window?: ColumnWindow): Promise<string[]>;
}

interface Dimensions {
  num_table_rows: number;
  num_table_columns: number;
  num_view_rows: number;
  num_view_columns: number;
}

interface ColumnWindow {
  start_col?: number;
  end_col?: number;
}

// Check view structure
const schema = await view.schema();
const config = await view.get_config();
const dimensions = await view.dimensions();

console.log("View has", dimensions.num_view_rows, "rows");
console.log("Grouped from", dimensions.num_table_rows, "table rows");

// Get column information for pivot tables
const columnPaths = await view.column_paths();
console.log("Column paths:", columnPaths);
// Example output: ["Sales|Q1", "Sales|Q2", "Count|Q1", "Count|Q2"]

interface View {
  /** Export to JSON array (row-oriented) */
  to_json(window?: ViewWindow): Promise<Record<string, any>[]>;
  
  /** Export to JSON string (row-oriented) */
  to_json_string(window?: ViewWindow): Promise<string>;
  
  /** Export to JSON object (column-oriented) */
  to_columns(window?: ViewWindow): Promise<Record<string, any[]>>;
  
  /** Export to JSON string (column-oriented) */
  to_columns_string(window?: ViewWindow): Promise<string>;
  
  /** Export to Apache Arrow format */
  to_arrow(window?: ViewWindow): Promise<ArrayBuffer>;
  
  /** Export to CSV format */
  to_csv(window?: ViewWindow): Promise<string>;
  
  /** Export to NDJSON format */
  to_ndjson(window?: ViewWindow): Promise<string>;
}

interface ViewWindow {
  start_row?: number;
  end_row?: number;
  start_col?: number;
  end_col?: number;
}

// Export full dataset
const jsonData = await view.to_json();
const csvData = await view.to_csv();
const arrowBuffer = await view.to_arrow();

// Export specific window
const pageData = await view.to_json({
  start_row: 0,
  end_row: 100,
  start_col: 0,
  end_col: 5,
});

// Column-oriented export for visualization
const columnsData = await view.to_columns();
// Result: { name: ["Alice", "Bob"], age: [25, 30], ... }

// Stream-friendly formats
const ndjsonData = await view.to_ndjson();
// Result: {"name":"Alice","age":25}\n{"name":"Bob","age":30}\n

/**
 * Calculate min/max values for a column
 * @param column - Column name to analyze
 * @returns Promise resolving to [min, max] tuple
 */
get_min_max(column: string): Promise<[any, any]>;

// Get value ranges for numeric columns
const [minAge, maxAge] = await view.get_min_max("age");
const [minSalary, maxSalary] = await view.get_min_max("salary");

console.log(`Age range: ${minAge} - ${maxAge}`);
console.log(`Salary range: ${minSalary} - ${maxSalary}`);

// Use for data validation or visualization scaling
const [minDate, maxDate] = await view.get_min_max("created_date");

/**
 * Expand grouped row to show child rows
 * @param row_index - Row index in the view
 * @returns Promise resolving to number of newly visible rows
 */
expand(row_index: number): Promise<number>;

/**
 * Collapse grouped row to hide child rows  
 * @param row_index - Row index in the view
 * @returns Promise resolving to number of hidden rows
 */
collapse(row_index: number): Promise<number>;

/**
 * Set expansion depth for the entire group_by tree
 * @param depth - Maximum expansion depth (0 = all collapsed)
 */
set_depth(depth: number): Promise<void>;

// Create grouped view
const groupedView = await table.view({
  group_by: ["region", "country", "city"],
  aggregates: { sales: "sum" },
});

// Set initial expansion level
await groupedView.set_depth(1); // Show regions only

// Expand specific region to show countries
const newRowCount = await groupedView.expand(0); // Expand first region
console.log(`Added ${newRowCount} country rows`);

// Collapse region to hide countries
await groupedView.collapse(0);

// Show all levels
await groupedView.set_depth(3); // Show regions, countries, and cities

/**
 * Register update callback
 * @param callback - Function called on data updates
 * @param options - Update callback configuration
 * @returns Promise resolving to callback ID
 */
on_update(
  callback: (update: OnUpdateData) => void,
  options?: OnUpdateOptions
): Promise<number>;

/**
 * Remove update callback
 * @param id - Callback ID returned by on_update
 */
remove_update(id: number): Promise<void>;

interface OnUpdateOptions {
  /** Include delta data in updates */
  mode?: "row";
}

interface OnUpdateData {
  /** Port ID that triggered the update */
  port_id: number;
  /** Delta data (only when mode: "row") */
  delta?: ArrayBuffer;
}

// Basic update monitoring
const updateId = await view.on_update((update) => {
  console.log("View updated via port:", update.port_id);
  // Refresh UI or recalculate derived data
  refreshChart();
});

// Monitor with delta data
const deltaId = await view.on_update((update) => {
  if (update.delta) {
    // Process incremental changes
    const deltaRows = parseArrowBuffer(update.delta);
    updateVisualizationIncremental(deltaRows);
  } else {
    // Full refresh needed
    refreshVisualization();
  }
}, { mode: "row" });

// Remove callbacks when no longer needed
await view.remove_update(updateId);
await view.remove_update(deltaId);

/**
 * Delete view and cleanup resources
 */
delete(): Promise<void>;

/**
 * Register callback for view deletion
 * @param callback - Function called when view is deleted
 * @returns Promise resolving to callback ID
 */
on_delete(callback: () => void): Promise<number>;

/**
 * Remove delete callback
 * @param id - Callback ID returned by on_delete
 */
remove_delete(id: number): Promise<void>;

// Monitor view lifecycle
const deleteId = await view.on_delete(() => {
  console.log("View was deleted, cleaning up UI");
  removeChartFromDOM();
});

// Cleanup when done
await view.delete();

// Or remove callback first, then delete
await view.remove_delete(deleteId);
await view.delete();

const pivotView = await table.view({
  group_by: ["region", "product"],
  split_by: ["quarter"],
  aggregates: {
    revenue: "sum",
    units: "count",
    avg_price: "mean",
  },
});

const timeSeriesView = await table.view({
  group_by: ["date"],
  aggregates: { value: "sum" },
  sort: [["date", "asc"]],
  expressions: {
    "moving_avg": "window(mean(value), 7)",
    "percent_change": "(value - lag(value)) / lag(value) * 100",
  },
});

const filteredView = await table.view({
  filter: [
    ["date", ">=", "2023-01-01"],
    ["date", "<", "2024-01-01"],
    ["category", "in", ["A", "B", "C"]],
    ["value", ">", 100],
    ["status", "!=", "cancelled"],
  ],
});

const hierarchicalView = await table.view({
  group_by: ["country", "state", "city"],
  aggregates: {
    population: "sum",
    avg_income: "mean",
    max_temp: "max",
  },
  sort: [
    ["country", "asc"],
    ["population", "desc"],
  ],
});