@dappql/react 1.0.5 → 1.0.9

package/README.md

@@ -0,0 +1,143 @@
+# @dappql/react
+
+> React hooks for [DappQL](https://github.com/dappql/core). Typed, batched smart-contract reads and writes on top of [wagmi](https://wagmi.sh) + [viem](https://viem.sh), with automatic multicall fusion across your entire component tree, per-block reactivity, iterator queries, and mutation tracking.
+
+## Install
+
+```bash
+npm install @dappql/react wagmi viem @tanstack/react-query
+```
+
+Pair with the [`dappql`](https://www.npmjs.com/package/dappql) CLI to generate your typed contract modules.
+
+## Provider
+
+```tsx
+import { WagmiProvider } from 'wagmi'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { DappQLProvider } from '@dappql/react'
+
+const queryClient = new QueryClient()
+
+export function Root({ children }) {
+  return (
+    <WagmiProvider config={wagmiConfig}>
+      <QueryClientProvider client={queryClient}>
+        <DappQLProvider watchBlocks>{children}</DappQLProvider>
+      </QueryClientProvider>
+    </WagmiProvider>
+  )
+}
+```
+
+Provider options:
+
+| Option | Purpose |
+| --- | --- |
+| `watchBlocks` | Refetch on every new block, makes reads reactive to chain state. |
+| `simulateMutations` | Preflight every tx via `eth_call`. Aborts on revert. |
+| `onMutationUpdate` | Single callback for every transaction lifecycle event, one place to drive toasts, analytics, receipts. |
+| `addressResolver` | Function that resolves contract names to addresses, for registries, proxies, multi-deploy. |
+| `AddressResolverComponent` | Async alternative to `addressResolver` when the resolver needs hooks. |
+
+## Reads
+
+### `useContextQuery`: the default
+
+Batches calls across your **entire** component tree into one multicall.
+
+```tsx
+import { Token, ToDo } from './contracts'
+import { useContextQuery } from '@dappql/react'
+
+function Dashboard({ account }) {
+  const { data, isLoading } = useContextQuery({
+    balance: Token.call.balanceOf(account),
+    symbol: Token.call.symbol(),
+    totalTasks: ToDo.call.totalTasks(),
+  })
+
+  if (isLoading) return <Spinner />
+  return <p>{data.balance.toString()} {data.symbol}</p>
+}
+```
+
+If `<Dashboard>` and `<Sidebar>` both use `useContextQuery`, their calls fuse into one RPC, not two.
+
+### `useQuery`: component-scoped batching
+
+Same shape as `useContextQuery`, but scoped to this hook call. Use when you need `blockNumber`, `paused`, custom `refetchInterval`, or `batchSize` overrides.
+
+### `useSingleQuery` / `useSingleContextQuery`
+
+```tsx
+const { data } = useSingleContextQuery(Token.call.balanceOf(account))
+// data: bigint (inferred from the ABI)
+```
+
+### `useIteratorQuery`: on-chain arrays
+
+```tsx
+import { useIteratorQuery } from '@dappql/react'
+
+const { data } = useIteratorQuery(totalTasks, (i) => ToDo.call.taskAt(account, i))
+```
+
+## Writes
+
+```tsx
+import { useMutation } from '@dappql/react'
+import { ToDo } from './contracts'
+
+function NewTask() {
+  const mutation = useMutation(ToDo.mutation.addItem, 'Add task')
+
+  return (
+    <button
+      disabled={mutation.isLoading}
+      onClick={() => mutation.send('Buy milk', 0n)}
+    >
+      {mutation.confirmation.isSuccess ? 'Added' : 'Add task'}
+    </button>
+  )
+}
+```
+
+Surface:
+
+```ts
+mutation.send(...args)              // broadcast; spread args, not array
+mutation.simulate(...args)          // manual preflight
+mutation.estimate(...args)          // gas estimate
+mutation.isPending                  // awaiting signature
+mutation.isLoading                  // awaiting signature OR mining
+mutation.confirmation.isSuccess     // receipt confirmed
+mutation.reset()
+```
+
+## Fluent request API
+
+Every generated call exposes a small fluent API for overrides:
+
+```ts
+Token.call.balanceOf(account)
+  .at('0x...')       // override deploy address
+  .defaultTo(0n)     // default value until the call resolves
+```
+
+## Related packages
+
+| Package | Purpose |
+| --- | --- |
+| [`dappql`](https://www.npmjs.com/package/dappql) | Codegen CLI, generates the typed contract modules you import above |
+| [`@dappql/async`](https://www.npmjs.com/package/@dappql/async) | Non-React runtime, same typed calls, no React required |
+| [`@dappql/codegen`](https://www.npmjs.com/package/@dappql/codegen) | Framework-agnostic codegen engine |
+| [`@dappql/mcp`](https://www.npmjs.com/package/@dappql/mcp) | MCP server, live contract context for AI coding agents |
+
+## Full documentation
+
+[github.com/dappql/core](https://github.com/dappql/core)
+
+## License
+
+MIT

package/dist/ContextQueryManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ContextQueryManager.d.ts","sourceRoot":"","sources":["../src/ContextQueryManager.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,GAAG,EAAa,OAAO,EAAE,MAAM,MAAM,CAAA;AAE9C,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAW,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAGxH,KAAK,KAAK,GAAG;IAAE,UAAU,EAAE,iBAAiB,CAAC;IAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,IAAI,CAAA;CAAE,CAAA;AAC/F;;GAEG;AACH,KAAK,IAAI,GAAG;IACV,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,GAAG,CAAA;IACR,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,SAAS,GAAG,EAAE,CAAA;IACpB,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;GAEG;AACH,KAAK,YAAY,GAAG;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,KAAK,EAAE,IAAI,EAAE,CAAA;CACd,CAAA;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,UAAU,CAAqD;IACvE,OAAO,CAAC,OAAO,CAAI;IACnB,OAAO,CAAC,OAAO,CAAY;IAC3B,OAAO,CAAC,eAAe,CAAC,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAsC;IAEtD;;;;OAIG;gBACS,QAAQ,EAAE,CAAC,YAAY,EAAE,YAAY,KAAK,GAAG,EAAE,eAAe,CAAC,EAAE,uBAAuB;IAKpG,eAAe,IAAI,YAAY;IAI/B,UAAU,IAAI,MAAM;IAIpB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAQ9B,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAM7B,OAAO,CAAC,gBAAgB;IAsCxB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,uBAAuB;IAKrD,QAAQ,CAAC,MAAM,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM;CAuBtD;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,QAAQ,EACR,gBAAgB,EAChB,WAAW,EACX,qBAAqB,GACtB,EAAE;IAAE,QAAQ,EAAE,GAAG,CAAA;CAAE,GAAG,iBAAiB,2CAiCvC;AAED,wBAAgB,uBAAuB,wBAEtC"}
+{"version":3,"file":"ContextQueryManager.d.ts","sourceRoot":"","sources":["../src/ContextQueryManager.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,GAAG,EAAa,OAAO,EAAE,MAAM,MAAM,CAAA;AAE9C,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAW,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAGxH,KAAK,KAAK,GAAG;IAAE,UAAU,EAAE,iBAAiB,CAAC;IAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,IAAI,CAAA;CAAE,CAAA;AAC/F;;GAEG;AACH,KAAK,IAAI,GAAG;IACV,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,GAAG,CAAA;IACR,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,SAAS,GAAG,EAAE,CAAA;IACpB,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;GAEG;AACH,KAAK,YAAY,GAAG;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,KAAK,EAAE,IAAI,EAAE,CAAA;CACd,CAAA;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,UAAU,CAAqD;IACvE,OAAO,CAAC,OAAO,CAAI;IACnB,OAAO,CAAC,OAAO,CAAY;IAC3B,OAAO,CAAC,eAAe,CAAC,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAsC;IAEtD;;;;OAIG;gBACS,QAAQ,EAAE,CAAC,YAAY,EAAE,YAAY,KAAK,GAAG,EAAE,eAAe,CAAC,EAAE,uBAAuB;IAKpG,eAAe,IAAI,YAAY;IAI/B,UAAU,IAAI,MAAM;IAIpB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM;IAQ9B,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAM7B,OAAO,CAAC,gBAAgB;IAsCxB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,uBAAuB;IAKrD,QAAQ,CAAC,MAAM,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM;CAuBtD;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,QAAQ,EACR,gBAAgB,EAChB,WAAW,EACX,qBAAqB,GACtB,EAAE;IAAE,QAAQ,EAAE,GAAG,CAAA;CAAE,GAAG,iBAAiB,2CAwCvC;AAED,wBAAgB,uBAAuB,wBAEtC"}

package/dist/ContextQueryManager.js

@@ -116,7 +116,13 @@ export function ContextQueryProvider({ children, defaultBatchSize, watchBlocks,
     const queryManager = useMemo(() => new ContextQueryManager(setQuery, addressResolver), []);
     const [blockNumber, setBlockNumber] = useState();
     useEffect(() => {
-        const unsubscribe = onBlockChange((blockNumber) => setBlockNumber(blockNumber));
+        const unsubscribe = onBlockChange((block) => {
+            // Only set block number if it's a real block (not genesis)
+            // This prevents querying at block 0 before the subscription initializes
+            if (block > 0n) {
+                setBlockNumber(block);
+            }
+        });
         return () => {
             unsubscribe();
         };
@@ -130,7 +136,8 @@ export function ContextQueryProvider({ children, defaultBatchSize, watchBlocks,
             notifyOnChangeProps: ['data', 'error'],
         },
         batchSize: defaultBatchSize,
-        blockNumber: blockNumber,
+        // Don't pass blockNumber until we have a real one - let wagmi use "latest"
+        blockNumber: blockNumber && blockNumber > 0n ? blockNumber : undefined,
     });
     useRefetchOnBlockChange(result.refetch, watchBlocks && !!query.calls.length, blocksRefetchInterval);
     useEffect(() => {

package/dist/blocksHandler.d.ts

@@ -3,7 +3,7 @@ export declare class BlockSubscriptionManager {
     private subscribers;
     private currentBlock;
     subscribe(callback: Subscriber): () => boolean;
-    onBlockUptated(newBlock: bigint): void;
+    onBlockUpdated(newBlock: bigint): void;
 }
 export declare function useBlockNumberSubscriber(): (callback: Subscriber) => () => boolean;
 export {};

package/dist/blocksHandler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blocksHandler.d.ts","sourceRoot":"","sources":["../src/blocksHandler.ts"],"names":[],"mappings":"AAGA,KAAK,UAAU,GAAG,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAA;AAE/C,qBAAa,wBAAwB;IACnC,OAAO,CAAC,WAAW,CAAwB;IAC3C,OAAO,CAAC,YAAY,CAAa;IAEjC,SAAS,CAAC,QAAQ,EAAE,UAAU;IAO9B,cAAc,CAAC,QAAQ,EAAE,MAAM;CAIhC;AAED,wBAAgB,wBAAwB,eAazB,UAAU,mBAKxB"}
+{"version":3,"file":"blocksHandler.d.ts","sourceRoot":"","sources":["../src/blocksHandler.ts"],"names":[],"mappings":"AAGA,KAAK,UAAU,GAAG,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAA;AAE/C,qBAAa,wBAAwB;IACnC,OAAO,CAAC,WAAW,CAAwB;IAC3C,OAAO,CAAC,YAAY,CAAgC;IAEpD,SAAS,CAAC,QAAQ,EAAE,UAAU;IAS9B,cAAc,CAAC,QAAQ,EAAE,MAAM;CAIhC;AAED,wBAAgB,wBAAwB,eAazB,UAAU,mBAKxB"}

package/dist/blocksHandler.js

@@ -3,15 +3,17 @@ import { usePublicClient } from 'wagmi';
 export class BlockSubscriptionManager {
     constructor() {
         this.subscribers = new Set();
-        this.currentBlock = 0n;
+        this.currentBlock = undefined;
     }
     subscribe(callback) {
         this.subscribers.add(callback);
-        // Immediately call with current value
-        callback(this.currentBlock);
+        // Only call immediately if we have a real block number
+        if (this.currentBlock !== undefined && this.currentBlock > 0n) {
+            callback(this.currentBlock);
+        }
         return () => this.subscribers.delete(callback);
     }
-    onBlockUptated(newBlock) {
+    onBlockUpdated(newBlock) {
         this.currentBlock = newBlock;
         this.subscribers.forEach((sub) => sub(newBlock));
     }
@@ -22,7 +24,7 @@ export function useBlockNumberSubscriber() {
     useEffect(() => {
         return client?.watchBlockNumber({
             onBlockNumber: (blockNumber) => {
-                manager.onBlockUptated(blockNumber);
+                manager.onBlockUpdated(blockNumber);
             },
         });
     }, [client, manager]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dappql/react",
-  "version": "1.0.5",
+  "version": "1.0.9",
   "description": "Streamlined smart contract data fetching library for React dApps with TypeScript support",
   "author": "DappQL Team",
   "type": "module",
@@ -28,12 +28,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/dappql/monorepo.git"
+    "url": "git+https://github.com/dappql/core.git"
   },
   "bugs": {
-    "url": "https://github.com/dappql/monorepo/issues"
+    "url": "https://github.com/dappql/core/issues"
   },
-  "homepage": "https://github.com/dappql/monorepo#readme",
+  "homepage": "https://github.com/dappql/core#readme",
   "license": "MIT",
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",