Utilities

The SDK exports utility functions for working with ConnectRPC pagination and query transformation.

import {
  getConnectNextPageParam,
  getGroupCountMapFromFirstPage,
  DEFAULT_PAGE_SIZE,
  transformDataTableQueryToRQLRequest,
} from "@raystack/frontier/admin";

`DEFAULT_PAGE_SIZE`

Default page size used for paginated queries.

const DEFAULT_PAGE_SIZE = 50;

`getConnectNextPageParam`

Returns the next page parameters for infinite queries using ConnectRPC pagination. Returns undefined when there are no more pages.

Signature

function getConnectNextPageParam<T extends ConnectRPCPaginatedResponse>(
  lastPage: T,
  queryParams: { query: RQLRequest },
  itemsKey?: string, // default: "organizations"
): { query: RQLRequest } | undefined;

Parameters

Parameter	Type	Description
`lastPage`	`ConnectRPCPaginatedResponse`	The last page response from the API.
`queryParams`	`\{ query: RQLRequest \}`	The current query parameters.
`itemsKey`	`string`	The key in the response that contains the items array. Defaults to `"organizations"`.

Example

import { useInfiniteQuery } from "@connectrpc/connect-query";
import { AdminServiceQueries } from "@raystack/proton/frontier";
import { getConnectNextPageParam } from "@raystack/frontier/admin";

const { data, fetchNextPage } = useInfiniteQuery(
  AdminServiceQueries.searchUsers,
  { query },
  {
    pageParamKey: "query",
    getNextPageParam: (lastPage) =>
      getConnectNextPageParam(lastPage, { query }, "users"),
  },
);

`getGroupCountMapFromFirstPage`

Extracts group count data from the first page of an infinite query response. Useful for displaying group counts in DataTable column headers.

Signature

function getGroupCountMapFromFirstPage(
  infiniteData: { pages: ConnectRPCPaginatedResponse[] },
): Record<string, Record<string, number>>;

Example

const groupCountMap = infiniteData
  ? getGroupCountMapFromFirstPage(infiniteData)
  : {};

const columns = getColumns({ groupCountMap });

`transformDataTableQueryToRQLRequest`

Converts an Apsara DataTableQuery object into an RQLRequest compatible with ConnectRPC APIs. Handles filters, sorting, pagination, and search.

Signature

function transformDataTableQueryToRQLRequest(
  query: DataTableQuery,
  options?: TransformOptions,
): RQLRequest;

Options

Option	Type	Description
`defaultLimit`	`number`	Default page size. Defaults to `50`.
`fieldNameMapping`	`Record<string, string>`	Maps frontend field names to API field names (e.g. `\{ createdAt: "created_at" \}`).

Example

import { transformDataTableQueryToRQLRequest } from "@raystack/frontier/admin";

const query = transformDataTableQueryToRQLRequest(tableQuery, {
  fieldNameMapping: {
    createdAt: "created_at",
    updatedAt: "updated_at",
  },
});

`ConnectRPCPaginatedResponse`

Type for paginated API responses.

type ConnectRPCPaginatedResponse = {
  pagination?: RQLQueryPaginationResponse;
  group?: RQLQueryGroupResponse;
  [key: string]: unknown;
};

`TransformOptions`

Options for transformDataTableQueryToRQLRequest.

interface TransformOptions {
  defaultLimit?: number;
  fieldNameMapping?: Record<string, string>;
}