Ponder Client

Type-safe, lightweight Ponder client

Features

• Full end-to-end typesafety
• No build step
• Zero dependencies
• Zero JS bundled

Quickstart

Installation

bun install ponder-client
# or
npm install ponder-client
# or
yarn add ponder-client
# or
pnpm add ponder-client

Schema

Import or copy your Ponder schema into the project:

import { createSchema } from '@ponder/core';

const schema = createSchema((p) => ({
  Entity: p.createTable({
    id: p.string(),
    address: p.hex(),
    chainId: p.int(),
    factory: p.hex(),
    values: p.hex().list(),
  }),
}));

export default schema;

Querying

Make your first query:

import { one, many, query as queryPonder } from 'ponder-client';

import schema from './schema';

const query = {
  entities: many<
    'Entity',
    (typeof schema.tables)['Entity'],
    { address: true; chainId: true },
    {
      endCursor: true;
      hasNextPage: true;
    }
  >('Entity')(
    {
      limit: 10,
      where: {
        factory: FACTORY_ADDRESS,
      },
      orderBy: 'address',
      orderDirection: 'asc',
      after: AFTER_CURSOR,
    },
    {
      address: true,
      chainId: true,
    },
    {
      endCursor: true,
      hasNextPage: true,
    },
  ),
} satisfies Query;
const data: Data<typeof query> = await queryPonder(PONDER_ENDPOINT, query);

console.log(typeof data.entities.items[0].address); // Hex
console.log(typeof data.entities.items[0].chainId); // number
console.log(typeof data.entities.pageInfo.endCursor); // string
console.log(typeof data.entities.pageInfo.hasNextPage); // boolean

TODO

• [ ] Essential unit tests
• [ ] Fix typing issue when querying multiple tables
• [ ] Validate table names
• [ ] Simplify the API (#1)
• [ ] Support filtering extensions (e.g _gt, _in)
• [ ] Support filtering conditions (OR, AND, combinations)
• [ ] Support time-travel queries (timestamp)
• [ ] Support reference columns
• [ ] Pagination utils
• [ ] Serialization unit tests
• [ ] Robust typing tests