@monygroupcorp/micro-web3 0.1.1 → 1.2.0

package/src/services/EventIndexer.js

@@ -0,0 +1,399 @@
+// src/services/EventIndexer.js
+
+import { selectAdapter } from '../storage/index.js';
+import { QueryEngine, SyncEngine, EntityResolver, Patterns } from '../indexer/index.js';
+import { ethers } from 'ethers';
+
+/**
+ * Error types for EventIndexer.
+ */
+class EventIndexerError extends Error {
+  constructor(message, code, cause) {
+    super(message);
+    this.name = 'EventIndexerError';
+    this.code = code;
+    this.cause = cause;
+  }
+}
+
+const ErrorCodes = {
+  NOT_INITIALIZED: 'NOT_INITIALIZED',
+  STORAGE_ERROR: 'STORAGE_ERROR',
+  SYNC_ERROR: 'SYNC_ERROR',
+  QUERY_ERROR: 'QUERY_ERROR',
+  INVALID_CONFIG: 'INVALID_CONFIG',
+  PROVIDER_ERROR: 'PROVIDER_ERROR',
+  REORG_DETECTED: 'REORG_DETECTED'
+};
+
+/**
+ * EventIndexer - Client-side event indexing for dApps.
+ *
+ * Provides three levels of abstraction:
+ * - Events: Raw indexed events with filtering
+ * - Entities: Domain objects derived from events
+ * - Patterns: Pre-built solutions (activity feeds, leaderboards)
+ */
+class EventIndexer {
+  /**
+   * Create EventIndexer instance.
+   * @param {EventBus} eventBus - microact EventBus instance
+   * @param {Object} options - Options
+   * @param {BlockchainService} options.blockchainService - For provider access (optional)
+   */
+  constructor(eventBus, options = {}) {
+    if (!eventBus) {
+      throw new EventIndexerError('EventBus is required', ErrorCodes.INVALID_CONFIG);
+    }
+
+    this.eventBus = eventBus;
+    this.blockchainService = options.blockchainService;
+
+    // Internal components (initialized in initialize())
+    this.storage = null;
+    this.queryEngine = null;
+    this.syncEngine = null;
+    this.entityResolver = null;
+    this.patternsAPI = null;
+    this.contract = null;
+
+    this.initialized = false;
+    this.config = null;
+  }
+
+  /**
+   * Initialize the EventIndexer.
+   * @param {EventIndexerConfig} config - Configuration
+   */
+  async initialize(config) {
+    this._validateConfig(config);
+    this.config = config;
+
+    try {
+      // Get provider
+      const provider = this._getProvider(config);
+
+      // Get chain ID
+      const network = await provider.getNetwork();
+      const chainId = Number(network.chainId);
+
+      // Extract event types from ABI
+      const eventTypes = this._extractEventTypes(config.contract.abi);
+
+      // Initialize storage
+      this.storage = selectAdapter(config.persistence);
+      await this.storage.initialize({
+        dbName: config.persistence?.dbName || `micro-web3-events-${chainId}`,
+        version: config.persistence?.version || 1,
+        eventTypes
+      });
+
+      // Create contract instance
+      this.contract = new ethers.Contract(
+        config.contract.address,
+        config.contract.abi,
+        provider
+      );
+
+      // Detect deploy block if not provided
+      const deployBlock = config.contract.deployBlock || await this._detectDeployBlock(provider);
+
+      // Initialize components
+      this.queryEngine = new QueryEngine(this.storage, this.eventBus);
+
+      this.syncEngine = new SyncEngine(
+        this.storage,
+        this.queryEngine,
+        this.eventBus,
+        config.sync || {}
+      );
+      await this.syncEngine.initialize({
+        provider,
+        contract: this.contract,
+        eventTypes,
+        deployBlock,
+        chainId
+      });
+
+      // Initialize entity resolver if entities defined
+      if (config.entities) {
+        this.entityResolver = new EntityResolver(this.queryEngine, config.entities);
+      }
+
+      // Initialize patterns
+      this.patternsAPI = new Patterns(this.queryEngine, this.entityResolver);
+
+      this.initialized = true;
+      this.eventBus.emit('indexer:initialized', {});
+
+      // Start syncing
+      await this.syncEngine.start();
+
+    } catch (error) {
+      this.eventBus.emit('indexer:error', {
+        code: ErrorCodes.STORAGE_ERROR,
+        message: `Initialization failed: ${error.message}`,
+        cause: error,
+        recoverable: false
+      });
+      throw new EventIndexerError(
+        `Failed to initialize EventIndexer: ${error.message}`,
+        ErrorCodes.STORAGE_ERROR,
+        error
+      );
+    }
+  }
+
+  _validateConfig(config) {
+    if (!config.contract) {
+      throw new EventIndexerError('contract config is required', ErrorCodes.INVALID_CONFIG);
+    }
+    if (!config.contract.address) {
+      throw new EventIndexerError('contract.address is required', ErrorCodes.INVALID_CONFIG);
+    }
+    if (!config.contract.abi || !Array.isArray(config.contract.abi)) {
+      throw new EventIndexerError('contract.abi is required and must be an array', ErrorCodes.INVALID_CONFIG);
+    }
+    if (!config.provider && !this.blockchainService) {
+      throw new EventIndexerError(
+        'Either provider in config or blockchainService in constructor is required',
+        ErrorCodes.INVALID_CONFIG
+      );
+    }
+  }
+
+  _getProvider(config) {
+    if (config.provider) {
+      return config.provider;
+    }
+    if (this.blockchainService?.getProvider) {
+      return this.blockchainService.getProvider();
+    }
+    if (this.blockchainService?.provider) {
+      return this.blockchainService.provider;
+    }
+    throw new EventIndexerError('No provider available', ErrorCodes.PROVIDER_ERROR);
+  }
+
+  _extractEventTypes(abi) {
+    const eventTypes = [];
+
+    for (const item of abi) {
+      if (item.type === 'event') {
+        const indexedParams = item.inputs
+          .filter(input => input.indexed)
+          .map(input => input.name);
+
+        eventTypes.push({
+          name: item.name,
+          inputs: item.inputs,
+          indexedParams
+        });
+      }
+    }
+
+    return eventTypes;
+  }
+
+  async _detectDeployBlock(provider) {
+    // Default to 0 if we can't detect
+    // In production, you'd want to either require this or use a heuristic
+    console.warn('[EventIndexer] No deployBlock specified, starting from block 0');
+    return 0;
+  }
+
+  /**
+   * Events API - Level 1 (Low-level)
+   * Direct access to raw indexed events.
+   */
+  get events() {
+    this._checkInitialized();
+    return {
+      query: (eventName, options) => this.queryEngine.query(eventName, options),
+      get: (eventName, id) => this.queryEngine.get(eventName, id),
+      subscribe: (eventNames, callback) => this.queryEngine.subscribe(eventNames, callback),
+      count: (eventName, where) => this.queryEngine.count(eventName, where)
+    };
+  }
+
+  /**
+   * Entities API - Level 2 (Domain-level)
+   * Access to domain objects derived from events.
+   * Returns proxy for entity.EntityName access pattern.
+   */
+  get entities() {
+    this._checkInitialized();
+
+    if (!this.entityResolver) {
+      console.warn('[EventIndexer] No entities configured');
+      return {};
+    }
+
+    return new Proxy({}, {
+      get: (target, prop) => {
+        return this.entityResolver.getEntity(prop);
+      }
+    });
+  }
+
+  /**
+   * Patterns API - Level 3 (Zero-config)
+   * Pre-built solutions for common needs.
+   */
+  get patterns() {
+    this._checkInitialized();
+    return this.patternsAPI;
+  }
+
+  /**
+   * Sync API - Control sync behavior.
+   */
+  get sync() {
+    this._checkInitialized();
+    return {
+      getStatus: () => this.syncEngine.getStatus(),
+      resync: (fromBlock) => this.syncEngine.resync(fromBlock),
+      clear: () => this.storage.clear(),
+      pause: () => this.syncEngine.pause(),
+      resume: () => this.syncEngine.resume()
+    };
+  }
+
+  _checkInitialized() {
+    if (!this.initialized) {
+      throw new EventIndexerError(
+        'EventIndexer not initialized. Call initialize() first.',
+        ErrorCodes.NOT_INITIALIZED
+      );
+    }
+  }
+
+  /**
+   * Cleanup and close connections.
+   */
+  async destroy() {
+    if (this.syncEngine) {
+      await this.syncEngine.stop();
+    }
+    if (this.storage) {
+      await this.storage.close();
+    }
+    this.initialized = false;
+  }
+
+  /**
+   * Install useIndexer hook on Component class.
+   * Call this once after importing your Component class.
+   *
+   * @param {typeof Component} ComponentClass - The Component class to extend
+   *
+   * @example
+   * import { Component } from '@monygroupcorp/microact';
+   * import { EventIndexer } from '@monygroupcorp/micro-web3';
+   * EventIndexer.installHook(Component);
+   */
+  static installHook(ComponentClass) {
+    if (ComponentClass.prototype.useIndexer) {
+      console.warn('[EventIndexer] useIndexer hook already installed');
+      return;
+    }
+
+    /**
+     * Reactive query hook for EventIndexer.
+     * Auto-updates when indexed events change.
+     *
+     * @param {EntityQueryable|EventsAPI} queryable - What to query (entity or events)
+     * @param {Object|Function} where - Filter conditions (can be reactive functions)
+     * @param {Object} options - Hook options
+     * @param {Function} options.onUpdate - Called when results change
+     * @param {Function} options.onError - Called on query error
+     * @returns {Proxy} Proxy that returns current results
+     */
+    ComponentClass.prototype.useIndexer = function(queryable, where = {}, options = {}) {
+      const self = this;
+      let result = null;
+      let isLoading = true;
+      let unsubscribe = null;
+
+      // Resolve reactive where values
+      const resolveWhere = () => {
+        const resolved = {};
+        for (const [key, value] of Object.entries(where)) {
+          resolved[key] = typeof value === 'function' ? value() : value;
+        }
+        return resolved;
+      };
+
+      // Execute query
+      const executeQuery = async () => {
+        try {
+          const whereValues = resolveWhere();
+
+          if (queryable.query) {
+            // Entity or events queryable
+            const queryResult = await queryable.query(whereValues);
+            result = Array.isArray(queryResult) ? queryResult : queryResult.events;
+          } else {
+            result = [];
+          }
+
+          isLoading = false;
+
+          if (options.onUpdate) {
+            options.onUpdate(result);
+          }
+        } catch (error) {
+          isLoading = false;
+          console.error('[useIndexer] Query error:', error);
+          if (options.onError) {
+            options.onError(error);
+          }
+        }
+      };
+
+      // Initial query
+      executeQuery();
+
+      // Subscribe to changes
+      if (queryable.subscribe) {
+        unsubscribe = queryable.subscribe(resolveWhere(), () => {
+          executeQuery();
+        });
+      }
+
+      // Register cleanup
+      if (this.registerCleanup) {
+        this.registerCleanup(() => {
+          if (unsubscribe) unsubscribe();
+        });
+      }
+
+      // Return proxy for array-like access
+      return new Proxy([], {
+        get(target, prop) {
+          if (prop === 'length') return result?.length || 0;
+          if (prop === 'isLoading') return isLoading;
+          if (prop === Symbol.iterator) {
+            return function* () {
+              if (result) yield* result;
+            };
+          }
+          if (typeof prop === 'string' && !isNaN(prop)) {
+            return result?.[parseInt(prop)];
+          }
+          // Array methods
+          if (result && typeof result[prop] === 'function') {
+            return result[prop].bind(result);
+          }
+          return result?.[prop];
+        }
+      });
+    };
+  }
+}
+
+// Export error types for external use
+EventIndexer.EventIndexerError = EventIndexerError;
+EventIndexer.ErrorCodes = ErrorCodes;
+
+export default EventIndexer;