@affino/datagrid-server-adapters

Compatibility: 0.1.7 tracks the current @affino/datagrid-core and server client through the workspace release protocol. Run pnpm run quality:packages:compatibility before publishing.

Opinionated server datasource adapters for Affino DataGrid.

Use this package when you want the simplest path from a backend-owned table to a working grid datasource.

When To Use

• use this package for the primary frontend integration path
• use @affino/datagrid-server-client only when you need low-level transport or change-feed helpers
• keep sandbox-specific adapter code in the sandbox package, not here

Install

pnpm add @affino/datagrid-server-adapters

Minimal Example

import { createAffinoDatasource } from "@affino/datagrid-server-adapters"

type AuctionRow = {
  id: string
  index: number
  title: string
  status: string
}

const datasource = createAffinoDatasource<AuctionRow>({
  baseUrl: "http://localhost:8000",
  tableId: "auctions",
})

createAffinoDatasource() returns a DataGridDataSource<T>-compatible facade with the additional change-feed and history helpers surfaced on the typed return value.

Optional Options

• headers forwards request headers on adapter-owned requests
• historyScope forwards workspace_id, user_id, and session_id into edit, fill, and history bodies
• histogram.ignoreSelfFilter sets the default histogram behavior for requests that should ignore the active column filter
• queryCodec configures the default pull request codec, including columnIdMap, quickFilterModeFallback
• mapQuery receives the normalized backend DTO and can adapt it to a backend-specific request body
• mapPullRequest receives the raw DataGridDataSourcePullRequest and bypasses the package codec entirely

Server Query Codec

Pull requests are normalized into a stable backend DTO by default. The codec is a boundary helper: it converts DataGrid request state into JSON-safe transport data, but it is not a SQL compiler, ORM adapter, permissions layer, or backend execution engine.

import { normalizeDataGridServerQuery } from "@affino/datagrid-server-adapters"

const query = normalizeDataGridServerQuery(request, {
  columnIdMap: {
    updatedAt: "updated_at",
  },
  quickFilterModeFallback: "contains",
})

The normalized shape keeps request concerns explicit:

{
  range: { startRow: 0, endRow: 50 },
  sortModel: [{ colId: "updated_at", sort: "desc" }],
  filterModel: {
    columnFilters: {
      status: { kind: "valueSet", tokens: ["string:active"] },
    },
    quickFilter: {
      query: "platform",
      columns: ["name", "status"],
      mode: "tokens",
    },
  },
  pagination: { pageSize: 50, currentPage: 0 },
}

quickFilter stays inside filterModel. The codec trims the query, dedupes columns, defaults invalid modes to "contains" unless configured otherwise, and never creates a top-level search field.

Pivot is an explicit enterprise backend boundary. The default codec does not serialize request.pivot; backends that implement server pivot projection should use mapPullRequest to forward the raw DataGridDataSourcePullRequest or map request.pivot into their own approved API shape.

Request Mapping

Use the default normalized DTO when your backend accepts the package request shape:

const datasource = createAffinoDatasource<AuctionRow>({
  baseUrl: "http://localhost:8000",
  tableId: "auctions",
  queryCodec: {
    columnIdMap: {
      updatedAt: "updated_at",
    },
  },
})

Use mapQuery when the backend needs small shape changes while still relying on the package codec:

const datasource = createAffinoDatasource<AuctionRow>({
  baseUrl: "http://localhost:8000",
  tableId: "auctions",
  mapQuery: query => ({
    rows: query.range,
    order: query.sortModel ?? [],
    filters: query.filterModel,
  }),
})

Use mapPullRequest only when the backend expects the raw DataGrid protocol or a fully custom body:

const datasource = createAffinoDatasource<AuctionRow>({
  baseUrl: "http://localhost:8000",
  tableId: "auctions",
  mapPullRequest: request => ({
    range: request.range,
    sortModel: request.sortModel,
    filterModel: request.filterModel,
    groupBy: request.groupBy,
    groupExpansion: request.groupExpansion,
    treeData: request.treeData,
    pivot: request.pivot,
    pagination: request.pagination,
  }),
})

Backend Capabilities

The adapter works best when the backend supports:

• histograms for POST /api/{tableId}/histogram
• edits for POST /api/{tableId}/edits
• fill for POST /api/{tableId}/fill-boundary and POST /api/{tableId}/fill/commit
• history for POST /api/history/undo, POST /api/history/redo, and POST /api/history/status

If a backend omits history endpoints, set :server-history="false" on @affino/datagrid-vue-app to prevent the grid from requesting history status or invoking server undo/redo. This setting is independent from the local history prop.

Docs

• Server datasource quick start
• Server datasource UX contract
• Frontend adapter reference
• Server client package

Server-wide selection summaries

The datasource summarizeSelection() capability sends exact selected-range aggregate requests without requiring every row to be loaded. The Affino adapter uses POST /api/{tableId}/selection-summary; the low-level client accepts endpoints.selectionSummary and optional request/response mappers.