Custom API Functions

.changeset/shy-donuts-battle.md

@@ -0,0 +1,6 @@
+---
+"create-ponder": minor
+"@ponder/core": minor
+---
+
+[Experimental] Introduced API functions. [Read more](https://ponder-docs-git-kjs-api2-ponder-sh.vercel.app/docs/query/api-functions).

.changeset/silent-walls-give.md

@@ -0,0 +1,5 @@
+---
+"@ponder/core": patch
+---
+
+Added per network progress to the "/status" endpoint on the server and the "_metadata" entity on the GraphQL schema.

docs/pages/docs/_meta.ts

@@ -30,11 +30,11 @@ export default {
   },
   indexing: { display: "children", title: "Indexing" },
 
-  "-- Query the database": {
+  "-- Query": {
     type: "separator",
-    title: "Query the database",
+    title: "Query",
   },
-  query: { display: "children", title: "Query the database" },
+  query: { display: "children", title: "Query" },
 
   "-- Production": {
     type: "separator",

docs/pages/docs/query/_meta.ts

@@ -1,4 +1,5 @@
 export default {
+  "api-functions": "API functions (experimental)",
   "graphql": "GraphQL",
   "direct-sql": "Direct SQL",
 };

docs/pages/docs/query/api-functions.mdx

@@ -0,0 +1,137 @@
+---
+title: "API functions"
+description: "Use API functions to customize the API layer of your app."
+---
+
+import { Callout, Steps } from "nextra/components";
+
+# API functions (experimental)
+
+**API functions** are user-defined functions that respond to incoming Web requests. You can use them to customize the API layer of your app with direct SQL queries, authentication, data from external sources, and more.
+
+API functions are built on top of [Hono](https://hono.dev/), a fast and lightweight routing framework.
+
+## Get started
+
+<Steps>
+
+### Install `hono` and `@ponder/core@next`
+
+To use API functions, install `hono` and the prerelease version of `@ponder/core`.
+
+```bash
+npm install hono @ponder/core@next
+```
+
+### Create `src/api/index.ts` file
+
+To opt-in to API functions, create a file named `src/api/index.ts` with the following code.
+
+```ts filename="src/api/index.ts"
+import { ponder } from "@/generated";
+
+ponder.get("/hello", (c) => {
+  return c.text("Hello, world!");
+});
+```
+
+### Send a request
+
+With the server running, visit `http://localhost:42069/hello` in your browser to see the response.
+
+### Add the GraphQL middleware
+
+To register the standard GraphQL API that was automatically included in versions `<0.5.0`, register the `graphql` middleware exported from `@ponder/core`.
+
+```ts filename="src/api/index.ts" {2,4}
+import { ponder } from "@/generated";
+import { graphql } from "@ponder/core";
+
+ponder.use("/graphql", graphql());
+
+// ...
+```
+
+</Steps>
+
+## Query the database
+
+API functions have read-only access to your database using a [Hono Variable](https://hono.dev/docs/api/context#set-get) named `db`. Unlike indexing functions, the `create`, `update`, `delete`, `createMany`, and `updateMany` methods are not available in API functions.
+
+### `findUnique` and `findMany`
+
+API functions can use `findUnique` and `findMany` to query the database. These methods work just like they do within indexing functions. [Read more](/docs/indexing/create-update-records#findmany) about the store API.
+
+```ts filename="src/api/index.ts" {5,7-9}
+import { ponder } from "@/generated";
+
+ponder.get("/account/:address", (c) => {
+  const address = c.req.param("address");
+  const db = c.get("db");
+
+  const account = await db.Account.findUnique({
+    id: address,
+  });
+
+  if (account) {
+    return c.json(account);
+  } else {
+    return c.status(404).json({ error: "Account not found" });
+  }
+});
+```
+
+### Direct SQL
+
+Use `db.query(...){:ts}` to execute raw SQL queries against your database.
+
+```ts filename="src/api/index.ts" {6,8-10}
+import { ponder } from "@/generated";
+import { sql } from "@ponder/core";
+
+ponder.get("/:token/ticker", (c) => {
+  const token = c.req.param("token");
+  const db = c.get("db");
+
+  const result = await db.query(
+    sql`SELECT ticker FROM "Token" WHERE id = ${token}`
+  );
+  const ticker = result.rows[0]?.ticker;
+
+  return c.text(ticker);
+});
+```
+
+## Register middleware
+
+Use `ponder.use(...){:ts}` to add middleware to your API functions. Middleware functions can modify the request and response objects, add logs, do authentication, and more. [Read more](https://hono.dev/docs/guides/middleware) about Hono middleware.
+
+```ts filename="src/api/index.ts" {3}
+import { ponder } from "@/generated";
+
+ponder.use((c) => {
+  console.log("Request received:", c.req.url);
+  return c.next();
+});
+```
+
+## Access the Hono instance
+
+You can register API functions and middleware using `ponder.get(...){:ts}`, `ponder.post(...){:ts}`, and `ponder.use(...){:ts}`. If you need to access the underlying Hono instance, use the `hono` property.
+
+```ts filename="src/api/index.ts" {3}
+import { ponder } from "@/generated";
+
+ponder.hono.notFound((c) => {
+  return c.text("Custom 404 Message", 404);
+});
+
+// ...
+```
+
+## Internal routes
+
+Ponder registers internal routes under the `/_ponder/*` path. If you attempt to register API functions that conflict with internal routes, the build will fail.
+
+- `/_ponder/health`: Returns a `200` status code after the app has completed historical indexing OR the healthcheck timeout has expired, whichever comes first. [Read more](/docs/production/zero-downtime) about healthchecks.
+- `/_ponder/metrics`: Returns Prometheus metrics. [Read more](/docs/advanced/metrics) about metrics.

examples/reference-erc20/package.json

@@ -12,6 +12,7 @@
   },
   "dependencies": {
     "@ponder/core": "workspace:*",
+    "hono": "^4.4.6",
     "viem": "^1.19.9"
   },
   "devDependencies": {

examples/reference-erc20/src/api/index.ts

@@ -0,0 +1,19 @@
+import { ponder } from "@/generated";
+import { desc, graphql } from "@ponder/core";
+import { formatEther } from "viem";
+
+ponder.use("/graphql", graphql()).get("/big", async (c) => {
+  const { Account } = c.tables;
+
+  const account = await c.db
+    .select({ balance: Account.balance })
+    .from(Account)
+    .orderBy(desc(Account.balance))
+    .limit(1);
+
+  if (account.length === 0) {
+    return c.text("Not Found!");
+  } else {
+    return c.text(`Balance: ${formatEther(account[0]!.balance)}`);
+  }
+});

package.json

@@ -17,13 +17,17 @@
     "@biomejs/biome": "^1.8.1",
     "@changesets/changelog-github": "^0.4.8",
     "@changesets/cli": "^2.26.2",
+    "hono": "4.0.0",
     "lint-staged": "^15.1.0",
     "simple-git-hooks": "^2.9.0",
     "typescript": "5.0.4",
     "viem": "1.16.0"
   },
   "lint-staged": {
-    "*.ts": ["biome format --no-errors-on-unmatched --write", "biome check"],
+    "*.ts": [
+      "biome format --no-errors-on-unmatched --write",
+      "biome check --no-errors-on-unmatched"
+    ],
     "!(*.ts)": ["biome format --no-errors-on-unmatched --write"]
   },
   "simple-git-hooks": {
@@ -32,7 +36,6 @@
   "packageManager": "pnpm@8.6.10",
   "pnpm": {
     "patchedDependencies": {
-      "graphql@16.8.1": "patches/graphql@16.8.1.patch",
       "detect-package-manager@3.0.1": "patches/detect-package-manager@3.0.1.patch"
     },
     "peerDependencyRules": {

packages/core/package.json

@@ -33,6 +33,7 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
+    "hono": ">=4",
     "typescript": ">=5.0.4",
     "viem": ">=1.16"
   },
@@ -56,17 +57,15 @@
     "dataloader": "^2.2.2",
     "detect-package-manager": "^3.0.1",
     "dotenv": "^16.3.1",
+    "drizzle-orm": "^0.31.2",
     "emittery": "^1.0.1",
     "ethereum-bloom-filters": "^1.0.10",
     "glob": "^10.3.10",
     "graphql": "^16.8.1",
-    "graphql-type-json": "^0.3.2",
     "graphql-yoga": "^5.3.0",
-    "hono": "^4.4.2",
     "http-terminator": "^3.2.0",
     "ink": "^4.4.1",
     "kysely": "^0.26.3",
-    "magic-string": "^0.30.5",
     "p-queue": "^7.4.1",
     "pg": "^8.11.3",
     "pg-connection-string": "^2.6.2",

packages/core/src/_test/e2e/erc20/src/api/index.ts

@@ -0,0 +1,11 @@
+// @ts-ignore
+import { ponder } from "@/generated";
+import { graphql } from "@/index.js";
+
+// biome-ignore lint/suspicious/noRedeclare: :)
+declare const ponder: import("@/index.js").Virtual.Registry<
+  typeof import("../../ponder.config.js").default,
+  typeof import("../../ponder.schema.js").default
+>;
+
+ponder.use("/graphql", graphql());

packages/core/src/_test/e2e/factory/src/api/index.ts

@@ -0,0 +1,11 @@
+// @ts-ignore
+import { ponder } from "@/generated";
+import { graphql } from "@/index.js";
+
+// biome-ignore lint/suspicious/noRedeclare: :)
+declare const ponder: import("@/index.js").Virtual.Registry<
+  typeof import("../../ponder.config.js").default,
+  typeof import("../../ponder.schema.js").default
+>;
+
+ponder.use("/graphql", graphql());

packages/core/src/_test/utils.ts

@@ -694,10 +694,12 @@ export async function waitForIndexedBlock(
       reject(new Error("Timed out while waiting for the indexed block."));
     }, 5_000);
     const interval = setInterval(async () => {
-      const response = await fetch(`http://localhost:${port}/status`);
+      const response = await fetch(`http://localhost:${port}/_ponder/status`);
       if (response.status === 200) {
-        const status = (await response.json()) as Status;
-        const statusBlockNumber = status[networkName]?.block?.number;
+        const status = (await response.json()) as Status | null;
+        const statusBlockNumber = status
+          ? status[networkName]?.block?.number
+          : undefined;
         if (
           statusBlockNumber !== undefined &&
           statusBlockNumber >= blockNumber

packages/core/src/bin/commands/codegen.ts

@@ -57,7 +57,7 @@ export async function codegen({ cliOptions }: { cliOptions: CliOptions }) {
     properties: { cli_command: "codegen" },
   });
 
-  runCodegen({ common, graphqlSchema: buildResult.build.graphqlSchema });
+  runCodegen({ common, graphQLSchema: buildResult.build.graphQLSchema });
 
   logger.info({ service: "codegen", msg: "Wrote ponder-env.d.ts" });
   logger.info({ service: "codegen", msg: "Wrote schema.graphql" });