@0xobelisk/react 1.2.0-pre.64

package/src/sui/provider.tsx

@@ -0,0 +1,341 @@
+/**
+ * Dubhe Provider - useRef Pattern for Client Management
+ *
+ * Features:
+ * - 🎯 Single client instances across application lifecycle
+ * - ⚡ useRef-based storage (no re-initialization on re-renders)
+ * - 🔧 Provider pattern for dependency injection
+ * - 🛡️ Complete type safety with strict TypeScript
+ * - 📦 Context-based client sharing
+ */
+
+import React, { createContext, useContext, useRef, ReactNode } from 'react';
+import { Dubhe } from '@0xobelisk/sui-client';
+import { createDubheGraphqlClient } from '@0xobelisk/graphql-client';
+import { createECSWorld } from '@0xobelisk/ecs';
+import { useDubheConfig } from './config';
+import type { DubheConfig, DubheReturn } from './types';
+
+/**
+ * Context interface for Dubhe client instances
+ * All clients are stored using useRef to ensure single initialization
+ */
+interface DubheContextValue {
+  getContract: () => Dubhe;
+  getGraphqlClient: () => any | null;
+  getEcsWorld: () => any | null;
+  getAddress: () => string;
+  getMetrics: () => {
+    initTime: number;
+    requestCount: number;
+    lastActivity: number;
+  };
+  config: DubheConfig;
+}
+
+/**
+ * Context for sharing Dubhe clients across the application
+ * Uses useRef pattern to ensure clients are created only once
+ */
+const DubheContext = createContext<DubheContextValue | null>(null);
+
+/**
+ * Props interface for DubheProvider component
+ */
+interface DubheProviderProps {
+  /** Configuration for Dubhe initialization */
+  config: Partial<DubheConfig>;
+  /** Child components that will have access to Dubhe clients */
+  children: ReactNode;
+}
+
+/**
+ * DubheProvider Component - useRef Pattern Implementation
+ *
+ * This Provider uses useRef to store client instances, ensuring they are:
+ * 1. Created only once during component lifecycle
+ * 2. Persisted across re-renders without re-initialization
+ * 3. Shared efficiently via React Context
+ *
+ * Key advantages over useMemo:
+ * - useRef guarantees single initialization (useMemo can re-run on dependency changes)
+ * - No dependency array needed (eliminates potential re-initialization bugs)
+ * - Better performance for heavy client objects
+ * - Clearer separation of concerns via Provider pattern
+ *
+ * @param props - Provider props containing config and children
+ * @returns Provider component wrapping children with Dubhe context
+ *
+ * @example
+ * ```typescript
+ * // App root setup
+ * function App() {
+ *   const dubheConfig = {
+ *     network: 'devnet',
+ *     packageId: '0x123...',
+ *     metadata: contractMetadata,
+ *     credentials: {
+ *       secretKey: process.env.NEXT_PUBLIC_PRIVATE_KEY
+ *     }
+ *   };
+ *
+ *   return (
+ *     <DubheProvider config={dubheConfig}>
+ *       <MyApplication />
+ *     </DubheProvider>
+ *   );
+ * }
+ * ```
+ */
+export function DubheProvider({ config, children }: DubheProviderProps) {
+  // Merge configuration with defaults (only runs once)
+  const finalConfig = useDubheConfig(config);
+
+  // Track initialization start time (useRef ensures single timestamp)
+  const startTimeRef = useRef<number>(performance.now());
+
+  // useRef for contract instance - guarantees single initialization
+  // Unlike useMemo, useRef.current is never re-calculated
+  const contractRef = useRef<Dubhe | undefined>(undefined);
+  const getContract = (): Dubhe => {
+    if (!contractRef.current) {
+      try {
+        console.log('Initializing Dubhe contract instance (one-time)');
+        contractRef.current = new Dubhe({
+          networkType: finalConfig.network,
+          packageId: finalConfig.packageId,
+          metadata: finalConfig.metadata,
+          secretKey: finalConfig.credentials?.secretKey
+        });
+      } catch (error) {
+        console.error('Contract initialization failed:', error);
+        throw error;
+      }
+    }
+    return contractRef.current;
+  };
+
+  // useRef for GraphQL client instance - single initialization guaranteed
+  const graphqlClientRef = useRef<any | null>(null);
+  const hasInitializedGraphql = useRef(false);
+  const getGraphqlClient = (): any | null => {
+    if (!hasInitializedGraphql.current && finalConfig.dubheMetadata) {
+      try {
+        console.log('Initializing GraphQL client instance (one-time)');
+        graphqlClientRef.current = createDubheGraphqlClient({
+          endpoint: finalConfig.endpoints?.graphql || 'http://localhost:4000/graphql',
+          subscriptionEndpoint: finalConfig.endpoints?.websocket || 'ws://localhost:4000/graphql',
+          dubheMetadata: finalConfig.dubheMetadata
+        });
+        hasInitializedGraphql.current = true;
+      } catch (error) {
+        console.error('GraphQL client initialization failed:', error);
+        throw error;
+      }
+    }
+    return graphqlClientRef.current;
+  };
+
+  // useRef for ECS World instance - depends on GraphQL client
+  const ecsWorldRef = useRef<any | null>(null);
+  const hasInitializedEcs = useRef(false);
+  const getEcsWorld = (): any | null => {
+    const graphqlClient = getGraphqlClient();
+    if (!hasInitializedEcs.current && graphqlClient) {
+      try {
+        console.log('Initializing ECS World instance (one-time)');
+        ecsWorldRef.current = createECSWorld(graphqlClient, {
+          queryConfig: {
+            enableBatchOptimization: finalConfig.options?.enableBatchOptimization ?? true,
+            defaultCacheTimeout: finalConfig.options?.cacheTimeout ?? 5000
+          },
+          subscriptionConfig: {
+            defaultDebounceMs: finalConfig.options?.debounceMs ?? 100,
+            reconnectOnError: finalConfig.options?.reconnectOnError ?? true
+          }
+        });
+        hasInitializedEcs.current = true;
+      } catch (error) {
+        console.error('ECS World initialization failed:', error);
+        throw error;
+      }
+    }
+    return ecsWorldRef.current;
+  };
+
+  // Address getter - calculated from contract
+  const getAddress = (): string => {
+    return getContract().getAddress();
+  };
+
+  // Metrics getter - performance tracking
+  const getMetrics = () => ({
+    initTime: performance.now() - (startTimeRef.current || 0),
+    requestCount: 0, // Can be enhanced with actual tracking
+    lastActivity: Date.now()
+  });
+
+  // Context value - stable reference (no re-renders for consumers)
+  const contextValue: DubheContextValue = {
+    getContract,
+    getGraphqlClient,
+    getEcsWorld,
+    getAddress,
+    getMetrics,
+    config: finalConfig
+  };
+
+  return <DubheContext.Provider value={contextValue}>{children}</DubheContext.Provider>;
+}
+
+/**
+ * Custom hook to access Dubhe context
+ * Provides type-safe access to all Dubhe client instances
+ *
+ * @returns DubheContextValue with all client getters and config
+ * @throws Error if used outside of DubheProvider
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const dubheContext = useDubheContext();
+ *
+ *   const contract = dubheContext.getContract();
+ *   const graphqlClient = dubheContext.getGraphqlClient();
+ *   const ecsWorld = dubheContext.getEcsWorld();
+ *   const address = dubheContext.getAddress();
+ *
+ *   return <div>Connected as {address}</div>;
+ * }
+ * ```
+ */
+export function useDubheContext(): DubheContextValue {
+  const context = useContext(DubheContext);
+
+  if (!context) {
+    throw new Error(
+      'useDubheContext must be used within a DubheProvider. ' +
+        'Make sure to wrap your app with <DubheProvider config={...}>'
+    );
+  }
+
+  return context;
+}
+
+/**
+ * Enhanced hook that mimics the original useDubhe API
+ * Uses the Provider pattern internally but maintains backward compatibility
+ *
+ * @returns DubheReturn object with all instances and metadata
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const { contract, graphqlClient, ecsWorld, address } = useDubheFromProvider();
+ *
+ *   const handleTransaction = async () => {
+ *     const tx = new Transaction();
+ *     await contract.tx.my_system.my_method({ tx });
+ *   };
+ *
+ *   return <button onClick={handleTransaction}>Execute</button>;
+ * }
+ * ```
+ */
+export function useDubheFromProvider(): DubheReturn {
+  const context = useDubheContext();
+
+  // Get instances (lazy initialization via getters)
+  const contract = context.getContract();
+  const graphqlClient = context.getGraphqlClient();
+  const ecsWorld = context.getEcsWorld();
+  const address = context.getAddress();
+  const metrics = context.getMetrics();
+
+  // Enhanced contract with additional methods (similar to original implementation)
+  const enhancedContract = contract as any;
+
+  // Add transaction methods with error handling (if not already added)
+  if (!enhancedContract.txWithOptions) {
+    enhancedContract.txWithOptions = (system: string, method: string, options: any = {}) => {
+      return async (params: any) => {
+        try {
+          const startTime = performance.now();
+          const result = await contract.tx[system][method](params);
+          const executionTime = performance.now() - startTime;
+
+          if (process.env.NODE_ENV === 'development') {
+            console.log(
+              `Transaction ${system}.${method} completed in ${executionTime.toFixed(2)}ms`
+            );
+          }
+
+          options.onSuccess?.(result);
+          return result;
+        } catch (error) {
+          options.onError?.(error);
+          throw error;
+        }
+      };
+    };
+  }
+
+  // Add query methods with performance tracking (if not already added)
+  if (!enhancedContract.queryWithOptions) {
+    enhancedContract.queryWithOptions = (system: string, method: string, options: any = {}) => {
+      return async (params: any) => {
+        const startTime = performance.now();
+        const result = await contract.query[system][method](params);
+        const executionTime = performance.now() - startTime;
+
+        if (process.env.NODE_ENV === 'development') {
+          console.log(`Query ${system}.${method} completed in ${executionTime.toFixed(2)}ms`);
+        }
+
+        return result;
+      };
+    };
+  }
+
+  return {
+    contract: enhancedContract,
+    graphqlClient,
+    ecsWorld,
+    metadata: context.config.metadata,
+    network: context.config.network,
+    packageId: context.config.packageId,
+    dubheSchemaId: context.config.dubheSchemaId,
+    address,
+    options: context.config.options,
+    metrics
+  };
+}
+
+/**
+ * Individual client hooks for components that only need specific instances
+ * These are more efficient than useDubheFromProvider for single-client usage
+ */
+
+/**
+ * Hook for accessing only the Dubhe contract instance
+ */
+export function useDubheContractFromProvider(): Dubhe {
+  const { contract } = useDubheFromProvider();
+  return contract;
+}
+
+/**
+ * Hook for accessing only the GraphQL client instance
+ */
+export function useDubheGraphQLFromProvider(): any | null {
+  const { getGraphqlClient } = useDubheContext();
+  return getGraphqlClient();
+}
+
+/**
+ * Hook for accessing only the ECS World instance
+ */
+export function useDubheECSFromProvider(): any | null {
+  const { getEcsWorld } = useDubheContext();
+  return getEcsWorld();
+}

package/src/sui/types.ts

@@ -0,0 +1,99 @@
+import { SuiMoveNormalizedModules, Dubhe } from '@0xobelisk/sui-client';
+import type { DubheGraphqlClient } from '@0xobelisk/graphql-client';
+import type { DubheECSWorld } from '@0xobelisk/ecs';
+
+/**
+ * Network type
+ */
+export type NetworkType = 'mainnet' | 'testnet' | 'devnet' | 'localnet';
+
+/**
+ * Modern Dubhe client configuration for auto-initialization
+ */
+export interface DubheConfig {
+  /** Network type */
+  network: NetworkType;
+  /** Contract package ID */
+  packageId: string;
+  /** Dubhe Schema ID (optional, for enhanced features) */
+  dubheSchemaId: string;
+  /** Contract metadata (required for contract instantiation) */
+  metadata: SuiMoveNormalizedModules;
+  /** Dubhe metadata (enables GraphQL/ECS features) */
+  dubheMetadata?: any;
+  /** Authentication credentials */
+  credentials?: {
+    secretKey?: string;
+    mnemonics?: string;
+  };
+  /** Service endpoints configuration */
+  endpoints?: {
+    graphql?: string;
+    websocket?: string;
+  };
+  /** Performance and behavior options */
+  options?: {
+    /** Enable batch query optimization */
+    enableBatchOptimization?: boolean;
+    /** Default cache timeout (milliseconds) */
+    cacheTimeout?: number;
+    /** Request debounce delay (milliseconds) */
+    debounceMs?: number;
+    /** Auto-reconnect on WebSocket errors */
+    reconnectOnError?: boolean;
+  };
+}
+
+/**
+ * Return type for the main useDubhe hook
+ */
+export interface DubheReturn {
+  /** Dubhe contract instance with enhanced methods */
+  contract: Dubhe & {
+    /** Enhanced transaction methods with options */
+    txWithOptions?: (
+      system: string,
+      method: string,
+      options?: any
+    ) => (params: any) => Promise<any>;
+    /** Enhanced query methods with options */
+    queryWithOptions?: (
+      system: string,
+      method: string,
+      options?: any
+    ) => (params: any) => Promise<any>;
+  };
+  /** GraphQL client (null if dubheMetadata not provided) */
+  graphqlClient: DubheGraphqlClient | null;
+  /** ECS World instance (null if GraphQL not available) */
+  ecsWorld: DubheECSWorld | null;
+  /** Contract metadata */
+  metadata: SuiMoveNormalizedModules;
+  /** Network type */
+  network: NetworkType;
+  /** Package ID */
+  packageId: string;
+  /** Dubhe Schema ID (if provided) */
+  dubheSchemaId?: string;
+  /** User address */
+  address: string;
+  /** Configuration options used */
+  options?: {
+    enableBatchOptimization?: boolean;
+    cacheTimeout?: number;
+    debounceMs?: number;
+    reconnectOnError?: boolean;
+  };
+  /** Performance metrics */
+  metrics?: {
+    initTime?: number;
+    requestCount?: number;
+    lastActivity?: number;
+  };
+}
+
+/**
+ * Compatibility alias for DubheReturn
+ * @deprecated Use DubheReturn instead for better consistency
+ */
+export type ContractReturn = DubheReturn;

package/src/sui/utils.ts

@@ -0,0 +1,192 @@
+/**
+ * Utility Functions for Dubhe Configuration Management
+ *
+ * Features:
+ * - Configuration validation and error handling
+ * - Smart configuration merging with proper type safety
+ * - Type-safe configuration validation
+ */
+
+import type { DubheConfig, NetworkType } from './types';
+
+/**
+ * Merge multiple configuration objects with proper deep merging
+ * Later configurations override earlier ones
+ *
+ * @param baseConfig - Base configuration (usually defaults)
+ * @param overrideConfig - Override configuration (user provided)
+ * @returns Merged configuration
+ */
+export function mergeConfigurations(
+  baseConfig: Partial<DubheConfig>,
+  overrideConfig?: Partial<DubheConfig>
+): Partial<DubheConfig> {
+  if (!overrideConfig) {
+    return { ...baseConfig };
+  }
+
+  const result: Partial<DubheConfig> = { ...baseConfig };
+
+  // Merge top-level properties
+  Object.assign(result, overrideConfig);
+
+  // Deep merge nested objects
+  if (overrideConfig.credentials || baseConfig.credentials) {
+    result.credentials = {
+      ...baseConfig.credentials,
+      ...overrideConfig.credentials
+    };
+  }
+
+  if (overrideConfig.endpoints || baseConfig.endpoints) {
+    result.endpoints = {
+      ...baseConfig.endpoints,
+      ...overrideConfig.endpoints
+    };
+  }
+
+  if (overrideConfig.options || baseConfig.options) {
+    result.options = {
+      ...baseConfig.options,
+      ...overrideConfig.options
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Validate configuration and ensure required fields are present
+ * Throws descriptive errors for missing required fields
+ *
+ * @param config - Configuration to validate
+ * @returns Validated and typed configuration
+ * @throws Error if required fields are missing or invalid
+ */
+export function validateConfig(config: Partial<DubheConfig>): DubheConfig {
+  const errors: string[] = [];
+
+  // Check required fields
+  if (!config.network) {
+    errors.push('network is required');
+  }
+
+  if (!config.packageId) {
+    errors.push('packageId is required');
+  }
+
+  if (!config.metadata) {
+    errors.push('metadata is required');
+  } else {
+    // Basic metadata validation
+    if (typeof config.metadata !== 'object') {
+      errors.push('metadata must be an object');
+    } else if (Object.keys(config.metadata).length === 0) {
+      errors.push('metadata cannot be empty');
+    }
+  }
+
+  // Validate network type
+  if (config.network && !['mainnet', 'testnet', 'devnet', 'localnet'].includes(config.network)) {
+    errors.push(
+      `invalid network: ${config.network}. Must be one of: mainnet, testnet, devnet, localnet`
+    );
+  }
+
+  // Validate package ID format (enhanced check)
+  if (config.packageId) {
+    if (!config.packageId.startsWith('0x')) {
+      errors.push('packageId must start with 0x');
+    } else if (config.packageId.length < 3) {
+      errors.push('packageId must be longer than 0x');
+    } else if (!/^0x[a-fA-F0-9]+$/.test(config.packageId)) {
+      errors.push('packageId must contain only hexadecimal characters after 0x');
+    }
+  }
+
+  // Validate dubheMetadata if provided
+  if (config.dubheMetadata !== undefined) {
+    if (typeof config.dubheMetadata !== 'object' || config.dubheMetadata === null) {
+      errors.push('dubheMetadata must be an object');
+    } else if (!config.dubheMetadata.components && !config.dubheMetadata.resources) {
+      errors.push('dubheMetadata must contain components or resources');
+    }
+  }
+
+  // Validate credentials if provided
+  if (config.credentials) {
+    if (config.credentials.secretKey && typeof config.credentials.secretKey !== 'string') {
+      errors.push('credentials.secretKey must be a string');
+    }
+    if (config.credentials.mnemonics && typeof config.credentials.mnemonics !== 'string') {
+      errors.push('credentials.mnemonics must be a string');
+    }
+  }
+
+  // Validate URLs if provided
+  if (config.endpoints?.graphql && !isValidUrl(config.endpoints.graphql)) {
+    errors.push('endpoints.graphql must be a valid URL');
+  }
+
+  if (config.endpoints?.websocket && !isValidUrl(config.endpoints.websocket)) {
+    errors.push('endpoints.websocket must be a valid URL');
+  }
+
+  // Validate numeric options
+  if (
+    config.options?.cacheTimeout !== undefined &&
+    (typeof config.options.cacheTimeout !== 'number' || config.options.cacheTimeout < 0)
+  ) {
+    errors.push('options.cacheTimeout must be a non-negative number');
+  }
+
+  if (
+    config.options?.debounceMs !== undefined &&
+    (typeof config.options.debounceMs !== 'number' || config.options.debounceMs < 0)
+  ) {
+    errors.push('options.debounceMs must be a non-negative number');
+  }
+
+  if (errors.length > 0) {
+    const errorMessage = `Invalid Dubhe configuration (${errors.length} error${errors.length > 1 ? 's' : ''}):\n${errors.map((e) => `- ${e}`).join('\n')}`;
+    console.error('Configuration validation failed:', { errors, config });
+    throw new Error(errorMessage);
+  }
+
+  return config as DubheConfig;
+}
+
+/**
+ * Simple URL validation helper
+ *
+ * @param url - URL string to validate
+ * @returns true if URL is valid, false otherwise
+ */
+function isValidUrl(url: string): boolean {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Generate a configuration summary for debugging
+ * Hides sensitive information like private keys
+ *
+ * @param config - Configuration to summarize
+ * @returns Safe configuration summary
+ */
+export function getConfigSummary(config: DubheConfig): object {
+  return {
+    network: config.network,
+    packageId: config.packageId,
+    dubheSchemaId: config.dubheSchemaId,
+    hasMetadata: !!config.metadata,
+    hasDubheMetadata: !!config.dubheMetadata,
+    hasCredentials: !!config.credentials?.secretKey,
+    endpoints: config.endpoints,
+    options: config.options
+  };
+}