Skip to main content

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​

ParameterTypeDescription
lastPageConnectRPCPaginatedResponseThe last page response from the API.
queryParams{ query: RQLRequest }The current query parameters.
itemsKeystringThe 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​

OptionTypeDescription
defaultLimitnumberDefault page size. Defaults to 50.
fieldNameMappingRecord<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>;
}