Events & Commands

GridStorm uses two complementary systems for communication: the EventBus for notifications (something happened) and the CommandBus for mutations (make something happen). Events flow outward to inform you of state changes. Commands flow inward to trigger state changes. Together they enforce a strict unidirectional data flow.

Events vs Commands

Installation

Both systems are part of @gridstorm/core and are created automatically with the grid engine:

pnpm add @gridstorm/core

EventBus API

on(event, listener)

Subscribe to an event. Returns an unsubscribe function:

const unsub = engine.eventBus.on('selection:changed', (event) => {
  console.log('Selected:', event.selectedNodes.length);
  console.log('Source:', event.source);
});

// Later: unsubscribe
unsub();

once(event, listener)

Subscribe to an event for a single firing. The listener is automatically removed after it runs:

engine.eventBus.once('grid:ready', (event) => {
  console.log('Grid is ready, API:', event.api);
});

off(event, listener)

Manually remove a specific listener by reference:

function onSort(event) {
  console.log('Sort changed:', event.sortModel);
}

engine.eventBus.on('column:sort:changed', onSort);

// Later: remove by reference
engine.eventBus.off('column:sort:changed', onSort);

emit(event, payload)

Emit an event to all registered listeners. Primarily used by plugins and the engine internals:

engine.eventBus.emit('row:clicked', {
  node: rowNode,
  event: mouseEvent,
});

Listeners that throw errors are caught and logged without interrupting other listeners.

Via the GridApi

The GridApi wraps the EventBus with addEventListener and removeEventListener:

const unsub = api.addEventListener('filter:changed', (event) => {
  console.log('Filters:', event.filterModel);
});

// The return value is an unsubscribe function
unsub();

Via React Hooks

In React, use the useGridEvent hook which handles the subscription lifecycle automatically:

import { useGridEvent } from '@gridstorm/react';

useGridEvent('cell:clicked', (event) => {
  console.log('Clicked:', event.colId, event.value);
});

Or use event callback props on the <GridStorm> component:

<GridStorm
  columns={columns}
  rowData={data}
  onSortChanged={(e) => console.log('Sort:', e.sortModel)}
  onSelectionChanged={(e) => console.log('Selected:', e.selectedNodes.length)}
  onCellValueChanged={(e) => console.log('Changed:', e.colId, e.newValue)}
/>

CommandBus API

registerHandler(commandType, handler)

Register a synchronous handler for a command type. Multiple handlers per type are supported -- all are invoked when the command is dispatched. Returns an unsubscribe function:

const unregister = engine.commandBus.registerHandler('sort:set', (payload) => {
  console.log('Sort model set to:', payload.sortModel);
});

// Later: remove the handler
unregister();

registerAsyncHandler(commandType, handler)

Register an asynchronous handler. Async handlers are only invoked via dispatchAsync() and run sequentially (each awaited before the next):

engine.commandBus.registerAsyncHandler('ssrm:refresh', async (payload) => {
  const data = await fetch('/api/rows');
  engine.store.setState((prev) => ({ ...prev, /* ... */ }));
});

dispatch(commandType, payload)

Dispatch a command synchronously. Middleware runs first, then all registered handlers:

engine.commandBus.dispatch('sort:set', {
  sortModel: [{ colId: 'name', sort: 'asc' }],
});

If no handler is registered and __GRIDSTORM_DEV__ is enabled, a warning is logged.

dispatchAsync(commandType, payload)

Dispatch a command asynchronously. Middleware runs synchronously first. Then sync handlers run, followed by async handlers in sequence:

await engine.commandBus.dispatchAsync('ssrm:refresh', {});

Command Middleware

Middleware intercepts every command before handlers run. Use it for logging, validation, analytics, or cancellation:

const removeMiddleware = engine.commandBus.use((context) => {
  console.log(`[Command] ${context.commandType}`, context.payload);
});

// Later: remove
removeMiddleware();

Cancelling Commands

Call context.cancel() to prevent a command from reaching its handlers:

engine.commandBus.use((context) => {
  if (context.commandType === 'editing:start') {
    const { colId } = context.payload;
    if (colId === 'id') {
      console.warn('Cannot edit the ID column');
      context.cancel();
    }
  }
});

Middleware Context

The CommandContext object passed to middleware contains:

Middleware functions run in registration order. If any middleware calls cancel(), no subsequent middleware or handlers run.

Complete Event Reference

Lifecycle Events

Data Events

Column Events

Selection Events

The source field indicates what triggered the selection: 'api', 'click', 'checkbox', 'keyboard', or 'selectAll'.

Editing Events

Filter Events

Scroll and Viewport Events

Row Interaction Events

Row Grouping Events

Aggregation Events

Pagination Events

Pivot Events

Context Menu Events

DOM Renderer Events

Row Reorder Events

Clipboard Events

Complete Command Reference

Core Engine Commands

Sorting Plugin Commands

Filtering Plugin Commands

Selection Plugin Commands

Editing Plugin Commands

Pagination Plugin Commands

Column Pinning Commands

Column Resize Commands

Column Reorder Commands

Grouping Plugin Commands

Aggregation Plugin Commands

Context Menu Commands

Clipboard Commands

Row Reorder Commands

Tree Commands

Server-Side Row Model Commands

Export Commands

Master-Detail Commands

Custom Commands

Plugins can register custom commands via declaration merging:

declare module '@gridstorm/core' {
  interface CommandMap {
    'myPlugin:doSomething': { value: string };
  }
}

// Now type-safe to dispatch
engine.commandBus.dispatch('myPlugin:doSomething', { value: 'hello' });

Next Steps

• Store -- How the store reacts to commands and notifies subscribers.
• Plugin System -- Registering command handlers and event listeners in plugins.
• React Guide -- Event callback props and hooks.