@ic-reactor/core 2.0.0-alpha.0 → 2.0.1

package/dist/classes/agent/types.d.ts

@@ -1,27 +1,87 @@
-import type { HttpAgent, HttpAgentOptions, Identity } from "@dfinity/agent";
+import type { AgentError, HttpAgent, HttpAgentOptions, Identity } from "@dfinity/agent";
 import type { AuthClient } from "@dfinity/auth-client";
-import type { StoreApiWithDevtools } from "../../types";
+import type { StoreWithAllMiddleware } from "../../types";
 export { HttpAgentOptions, AuthClient, Identity };
+/**
+ * Parameters for configuring an AgentManager instance.
+ * Extends the options available in `HttpAgentOptions`.
+ *
+ * @extends HttpAgentOptions
+ *
+ * @property {number} [port] - The port number to be used by the agent.
+ * @property {boolean} [withLocalEnv] - Whether to include local environment variables.
+ * @property {boolean} [withDevtools] - Whether to enable developer tools integration.
+ * @property {boolean} [withProcessEnv] - Whether to include process environment variables.
+ * @property {boolean} [initializeOnCreate] - Whether to initialize the agent upon creation.
+ */
 export interface AgentManagerParameters extends HttpAgentOptions {
     port?: number;
     withLocalEnv?: boolean;
     withDevtools?: boolean;
     withProcessEnv?: boolean;
+    initializeOnCreate?: boolean;
 }
+/**
+ * Represents the state of an agent.
+ */
 export interface AgentState {
+    /**
+     * @deprecated Use `isInitialized` instead.
+     * Indicates whether the agent has been initialized.
+     */
     initialized: boolean;
+    /**
+     * Indicates whether the agent has been initialized.
+     */
+    isInitialized: boolean;
+    /**
+     * @deprecated Use `isInitializing` instead.
+     * Indicates whether the agent is in the process of initializing.
+     */
     initializing: boolean;
-    error: Error | undefined;
-    network: string;
+    /**
+     * Indicates whether the agent is in the process of initializing.
+     */
+    isInitializing: boolean;
+    /**
+     * Represents an error associated with the agent, if any.
+     */
+    error: AgentError | undefined;
+    /**
+     * Represents the network associated with the agent, if any.
+     */
+    network: string | undefined;
 }
+/**
+ * Represents the authentication state of an agent.
+ */
 export interface AuthState {
     identity: Identity | null;
+    /**
+     * @deprecated Use `isAuthenticating` instead.
+     * Indicates whether the authentication process is ongoing.
+     */
     authenticating: boolean;
+    /**
+     * Indicates whether the authentication process is ongoing.
+     */
+    isAuthenticating: boolean;
+    /**
+     * @deprecated Use `isAuthenticated` instead.
+     * Indicates whether the agent is authenticated.
+     */
     authenticated: boolean;
+    /**
+     * Indicates whether the agent is authenticated.
+     */
+    isAuthenticated: boolean;
+    /**
+     * Represents any error that occurred during authentication.
+     */
     error: Error | undefined;
 }
 export interface UpdateAgentParameters extends HttpAgentOptions {
     agent?: HttpAgent;
 }
-export type AgentStore = StoreApiWithDevtools<AgentState>;
-export type AuthStore = StoreApiWithDevtools<AuthState>;
+export type AgentStore = StoreWithAllMiddleware<AgentState>;
+export type AuthStore = StoreWithAllMiddleware<AuthState>;

package/dist/classes/types.d.ts

@@ -1,8 +1,15 @@
 export * from "./agent/types";
 export * from "./actor/types";
 export * from "./adapter/types";
-import { NamedSet } from "zustand/middleware";
-import type { StoreApi } from "zustand";
-export interface StoreApiWithDevtools<T> extends StoreApi<T> {
-    setState: NamedSet<T>;
-}
+import { type StateCreator, type StoreApi, type StoreMutatorIdentifier, type Mutate } from "zustand";
+export type StoreWithMiddleware<T, Mis extends [StoreMutatorIdentifier, unknown][] = [], Mos extends [StoreMutatorIdentifier, unknown][] = []> = StateCreator<T, Mis, Mos>;
+export type StoreApiWithMiddleware<T, Mos extends [StoreMutatorIdentifier, unknown][] = []> = Mutate<StoreApi<T>, Mos>;
+export type WithDevtools = ["zustand/devtools", never];
+export type WithSubscribeSelector = ["zustand/subscribeWithSelector", never];
+export type StoreWithAllMiddleware<T> = StoreApiWithMiddleware<T, [
+    WithDevtools,
+    WithSubscribeSelector
+]>;
+export type StoreWithSubscribeOnly<T> = StoreApiWithMiddleware<T, [
+    WithSubscribeSelector
+]>;

package/dist/classes/types.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// Re-export existing types
 __exportStar(require("./agent/types"), exports);
 __exportStar(require("./actor/types"), exports);
 __exportStar(require("./adapter/types"), exports);

package/dist/createReactorCore.js

@@ -1,24 +1,4 @@
 "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.createReactorCore = void 0;
 const createReactorStore_1 = require("./createReactorStore");
@@ -32,7 +12,7 @@ const utils_1 = require("./utils");
  * @includeExample ./packages/core/README.md:32-86
  */
 const createReactorCore = (config) => {
-    const _a = (0, createReactorStore_1.createReactorStore)(config), { subscribeActorState, updateMethodState, callMethodWithOptions, callMethod, getState, agentManager } = _a, rest = __rest(_a, ["subscribeActorState", "updateMethodState", "callMethodWithOptions", "callMethod", "getState", "agentManager"]);
+    const { subscribeActorState, updateMethodState, callMethodWithOptions, callMethod, getState, agentManager, ...rest } = (0, createReactorStore_1.createReactorStore)(config);
     const actorMethod = (functionName, args, options = {}) => {
         const requestHash = (0, utils_1.generateRequestHash)(args);
         const updateState = (newState = {}) => {
@@ -64,13 +44,13 @@ const createReactorCore = (config) => {
                 });
                 return unsubscribe;
             };
-            const call = (replaceArgs) => __awaiter(void 0, void 0, void 0, function* () {
+            const call = async (replaceArgs) => {
                 updateState({
                     loading: true,
                     error: undefined,
                 });
                 try {
-                    const data = yield callMethodWithOptions(options)(functionName, ...(replaceArgs !== null && replaceArgs !== void 0 ? replaceArgs : args));
+                    const data = await callMethodWithOptions(options)(functionName, ...(replaceArgs ?? args));
                     updateState({ data, loading: false });
                     return data;
                 }
@@ -81,7 +61,7 @@ const createReactorCore = (config) => {
                     });
                     throw error;
                 }
-            });
+            };
             return {
                 requestHash,
                 subscribe,
@@ -97,10 +77,9 @@ const createReactorCore = (config) => {
             throw error;
         }
     };
-    const queryCall = (_a) => {
-        var { functionName, args = [], refetchOnMount = true, refetchInterval = false } = _a, options = __rest(_a, ["functionName", "args", "refetchOnMount", "refetchInterval"]);
+    const queryCall = ({ functionName, args = [], refetchOnMount = true, refetchInterval = false, ...options }) => {
         let intervalId = null;
-        const _b = actorMethod(functionName, args, options), { call } = _b, rest = __rest(_b, ["call"]);
+        const { call, ...rest } = actorMethod(functionName, args, options);
         if (refetchInterval) {
             intervalId = setInterval(() => {
                 call();
@@ -114,17 +93,20 @@ const createReactorCore = (config) => {
         let dataPromise = Promise.resolve();
         if (refetchOnMount)
             dataPromise = call();
-        return Object.assign(Object.assign({}, rest), { call, dataPromise, intervalId, clearRefetchInterval });
+        return { ...rest, call, dataPromise, intervalId, clearRefetchInterval };
     };
-    const updateCall = (_a) => {
-        var { functionName, args = [] } = _a, options = __rest(_a, ["functionName", "args"]);
+    const updateCall = ({ functionName, args = [], ...options }) => {
         return actorMethod(functionName, args, options);
     };
-    return Object.assign(Object.assign({ getState,
+    return {
+        getState,
         queryCall,
         updateCall,
         callMethod,
         callMethodWithOptions,
-        subscribeActorState }, agentManager), rest);
+        subscribeActorState,
+        ...agentManager,
+        ...rest,
+    };
 };
 exports.createReactorCore = createReactorCore;

package/dist/createReactorStore.js

@@ -1,15 +1,4 @@
 "use strict";
-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.createReactorStore = void 0;
 const createActorManager_1 = require("./createActorManager");
@@ -23,9 +12,12 @@ const createAgentManager_1 = require("./createAgentManager");
  * @includeExample ./packages/core/README.md:200-225
  */
 const createReactorStore = (config) => {
-    const { idlFactory, canisterId, withDevtools = false, initializeOnCreate = true, withVisitor = false, agentManager: maybeAgentManager } = config, agentParameters = __rest(config, ["idlFactory", "canisterId", "withDevtools", "initializeOnCreate", "withVisitor", "agentManager"]);
+    const { idlFactory, canisterId, withDevtools = false, initializeOnCreate = true, withVisitor = false, agentManager: maybeAgentManager, ...agentParameters } = config;
     const agentManager = maybeAgentManager ||
-        (0, createAgentManager_1.createAgentManager)(Object.assign({ withDevtools }, agentParameters));
+        (0, createAgentManager_1.createAgentManager)({
+            withDevtools,
+            ...agentParameters,
+        });
     const actorManager = (0, createActorManager_1.createActorManager)({
         idlFactory,
         canisterId,

package/dist/index.js

@@ -18,13 +18,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.utils = exports.types = exports.classes = void 0;
 __exportStar(require("./createReactorCore"), exports);

package/dist/types.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 import type { ActorMethod, ActorSubclass, HttpAgentOptions, HttpAgent, Identity, CallConfig } from "@dfinity/agent";
 import type { Principal } from "@dfinity/principal";
 import type { IDL } from "@dfinity/candid";
@@ -49,9 +48,49 @@ export interface ActorUpdateParameters<A, M extends FunctionName<A>> extends Cal
 export type ActorMethodCall<A = Record<string, ActorMethod>> = <M extends FunctionName<A>>(functionName: M, args: ActorMethodParameters<A[M]>, options?: CallConfig) => ActorUpdateReturnType<A, M>;
 export type ActorQuery<A = Record<string, ActorMethod>> = <M extends FunctionName<A>>(params: ActorQueryParameters<A, M>) => ActorQueryReturnType<A, M>;
 export type ActorUpdate<A = Record<string, ActorMethod>> = <M extends FunctionName<A>>(params: ActorUpdateParameters<A, M>) => ActorUpdateReturnType<A, M>;
-export interface CreateReactorCoreParameters extends CreateReactorStoreParameters {
-}
+export type CreateReactorCoreParameters = CreateReactorStoreParameters;
 export interface CreateReactorCoreReturnType<A = BaseActor> extends AgentManager, Omit<ActorManager<A>, "updateMethodState"> {
     queryCall: ActorQuery<A>;
     updateCall: ActorUpdate<A>;
 }
+export type UnwrapResult<T> = T extends {
+    Ok: infer U;
+} ? U : T extends {
+    Err: infer E;
+} ? E : T;
+type ExtractOkErr<T> = T extends {
+    Ok: infer U;
+} ? {
+    OkType: U;
+    ErrType: never;
+} : T extends {
+    Err: infer E;
+} ? {
+    OkType: never;
+    ErrType: E;
+} : {
+    OkType: T;
+    ErrType: never;
+};
+export type ExtractOk<T> = T extends {
+    Ok: infer U;
+} ? U : never;
+export type ExtractErr<T> = T extends {
+    Err: infer E;
+} ? E : never;
+export type CompiledOkResult<U> = {
+    isOk: true;
+    isErr: false;
+    value: U;
+    error: null;
+};
+export type CompiledErrResult<E> = {
+    isOk: false;
+    isErr: true;
+    value: null;
+    error: E;
+};
+export type CompiledResult<T> = ExtractOkErr<T> extends {
+    OkType: infer U;
+    ErrType: infer E;
+} ? CompiledOkResult<U> | CompiledErrResult<E> : never;

package/dist/utils/constants.d.ts

@@ -6,11 +6,3 @@ export declare const DEFAULT_LOCAL_DIDJS_ID = "bd3sg-teaaa-aaaaa-qaaba-cai";
 export declare const DEFAULT_IC_DIDJS_ID = "a4gq6-oaaaa-aaaab-qaa4q-cai";
 export declare const IC_INTERNET_IDENTITY_PROVIDER = "https://identity.ic0.app/#authorize";
 export declare const LOCAL_INTERNET_IDENTITY_PROVIDER = "http://rdmx6-jaaaa-aaaaa-aaadq-cai.localhost:4943/#authorize";
-export declare const ACTOR_INITIAL_STATE: {
-    name: string;
-    version: number;
-    methodState: {};
-    initializing: boolean;
-    initialized: boolean;
-    error: undefined;
-};

package/dist/utils/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ACTOR_INITIAL_STATE = exports.LOCAL_INTERNET_IDENTITY_PROVIDER = exports.IC_INTERNET_IDENTITY_PROVIDER = exports.DEFAULT_IC_DIDJS_ID = exports.DEFAULT_LOCAL_DIDJS_ID = exports.LOCAL_HOST_NETWORK_URI = exports.IC_HOST_NETWORK_URI = exports.LOCAL_HOSTS = exports.REMOTE_HOSTS = void 0;
+exports.LOCAL_INTERNET_IDENTITY_PROVIDER = exports.IC_INTERNET_IDENTITY_PROVIDER = exports.DEFAULT_IC_DIDJS_ID = exports.DEFAULT_LOCAL_DIDJS_ID = exports.LOCAL_HOST_NETWORK_URI = exports.IC_HOST_NETWORK_URI = exports.LOCAL_HOSTS = exports.REMOTE_HOSTS = void 0;
 exports.REMOTE_HOSTS = [".github.dev", ".gitpod.io"];
 exports.LOCAL_HOSTS = ["localhost", "127.0.0.1"];
 exports.IC_HOST_NETWORK_URI = "https://ic0.app";
@@ -9,11 +9,3 @@ exports.DEFAULT_LOCAL_DIDJS_ID = "bd3sg-teaaa-aaaaa-qaaba-cai";
 exports.DEFAULT_IC_DIDJS_ID = "a4gq6-oaaaa-aaaab-qaa4q-cai";
 exports.IC_INTERNET_IDENTITY_PROVIDER = "https://identity.ic0.app/#authorize";
 exports.LOCAL_INTERNET_IDENTITY_PROVIDER = "http://rdmx6-jaaaa-aaaaa-aaadq-cai.localhost:4943/#authorize";
-exports.ACTOR_INITIAL_STATE = {
-    name: "",
-    version: 0,
-    methodState: {},
-    initializing: false,
-    initialized: false,
-    error: undefined,
-};

package/dist/utils/hash.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Creates a stable string representation of any JavaScript value
+ * Handles circular references and maintains consistent object key ordering
+ */
+export declare function stringifyStable(value: unknown): string;
+/**
+ * Creates a simple numeric hash code and returns it as a hex string
+ * @param value - Any JavaScript value
+ * @param length - Desired length of the hex string (default: 8)
+ * @returns string - Hex string of specified length
+ */
+export declare function createSimpleHash(value: unknown, length?: number): string;

package/dist/utils/hash.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stringifyStable = stringifyStable;
+exports.createSimpleHash = createSimpleHash;
+/**
+ * Creates a stable string representation of any JavaScript value
+ * Handles circular references and maintains consistent object key ordering
+ */
+function stringifyStable(value) {
+    const seen = new WeakSet();
+    return JSON.stringify(value, (_, value) => {
+        if (value === undefined)
+            return "[undefined]";
+        if (value === null)
+            return "[null]";
+        if (Number.isNaN(value))
+            return "[NaN]";
+        if (value === Infinity)
+            return "[Infinity]";
+        if (value === -Infinity)
+            return "[-Infinity]";
+        if (typeof value === "bigint")
+            return value.toString();
+        if (typeof value === "function")
+            return value.toString();
+        if (value instanceof Date)
+            return value.toISOString();
+        if (value instanceof RegExp)
+            return value.toString();
+        if (ArrayBuffer.isView(value)) {
+            return Array.from(value).join(",");
+        }
+        if (typeof value === "object" && value !== null) {
+            if (seen.has(value))
+                return "[Circular]";
+            seen.add(value);
+            if (Array.isArray(value)) {
+                return value;
+            }
+            const sortedObj = {};
+            const sortedKeys = Object.keys(value).sort();
+            for (const key of sortedKeys) {
+                sortedObj[key] = value[key];
+            }
+            return sortedObj;
+        }
+        return value;
+    });
+}
+/**
+ * Creates a simple numeric hash code and returns it as a hex string
+ * @param value - Any JavaScript value
+ * @param length - Desired length of the hex string (default: 8)
+ * @returns string - Hex string of specified length
+ */
+function createSimpleHash(value, length = 8) {
+    const str = stringifyStable(value);
+    let hash = 0;
+    // Generate a more distributed hash
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash; // Convert to 32-bit integer
+    }
+    // Convert to positive hex string and ensure proper length
+    const positiveHash = Math.abs(hash);
+    const hexString = positiveHash.toString(16);
+    // Pad with zeros to match desired length
+    return hexString.padStart(length, "0");
+}

package/dist/utils/helper.d.ts

@@ -1,16 +1,64 @@
 import { DevtoolsOptions } from "zustand/middleware";
-import type { BaseActor, CandidDefenition, IDL } from "../types";
-export declare function createStoreWithOptionalDevtools<T>(initialState: T, config: DevtoolsOptions): Omit<import("zustand/vanilla").StoreApi<T>, "setState"> & {
-    setState<A extends string | {
-        type: string;
-    }>(partial: T | Partial<T> | ((state: T) => T | Partial<T>), replace?: boolean | undefined, action?: A | undefined): void;
-};
+import type { CompiledResult, BaseActor, CandidDefenition, IDL, ExtractOk, StoreWithAllMiddleware } from "../types";
+/**
+ * No operation function that does nothing.
+ * It can be used as a placeholder or for logging purposes.
+ */
+export declare function noop(): void;
+/**
+ * Creates a Zustand store with optional DevTools middleware.
+ *
+ * @param initialState - The initial state of the store.
+ * @param config - Configuration options for DevTools.
+ * @returns A Zustand store with DevTools enabled if configured, otherwise a standard store.
+ */
+export declare function createStoreWithOptionalDevtools<T extends object>(initialState: T, config: DevtoolsOptions & {
+    withDevtools?: boolean;
+}): StoreWithAllMiddleware<T>;
 export declare const importCandidDefinition: (candidDef: string) => Promise<CandidDefenition>;
+/**
+ * Checks if the current environment is local or development.
+ *
+ * @returns `true` if running in a local or development environment, otherwise `false`.
+ */
 export declare const isInLocalOrDevelopment: () => boolean;
+/**
+ * Retrieves the network from the process environment variables.
+ *
+ * @returns The network name, defaulting to "ic" if not specified.
+ */
 export declare const getProcessEnvNetwork: () => string;
+/**
+ * Determines the network type based on the provided hostname.
+ *
+ * @param hostname - The hostname to evaluate.
+ * @returns A string indicating the network type: "local", "remote", or "ic".
+ */
+export declare function getNetworkByHostname(hostname: string): "local" | "remote" | "ic";
+/**
+ * Checks if a given IDL function is a query.
+ *
+ * @param func - The IDL function to check.
+ * @returns `true` if the function is a query or composite query, otherwise `false`.
+ */
 export declare function isQuery(func: IDL.FuncClass): boolean;
 export declare const jsonToString: (json: unknown, space?: number) => string;
 export declare const generateRequestHash: (args?: unknown[]) => `0x${string}`;
 export declare const generateHash: (field?: unknown) => `0x${string}`;
 export declare const generateActorHash: (actor: BaseActor) => `0x${string}`;
 export declare const stringToHash: (str: string) => `0x${string}`;
+/**
+ * Helper function for extracting the value from a compiled result { Ok: T } or { Err: E }
+ *
+ * @param result - The compiled result to extract from.
+ * @returns A `CompiledResult` object indicating success or failure.
+ */
+export declare function createCompiledResult<T>(result: T): CompiledResult<T>;
+/**
+ * Helper function for extracting the value from a compiled result { Ok: T } or throw the error if { Err: E }
+ *
+ * @param result - The compiled result to extract from.
+ * @returns The extracted value from the compiled result.
+ * @throws The error from the compiled result.
+ */
+export declare function extractOkResult<T>(result: T): ExtractOk<T>;