Table Operations

/**
 * Create table from data or schema
 * @param data - Input data or schema definition
 * @param options - Table configuration options
 * @returns Promise resolving to Table instance
 */
table(data: TableInitData, options?: TableInitOptions): Promise<Table>;

type TableInitData = string | ArrayBuffer | Record<string, unknown[]> | Record<string, unknown>[];

interface TableInitOptions {
  /** Maximum number of rows (enables circular buffer) */
  limit?: number;
  /** Column name to use as index for updates */
  index?: string;
  /** Table name for identification */
  name?: string;
  /** Explicit data format override */
  format?: "json" | "columns" | "csv" | "arrow";
}

// CSV string input
const csvTable = await client.table("x,y\n1,2\n3,4");

// JSON row-oriented data
const jsonTable = await client.table([
  { name: "Alice", age: 25, active: true },
  { name: "Bob", age: 30, active: false },
]);

// JSON column-oriented data  
const columnsTable = await client.table({
  name: ["Alice", "Bob"],
  age: [25, 30],
  active: [true, false],
});

// Apache Arrow binary data
const arrowBuffer = await fetch("data.arrow").then(r => r.arrayBuffer());
const arrowTable = await client.table(arrowBuffer);

// With configuration options
const indexedTable = await client.table(data, {
  index: "id",
  limit: 10000,
  name: "user_data",
});

// Schema-only table (empty with defined structure)
const schemaTable = await client.table({
  name: "string",
  age: "integer", 
  salary: "float",
  active: "boolean",
  created: "datetime",
});

interface Table {
  /** Get table schema (column names → types) */
  schema(): Promise<Schema>;
  
  /** Get column names in natural order */
  columns(): Promise<string[]>;
  
  /** Get number of rows */
  size(): Promise<number>;
  
  /** Get index column name */
  get_index(): Promise<string | null>;
  
  /** Get table name */
  get_name(): Promise<string>;
  
  /** Get row limit */
  get_limit(): Promise<number | null>;
  
  /** Get associated client instance */
  get_client(): Promise<Client>;
}

type Schema = Record<string, "boolean" | "date" | "datetime" | "float" | "integer" | "string">;

// Get schema information
const schema = await table.schema();
console.log(schema); // { name: "string", age: "integer", active: "boolean" }

// Get table dimensions
const rowCount = await table.size();
const columns = await table.columns();
console.log(`Table has ${rowCount} rows and ${columns.length} columns`);

// Check table configuration
const indexCol = await table.get_index();
const limit = await table.get_limit();
if (indexCol) {
  console.log(`Table is indexed on column: ${indexCol}`);
}

/**
 * Add or update rows in the table
 * @param data - New data to insert/update
 * @param options - Update configuration
 * @returns Promise that resolves when update completes
 */
update(data: TableInitData, options?: UpdateOptions): Promise<void>;

interface UpdateOptions {
  /** Data format override */
  format?: "json" | "columns" | "csv" | "arrow";
  /** Port ID for update tracking */
  port_id?: number;
}

// Add new rows
await table.update([
  { name: "Charlie", age: 35, active: true },
  { name: "Diana", age: 28, active: false },
]);

// Partial update with index (requires table to have index column)
await indexedTable.update([
  { id: 1, active: false }, // Only updates 'active' column for id=1
  { id: 2, age: 31 },       // Only updates 'age' column for id=2
]);

// Update with CSV data
await table.update("name,age\nEve,29\nFrank,42");

// Update with specific format
const arrowUpdate = new Uint8Array([/* Arrow data */]);
await table.update(arrowUpdate, { format: "arrow" });

// Update with port tracking
await table.update(newData, { port_id: 42 });

/**
 * Remove rows by index values
 * @param indices - Index column values of rows to remove
 * @param options - Remove operation options
 */
remove(indices: any[], options?: UpdateOptions): Promise<void>;

/** Remove all rows, preserve schema and structure */
clear(): Promise<void>;

// Remove specific rows by index values (requires indexed table)
await indexedTable.remove([1, 3, 7]);

// Clear all data but keep schema
await table.clear();

// Remove with format specification
await table.remove(["alice", "bob"], { format: "json" });

/**
 * Replace all table data
 * @param data - New data to replace existing data
 * @param options - Replace operation options
 */
replace(data: TableInitData, options?: UpdateOptions): Promise<void>;

// Replace all data with new dataset
await table.replace([
  { name: "New User 1", age: 25, active: true },
  { name: "New User 2", age: 30, active: false },
]);

// Replace with CSV data
await table.replace("name,age,active\nReplaced,25,true");

// Maintain existing views and callbacks
const view = await table.view(); // View remains valid after replace
await table.replace(newData);
const updatedData = await view.to_json(); // Shows new data

/**
 * Open existing hosted table by name
 * @param name - Table name to open
 * @returns Promise resolving to Table instance
 */
open_table(name: string): Promise<Table>;

/**
 * Get names of all hosted tables
 * @returns Promise resolving to array of table names
 */
get_hosted_table_names(): Promise<string[]>;

// List available tables
const tableNames = await client.get_hosted_table_names();
console.log("Available tables:", tableNames);

// Open existing table by name
const existingTable = await client.open_table("user_data");

// Work with shared tables across clients
const sharedTable = await client.open_table("shared_metrics");
await sharedTable.update(newMetrics);

/**
 * Create unique channel ID for update tracking
 * @returns Promise resolving to port ID number
 */
make_port(): Promise<number>;

// Create port for tracking updates
const portId = await table.make_port();

// Use port ID in updates
await table.update(newData, { port_id: portId });

// Views can listen for updates on specific ports
const view = await table.view();
view.on_update((update) => {
  if (update.port_id === portId) {
    console.log("Update from our port:", update);
  }
});

/**
 * Delete table and cleanup resources
 * @param options - Deletion configuration
 */
delete(options?: DeleteOptions): Promise<void>;

interface DeleteOptions {
  /** Delete lazily when no views reference the table */
  lazy?: boolean;
}

// Immediate deletion (requires no active views)
await table.delete();

// Lazy deletion (waits until no views reference table)
await table.delete({ lazy: true });

/**
 * Register callback for table deletion
 * @param callback - Function called when table 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 table deletion
const deleteId = await table.on_delete(() => {
  console.log("Table was deleted");
});

// Remove callback when no longer needed
await table.remove_delete(deleteId);

/**
 * Validate column expressions
 * @param expressions - Expression definitions to validate
 * @returns Promise resolving to validation results
 */
validate_expressions(expressions: Record<string, string>): Promise<any>;

// Validate expressions before creating view
const expressions = {
  "age_group": "if(age < 30, 'young', 'mature')",
  "total_score": "score1 + score2 + score3",
};

const validation = await table.validate_expressions(expressions);
// Use validation result to determine if expressions are valid
const view = await table.view({ expressions });