Infer paginated type | Convex Community | Page 1

echo harness Mar 26, 2025, 9:16 PM

#

Infer paginated type of a internal or public query

ashen valveBOT Mar 26, 2025, 9:16 PM

#

Hi @echo harness. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

To infer the type of a paginated query in Convex, you have several options depending on what specific type information you need.

Inferring the Item Type

If you need the type of individual items in the paginated results:

import { PaginatedQueryItem } from "convex/react";
import { api } from "../convex/_generated/api";

type MyItemType = PaginatedQueryItem<typeof api.myModule.myPaginatedQuery>;

This will give you the type of a single item in the page array returned by your paginated query PaginatedQueryItem.

Inferring the Full Return Type

If you need the complete return type of usePaginatedQuery, including loading states:

import { UsePaginatedQueryReturnType } from "convex/react";
import { api } from "../convex/_generated/api";

type MyPaginatedQueryResult = UsePaginatedQueryReturnType<typeof api.myModule.myPaginatedQuery>;

This gives you the full type including results, status, isLoading, and loadMore UsePaginatedQueryReturnType.

Inferring the Arguments Type

If you need the type of arguments for a paginated query (excluding the pagination options):

import { PaginatedQueryArgs } from "convex/react";
import { api } from "../convex/_generated/api";

type MyQueryArgs = PaginatedQueryArgs<typeof api.myModule.myPaginatedQuery>;

This gives you the type of arguments excluding the paginationOpts property PaginatedQueryArgs.

Example Usage

Here's how you might use these types in a component:

import { UsePaginatedQueryReturnType, PaginatedQueryItem } from "convex/react";
import { api } from "../convex/_generated/api";

#

// Type for a single item
type DocumentItem = PaginatedQueryItem<typeof api.documents.list>;

// Type for the full query result
type DocumentsQueryResult = UsePaginatedQueryReturnType<typeof api.documents.list>;

// In a component that receives the query result as a prop
function MyHelperComponent(props: {
paginatedData: DocumentsQueryResult;
}) {
// Use the paginated data
const { results, status, loadMore } = props.paginatedData;

// ...
}


These type utilities work for both internal and public query functions, as long as they are properly set up as paginated queries.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------

#

@echo harness Kapa.ai is still learning and improving, please let me know how I did by reacting below.

echo harness Mar 26, 2025, 9:18 PM

#

@ashen valve I want convex api not react

ashen valveBOT Mar 26, 2025, 9:18 PM

#

Let me check the knowledge base for you again. One moment! :books:

#

I understand you're looking for the Convex API types for pagination rather than the React-specific types. Here's how to work with pagination types in the Convex server API:

Server-Side Pagination Types

For server-side code, you can use the following types from the Convex server module:

import { PaginationOptions, PaginationResult, Cursor } from "convex/server";

PaginationOptions: The type for pagination options passed to .paginate()
PaginationResult: The return type of .paginate()
Cursor: The type for pagination cursors

Inferring Function Return Types

To infer the return type of a paginated query function (without React hooks):

import { FunctionReturnType } from "convex/server";
import { api } from "../convex/_generated/api";

// Get the full return type of a paginated query
type PaginatedQueryResult = FunctionReturnType<typeof api.myModule.myPaginatedQuery>;

// Extract just the page items type
type PageItemType = PaginatedQueryResult["page"][number];

Example Usage in Server Code

Here's how you might use these types in a Convex function:

import { query } from "./_generated/server";
import { paginationOptsValidator } from "convex/server";
import type { PaginationResult } from "convex/server";

export const list = query({
  args: { paginationOpts: paginationOptsValidator },
  handler: async (ctx, args): Promise<PaginationResult<MyDocType>> => {
    return await ctx.db
      .query("myTable")
      .order("desc")
      .paginate(args.paginationOpts);
  },
});

#

#Infer paginated type