@ic-reactor/react 0.0.1

package/LICENSE.md

@@ -0,0 +1,8 @@
+The MIT License (MIT)
+Copyright © 2023 B3Pay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# IC-ReActor - React
+
+`@ic-reactor/react` is a comprehensive React library designed to streamline interactions with the Internet Computer (IC) blockchain. It provides React hooks and utilities for efficient state management, authentication, and interaction with IC actors.
+
+## Features
+
+- **React Hooks Integration**: Custom hooks for managing blockchain actor states and authentication within React applications.
+- **Efficient State Management**: Utilize the power of Zustand for global state management in React components.
+- **Asynchronous Data Handling**: Easy handling of asynchronous operations related to IC actors.
+- **Authentication Support**: Integrated hooks for managing authentication with the IC blockchain.
+- **Auto-Refresh and Query Capabilities**: Support for auto-refreshing data and querying IC actors.
+
+## Installation
+
+Install the package using npm:
+
+```bash
+npm install @ic-reactor/react
+```
+
+or using yarn:
+
+```bash
+yarn add @ic-reactor/react
+```
+
+## Usage
+
+To use `@ic-reactor/react`, start by importing and setting up the `createReActor` function with your actor configurations:
+
+```javascript
+import createReActor from '@ic-reactor/react';
+
+const actorInitializer = /* Your actor initialization logic */;
+const reActorConfig = /* Your ReActor configuration options */;
+
+const { ReActorProvider, useReActorQuery, useReActorUpdate, ... } = createReActor(actorInitializer, reActorConfig);
+```
+
+Then, wrap your React application with the `ReActorProvider` component:
+
+```javascript
+const App = () => (
+  <ReActorProvider>
+    <YourApp />
+  </ReActorProvider>
+)
+```
+
+Finally, use the `useReActorQuery` and `useReActorUpdate` hooks to query and update actor state:
+
+### Example: Querying Actor State
+
+```javascript
+const { recall, data, loading, error } = useQueryCall({
+  functionName: "fetchData",
+  args: ["arg1", "arg2"],
+  autoRefresh: true, // default: true
+  refreshInterval: 3000, // default: 5000
+  disableInitialCall: false, // default: false
+})
+
+// Use 'data', 'loading', 'error' in your component
+```
+
+### Example: Updating Actor State
+
+```javascript
+const { call, data, loading, error } = useUpdateCall({
+  functionName: "updateData",
+  args: ["arg1", "arg2"],
+})
+
+// Call the 'call' function to trigger an update call
+```
+
+## API Reference
+
+The library provides various hooks and utilities for interacting with IC actors:
+
+- `useQueryCall`: Hook for querying data from an actor.
+- `useUpdateCall`: Hook for updating data in an actor.
+- `useReActor`: Hook to access the global actor state.
+- `ReActorProvider`: React context provider for ReActor state.
+- Additional hooks for handling loading, errors, authentication, and more.
+
+For detailed API usage and options, please refer to the [documentation](#).
+
+## Contributing
+
+Contributions to `@ic-reactor/react` are welcome! Please read our [contributing guidelines](#) for more information.
+
+## License
+
+`@ic-reactor/react` is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
+
+---
+
+This README provides a foundational overview of your package. You should expand it with more detailed documentation, examples, and links to additional resources or documentation as needed. Replace placeholders with actual information and links relevant to your project.

package/dist/hooks.d.ts

@@ -0,0 +1,23 @@
+import { CallMethod, ExtractReActorMethodArgs, ReActorState } from "@ic-reactor/store";
+import { StoreApi } from "zustand";
+import { ReActorUseQueryArgs, ReActorUseUpdateArgs } from "./types";
+export declare const getStateHooks: <A extends unknown>(store: StoreApi<ReActorState<A>>, callMethod: CallMethod<A>) => {
+    useReActor: () => ReActorState<A>;
+    useLoading: () => boolean;
+    useError: () => Error | undefined;
+    useInitialized: () => boolean;
+    useInitializing: () => boolean;
+    useActorState: () => import("@ic-reactor/store").ReActorActorState<A>;
+    useQueryCall: <M extends keyof A>({ autoRefresh, refreshInterval, disableInitialCall, ...rest }: ReActorUseQueryArgs<A, M>) => {
+        data: import("@ic-reactor/store").ExtractReActorMethodReturnType<A[M]> | undefined;
+        error: Error | undefined;
+        loading: boolean;
+        recall: (replaceArgs?: ExtractReActorMethodArgs<A[M]> | undefined) => Promise<import("@ic-reactor/store").ExtractReActorMethodReturnType<A[M]>>;
+    };
+    useUpdateCall: <M_1 extends keyof A>(args: ReActorUseUpdateArgs<A, M_1>) => {
+        data: import("@ic-reactor/store").ExtractReActorMethodReturnType<A[M_1]> | undefined;
+        error: Error | undefined;
+        loading: boolean;
+        call: (replaceArgs?: ExtractReActorMethodArgs<A[M_1]> | undefined) => Promise<import("@ic-reactor/store").ExtractReActorMethodReturnType<A[M_1]>>;
+    };
+};

package/dist/hooks.js

@@ -0,0 +1,112 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getStateHooks = void 0;
+const react_1 = require("react");
+const zustand_1 = require("zustand");
+const getStateHooks = (store, callMethod) => {
+    const useReActor = () => {
+        const state = (0, zustand_1.useStore)(store);
+        return state;
+    };
+    const useLoading = () => {
+        const loading = (0, zustand_1.useStore)(store, (state) => state.loading);
+        return loading;
+    };
+    const useError = () => {
+        const error = (0, zustand_1.useStore)(store, (state) => state.error);
+        return error;
+    };
+    const useInitialized = () => {
+        const initialized = (0, zustand_1.useStore)(store, (state) => state.initialized);
+        return initialized;
+    };
+    const useInitializing = () => {
+        const initializing = (0, zustand_1.useStore)(store, (state) => state.initializing);
+        return initializing;
+    };
+    const useActorState = () => {
+        const actorState = (0, zustand_1.useStore)(store, (state) => state.actorState);
+        return actorState;
+    };
+    const useReActorCall = ({ onError, onSuccess, onLoading, args = [], functionName, }) => {
+        const [state, setState] = (0, react_1.useState)({
+            data: undefined,
+            error: undefined,
+            loading: false,
+        });
+        const call = (0, react_1.useCallback)((replaceArgs) => __awaiter(void 0, void 0, void 0, function* () {
+            onLoading === null || onLoading === void 0 ? void 0 : onLoading(true);
+            onError === null || onError === void 0 ? void 0 : onError(undefined);
+            setState((prevState) => (Object.assign(Object.assign({}, prevState), { loading: true, error: undefined })));
+            try {
+                const data = yield callMethod(functionName, ...(replaceArgs !== null && replaceArgs !== void 0 ? replaceArgs : args));
+                onLoading === null || onLoading === void 0 ? void 0 : onLoading(false);
+                onSuccess === null || onSuccess === void 0 ? void 0 : onSuccess(data);
+                setState((prevState) => (Object.assign(Object.assign({}, prevState), { data, loading: false })));
+                return data;
+            }
+            catch (error) {
+                onError === null || onError === void 0 ? void 0 : onError(error);
+                onLoading === null || onLoading === void 0 ? void 0 : onLoading(false);
+                setState((prevState) => (Object.assign(Object.assign({}, prevState), { error: error, loading: false })));
+                throw error;
+            }
+        }), [args, functionName, onError, onSuccess, onLoading]);
+        return Object.assign({ call }, state);
+    };
+    const useQueryCall = (_a) => {
+        var { autoRefresh, refreshInterval = 5000, disableInitialCall } = _a, rest = __rest(_a, ["autoRefresh", "refreshInterval", "disableInitialCall"]);
+        const _b = useReActorCall(rest), { call: recall } = _b, state = __rest(_b, ["call"]);
+        let intervalId = (0, react_1.useRef)(undefined);
+        (0, react_1.useEffect)(() => {
+            // Auto-refresh logic
+            if (autoRefresh) {
+                intervalId.current = setInterval(() => {
+                    recall();
+                }, refreshInterval);
+            }
+            // Initial call logic
+            if (!disableInitialCall) {
+                recall();
+            }
+            return () => {
+                clearInterval(intervalId.current);
+            };
+        }, [disableInitialCall, autoRefresh, refreshInterval]);
+        return Object.assign({ recall }, state);
+    };
+    const useUpdateCall = (args) => {
+        return useReActorCall(args);
+    };
+    return {
+        useReActor,
+        useLoading,
+        useError,
+        useInitialized,
+        useInitializing,
+        useActorState,
+        useQueryCall,
+        useUpdateCall,
+    };
+};
+exports.getStateHooks = getStateHooks;

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+/// <reference types="react" />
+import type { HttpAgent, HttpAgentOptions } from "@dfinity/agent";
+import { AuthClientLoginOptions } from "@dfinity/auth-client";
+import type { ActorSubclass, ReActorStore } from "@ic-reactor/store";
+export type ReActorContextType<A = ActorSubclass<any>> = ReActorStore<A>;
+export interface CreateReActorOptions extends HttpAgentOptions {
+    initializeOnMount?: boolean;
+}
+export declare const createReActor: <A extends unknown>(actorInitializer: (agent: HttpAgent) => A, options?: CreateReActorOptions) => {
+    useReActor: () => import("@ic-reactor/store").ReActorState<A>;
+    useLoading: () => boolean;
+    useError: () => Error | undefined;
+    useQueryCall: <M extends keyof A>({ autoRefresh, refreshInterval, disableInitialCall, ...rest }: import("./types").ReActorUseQueryArgs<A, M>) => {
+        data: import("@ic-reactor/store").ExtractReActorMethodReturnType<A[M]> | undefined;
+        error: Error | undefined;
+        loading: boolean;
+        recall: (replaceArgs?: import("@ic-reactor/store").ExtractReActorMethodArgs<A[M]> | undefined) => Promise<import("@ic-reactor/store").ExtractReActorMethodReturnType<A[M]>>;
+    };
+    useUpdateCall: <M_1 extends keyof A>(args: import("./types").ReActorUseUpdateArgs<A, M_1>) => {
+        data: import("@ic-reactor/store").ExtractReActorMethodReturnType<A[M_1]> | undefined;
+        error: Error | undefined;
+        loading: boolean;
+        call: (replaceArgs?: import("@ic-reactor/store").ExtractReActorMethodArgs<A[M_1]> | undefined) => Promise<import("@ic-reactor/store").ExtractReActorMethodReturnType<A[M_1]>>;
+    };
+    useAuthClient: () => {
+        authClient: import("@dfinity/auth-client").AuthClient | null;
+        authenticated: boolean;
+        authenticating: boolean;
+        identity: import("@dfinity/agent").Identity | null;
+        login: (options?: AuthClientLoginOptions) => Promise<void>;
+        logout: (options?: {
+            returnTo?: string;
+        }) => Promise<void>;
+        authenticate: () => Promise<void>;
+        loginLoading: boolean;
+        loginError: unknown;
+    };
+    useActorState: () => import("@ic-reactor/store").ReActorActorState<A>;
+    useInitialized: () => boolean;
+    useInitializing: () => boolean;
+    initialize: (identity?: import("@dfinity/agent").Identity | undefined) => void;
+    authenticate: () => Promise<void>;
+    resetState: () => void;
+    updateState: (newState: Partial<import("@ic-reactor/store").ReActorState<A>>) => void;
+    callMethod: import("@ic-reactor/store").CallMethod<A>;
+    ReActorProvider: import("react").FC<{
+        children: React.ReactNode;
+    }>;
+};
+export default createReActor;

package/dist/index.js

@@ -0,0 +1,102 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReActor = void 0;
+const store_1 = __importDefault(require("@ic-reactor/store"));
+const react_1 = require("react");
+const hooks_1 = require("./hooks");
+const defaultCreateReActorOptions = {
+    initializeOnMount: true,
+    host: process.env.NODE_ENV === "production"
+        ? "https://icp-api.io"
+        : "http://localhost:4943",
+};
+const createReActor = (actorInitializer, options = {}) => {
+    const optionsWithDefaults = Object.assign(Object.assign({}, defaultCreateReActorOptions), options);
+    const Context = (0, react_1.createContext)(undefined);
+    const { actions, initializeActor, store } = (0, store_1.default)((agent) => actorInitializer(agent), optionsWithDefaults);
+    if (optionsWithDefaults.initializeOnMount) {
+        try {
+            initializeActor();
+        }
+        catch (e) {
+            console.error(e);
+        }
+    }
+    const ReActorProvider = ({ children, }) => {
+        (0, react_1.useEffect)(() => actions.resetState, [actions.resetState]);
+        return (0, react_1.createElement)(Context.Provider, { value: store }, children);
+    };
+    const { useReActor, useLoading, useError, useQueryCall, useUpdateCall, useInitialized, useInitializing, useActorState, } = (0, hooks_1.getStateHooks)(store, actions.callMethod);
+    const useAuthClient = () => {
+        const [loginLoading, setLoginLoading] = (0, react_1.useState)(false);
+        const [loginError, setLoginError] = (0, react_1.useState)(null);
+        const { authClient, authenticated, authenticating, identity } = useReActor();
+        const authenticate = () => __awaiter(void 0, void 0, void 0, function* () {
+            yield actions.authenticate();
+        });
+        const login = (options) => __awaiter(void 0, void 0, void 0, function* () {
+            setLoginLoading(true);
+            setLoginError(null);
+            try {
+                yield (authClient === null || authClient === void 0 ? void 0 : authClient.login(Object.assign(Object.assign({}, options), { onSuccess: () => __awaiter(void 0, void 0, void 0, function* () {
+                        var _a;
+                        setLoginLoading(false);
+                        yield authenticate();
+                        (_a = options === null || options === void 0 ? void 0 : options.onSuccess) === null || _a === void 0 ? void 0 : _a.call(options);
+                    }), onError: (e) => {
+                        var _a;
+                        setLoginError(e);
+                        setLoginLoading(false);
+                        (_a = options === null || options === void 0 ? void 0 : options.onError) === null || _a === void 0 ? void 0 : _a.call(options, e);
+                    } })));
+            }
+            catch (e) {
+                setLoginLoading(false);
+                setLoginError(e);
+            }
+        });
+        const logout = (options) => __awaiter(void 0, void 0, void 0, function* () {
+            yield (authClient === null || authClient === void 0 ? void 0 : authClient.logout(options));
+            yield authenticate();
+        });
+        (0, react_1.useEffect)(() => {
+            if (!authClient && !authenticating) {
+                authenticate();
+            }
+        }, [authClient, authenticating]);
+        return {
+            authClient,
+            authenticated,
+            authenticating,
+            identity,
+            login,
+            logout,
+            authenticate,
+            loginLoading,
+            loginError,
+        };
+    };
+    return Object.assign(Object.assign({ ReActorProvider }, actions), { useReActor,
+        useLoading,
+        useError,
+        useQueryCall,
+        useUpdateCall,
+        useAuthClient,
+        useActorState,
+        useInitialized,
+        useInitializing });
+};
+exports.createReActor = createReActor;
+exports.default = exports.createReActor;

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+import { ExtractReActorMethodArgs, ExtractReActorMethodReturnType } from "@ic-reactor/store";
+export type ReActorCallArgs<A, M extends keyof A> = {
+    functionName: M;
+    args?: ExtractReActorMethodArgs<A[M]>;
+    onLoading?: (loading: boolean) => void;
+    onError?: (error: Error | unknown) => void;
+    onSuccess?: (data: ExtractReActorMethodReturnType<A[M]> | undefined) => void;
+};
+export type ReActorHookState<A, M extends keyof A> = {
+    data: ExtractReActorMethodReturnType<A[M]> | undefined;
+    error: Error | undefined;
+    loading: boolean;
+};
+export interface ReActorUseQueryArgs<A, M extends keyof A> extends ReActorCallArgs<A, M> {
+    disableInitialCall?: boolean;
+    autoRefresh?: boolean;
+    refreshInterval?: number;
+}
+export interface ReActorUseUpdateArgs<A, M extends keyof A> extends ReActorCallArgs<A, M> {
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@ic-reactor/react",
+  "version": "0.0.1",
+  "description": "A React library for interacting with Dfinity actors",
+  "main": "dist/index.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/*"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:b3hr4d/ic-reactor.git"
+  },
+  "keywords": [
+    "actor",
+    "react",
+    "candid",
+    "dfinity",
+    "web3",
+    "dapp"
+  ],
+  "author": "b3hr4d",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/b3hr4d/ic-reactor/issues"
+  },
+  "homepage": "https://github.com/b3hr4d/ic-reactor/tree/main/packages/react#readme",
+  "scripts": {
+    "test": "npx jest",
+    "start": "tsc watch",
+    "build": "npx tsc",
+    "clean": "rimraf dist"
+  },
+  "engines": {
+    "node": ">=10"
+  },
+  "dependencies": {
+    "@dfinity/agent": "^0.20",
+    "@dfinity/auth-client": "^0.20",
+    "@dfinity/candid": "0.20",
+    "@dfinity/identity": "^0.20",
+    "@dfinity/principal": "^0.20",
+    "@ic-reactor/store": "^0.0.1",
+    "zustand": "4.4"
+  },
+  "peerDependencies": {
+    "@peculiar/webcrypto": "1.4",
+    "react": ">=16.8"
+  },
+  "gitHead": "b1f673a150b591ad3cfbb8964794e4ea9b0ff1c2"
+}