Proposal: Enhanced API for @ic-reactor/react

[b3hr4d]

1. ReactorProvider Enhancements

The New ReactorProvider accepts an actors prop for registering multiple actors at once. This eliminates the need to manually register actors with a separate function, making setup more declarative.

Example Usage:

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import { ReactorProvider } from "@ic-reactor/react";
import { actors } from "./actors";

const root = ReactDOM.createRoot(document.getElementById("root")!);
root.render(
  <React.StrictMode>
    <ReactorProvider actors={actors}>
      <App />
    </ReactorProvider>
  </React.StrictMode>
);

---

2. Registering Actors

The new API allows developers to pass an actors object to ReactorProvider, which registers actors by name. This simplifies managing multiple actors and enables using names as parameters inside hooks.

Usage Example:
The actors object:

// actors.ts
import { defineActor } from "@ic-reactor/react";

export const actors = {
  myCanister: defineActor({
    idlFactory: ({ IDL }) => IDL.Service({
      greet: IDL.Func([IDL.Text], [IDL.Text], []),
    }),
    canisterId: process.env.MY_CANISTER_ID,
  }),
  anotherCanister: defineActor({
    idlFactory: ({ IDL }) => IDL.Service({
      doSomething: IDL.Func([], [IDL.Bool], []),
    }),
    canisterId: process.env.ANOTHER_CANISTER_ID,
  }),
};

---

3. Enhanced Hooks for Actor Methods

New hooks like useQuery, useMutation, and useActor provide flexible interaction with canister methods. Hooks can now take additional parameters for handling callbacks, loading states, and errors.

Example Usage in a Component:

import React from "react";
import { useQuery } from "@ic-reactor/react";

function App() {
  const { data, isLoading, error, refetch } = useQuery("myActor", {
    functionName: "greet",
    args: ["Hello, Internet Computer!"],
    onLoading: (loading) => console.log("Loading:", loading),
    onError: (err) => console.error("Error:", err),
    onSuccess: (data) => console.log("Success:", data),
  });

  return (
    <div>
      <h1>ICP React App</h1>
      {isLoading && <p>Loading...</p>}
      {error && <p>Error: {error.message}</p>}
      <p>{data}</p>
      <button onClick={() => refetch(["New Greeting!"])}>Refetch</button>
    </div>
  );
}

---

4. Advanced Features

• Dynamic Actor Selection: Use actor names dynamically in hooks.
• Built-in Result Compilation: Optional automatic compilation of results (compileResult).

---

Benefits of the Proposal

1. Scalability: Simplifies working with multiple actors by allowing actor registration through a single provider.
2. Flexibility: Advanced hook options accommodate various use cases without extra boilerplate.
3. Developer Experience: Declarative APIs and clear patterns reduce setup time and improve maintainability.

---

Implementation Plan

1. New ReactorProvider: Support for an actors prop to handle actor registration.
2. Update Hooks: Create hooks (useQuery, useMutation, useActor) with the proposed options.
3. Backward Compatibility: Ensure existing APIs remain functional for a smooth transition.
4. Documentation: Provide detailed guides, examples, and type definitions.