DataSource

DataSource<T> is the interface for running a command against a real data source.

interface DataSource {
  execute(req: T): Promise<Record<string, any>[]>;
  addRef(): void;
  release(): Promise<void>;
}

The command type is T.

• for SQL-based sources, T is usually string
• for API-based sources, T can be a valid request object that api accepts
• for custom sources, T can be any command shape your source accepts

Example:

Run a SQL query against the data source

await sqlDataSource.execute("SELECT city, revenue FROM sales");

Send a request to an API endpoint with given payload

await apiDataSource.execute({
  endpoint: "/query",
  method: "GET",
  body: { groupBy: ["city"] },
});

A single DataSource instance can be shared by multiple consumers. Use addRef() and release() to manage that lifecycle. See the API Reference for details.

Responsibilities

DataSource only does three things:

• accepts a command
• runs it against the source
• returns rows

It does not decide which command to run. The caller decides that and passes the command to execute(...).

What "downstream" means here

Downstream code means code that uses the data source, usually a data model. That code prepares the command. DataSource executes it.

Example flow:

const sql = buildQueryFromState(gridState);
const rows = await dataSource.execute(sql);

Built-in implementations

This package provides SQL-based implementations:

DataSource<T>
└── SqlDataSource
    ├── DuckDBDataSource
    └── DuckDBWasmDataSource

That means the built-in sources expect SQL strings.

Implementing your own DataSource

The library includes built-in API-based and browser WASM SQL-based data sources for common cases. If you need something else, implement DataSource<T> yourself or extend an existing data source.

Example: an in-memory JavaScript data source.

import { DataSource } from "grid";

interface DataSourceConfig {
  maxRows: number;
}

const defaultConfig: DataSourceConfig = {
  maxRows: 10 ** 6,
};

type InMemoryCommand = {
  filter?: (row: Record<string, any>) => boolean;
  // more operators
};

class InMemoryJsDataSource implements DataSource<InMemoryCommand> {
  private rows: Record<string, any>[];
  private refCount = 1;
  private config: DataSourceConfig;

  private constructor(rows: Record<string, any>[], config: DataSourceConfig) {
    this.rows = rows;
    this.config = config;
  }

  static create(rows: Record<string, any>[]): DataSource<InMemoryCommand> {
    return new InMemoryJsDataSource(rows, defaultConfig);
  }

  addRef(): void {
    this.refCount++;
  }

  async execute(command: InMemoryCommand): Promise<Record<string, any>[]> {
    const rows = command.filter ? this.rows.filter(command.filter) : this.rows;
    return rows.slice(0, this.config.maxRows);
  }

  async release(): Promise<void> {
    this.refCount--;
    if (this.refCount <= 0) {
      this.rows = [];
    }
  }
}

Usage

DataSource<T> is an interface. You do not create it directly. Instead, create an instance of a concrete data source class and pass that instance to a data model.

Typical flow:

1. User creates a data source instance.

const ds = InMemoryJsDataSource.create(rows);

2. User passes the DataSource instance and schema to a data model.

const model = new InMemoryJsDataModel(schema, ds);

3. The grid calls the data model functions which in turn calls dataSource.execute(...).
4. The data source returns rows.

API Reference

Generic interface for query execution with ref-counted lifecycle.

Multiple consumers (e.g. pivot grid and flat table) can share a single DataSource instance. Use addRef / release to manage ownership.