sorter-table-vis

API Documentation

Complete API reference for the Sorter Table Visualization library.

Table of Contents

• Constructor
• Data Management
• Selection
• Filtering
• Column Operations
• Grouping & Aggregation
• UI Methods
• Event Callbacks
• Types & Interfaces

Constructor

new sorterTable(data, columnNames, changed, options)

Creates a new sorterTable instance.

Parameters:

• data (Array

• columnNames (Array<string

  Object>): Array of column names or column definition objects.

  • String format: 'columnName'
  • Object format: { column: 'columnName', alias: 'Display Name', unique: false, type: 'string' }
• changed (Function): Callback function called when table state changes. Receives event object.
• options (Object, optional): Configuration options (see Configuration Options)

Returns: sorterTable instance

Example:

const table = new sorterTable(
  [{ id: 1, name: 'Alice' }],
  ['id', 'name'],
  (event) => console.log(event),
  { height: '600px' }
);

Data Management

updateData(newData, options)

Updates the table data. Returns a Promise that resolves when update is complete.

Parameters:

• newData (Array
• options (Object, optional):
  • replaceInitial (boolean, default: false): Replace initial data reference
  • updateTypes (boolean, default: false): Re-infer column types
  • resetState (boolean, default: true): Reset filters, sorting, etc.
  • optimizeMemory (boolean, default: true): Apply memory optimizations

Returns: Promise<boolean>

Example:

await table.updateData(newData, {
  updateTypes: true,
  resetState: false
});

resetTable(useInitialData, options)

Resets the table to initial state or specified state.

Parameters:

• useInitialData (boolean, default: true): Use initial data if true
• options (Object, optional):
  • resetSorting (boolean, default: true)
  • resetFilters (boolean, default: true)
  • resetSelection (boolean, default: true)

Returns: void

Example:

table.resetTable(true, {
  resetSorting: false
});

preprocessData(data, columnNames)

Preprocesses data before use. Called automatically during construction.

Parameters:

• data (Array
• columnNames (Array): Column names/definitions

Returns: Array<Object> - Preprocessed data

Selection

setSelectedData(selectedIndices)

Selects rows by their visible index in the table.

Parameters:

• selectedIndices (Array): Array of row indices (0-based)

Returns: void

Example:

table.setSelectedData([0, 2, 5]); // Select first, third, and sixth visible rows

setSelectedDataByIds(ids, idPropertyName)

Selects rows by their ID property.

Parameters:

• ids (Array): Array of ID values
• idPropertyName (string, default: ‘id’): Property name containing the ID

Returns: void

Example:

table.setSelectedDataByIds([1, 2, 3], 'userId');

getSelection()

Gets currently selected row indices.

Returns: Array<number> - Array of selected row indices

Example:

const selected = table.getSelection();
console.log(`${selected.length} rows selected`);

getSelectionRule()

Gets a human-readable description of the current selection.

Returns: string - Selection rule description

clearSelection()

Clears all row selections.

Returns: void

selectRow(rowElement)

Selects a specific row element (internal use, but can be called).

Parameters:

• rowElement (HTMLElement): Table row element

Returns: void

unselectRow(rowElement)

Unselects a specific row element.

Parameters:

• rowElement (HTMLElement): Table row element

Returns: void

Filtering

filter()

Applies the current selection as a filter. Only selected rows remain visible.

Returns: void

Example:

table.setSelectedData([0, 1, 2]);
table.filter(); // Table now shows only rows 0, 1, 2

applyCustomFilter(filterFunction, options)

Applies a custom filter function to the data.

Parameters:

• filterFunction (Function): Function that receives (rowData) and returns boolean
• options (Object, optional):
  • consecutive (boolean, default: true): Apply to current filtered data or all data
  • customRule (string, optional): Custom rule description

Returns: void

Example:

table.applyCustomFilter((row) => {
  return row.age > 25 && row.salary > 50000;
}, {
  customRule: 'Age > 25 and Salary > 50000'
});

setFilteredDataById(ids, idPropertyName, options)

Filters table to show only rows with specified IDs.

Parameters:

• ids (Array): Array of ID values
• idPropertyName (string, default: ‘id’): Property name containing the ID
• options (Object, optional): Filter options

Returns: void

Column Operations

setColumnType(columnName, type)

Sets the data type for a column. Types affect sorting and visualization.

Parameters:

• columnName (string): Column name
• type (string): Type - ‘string’, ‘number’, ‘date’, ‘boolean’, ‘ordinal’

Returns: void

Example:

table.setColumnType('birthDate', 'date');
table.setColumnType('category', 'ordinal');

getColumnType(data, column)

Gets the inferred type for a column.

Parameters:

• data (Array
• column (string): Column name

Returns: string - Column type

getColumnValues(columnName, options)

Gets all values for a column with caching and sampling support.

Parameters:

• columnName (string): Column name
• options (Object, optional):
  • useSampling (boolean, default: true): Use sampling for large datasets

Returns: Array<{value: any, index: number}> - Array of value objects

Example:

const values = table.getColumnValues('salary', { useSampling: false });
const salaries = values.map(v => v.value);

getColumnValuesArray(columnName)

Gets column values as a simple array (optimized).

Parameters:

• columnName (string): Column name

Returns: Array<any> - Array of values

shiftCol(columnName, direction)

Moves a column left or right.

Parameters:

• columnName (string): Column name
• direction (string): ‘left’ or ‘right’

Returns: void

Example:

table.shiftCol('name', 'left');  // Move name column left
table.shiftCol('age', 'right');  // Move age column right

selectColumn(columnName)

Selects a column (highlights it).

Parameters:

• columnName (string): Column name

Returns: void

Grouping & Aggregation

groupBy(groupColumns, aggregators)

Groups data by specified columns and applies aggregators.

Parameters:

• groupColumns (Array): Array of column names to group by
• aggregators (Object, optional): Object mapping column names to aggregator functions
  • Format: { columnName: { fn: (values, context) => aggregatedValue, label: 'Label' } }

Returns: boolean - Success status

Example:

table.groupBy(['category', 'region'], {
  sales: {
    fn: (values) => values.reduce((a, b) => a + b, 0),
    label: 'Total Sales'
  },
  count: {
    fn: (values) => values.length,
    label: 'Count'
  }
});

Default Aggregators:

• Numbers: Sum
• Strings: First value
• Dates: First value
• Booleans: Any (true if any is true)

ungroup()

Removes grouping and restores original data.

Returns: boolean - Success status

Example:

table.ungroup(); // Restore original ungrouped data

UI Methods

getNode()

Gets the root DOM node of the table. Call this to render the table.

Returns: HTMLElement - Container div element

Example:

const tableNode = table.getNode();
document.getElementById('container').appendChild(tableNode);

setContainerSize(options)

Updates the container dimensions.

Parameters:

• options (Object):

  • width (string

    number, optional): New width

  • height (string

    number, optional): New height

Returns: void

Example:

table.setContainerSize({
  width: '800px',
  height: '600px'
});

rebuildTable()

Rebuilds the table DOM. Call after data changes.

Returns: void

Example:

table.updateData(newData);
table.rebuildTable(); // Usually called automatically

updateHistograms()

Updates histogram visualizations for all columns.

Returns: void

undo()

Undoes the last operation (sort, filter, group, etc.).

Returns: void

Example:

table.filter();
table.undo(); // Restore previous state

Event Callbacks

changed Callback

The callback function passed to the constructor is called whenever the table state changes.

Event Object Structure:

{
  type: string,        // Event type: 'sort', 'filter', 'groupBy', 'ungroup', 'undo', etc.
  dataInd?: Array,     // Current data indices
  columns?: Array,     // Column names
  sort?: Object,       // Current sort state
  // ... type-specific properties
}

Event Types:

Sort Event

{
  type: 'sort',
  column: 'columnName',
  direction: 'up' | 'down',
  dataInd: [0, 1, 2, ...],
  sort: { columnName: { how: 'up'|'down', priority: number } }
}

Filter Event

{
  type: 'filter',
  indeces: [0, 1, 2, ...],
  ids: [{ id: 1 }, { id: 2 }, ...],
  rule: 'Filter description'
}

GroupBy Event

{
  type: 'groupBy',
  groupByColumns: ['category', 'region'],
  aggregatedRows: 50,
  originalRows: 1000
}

Ungroup Event

{
  type: 'ungroup',
  restoredRows: 1000
}

Undo Event

{
  type: 'undo',
  action: 'sort' | 'filter' | 'groupBy' | 'state',
  dataInd: [0, 1, 2, ...],
  columns: ['col1', 'col2', ...],
  sort: { ... }
}

Example:

function onTableChange(event) {
  switch(event.type) {
    case 'sort':
      console.log(`Sorted by ${event.column}`);
      break;
    case 'filter':
      console.log(`Filtered to ${event.indeces.length} rows`);
      break;
    case 'groupBy':
      console.log(`Grouped into ${event.aggregatedRows} groups`);
      break;
  }
}

Types & Interfaces

Column Definition

interface ColumnDefinition {
  column: string;      // Column name (required)
  alias?: string;      // Display name
  unique?: boolean;    // Is column unique
  type?: string;       // Data type: 'string', 'number', 'date', 'boolean', 'ordinal'
}

Aggregator

interface Aggregator {
  fn: (values: Array<any>, context: {
    ordinalOrder?: Array,
    column: string
  }) => any;
  label?: string;      // Display label
}

Cell Renderer Function

type CellRenderer = (value: any, rowData: Object) => HTMLElement | Text;

Parameters:

• value: The cell value
• rowData: The entire row data object

Returns: HTMLElement or Text node

Example:

const renderer = (value, rowData) => {
  const div = document.createElement('div');
  div.textContent = value;
  div.style.color = value > 100 ? 'red' : 'green';
  return div;
};

Configuration Options

interface SorterTableOptions {
  // Container dimensions
  height?: string;                    // Default: '400px'
  width?: string;                     // Default: '100%'
  
  // Rendering
  rowsPerPage?: number;               // Default: 50
  useWindowing?: boolean;             // Default: true
  rowHeight?: number;                 // Default: 30
  bufferRows?: number;                // Default: 10
  
  // Performance
  useWorkers?: boolean;               // Default: true
  workerPoolSize?: number;            // Default: 2
  samplingThreshold?: number;         // Default: 50000
  maxSampleSize?: number;             // Default: 50000
  
  // Binning
  maxOrdinalBins?: number;            // Default: 12
  continuousBinMethod?: 'scott' | 'fd' | 'sturges';  // Default: 'scott'
  dateInterval?: string;              // Default: 'day'
  minBinSize?: number;                // Default: 5
  
  // Custom renderers
  cellRenderers?: Record<string, CellRenderer>;
  
  // UI
  showDefaultControls?: boolean;      // Default: true
  
  // Callbacks
  onNearEnd?: () => void;             // Called when scrolling near end
}

Performance Considerations

Large Datasets (>50k rows)

The library automatically uses sampling for large datasets:

• Histograms use sampled data
• Column value operations use sampling
• Set samplingThreshold and maxSampleSize to control behavior

Memory Management

• Column arrays are cached but cleared on data changes
• Histogram memory is optimized automatically
• Use updateData with optimizeMemory: true for large updates

Web Workers

Web Workers are used for histogram calculations:

• Set useWorkers: false to disable (uses main thread)
• Adjust workerPoolSize based on CPU cores
• Workers require proper path configuration in production

Error Handling

The library includes comprehensive error handling:

• Invalid data is logged with warnings
• Missing columns are handled gracefully
• Renderer errors don’t crash the table
• Check browser console for debug messages

Browser Compatibility

• Requires ES6+ support
• Web Workers for histogram calculations (optional)
• Modern browsers: Chrome, Firefox, Safari, Edge (latest 2 versions)

This site is open source. Improve this page.