@svgrid/enterprise 3.0.1 → 3.0.3

package/dist/server/server-selection.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Selection across rows that were never loaded.
+ *
+ * A grid that keeps a list of selected ids is right until the rows it has
+ * seen are a window onto a million on a server. Then "select all" has to mean
+ * a million, the header checkbox has to say so, and a bulk edit has to reach
+ * rows that never came down the wire. None of that fits a list of ids. It
+ * fits a RULE: "everything, except these" - which is what this model stores.
+ *
+ * Two shapes, chosen by `groupSelects`:
+ *
+ * - `self`: one flat rule. `{ selectAll, toggled }` - toggled ids are the
+ *   exceptions to `selectAll`, whatever level they sit on. A group row is a
+ *   row like any other.
+ * - `descendants`: a tree of rules. Ticking a group selects everything under
+ *   it, and an exception inside that group is recorded under that group, so
+ *   the state reads like the tree it describes:
+ *   `{ selectAllChildren: true, toggled: { EMEA: { selectAllChildren: false, toggled: { DE: { selectAllChildren: true } } } } }`
+ *   means "everything, except EMEA, except DE within it".
+ *
+ * The shapes are plain data (`getState()` / `setState()`), so a selection
+ * survives a page reload or travels to a bulk-edit endpoint as "apply to
+ * these rules". Headless and framework-free; the row model wires it to the
+ * grid's `rowSelectionModel` seam and re-renders on `onChange`.
+ */
+/** How ticking a group row behaves: itself, or everything beneath it. */
+export type ServerSelectionGroupMode = 'self' | 'descendants' | 'filteredDescendants';
+/** The flat rule, for `groupSelects: 'self'`. */
+export type ServerSelectionState = {
+    selectAll: boolean;
+    /** Exceptions to `selectAll`: selected ids when it is false, deselected ones when true. */
+    toggled: string[];
+};
+/** One node of the hierarchical rule, for `groupSelects: 'descendants'`. */
+export type ServerGroupSelectionNode = {
+    /** Whether everything under this node is selected, before exceptions. */
+    selectAllChildren: boolean;
+    /** Exceptions, keyed by child id (a group key or a leaf id) under this node. */
+    toggled: Record<string, ServerGroupSelectionNode>;
+    /**
+     * True when this node is a group. A flipped group is an exception of
+     * unknown size (its rows were never counted here); a flipped leaf is
+     * exactly one row. Absent on the root and on leaves.
+     */
+    group?: boolean;
+};
+/** What `createServerSelectionModel` takes: the group mode and a change callback. */
+export type ServerSelectionModelOptions = {
+    /**
+     * How ticking a group row behaves. `self` selects that one row;
+     * `descendants` selects everything beneath it. `filteredDescendants` is
+     * `descendants` under a filter, which on a server is the same rule - the
+     * server applies the filter - so it is accepted as an alias.
+     */
+    groupSelects?: ServerSelectionGroupMode;
+    /** Called after any change. The row model re-renders from here. */
+    onChange?: () => void;
+    /**
+     * How many leaves sit under a group, by its route, or `null` when that is
+     * not known. `selectedCount` needs it once a rule flips a whole group
+     * (a plan ticked under an unticked root): without it the count of such a
+     * rule is unknown. The row model answers from the group row's `count`
+     * aggregate.
+     */
+    leafCount?: (route: ReadonlyArray<string>) => number | null;
+};
+/** A selection kept as a rule - "everything, except these" - flat or per group, that the row model exposes to the grid. */
+export type ServerSelectionModel = {
+    readonly groupSelects: ServerSelectionGroupMode;
+    /** Whether the row `id` at `route` is selected. Leaves and groups alike. */
+    isSelected(route: ReadonlyArray<string>, id: string): boolean;
+    /**
+     * Set one row's selection. Under `descendants` a group takes its subtree
+     * along, and `isGroup` says which kind of row this is - the model cannot
+     * tell, and the difference decides whether a count is still exact.
+     */
+    toggle(route: ReadonlyArray<string>, id: string, next: boolean, isGroup?: boolean): void;
+    /** The header checkbox: select or clear everything. */
+    setAll(next: boolean): void;
+    clear(): void;
+    /** `all`, `none`, or `some` - what the header checkbox should draw. */
+    headerState(): 'none' | 'some' | 'all';
+    /**
+     * How many rows are selected, given the total. Exact for the flat rule.
+     * Under `descendants` it is exact only while no group is an exception (a
+     * group's size is not known here); then it is `null`, and a UI should say
+     * "some" rather than invent a number.
+     */
+    selectedCount(rowCount: number | null): number | null;
+    /** True when the rule is "everything" with no exceptions - a bulk edit can go by filter alone. */
+    isSelectAllWithoutExceptions(): boolean;
+    getState(): ServerSelectionState | ServerGroupSelectionNode;
+    setState(state: ServerSelectionState | ServerGroupSelectionNode): void;
+};
+/**
+ * Build a rule-based selection model. `createServerRowModel` makes one when
+ * its `selection` option is set; it is exported for a model of your own.
+ */
+export declare function createServerSelectionModel(options?: ServerSelectionModelOptions): ServerSelectionModel;

package/dist/server/server-selection.js

@@ -0,0 +1,215 @@
+/**
+ * Selection across rows that were never loaded.
+ *
+ * A grid that keeps a list of selected ids is right until the rows it has
+ * seen are a window onto a million on a server. Then "select all" has to mean
+ * a million, the header checkbox has to say so, and a bulk edit has to reach
+ * rows that never came down the wire. None of that fits a list of ids. It
+ * fits a RULE: "everything, except these" - which is what this model stores.
+ *
+ * Two shapes, chosen by `groupSelects`:
+ *
+ * - `self`: one flat rule. `{ selectAll, toggled }` - toggled ids are the
+ *   exceptions to `selectAll`, whatever level they sit on. A group row is a
+ *   row like any other.
+ * - `descendants`: a tree of rules. Ticking a group selects everything under
+ *   it, and an exception inside that group is recorded under that group, so
+ *   the state reads like the tree it describes:
+ *   `{ selectAllChildren: true, toggled: { EMEA: { selectAllChildren: false, toggled: { DE: { selectAllChildren: true } } } } }`
+ *   means "everything, except EMEA, except DE within it".
+ *
+ * The shapes are plain data (`getState()` / `setState()`), so a selection
+ * survives a page reload or travels to a bulk-edit endpoint as "apply to
+ * these rules". Headless and framework-free; the row model wires it to the
+ * grid's `rowSelectionModel` seam and re-renders on `onChange`.
+ */
+/**
+ * Build a rule-based selection model. `createServerRowModel` makes one when
+ * its `selection` option is set; it is exported for a model of your own.
+ */
+export function createServerSelectionModel(options = {}) {
+    const groupSelects = options.groupSelects ?? 'self';
+    const hierarchical = groupSelects !== 'self';
+    const notify = () => options.onChange?.();
+    // ------------------------------------------------------------- flat
+    let selectAll = false;
+    const toggled = new Set();
+    let root = { selectAllChildren: false, toggled: new Map(), group: true };
+    /** Walk the rule tree along `route`, returning the deepest node reached and the state it implies. */
+    function resolve(route) {
+        let node = root;
+        let state = root.selectAllChildren;
+        for (const key of route) {
+            const next = node.toggled.get(key);
+            if (!next)
+                return { node, state, exact: false };
+            node = next;
+            state = next.selectAllChildren;
+        }
+        return { node, state, exact: true };
+    }
+    /** Walk-or-create the rule tree along `route`, so an exception can be recorded beneath it. */
+    function ensurePath(route) {
+        let node = root;
+        for (const key of route) {
+            let next = node.toggled.get(key);
+            if (!next) {
+                // A group we descend into without an explicit rule inherits its
+                // parent's state, and records it so the exception below has a base.
+                next = { selectAllChildren: node.selectAllChildren, toggled: new Map(), group: true };
+                node.toggled.set(key, next);
+            }
+            node = next;
+        }
+        return node;
+    }
+    /** Drop nodes that no longer differ from their parent, so state stays minimal. */
+    function prune(node) {
+        for (const [key, child] of [...node.toggled]) {
+            prune(child);
+            if (child.toggled.size === 0 && child.selectAllChildren === node.selectAllChildren) {
+                node.toggled.delete(key);
+            }
+        }
+    }
+    const toPlain = (node) => ({
+        selectAllChildren: node.selectAllChildren,
+        toggled: Object.fromEntries([...node.toggled].map(([k, v]) => [k, toPlain(v)])),
+        ...(node.group ? { group: true } : {}),
+    });
+    const fromPlain = (plain, group = true) => ({
+        selectAllChildren: !!plain.selectAllChildren,
+        toggled: new Map(Object.entries(plain.toggled ?? {}).map(([k, v]) => [k, fromPlain(v, !!v.group)])),
+        group,
+    });
+    /**
+     * The number of rows the exceptions under `node` amount to, or null when
+     * one of them is a flipped GROUP - its size was never counted here. A
+     * group whose own state matches its parent is a pass-through; only what
+     * sits beneath it counts.
+     */
+    /**
+     * Leaves selected under `node`, whose own subtree holds `size` leaves
+     * (`null` when unknown). A selected node is its size minus the exceptions
+     * among its toggled children; an unselected one is the sum of what its
+     * toggled children select. A flipped group needs its size, which comes
+     * from `leafCount`; without it the answer is unknown.
+     */
+    function selectedUnder(node, route, size) {
+        if (node.selectAllChildren) {
+            if (size == null)
+                return null;
+            let minus = 0;
+            for (const [key, child] of node.toggled) {
+                if (child.group) {
+                    const childRoute = [...route, key];
+                    const childSize = options.leafCount?.(childRoute) ?? null;
+                    const selected = selectedUnder(child, childRoute, childSize);
+                    if (childSize == null || selected == null)
+                        return null;
+                    minus += childSize - selected;
+                }
+                else if (!child.selectAllChildren) {
+                    minus += 1;
+                }
+            }
+            return Math.max(0, size - minus);
+        }
+        let n = 0;
+        for (const [key, child] of node.toggled) {
+            if (child.group) {
+                const childRoute = [...route, key];
+                const selected = selectedUnder(child, childRoute, options.leafCount?.(childRoute) ?? null);
+                if (selected == null)
+                    return null;
+                n += selected;
+            }
+            else if (child.selectAllChildren) {
+                n += 1;
+            }
+        }
+        return n;
+    }
+    return {
+        groupSelects,
+        isSelected(route, id) {
+            if (!hierarchical)
+                return selectAll !== toggled.has(id);
+            const { node, state } = resolve(route);
+            const own = node.toggled.get(id);
+            return own ? own.selectAllChildren : state;
+        },
+        toggle(route, id, next, isGroup = false) {
+            if (!hierarchical) {
+                // The row differs from the rule when `next` disagrees with selectAll.
+                if (next !== selectAll)
+                    toggled.add(id);
+                else
+                    toggled.delete(id);
+                notify();
+                return;
+            }
+            const parent = ensurePath(route);
+            // A toggled row - group or leaf - becomes a node with no exceptions of
+            // its own: ticking a group throws away whatever was recorded beneath it.
+            if (next === parent.selectAllChildren)
+                parent.toggled.delete(id);
+            else
+                parent.toggled.set(id, { selectAllChildren: next, toggled: new Map(), group: isGroup });
+            prune(root);
+            notify();
+        },
+        setAll(next) {
+            if (!hierarchical) {
+                selectAll = next;
+                toggled.clear();
+            }
+            else {
+                root = { selectAllChildren: next, toggled: new Map(), group: true };
+            }
+            notify();
+        },
+        clear() {
+            this.setAll(false);
+        },
+        headerState() {
+            if (!hierarchical) {
+                if (selectAll)
+                    return toggled.size === 0 ? 'all' : 'some';
+                return toggled.size === 0 ? 'none' : 'some';
+            }
+            if (root.selectAllChildren)
+                return root.toggled.size === 0 ? 'all' : 'some';
+            return root.toggled.size === 0 ? 'none' : 'some';
+        },
+        selectedCount(rowCount) {
+            if (!hierarchical) {
+                if (!selectAll)
+                    return toggled.size;
+                return rowCount == null ? null : Math.max(0, rowCount - toggled.size);
+            }
+            return selectedUnder(root, [], rowCount);
+        },
+        isSelectAllWithoutExceptions() {
+            return hierarchical ? root.selectAllChildren && root.toggled.size === 0 : selectAll && toggled.size === 0;
+        },
+        getState() {
+            if (!hierarchical)
+                return { selectAll, toggled: [...toggled] };
+            return toPlain(root);
+        },
+        setState(state) {
+            if (!hierarchical) {
+                const flat = state;
+                selectAll = !!flat.selectAll;
+                toggled.clear();
+                for (const id of flat.toggled ?? [])
+                    toggled.add(id);
+            }
+            else {
+                root = fromPlain(state);
+            }
+            notify();
+        },
+    };
+}

package/dist/server/svgrid-adapter.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Adapters between the `ServerDataSource` contract and the callback-style
+ * datasource shape other server-side row models use: `getRows(params)` with
+ * `params.request` describing the block and `params.success` / `params.fail`
+ * answering it. A backend written for that shape keeps working behind
+ * `createServerRowModel` through `adaptCallbackDatasource`, so a migration is
+ * one line; `toCallbackDatasource` goes the other way, for a bench that runs
+ * two grids over one backend.
+ *
+ * The request fields map one for one:
+ *
+ * | Callback request              | ServerRequest                          |
+ * |-------------------------------|----------------------------------------|
+ * | `startRow` / `endRow`         | the same                               |
+ * | `rowGroupCols[].id`           | `groupBy`                              |
+ * | `groupKeys`                   | `groupKeys`                            |
+ * | `valueCols[].{id,aggFunc}`    | `aggregations[].{col,fn}`              |
+ * | `pivotCols[].id`, `pivotMode` | `pivotBy`, `pivotMode`                 |
+ * | `sortModel[].{colId,sort}`    | `sortModel[].{id,desc}`                |
+ * | `filterModel[col].{type,filter,filterTo}` | `filterModel.columns[col].{operator,value,valueTo}` |
+ *
+ * and the answer: `success({ rowData, rowCount, pivotResultFields })` becomes
+ * `{ rows, rowCount, pivotResultFields }` (a `rowCount` of `-1` or absent
+ * stays unknown), `fail()` rejects.
+ *
+ * A backend that keeps parsing the callback-style request JSON needs no
+ * datasource object at all: `getRows(request)` posts
+ * `toCallbackRequest(request)` and reads the answer as usual.
+ *
+ * The selection rule has a counterpart there too, `{ selectAll,
+ * toggledNodes }` flat and `{ nodeId, selectAllChildren, toggledNodes }`
+ * per group; `toCallbackSelectionState` / `fromCallbackSelectionState` map
+ * it for a saved selection or a bulk endpoint written against that shape.
+ */
+import type { ServerDataSource, ServerFilterModel, ServerRequest } from '@svgrid/grid';
+import type { ServerGroupSelectionNode, ServerSelectionState } from './server-selection.js';
+/** The request a callback-style datasource receives; the subset the adapter reads. */
+export type CallbackServerRequest = {
+    startRow?: number;
+    endRow?: number;
+    rowGroupCols: Array<{
+        id: string;
+        displayName?: string;
+        field?: string;
+        aggFunc?: string | null;
+    }>;
+    groupKeys: string[];
+    valueCols: Array<{
+        id: string;
+        displayName?: string;
+        field?: string;
+        aggFunc?: string | null;
+    }>;
+    pivotCols: Array<{
+        id: string;
+        displayName?: string;
+        field?: string;
+    }>;
+    pivotMode: boolean;
+    sortModel: Array<{
+        colId: string;
+        sort: 'asc' | 'desc';
+    }>;
+    filterModel: Record<string, CallbackColumnFilter> | null;
+};
+/** One column of the callback-style filter model (text, number or set). */
+export type CallbackColumnFilter = {
+    filterType?: string;
+    type?: string;
+    filter?: unknown;
+    filterTo?: unknown;
+    values?: string[];
+};
+/** What a callback-style datasource's `getRows` receives, and how it answers. */
+export type CallbackGetRowsParams<TData = unknown> = {
+    request: CallbackServerRequest;
+    success: (result: {
+        rowData: TData[];
+        rowCount?: number;
+        pivotResultFields?: string[];
+    }) => void;
+    fail: () => void;
+    context?: unknown;
+    parentNode?: {
+        data?: TData;
+    } | null;
+};
+/** A datasource in the callback shape: `getRows(params)` answering through `params.success` / `params.fail`. */
+export type CallbackDatasource<TData = unknown> = {
+    getRows(params: CallbackGetRowsParams<TData>): void;
+    destroy?(): void;
+};
+/** The callback-style per-column filter model -> `ServerFilterModel`. */
+export declare function fromCallbackFilterModel(model: Record<string, CallbackColumnFilter> | null | undefined): ServerFilterModel;
+/** `ServerFilterModel` -> the callback-style per-column filter model. The global search has no form there and is dropped. */
+export declare function toCallbackFilterModel(model: ServerFilterModel): Record<string, CallbackColumnFilter>;
+/** `ServerRequest` -> the callback-style request shape. */
+export declare function toCallbackRequest(req: ServerRequest): CallbackServerRequest;
+/** The callback-style request shape -> `ServerRequest`. */
+export declare function fromCallbackRequest(req: CallbackServerRequest, extra?: Partial<ServerRequest>): ServerRequest;
+/**
+ * Wrap a callback-style datasource so `createServerRowModel` (or
+ * `createServerDataSource`) can drive it.
+ *
+ * ```ts
+ * const ctl = createServerRowModel(adaptCallbackDatasource(myDatasource), { groupBy: ['country'] })
+ * ```
+ */
+export declare function adaptCallbackDatasource<TData>(ds: CallbackDatasource<TData>): ServerDataSource<TData>;
+/**
+ * The other direction: a `ServerDataSource` as a callback-style datasource,
+ * so one backend can serve two grids side by side.
+ */
+export declare function toCallbackDatasource<TData>(source: ServerDataSource<TData>): CallbackDatasource<TData>;
+/** The flat selection rule in the callback-style shape. */
+export type CallbackSelectionState = {
+    selectAll: boolean;
+    /** Exceptions to `selectAll`, as row ids. */
+    toggledNodes: string[];
+};
+/**
+ * One node of the callback-style hierarchical rule. The root carries no
+ * `nodeId`; a child is a group row or a leaf, told apart by whether it has
+ * exceptions of its own (see `SelectionStateMapping.isGroup`).
+ */
+export type CallbackGroupSelectionState = {
+    nodeId?: string;
+    selectAllChildren?: boolean;
+    toggledNodes?: CallbackGroupSelectionState[];
+};
+/**
+ * How group rows are named across the two shapes. This model keys a group
+ * by its route segment (`['EMEA', 'DE']` is the DE group under EMEA); the
+ * callback shape keys it by a row node id that the app chose. When the two
+ * are the same string - the default - nothing needs to be passed.
+ */
+export type SelectionStateMapping = {
+    /** The node id of the group at `route`. Default: the last key of the route. */
+    groupId?: (route: string[]) => string;
+    /** The group key for a node id under `parentRoute`. Default: the id itself. */
+    groupKey?: (nodeId: string, parentRoute: string[]) => string;
+    /**
+     * Whether the node `nodeId` under `parentRoute` is a group row. Default:
+     * it is when it carries exceptions of its own, a leaf otherwise. A flipped
+     * group read as a leaf still selects the same rows; only `selectedCount`
+     * is off, since a group exception has no size of its own.
+     */
+    isGroup?: (nodeId: string, parentRoute: string[]) => boolean;
+};
+/** Whether a selection state is in the callback-style shape (either level). */
+export declare function isCallbackSelectionState(state: unknown): state is CallbackSelectionState | CallbackGroupSelectionState;
+/** The selection rule -> the callback-style shape, flat or per group. */
+export declare function toCallbackSelectionState(state: ServerSelectionState | ServerGroupSelectionNode, mapping?: SelectionStateMapping): CallbackSelectionState | CallbackGroupSelectionState;
+/** The callback-style shape -> the selection rule this model keeps. */
+export declare function fromCallbackSelectionState(state: CallbackSelectionState | CallbackGroupSelectionState, mapping?: SelectionStateMapping): ServerSelectionState | ServerGroupSelectionNode;

package/dist/server/svgrid-adapter.js

@@ -0,0 +1,202 @@
+const CALLBACK_TO_GRID_OPERATOR = {
+    contains: 'contains',
+    notContains: 'notContains',
+    equals: 'equals',
+    notEqual: 'notEquals',
+    startsWith: 'startsWith',
+    endsWith: 'endsWith',
+    lessThan: 'lessThan',
+    lessThanOrEqual: 'lessThanOrEqual',
+    greaterThan: 'greaterThan',
+    greaterThanOrEqual: 'greaterThanOrEqual',
+    inRange: 'between',
+    blank: 'isBlank',
+    notBlank: 'isNotBlank',
+};
+const GRID_TO_CALLBACK_OPERATOR = Object.fromEntries(Object.entries(CALLBACK_TO_GRID_OPERATOR).map(([theirs, ours]) => [ours, theirs]));
+const asString = (v) => (v == null ? '' : String(v));
+/** The callback-style per-column filter model -> `ServerFilterModel`. */
+export function fromCallbackFilterModel(model) {
+    const columns = {};
+    for (const [id, f] of Object.entries(model ?? {})) {
+        if (!f)
+            continue;
+        if (f.filterType === 'set' && Array.isArray(f.values)) {
+            columns[id] = { operator: 'in', value: '', selectedValues: f.values.map(asString) };
+            continue;
+        }
+        const operator = CALLBACK_TO_GRID_OPERATOR[f.type ?? ''] ?? f.type ?? 'equals';
+        columns[id] = {
+            operator,
+            value: asString(f.filter),
+            ...(f.filterTo != null ? { valueTo: asString(f.filterTo) } : {}),
+        };
+    }
+    return Object.keys(columns).length ? { columns } : {};
+}
+/** `ServerFilterModel` -> the callback-style per-column filter model. The global search has no form there and is dropped. */
+export function toCallbackFilterModel(model) {
+    const out = {};
+    for (const [id, f] of Object.entries(model.columns ?? {})) {
+        if (f.selectedValues) {
+            out[id] = { filterType: 'set', values: f.selectedValues };
+            continue;
+        }
+        out[id] = {
+            filterType: 'text',
+            type: GRID_TO_CALLBACK_OPERATOR[f.operator] ?? f.operator,
+            filter: f.value,
+            ...(f.valueTo != null ? { filterTo: f.valueTo } : {}),
+        };
+    }
+    return out;
+}
+/** `ServerRequest` -> the callback-style request shape. */
+export function toCallbackRequest(req) {
+    return {
+        startRow: req.startRow,
+        endRow: req.endRow,
+        rowGroupCols: (req.groupBy ?? []).map((id) => ({ id, field: id, displayName: id })),
+        groupKeys: [...(req.groupKeys ?? [])],
+        valueCols: (req.aggregations ?? []).map((a) => ({ id: a.col, field: a.col, displayName: a.col, aggFunc: a.fn })),
+        pivotCols: (req.pivotBy ?? []).map((id) => ({ id, field: id, displayName: id })),
+        pivotMode: !!req.pivotMode,
+        sortModel: req.sortModel.map((s) => ({ colId: s.id, sort: s.desc ? 'desc' : 'asc' })),
+        filterModel: toCallbackFilterModel(req.filterModel),
+    };
+}
+/** The callback-style request shape -> `ServerRequest`. */
+export function fromCallbackRequest(req, extra = {}) {
+    const startRow = req.startRow ?? 0;
+    const endRow = req.endRow ?? startRow + 100;
+    const pageSize = Math.max(1, endRow - startRow);
+    const sortModel = req.sortModel.map((s) => ({ id: s.colId, desc: s.sort === 'desc' }));
+    const out = {
+        startRow,
+        endRow,
+        pageIndex: Math.floor(startRow / pageSize),
+        pageSize,
+        sortModel,
+        filterModel: fromCallbackFilterModel(req.filterModel),
+        ...extra,
+    };
+    if (req.rowGroupCols.length) {
+        out.groupBy = req.rowGroupCols.map((c) => c.id);
+        out.groupKeys = [...req.groupKeys];
+    }
+    if (req.valueCols.length) {
+        out.aggregations = req.valueCols.map((c) => ({
+            col: c.id,
+            fn: (c.aggFunc ?? 'sum'),
+        }));
+    }
+    if (req.pivotMode && req.pivotCols.length) {
+        out.pivotBy = req.pivotCols.map((c) => c.id);
+        out.pivotMode = true;
+    }
+    return out;
+}
+/**
+ * Wrap a callback-style datasource so `createServerRowModel` (or
+ * `createServerDataSource`) can drive it.
+ *
+ * ```ts
+ * const ctl = createServerRowModel(adaptCallbackDatasource(myDatasource), { groupBy: ['country'] })
+ * ```
+ */
+export function adaptCallbackDatasource(ds) {
+    return {
+        getRows(req) {
+            return new Promise((resolve, reject) => {
+                let settled = false;
+                ds.getRows({
+                    request: toCallbackRequest(req),
+                    context: req.context,
+                    parentNode: req.parentRow === undefined ? null : { data: req.parentRow },
+                    success: ({ rowData, rowCount, pivotResultFields }) => {
+                        if (settled)
+                            return;
+                        settled = true;
+                        const result = {
+                            rows: rowData,
+                            rowCount: rowCount == null || rowCount < 0 ? -1 : rowCount,
+                        };
+                        if (pivotResultFields)
+                            result.pivotResultFields = pivotResultFields;
+                        resolve(result);
+                    },
+                    fail: () => {
+                        if (settled)
+                            return;
+                        settled = true;
+                        reject(new Error('The datasource reported a failed load'));
+                    },
+                });
+            });
+        },
+        ...(ds.destroy ? { destroy: () => ds.destroy() } : {}),
+    };
+}
+/**
+ * The other direction: a `ServerDataSource` as a callback-style datasource,
+ * so one backend can serve two grids side by side.
+ */
+export function toCallbackDatasource(source) {
+    return {
+        getRows(params) {
+            const extra = {};
+            if (params.context !== undefined)
+                extra.context = params.context;
+            if (params.parentNode?.data !== undefined)
+                extra.parentRow = params.parentNode.data;
+            source.getRows(fromCallbackRequest(params.request, extra)).then((res) => {
+                params.success({
+                    rowData: [...res.rows],
+                    rowCount: res.rowCount < 0 ? undefined : res.rowCount,
+                    ...(res.pivotResultFields ? { pivotResultFields: res.pivotResultFields } : {}),
+                });
+            }, () => params.fail());
+        },
+        ...(source.destroy ? { destroy: () => source.destroy() } : {}),
+    };
+}
+/** Whether a selection state is in the callback-style shape (either level). */
+export function isCallbackSelectionState(state) {
+    return typeof state === 'object' && state !== null && 'toggledNodes' in state;
+}
+/** The selection rule -> the callback-style shape, flat or per group. */
+export function toCallbackSelectionState(state, mapping = {}) {
+    if ('selectAll' in state)
+        return { selectAll: !!state.selectAll, toggledNodes: [...(state.toggled ?? [])] };
+    const walk = (node, route) => {
+        const out = {};
+        if (route.length) {
+            out.nodeId = node.group ? (mapping.groupId?.(route) ?? route[route.length - 1]) : route[route.length - 1];
+        }
+        out.selectAllChildren = !!node.selectAllChildren;
+        out.toggledNodes = Object.entries(node.toggled ?? {}).map(([key, child]) => walk(child, [...route, key]));
+        return out;
+    };
+    return walk(state, []);
+}
+/** The callback-style shape -> the selection rule this model keeps. */
+export function fromCallbackSelectionState(state, mapping = {}) {
+    if ('selectAll' in state) {
+        const flat = state;
+        return { selectAll: !!flat.selectAll, toggled: (flat.toggledNodes ?? []).map(String) };
+    }
+    const walk = (node, route) => {
+        const toggled = {};
+        for (const child of node.toggledNodes ?? []) {
+            if (child.nodeId == null)
+                continue;
+            const id = String(child.nodeId);
+            const group = mapping.isGroup?.(id, route) ?? (child.toggledNodes?.length ?? 0) > 0;
+            const key = group ? (mapping.groupKey?.(id, route) ?? id) : id;
+            const plain = walk(child, [...route, key]);
+            toggled[key] = group ? { ...plain, group: true } : plain;
+        }
+        return { selectAllChildren: !!node.selectAllChildren, toggled };
+    };
+    return walk(state, []);
+}