@ponder/react 0.14.12 → 0.15.0

package/dist/esm/utils.js

@@ -4,7 +4,7 @@ export function getPonderQueryOptions(client, queryFn) {
     const queryPromise = queryFn(client.db);
     // @ts-expect-error
     if ("getSQL" in queryPromise === false) {
-        throw new Error('"queryFn" must return SQL');
+        throw new Error('"queryFn" must return SQL. You may have to remove `.execute()` from your query.');
     }
     const query = compileQuery(queryPromise);
     const queryKey = ["__ponder_react", query.sql, stringify(query.params)];

package/dist/esm/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE3D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAKtC,MAAM,UAAU,qBAAqB,CACnC,MAA8B,EAC9B,OAAgD;IAKhD,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAExC,mBAAmB;IACnB,IAAI,QAAQ,IAAI,YAAY,KAAK,KAAK,EAAE;QACtC,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;KAC9C;IAED,MAAM,KAAK,GAAG,YAAY,CAAC,YAAqC,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAG,CAAC,gBAAgB,EAAE,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAExE,OAAO;QACL,QAAQ;QACR,OAAO,EAAE,GAAG,EAAE,CAAC,YAAY;KAC5B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE3D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAKtC,MAAM,UAAU,qBAAqB,CACnC,MAA8B,EAC9B,OAAgD;IAKhD,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAExC,mBAAmB;IACnB,IAAI,QAAQ,IAAI,YAAY,KAAK,KAAK,EAAE;QACtC,MAAM,IAAI,KAAK,CACb,iFAAiF,CAClF,CAAC;KACH;IAED,MAAM,KAAK,GAAG,YAAY,CAAC,YAAqC,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAG,CAAC,gBAAgB,EAAE,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAExE,OAAO;QACL,QAAQ;QACR,OAAO,EAAE,GAAG,EAAE,CAAC,YAAY;KAC5B,CAAC;AACJ,CAAC"}

package/dist/types/checkpoint.d.ts

@@ -0,0 +1,10 @@
+export type Checkpoint = {
+    blockTimestamp: bigint;
+    chainId: bigint;
+    blockNumber: bigint;
+    transactionIndex: bigint;
+    eventType: number;
+    eventIndex: bigint;
+};
+export declare const decodeCheckpoint: (checkpoint: string) => Checkpoint;
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/types/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../src/checkpoint.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAgBF,eAAO,MAAM,gBAAgB,eAAgB,MAAM,KAAG,UAqCrD,CAAC"}

package/dist/types/hook.d.ts

@@ -3,11 +3,18 @@ import { type DefaultError, type QueryKey, type UseQueryOptions, type UseQueryRe
 import type { ResolvedSchema } from "./index.js";
 export declare function usePonderQuery<queryFnData = unknown, error = DefaultError, data = queryFnData>(params: {
     queryFn: (db: Client<ResolvedSchema>["db"]) => Promise<queryFnData>;
+    live?: boolean;
 } & Omit<UseQueryOptions<queryFnData, error, data>, "queryFn" | "queryKey">): UseQueryResult<data, error>;
 export declare function usePonderClient(): Client<ResolvedSchema>;
 export declare function usePonderQueryOptions<T>(queryFn: (db: Client<ResolvedSchema>["db"]) => T): {
     queryKey: QueryKey;
     queryFn: () => T;
 };
-export declare function usePonderStatus(params: Omit<UseQueryOptions<Status>, "queryFn" | "queryKey">): UseQueryResult<Status>;
+export declare function usePonderStatus<error = DefaultError>(params?: {
+    live?: boolean;
+} & Omit<UseQueryOptions<{
+    chain_name: string;
+    chain_id: number;
+    latest_checkpoint: string;
+}[], error, Status>, "queryFn" | "queryKey" | "select">): UseQueryResult<Status, error>;
 //# sourceMappingURL=hook.d.ts.map

package/dist/types/hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../src/hook.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,cAAc,EAGpB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,wBAAgB,cAAc,CAC5B,WAAW,GAAG,OAAO,EACrB,KAAK,GAAG,YAAY,EACpB,IAAI,GAAG,WAAW,EAElB,MAAM,EAAE;IACN,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;CACrE,GAAG,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC,GAC1E,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CAyB7B;AAED,wBAAgB,eAAe,IAAI,MAAM,CAAC,cAAc,CAAC,CAMxD;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAC/C;IACD,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,CAAC;CAClB,CAGA;AAID,wBAAgB,eAAe,CAC7B,MAAM,EAAE,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC,GAC5D,cAAc,CAAC,MAAM,CAAC,CAsBxB"}
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../src/hook.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,cAAc,EAGpB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,wBAAgB,cAAc,CAC5B,WAAW,GAAG,OAAO,EACrB,KAAK,GAAG,YAAY,EACpB,IAAI,GAAG,WAAW,EAElB,MAAM,EAAE;IACN,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACpE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,GAAG,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC,GAC1E,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CA8B7B;AAED,wBAAgB,eAAe,IAAI,MAAM,CAAC,cAAc,CAAC,CAMxD;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAC/C;IACD,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,CAAC;CAClB,CAGA;AAED,wBAAgB,eAAe,CAAC,KAAK,GAAG,YAAY,EAClD,MAAM,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAChC,eAAe,CACb;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,EAAE,EACrE,KAAK,EACL,MAAM,CACP,EACD,SAAS,GAAG,UAAU,GAAG,QAAQ,CAClC,GACA,cAAc,CAAC,MAAM,EAAE,KAAK,CAAC,CA6B/B"}

package/dist/types/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAE7E,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC,EAC9B,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAC/C;IACD,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,CAAC;CAClB,CAeA"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAE7E,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC,EAC9B,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAC/C;IACD,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,CAAC;CAClB,CAiBA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ponder/react",
-  "version": "0.14.12",
+  "version": "0.15.0",
   "description": "React hooks for Ponder",
   "license": "MIT",
   "repository": {
@@ -31,7 +31,7 @@
     "superjson": "^2.2.2"
   },
   "peerDependencies": {
-    "@ponder/client": ">=0.14.12",
+    "@ponder/client": ">=0.15.0",
     "@tanstack/react-query": ">=5.0.0",
     "react": ">=18",
     "typescript": ">=5.0.4"
@@ -52,7 +52,7 @@
     "rimraf": "^5.0.5",
     "tsx": "^4.19.2",
     "vitest": "^1.0.2",
-    "@ponder/client": "0.14.12"
+    "@ponder/client": "0.15.0"
   },
   "scripts": {
     "build": "tsx build.ts",

package/src/checkpoint.ts

@@ -0,0 +1,61 @@
+export type Checkpoint = {
+  blockTimestamp: bigint;
+  chainId: bigint;
+  blockNumber: bigint;
+  transactionIndex: bigint;
+  eventType: number;
+  eventIndex: bigint;
+};
+
+// 10 digits for unix timestamp gets us to the year 2277.
+const BLOCK_TIMESTAMP_DIGITS = 10;
+// Chain IDs are uint256. As of writing the largest Chain ID on https://chainlist.org
+// is 13 digits. 16 digits should be enough (JavaScript's max safe integer).
+const CHAIN_ID_DIGITS = 16;
+// Same logic as chain ID.
+const BLOCK_NUMBER_DIGITS = 16;
+// Same logic as chain ID.
+const TRANSACTION_INDEX_DIGITS = 16;
+// At time of writing, we only have 2 event types planned, so one digit (10 types) is enough.
+const EVENT_TYPE_DIGITS = 1;
+// This could contain log index, trace index, etc. 16 digits should be enough.
+const EVENT_INDEX_DIGITS = 16;
+
+export const decodeCheckpoint = (checkpoint: string): Checkpoint => {
+  let offset = 0;
+
+  const blockTimestamp = BigInt(
+    checkpoint.slice(offset, offset + BLOCK_TIMESTAMP_DIGITS),
+  );
+  offset += BLOCK_TIMESTAMP_DIGITS;
+
+  const chainId = BigInt(checkpoint.slice(offset, offset + CHAIN_ID_DIGITS));
+  offset += CHAIN_ID_DIGITS;
+
+  const blockNumber = BigInt(
+    checkpoint.slice(offset, offset + BLOCK_NUMBER_DIGITS),
+  );
+  offset += BLOCK_NUMBER_DIGITS;
+
+  const transactionIndex = BigInt(
+    checkpoint.slice(offset, offset + TRANSACTION_INDEX_DIGITS),
+  );
+  offset += TRANSACTION_INDEX_DIGITS;
+
+  const eventType = +checkpoint.slice(offset, offset + EVENT_TYPE_DIGITS);
+  offset += EVENT_TYPE_DIGITS;
+
+  const eventIndex = BigInt(
+    checkpoint.slice(offset, offset + EVENT_INDEX_DIGITS),
+  );
+  offset += EVENT_INDEX_DIGITS;
+
+  return {
+    blockTimestamp,
+    chainId,
+    blockNumber,
+    transactionIndex,
+    eventType,
+    eventIndex,
+  };
+};

package/src/hook.ts

@@ -10,6 +10,7 @@ import {
   useQueryClient,
 } from "@tanstack/react-query";
 import { useContext, useEffect, useMemo } from "react";
+import { decodeCheckpoint } from "./checkpoint.js";
 import { PonderContext } from "./context.js";
 import type { ResolvedSchema } from "./index.js";
 import { getPonderQueryOptions } from "./utils.js";
@@ -21,8 +22,10 @@ export function usePonderQuery<
 >(
   params: {
     queryFn: (db: Client<ResolvedSchema>["db"]) => Promise<queryFnData>;
+    live?: boolean;
   } & Omit<UseQueryOptions<queryFnData, error, data>, "queryFn" | "queryKey">,
 ): UseQueryResult<data, error> {
+  const live = params.live ?? true;
   const queryClient = useQueryClient();
 
   const client = usePonderClient();
@@ -35,17 +38,21 @@ export function usePonderQuery<
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: <explanation>
   useEffect(() => {
-    const { unsubscribe } = client.live(
-      () => Promise.resolve(),
-      () => queryClient.invalidateQueries({ queryKey: queryOptions.queryKey }),
-    );
+    if (live === false) return;
+
+    const { unsubscribe } = client.live(queryOptions.queryFn, (data) => {
+      queryClient.setQueryData(queryOptions.queryKey, data);
+    });
     return unsubscribe;
-  }, queryOptions.queryKey);
+  }, [...queryOptions.queryKey, live]);
 
   return useQuery({
     ...params,
     queryKey: queryOptions.queryKey,
     queryFn: queryOptions.queryFn,
+    staleTime: live
+      ? (params.staleTime ?? Number.POSITIVE_INFINITY)
+      : params.staleTime,
   });
 }
 
@@ -67,30 +74,42 @@ export function usePonderQueryOptions<T>(
   return getPonderQueryOptions(client, queryFn);
 }
 
-const statusQueryKey = ["status"];
-
-export function usePonderStatus(
-  params: Omit<UseQueryOptions<Status>, "queryFn" | "queryKey">,
-): UseQueryResult<Status> {
-  const queryClient = useQueryClient();
-
-  const client = useContext(PonderContext);
-  if (client === undefined) {
-    throw new Error("PonderProvider not found");
-  }
-
-  // biome-ignore lint/correctness/useExhaustiveDependencies: <explanation>
-  useEffect(() => {
-    const { unsubscribe } = client.live(
-      () => Promise.resolve(),
-      () => queryClient.invalidateQueries({ queryKey: statusQueryKey }),
-    );
-    return unsubscribe;
-  }, []);
-
-  return useQuery({
+export function usePonderStatus<error = DefaultError>(
+  params?: { live?: boolean } & Omit<
+    UseQueryOptions<
+      { chain_name: string; chain_id: number; latest_checkpoint: string }[],
+      error,
+      Status
+    >,
+    "queryFn" | "queryKey" | "select"
+  >,
+): UseQueryResult<Status, error> {
+  return usePonderQuery<
+    { chain_name: string; chain_id: number; latest_checkpoint: string }[],
+    error,
+    Status
+  >({
     ...params,
-    queryKey: statusQueryKey,
-    queryFn: () => client.getStatus(),
+    queryFn: (db) => db.execute("SELECT * FROM _ponder_checkpoint"),
+    select(checkpoints) {
+      const status: Status = {};
+      for (const {
+        chain_name,
+        chain_id,
+        latest_checkpoint,
+      } of checkpoints.sort((a, b) => (a.chain_id > b.chain_id ? 1 : -1))) {
+        status[chain_name] = {
+          id: chain_id,
+          block: {
+            number: Number(decodeCheckpoint(latest_checkpoint).blockNumber),
+            timestamp: Number(
+              decodeCheckpoint(latest_checkpoint).blockTimestamp,
+            ),
+          },
+        };
+      }
+
+      return status;
+    },
   });
 }

package/src/utils.ts

@@ -16,7 +16,9 @@ export function getPonderQueryOptions<T>(
 
   // @ts-expect-error
   if ("getSQL" in queryPromise === false) {
-    throw new Error('"queryFn" must return SQL');
+    throw new Error(
+      '"queryFn" must return SQL. You may have to remove `.execute()` from your query.',
+    );
   }
 
   const query = compileQuery(queryPromise as unknown as SQLWrapper);