# ServerSideConfig

> _Since v0.1.1_

Configuration for the server-side data plugin.

Controls how the grid fetches, caches, and paginates data from a remote source.
The grid requests data in **blocks** (contiguous node ranges) as the user scrolls,
caching them locally to avoid redundant network requests.

#### Example

```typescript
new ServerSidePlugin({
  pageSize: 100,
  maxConcurrentRequests: 2,
})
```

## Properties

| Property | 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. |

### Property Details

#### pageSize

**Default:** `100`

---

#### maxConcurrentRequests

**Default:** `2`

---

#### loadThreshold

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.

The threshold is applied symmetrically: the viewport is expanded by
`loadThreshold` rows in both directions before block coverage is
computed. The `maxConcurrentRequests` cap and per-block dedup still
apply, so a large threshold during fast scrolling will not flood the
server with requests.

A reasonable starting point is `pageSize / 2`. Values larger than
`pageSize` will eagerly request 2+ blocks ahead, which can hurt
perceived performance with slow backends.

**Default:** `0 (fetch only when the visible window enters an unloaded block)`

---

#### dataSource

```typescript
features: {
  serverSide: {
    pageSize: 50,
    dataSource: {
      async getRows(params) {
        const res = await fetch(`/api/data?start=${params.startNode}&end=${params.endNode}`);
        return res.json();
      },
    },
  },
}
```

---

#### sortMode

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.

Use `'local'` when the server cannot sort by every column the user can sort
(e.g. APIs that only support a single sort field, or no sort at all).

**Default:** `'server'`

---

#### filterMode

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.

In `'local'` mode the user only filters the currently loaded subset —
scrolling further loads more blocks which then re-enter the local filter.

**Default:** `'server'`

---