@monygroupcorp/micro-web3 0.1.1 → 1.2.0

package/src/indexer/Patterns.js

@@ -0,0 +1,277 @@
+// src/indexer/Patterns.js
+
+/**
+ * Pre-built patterns for common dApp needs.
+ * Zero-config solutions for activity feeds, leaderboards, etc.
+ */
+class Patterns {
+  constructor(queryEngine, entityResolver) {
+    this.queryEngine = queryEngine;
+    this.entityResolver = entityResolver;
+  }
+
+  /**
+   * User activity feed.
+   * @param {string} address - User address
+   * @param {Object} options - Options
+   * @param {string[]} options.events - Event types to include
+   * @param {string[]} options.userFields - Fields to match address against (auto-detected if omitted)
+   * @param {number} options.limit - Max results
+   * @param {number} options.offset - Skip N results
+   * @returns {Promise<ActivityItem[]>}
+   */
+  async userActivity(address, options = {}) {
+    const { events = [], userFields, limit = 50, offset = 0 } = options;
+    const normalizedAddress = address.toLowerCase();
+
+    // Collect activity from all event types
+    const allActivity = [];
+
+    for (const eventType of events) {
+      const result = await this.queryEngine.query(eventType, {
+        limit: 1000 // Get more to filter
+      });
+
+      // Auto-detect user fields if not specified
+      const fields = userFields || this._detectAddressFields(result.events[0]);
+
+      // Filter events involving this user
+      for (const event of result.events) {
+        const isUserEvent = fields.some(field => {
+          const value = event.indexed[field] || event.data[field];
+          return typeof value === 'string' && value.toLowerCase() === normalizedAddress;
+        });
+
+        if (isUserEvent) {
+          allActivity.push({
+            type: event.type,
+            timestamp: event.timestamp || event.blockNumber, // Fall back to block number
+            blockNumber: event.blockNumber,
+            transactionHash: event.transactionHash,
+            data: event.data
+          });
+        }
+      }
+    }
+
+    // Sort by timestamp/block descending
+    allActivity.sort((a, b) => (b.timestamp || b.blockNumber) - (a.timestamp || a.blockNumber));
+
+    // Paginate
+    return allActivity.slice(offset, offset + limit);
+  }
+
+  /**
+   * Find refundable items (cancelled parent + unclaimed).
+   * @param {Object} options - Options
+   * @param {string} options.itemEvent - Event creating the item
+   * @param {string} options.itemKey - Unique key field
+   * @param {string} options.parentKey - Field linking to parent
+   * @param {string} options.cancelEvent - Event that cancels parent
+   * @param {string} options.claimEvent - Event that claims item
+   * @param {string} options.userField - Field containing user address
+   * @param {string} options.user - User address to filter
+   * @returns {Promise<IndexedEvent[]>}
+   */
+  async refundable(options) {
+    const {
+      itemEvent,
+      itemKey,
+      parentKey,
+      cancelEvent,
+      claimEvent,
+      userField,
+      user
+    } = options;
+
+    const normalizedUser = user.toLowerCase();
+
+    // Get all items for user
+    const itemsResult = await this.queryEngine.query(itemEvent, { limit: 10000 });
+    const userItems = itemsResult.events.filter(e => {
+      const userValue = e.indexed[userField] || e.data[userField];
+      return typeof userValue === 'string' && userValue.toLowerCase() === normalizedUser;
+    });
+
+    // Get cancelled parents
+    const cancelResult = await this.queryEngine.query(cancelEvent, { limit: 10000 });
+    const cancelledParents = new Set(
+      cancelResult.events.map(e => e.indexed[parentKey] || e.data[parentKey])
+    );
+
+    // Get claimed items
+    const claimResult = await this.queryEngine.query(claimEvent, { limit: 10000 });
+    const claimedItems = new Set(
+      claimResult.events.map(e => e.indexed[itemKey] || e.data[itemKey])
+    );
+
+    // Filter: parent cancelled AND item not claimed
+    return userItems.filter(item => {
+      const itemKeyValue = item.indexed[itemKey] || item.data[itemKey];
+      const parentKeyValue = item.indexed[parentKey] || item.data[parentKey];
+
+      return cancelledParents.has(parentKeyValue) && !claimedItems.has(itemKeyValue);
+    });
+  }
+
+  /**
+   * Leaderboard aggregation.
+   * @param {Object} options - Options
+   * @param {string} options.event - Event to aggregate
+   * @param {string} options.groupBy - Field to group by
+   * @param {string} options.aggregate - 'count' or 'sum'
+   * @param {string} options.sumField - Field to sum (if aggregate: 'sum')
+   * @param {number} options.limit - Max results
+   * @param {Object} options.where - Filter conditions
+   * @returns {Promise<LeaderboardEntry[]>}
+   */
+  async leaderboard(options) {
+    const { event, groupBy, aggregate, sumField, limit = 10, where } = options;
+
+    const result = await this.queryEngine.query(event, {
+      where,
+      limit: 10000
+    });
+
+    // Group by field
+    const groups = new Map();
+    for (const e of result.events) {
+      const key = e.indexed[groupBy] || e.data[groupBy];
+      if (key === undefined) continue;
+
+      const normalizedKey = typeof key === 'string' ? key.toLowerCase() : key;
+
+      if (!groups.has(normalizedKey)) {
+        groups.set(normalizedKey, { key, events: [] });
+      }
+      groups.get(normalizedKey).events.push(e);
+    }
+
+    // Calculate aggregates
+    const entries = [];
+    for (const [normalizedKey, group] of groups) {
+      let value;
+      if (aggregate === 'count') {
+        value = group.events.length;
+      } else if (aggregate === 'sum') {
+        value = group.events.reduce((sum, e) => {
+          const fieldValue = e.indexed[sumField] || e.data[sumField];
+          const num = typeof fieldValue === 'string' ? parseFloat(fieldValue) : fieldValue;
+          return sum + (isNaN(num) ? 0 : num);
+        }, 0);
+      }
+
+      entries.push({ key: group.key, value });
+    }
+
+    // Sort by value descending
+    entries.sort((a, b) => b.value - a.value);
+
+    // Add ranks and limit
+    return entries.slice(0, limit).map((entry, index) => ({
+      ...entry,
+      rank: index + 1
+    }));
+  }
+
+  /**
+   * Time-series aggregation.
+   * @param {Object} options - Options
+   * @param {string} options.event - Event to aggregate
+   * @param {string} options.interval - 'hour' | 'day' | 'week'
+   * @param {string} options.aggregate - 'count' or 'sum'
+   * @param {string} options.sumField - Field to sum (if aggregate: 'sum')
+   * @param {Object} options.where - Filter conditions
+   * @param {number} options.periods - Number of periods (default: 30)
+   * @returns {Promise<TimeSeriesPoint[]>}
+   */
+  async timeSeries(options) {
+    const { event, interval, aggregate, sumField, where, periods = 30 } = options;
+
+    const result = await this.queryEngine.query(event, {
+      where,
+      limit: 100000
+    });
+
+    // Calculate interval in milliseconds
+    const intervalMs = {
+      hour: 60 * 60 * 1000,
+      day: 24 * 60 * 60 * 1000,
+      week: 7 * 24 * 60 * 60 * 1000
+    }[interval];
+
+    if (!intervalMs) {
+      throw new Error(`Invalid interval: ${interval}`);
+    }
+
+    // Group events by period
+    const now = Date.now();
+    const periodGroups = new Map();
+
+    // Initialize periods
+    for (let i = 0; i < periods; i++) {
+      const periodStart = now - (i + 1) * intervalMs;
+      const periodKey = new Date(periodStart).toISOString();
+      periodGroups.set(periodKey, []);
+    }
+
+    // Assign events to periods
+    for (const e of result.events) {
+      const eventTime = e.timestamp ? e.timestamp * 1000 : now; // Assume timestamp is in seconds
+      const periodsAgo = Math.floor((now - eventTime) / intervalMs);
+
+      if (periodsAgo >= 0 && periodsAgo < periods) {
+        const periodStart = now - (periodsAgo + 1) * intervalMs;
+        const periodKey = new Date(periodStart).toISOString();
+
+        if (periodGroups.has(periodKey)) {
+          periodGroups.get(periodKey).push(e);
+        }
+      }
+    }
+
+    // Calculate aggregates
+    const points = [];
+    for (const [period, events] of periodGroups) {
+      let value;
+      if (aggregate === 'count') {
+        value = events.length;
+      } else if (aggregate === 'sum') {
+        value = events.reduce((sum, e) => {
+          const fieldValue = e.indexed[sumField] || e.data[sumField];
+          const num = typeof fieldValue === 'string' ? parseFloat(fieldValue) : fieldValue;
+          return sum + (isNaN(num) ? 0 : num);
+        }, 0);
+      }
+
+      points.push({ period, value });
+    }
+
+    // Sort by period ascending (oldest first)
+    points.sort((a, b) => new Date(a.period) - new Date(b.period));
+
+    return points;
+  }
+
+  /**
+   * Detect address fields in an event.
+   * @param {IndexedEvent} event - Sample event
+   * @returns {string[]} Field names that look like addresses
+   */
+  _detectAddressFields(event) {
+    if (!event) return [];
+
+    const fields = [];
+    const allFields = { ...event.indexed, ...event.data };
+
+    for (const [key, value] of Object.entries(allFields)) {
+      if (typeof value === 'string' && value.match(/^0x[a-fA-F0-9]{40}$/)) {
+        fields.push(key);
+      }
+    }
+
+    return fields;
+  }
+}
+
+export default Patterns;

package/src/indexer/QueryEngine.js

@@ -0,0 +1,149 @@
+// src/indexer/QueryEngine.js
+
+/**
+ * Query engine for EventIndexer.
+ * Provides the Events API for direct event access.
+ */
+class QueryEngine {
+  constructor(storage, eventBus) {
+    this.storage = storage;
+    this.eventBus = eventBus;
+    this.subscriptions = new Map(); // subscriptionId -> { eventTypes, callback, where }
+    this.nextSubscriptionId = 1;
+  }
+
+  /**
+   * Query events with filters.
+   * @param {string} eventName - Event type to query
+   * @param {QueryOptions} options - Query options
+   * @returns {Promise<QueryResult>}
+   */
+  async query(eventName, options = {}) {
+    return this.storage.queryEvents(eventName, {
+      where: options.where,
+      orderBy: options.orderBy || 'blockNumber',
+      order: options.order || 'desc',
+      limit: options.limit || 100,
+      offset: options.offset || 0
+    });
+  }
+
+  /**
+   * Get single event by ID.
+   * @param {string} eventName - Event type
+   * @param {string} id - Event ID (txHash-logIndex)
+   * @returns {Promise<IndexedEvent|null>}
+   */
+  async get(eventName, id) {
+    return this.storage.getEvent(eventName, id);
+  }
+
+  /**
+   * Subscribe to new events.
+   * @param {string|string[]} eventNames - Event type(s) to subscribe to
+   * @param {Function} callback - Called with new events
+   * @returns {Function} Unsubscribe function
+   */
+  subscribe(eventNames, callback) {
+    const types = Array.isArray(eventNames) ? eventNames : [eventNames];
+    const subscriptionId = this.nextSubscriptionId++;
+
+    this.subscriptions.set(subscriptionId, {
+      eventTypes: new Set(types),
+      callback
+    });
+
+    // Return unsubscribe function
+    return () => {
+      this.subscriptions.delete(subscriptionId);
+    };
+  }
+
+  /**
+   * Count events matching filter.
+   * @param {string} eventName - Event type
+   * @param {Object} where - Filter conditions
+   * @returns {Promise<number>}
+   */
+  async count(eventName, where) {
+    return this.storage.countEvents(eventName, where);
+  }
+
+  /**
+   * Called by SyncEngine when new events are indexed.
+   * Notifies subscribers.
+   * @param {string} eventType - Event type
+   * @param {IndexedEvent[]} events - New events
+   */
+  notifyNewEvents(eventType, events) {
+    for (const subscription of this.subscriptions.values()) {
+      if (subscription.eventTypes.has(eventType) || subscription.eventTypes.has('*')) {
+        try {
+          subscription.callback(events);
+        } catch (error) {
+          console.error('[QueryEngine] Subscription callback error:', error);
+        }
+      }
+    }
+  }
+
+  /**
+   * Get all events for entity resolution (used by EntityResolver).
+   * Returns a lightweight checker interface.
+   * @param {Object} relatedWhere - Filter for related events
+   * @returns {Promise<EventChecker>}
+   */
+  async getEventChecker(relatedWhere = {}) {
+    // Pre-fetch all potentially related events
+    const eventCache = new Map();
+
+    return {
+      has: (eventName, where = {}) => {
+        const events = this._getCachedEvents(eventCache, eventName);
+        return events.some(e => this._matchesWhere(e, { ...relatedWhere, ...where }));
+      },
+
+      get: (eventName, where = {}) => {
+        const events = this._getCachedEvents(eventCache, eventName);
+        return events.filter(e => this._matchesWhere(e, { ...relatedWhere, ...where }));
+      },
+
+      count: (eventName, where = {}) => {
+        const events = this._getCachedEvents(eventCache, eventName);
+        return events.filter(e => this._matchesWhere(e, { ...relatedWhere, ...where })).length;
+      },
+
+      // Async method to prefetch events for a set of keys
+      prefetch: async (eventNames) => {
+        for (const eventName of eventNames) {
+          if (!eventCache.has(eventName)) {
+            const result = await this.storage.queryEvents(eventName, { limit: 10000 });
+            eventCache.set(eventName, result.events);
+          }
+        }
+      }
+    };
+  }
+
+  _getCachedEvents(cache, eventName) {
+    return cache.get(eventName) || [];
+  }
+
+  _matchesWhere(event, where) {
+    for (const [key, value] of Object.entries(where)) {
+      const eventValue = this._getNestedValue(event, key);
+      const normalizedEvent = typeof eventValue === 'string' ? eventValue.toLowerCase() : eventValue;
+      const normalizedValue = typeof value === 'string' ? value.toLowerCase() : value;
+      if (normalizedEvent !== normalizedValue) return false;
+    }
+    return true;
+  }
+
+  _getNestedValue(obj, path) {
+    if (obj.indexed?.[path] !== undefined) return obj.indexed[path];
+    if (obj.data?.[path] !== undefined) return obj.data[path];
+    return obj[path];
+  }
+}
+
+export default QueryEngine;