ponder-client/README.md

Type-safe, lightweight Ponder client

# Ponder Client

Type-safe, lightweight Ponder client

## Features

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

## Quickstart

### Installation

```bash
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:

```ts
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:

```ts
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](https://github.com/Destiner/ponder-client/issues/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