# ServerSidePlugin

> _Since v0.1.1_

Server-Side Data Plugin for tbw-grid

Central data orchestrator for the grid. Manages fetch, cache, and row-model for
server-side data loading. Structural plugins (Tree, GroupingRows) can claim data
via events; the core grid uses it as flat rows when unclaimed.

## Installation

```ts
import { ServerSidePlugin } from '@toolbox-web/grid/plugins/server-side';
```

## DataSource Interface

```ts
interface ServerSideDataSource {
  getRows(params: GetRowsParams): Promise<GetRowsResult>;
  getChildRows?(params: GetChildRowsParams): Promise<GetChildRowsResult>;
}
```

## [Configuration Options](/grid/plugins/server-side/interfaces/serversideconfig.md)

| Option | Type | Description |
| ------ | ---- | ----------- |
| `pageSize?` | <code>number</code> | Number of nodes requested per `getRows()` call. The same value is surfaced on `params.pageSize` inside the callback, so backends that expect an explicit page-size query parameter can forward it directly. Larger values reduce request count at the cost of longer per-request latency. |
| `cacheBlockSize?` | <code>number</code> |  |
| `maxConcurrentRequests?` | <code>number</code> | Maximum number of concurrent `getRows()` requests. Limits how many blocks can be fetched simultaneously during fast scrolling. Set to 1 for strict sequential loading; higher values improve perceived performance. |
| `loadThreshold?` | <code>number</code> | Prefetch slack in **node count** (rows). When `> 0`, blocks are loaded as soon as the user is within `loadThreshold` rows of an unloaded block, rather than only when the visible window enters it. This reduces the number of placeholder rows the user sees during gentle scrolling at the cost of slightly more eager fetching. |
| `dataSource?` | <code><a href="/grid/plugins/server-side/interfaces/serversidedatasource/">ServerSideDataSource</a>&lt;unknown&gt;</code> | Data source for server-side loading. When provided, the plugin auto-initializes on attach — no need to call `setDataSource()`. |
| `sortMode?` | <code>server &#124; local</code> | How sort changes affect the cache. - `'server'` (default): purge cache and refetch via `getRows({ sortModel })`.   Use when the backend supports the requested sort shape natively. - `'local'`: keep the loaded blocks; sort the loaded rows in-place via   the active sort plugin (MultiSort or core sort). `sortModel` is **not**   sent on subsequent block fetches. Placeholder rows (`__loading: true`)   are pinned to the end regardless of direction. |
| `filterMode?` | <code>server &#124; local</code> | How filter changes affect the cache. - `'server'` (default): purge cache and refetch via `getRows({ filterModel })`. - `'local'`: keep the loaded blocks; filter only the rows currently in cache   via FilteringPlugin's normal pipeline. `filterModel` is **not** sent on   subsequent block fetches. |

## Example

### Basic Server-Side Loading

```ts
import '@toolbox-web/grid';
import '@toolbox-web/grid/features/server-side';

grid.gridConfig = {
  columns: [...],
  features: {
    serverSide: {
      pageSize: 50,
      dataSource: {
        async getRows(params) {
          const response = await fetch(
            `/api/data?start=${params.startNode}&end=${params.endNode}`
          );
          const data = await response.json();
          return { rows: data.rows, totalNodeCount: data.total };
        },
      },
    },
  },
};
```

## See Also

- [`ServerSideConfig`](/grid/plugins/server-side/interfaces/serversideconfig.md) for configuration options
- [`ServerSideDataSource`](/grid/plugins/server-side/interfaces/serversidedatasource.md) for data source interface

> **Extends** [BaseGridPlugin](/docs/grid-api-plugin-development-classes-basegridplugin--docs)
>
> Inherited methods like `attach()`, `detach()`, `afterRender()`, etc. are documented in the base class.

## Methods

### setDataSource()

Set the data source for server-side loading.

```ts
setDataSource(dataSource: ServerSideDataSource): void
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `dataSource` | <code><a href="/grid/plugins/server-side/interfaces/serversidedatasource/">ServerSideDataSource</a></code> | Data source implementing the getRows method (and optionally getChildRows) |

***

### refresh()

Refresh all data from the server.
Purges cache and refetches from block 0.

```ts
refresh(): void
```

***

### purgeCache()

Clear all cached data without refreshing.

```ts
purgeCache(): void
```

***

### getTotalNodeCount()

Get the total node count from the server.

```ts
getTotalNodeCount(): number
```

***

### getTotalRowCount()

> ⚠️ **Deprecated**: Use getTotalNodeCount instead. Will be removed in a future version.

```ts
getTotalRowCount(): number
```

***

### isNodeLoaded()

Check if a specific node is loaded in the cache.

```ts
isNodeLoaded(nodeIndex: number): boolean
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `nodeIndex` | <code>number</code> | Node index to check |

***

### isRowLoaded()

> ⚠️ **Deprecated**: Use isNodeLoaded instead. Will be removed in a future version.

```ts
isRowLoaded(rowIndex: number): boolean
```

#### Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `rowIndex` | <code>number</code> |  |

***

### getLoadedBlockCount()

Get the number of loaded cache blocks.

```ts
getLoadedBlockCount(): number
```

***