@sschepis/magazine 0.1.0

package/src/components/EventFilter.js

@@ -0,0 +1,474 @@
+/**
+ * EventFilter - Advanced filtering and querying for blockchain events
+ */
+export default class EventFilter {
+    constructor(logger) {
+        this.logger = logger.child({ context: 'EventFilter' });
+        this.logger.info('EventFilter initialized');
+    }
+
+    /**
+     * Build filter criteria from user input
+     * @param {Object} options - Filter options
+     * @param {number} options.fromBlock - Starting block number
+     * @param {number} options.toBlock - Ending block number
+     * @param {string} options.eventName - Event name to filter
+     * @param {Object} options.parameters - Event parameter filters
+     * @param {string} options.transactionHash - Filter by transaction hash
+     * @param {string} options.address - Filter by contract address
+     * @returns {Object} Filter criteria
+     */
+    buildFilter(options = {}) {
+        const filter = {};
+
+        // Block range filtering
+        if (options.fromBlock !== undefined) {
+            filter.fromBlock = options.fromBlock;
+        }
+
+        if (options.toBlock !== undefined) {
+            filter.toBlock = options.toBlock;
+        }
+
+        // Event name filtering
+        if (options.eventName) {
+            filter.eventName = options.eventName;
+        }
+
+        // Parameter filtering
+        if (options.parameters && Object.keys(options.parameters).length > 0) {
+            filter.parameters = options.parameters;
+        }
+
+        // Transaction hash filtering
+        if (options.transactionHash) {
+            filter.transactionHash = options.transactionHash;
+        }
+
+        // Address filtering
+        if (options.address) {
+            filter.address = options.address.toLowerCase();
+        }
+
+        // Pass through logical operators
+        if (options.$or) filter.$or = options.$or;
+        if (options.$and) filter.$and = options.$and;
+        if (options.$nor) filter.$nor = options.$nor;
+
+        this.logger.debug('Built filter criteria', { filter });
+        return filter;
+    }
+
+    /**
+     * Apply filters to an array of events
+     * @param {Array} events - Events to filter
+     * @param {Object} filter - Filter criteria
+     * @returns {Array} Filtered events
+     */
+    applyFilter(events, filter) {
+        if (!Array.isArray(events)) {
+            this.logger.warn('Invalid events array provided to applyFilter');
+            return [];
+        }
+
+        let filtered = [...events];
+
+        // Handle top-level logical combinators
+        if (filter.$or) {
+            filtered = filtered.filter(event =>
+                filter.$or.some(condition => {
+                    const subFilter = this.buildFilter(condition);
+                    return this.applyFilter([event], subFilter).length > 0;
+                })
+            );
+        }
+
+        if (filter.$and) {
+            filtered = filtered.filter(event =>
+                filter.$and.every(condition => {
+                    const subFilter = this.buildFilter(condition);
+                    return this.applyFilter([event], subFilter).length > 0;
+                })
+            );
+        }
+
+        if (filter.$nor) {
+            filtered = filtered.filter(event =>
+                filter.$nor.every(condition => {
+                    const subFilter = this.buildFilter(condition);
+                    return this.applyFilter([event], subFilter).length === 0;
+                })
+            );
+        }
+
+        // Filter by block range
+        if (filter.fromBlock !== undefined) {
+            filtered = filtered.filter(event => event.blockNumber >= filter.fromBlock);
+        }
+
+        if (filter.toBlock !== undefined) {
+            filtered = filtered.filter(event => event.blockNumber <= filter.toBlock);
+        }
+
+        // Filter by event name
+        if (filter.eventName) {
+            filtered = filtered.filter(event => event.eventName === filter.eventName);
+        }
+
+        // Filter by transaction hash
+        if (filter.transactionHash) {
+            filtered = filtered.filter(event =>
+                event.transactionHash.toLowerCase() === filter.transactionHash.toLowerCase()
+            );
+        }
+
+        // Filter by address
+        if (filter.address) {
+            filtered = filtered.filter(event =>
+                event.address && event.address.toLowerCase() === filter.address
+            );
+        }
+
+        // Filter by parameters
+        if (filter.parameters) {
+            filtered = filtered.filter(event =>
+                this._matchesParameters(event.args || {}, filter.parameters)
+            );
+        }
+
+        this.logger.debug('Applied filters', {
+            originalCount: events.length,
+            filteredCount: filtered.length,
+            filter
+        });
+
+        return filtered;
+    }
+
+    /**
+     * Check if event parameters match filter criteria (public API)
+     */
+    matchesParameters(eventArgs, filterParams) {
+        return this._matchesParameters(eventArgs, filterParams);
+    }
+
+    /**
+     * Check if event parameters match filter criteria
+     * @private
+     */
+    _matchesParameters(eventArgs, filterParams) {
+        for (const [key, value] of Object.entries(filterParams)) {
+            // Handle different value types
+            if (typeof value === 'object' && value !== null) {
+                // 'exists' operator: check field presence
+                if (value.exists !== undefined) {
+                    const fieldExists = eventArgs.hasOwnProperty(key);
+                    if (value.exists && !fieldExists) return false;
+                    if (!value.exists && fieldExists) return false;
+                    // If exists is the only operator, skip remaining checks for this key
+                    const otherKeys = Object.keys(value).filter(k => k !== 'exists');
+                    if (otherKeys.length === 0) continue;
+                }
+
+                // For all non-exists operators, the field must be present
+                if (!eventArgs.hasOwnProperty(key)) {
+                    return false;
+                }
+
+                // Range filtering for numbers
+                if (value.gte !== undefined && eventArgs[key] < value.gte) {
+                    return false;
+                }
+                if (value.lte !== undefined && eventArgs[key] > value.lte) {
+                    return false;
+                }
+                if (value.gt !== undefined && eventArgs[key] <= value.gt) {
+                    return false;
+                }
+                if (value.lt !== undefined && eventArgs[key] >= value.lt) {
+                    return false;
+                }
+
+                // 'in' operator: value must be in array
+                if (value.in !== undefined && !value.in.includes(eventArgs[key])) {
+                    return false;
+                }
+
+                // 'nin' operator: value must NOT be in array
+                if (value.nin !== undefined && value.nin.includes(eventArgs[key])) {
+                    return false;
+                }
+
+                // 'not' operator: negate a sub-condition
+                if (value.not !== undefined) {
+                    const subMatch = this._matchesParameters(eventArgs, { [key]: value.not });
+                    if (subMatch) return false;
+                }
+
+                // 'regex' operator: pattern matching
+                if (value.regex !== undefined) {
+                    const pattern = new RegExp(value.regex);
+                    if (!pattern.test(String(eventArgs[key]))) {
+                        return false;
+                    }
+                }
+
+                // 'size' operator: array length check
+                if (value.size !== undefined) {
+                    const arr = eventArgs[key];
+                    if (!Array.isArray(arr) || arr.length !== value.size) {
+                        return false;
+                    }
+                }
+            } else {
+                // Exact match - field must exist
+                if (!eventArgs.hasOwnProperty(key)) {
+                    return false;
+                }
+                if (eventArgs[key] !== value) {
+                    return false;
+                }
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Sort events by specified criteria
+     * @param {Array} events - Events to sort
+     * @param {Object} options - Sort options
+     * @param {string} options.by - Field to sort by (blockNumber, timestamp, etc.)
+     * @param {string} options.order - Sort order ('asc' or 'desc')
+     * @returns {Array} Sorted events
+     */
+    sortEvents(events, options = {}) {
+        const { by = 'blockNumber', order = 'asc' } = options;
+
+        const sorted = [...events].sort((a, b) => {
+            let aVal = a[by];
+            let bVal = b[by];
+
+            // Handle nested properties (e.g., 'args.value')
+            if (by.includes('.')) {
+                const path = by.split('.');
+                aVal = path.reduce((obj, key) => obj?.[key], a);
+                bVal = path.reduce((obj, key) => obj?.[key], b);
+            }
+
+            if (aVal === bVal) return 0;
+
+            const comparison = aVal < bVal ? -1 : 1;
+            return order === 'asc' ? comparison : -comparison;
+        });
+
+        this.logger.debug('Sorted events', { by, order, count: sorted.length });
+        return sorted;
+    }
+
+    /**
+     * Group events by specified field
+     * @param {Array} events - Events to group
+     * @param {string} field - Field to group by
+     * @returns {Object} Grouped events
+     */
+    groupEvents(events, field) {
+        const grouped = {};
+
+        for (const event of events) {
+            let key = event[field];
+
+            // Handle nested properties
+            if (field.includes('.')) {
+                const path = field.split('.');
+                key = path.reduce((obj, k) => obj?.[k], event);
+            }
+
+            if (key === undefined) {
+                key = 'undefined';
+            }
+
+            if (!grouped[key]) {
+                grouped[key] = [];
+            }
+
+            grouped[key].push(event);
+        }
+
+        this.logger.debug('Grouped events', {
+            field,
+            groups: Object.keys(grouped).length,
+            totalEvents: events.length
+        });
+
+        return grouped;
+    }
+
+    /**
+     * Create a query builder for fluent API
+     * @param {Array} events - Events to query
+     * @returns {QueryBuilder} Query builder instance
+     */
+    query(events) {
+        return new QueryBuilder(events, this);
+    }
+}
+
+/**
+ * QueryBuilder - Fluent API for event queries
+ */
+class QueryBuilder {
+    constructor(events, eventFilter) {
+        this.events = events;
+        this.eventFilter = eventFilter;
+        this.filters = {};
+        this.sortOptions = null;
+        this._limit = null;
+        this._skip = null;
+    }
+
+    /**
+     * Filter by block range
+     */
+    blockRange(from, to) {
+        if (from !== undefined) this.filters.fromBlock = from;
+        if (to !== undefined) this.filters.toBlock = to;
+        return this;
+    }
+
+    /**
+     * Filter by event name
+     */
+    eventName(name) {
+        this.filters.eventName = name;
+        return this;
+    }
+
+    /**
+     * Filter by transaction hash
+     */
+    transactionHash(hash) {
+        this.filters.transactionHash = hash;
+        return this;
+    }
+
+    /**
+     * Filter by contract address
+     */
+    address(addr) {
+        this.filters.address = addr;
+        return this;
+    }
+
+    /**
+     * Filter by event parameters
+     */
+    where(field, value) {
+        if (!this.filters.parameters) {
+            this.filters.parameters = {};
+        }
+        this.filters.parameters[field] = value;
+        return this;
+    }
+
+    /**
+     * Add an $or condition
+     */
+    orWhere(field, value) {
+        if (!this.filters.$or) {
+            this.filters.$or = [];
+        }
+        this.filters.$or.push({ parameters: { [field]: value } });
+        return this;
+    }
+
+    /**
+     * Shorthand for exists check on a field
+     */
+    whereExists(field) {
+        if (!this.filters.parameters) {
+            this.filters.parameters = {};
+        }
+        this.filters.parameters[field] = { exists: true };
+        return this;
+    }
+
+    /**
+     * Shorthand for regex match on a field
+     */
+    whereRegex(field, pattern) {
+        if (!this.filters.parameters) {
+            this.filters.parameters = {};
+        }
+        this.filters.parameters[field] = { regex: pattern };
+        return this;
+    }
+
+    /**
+     * Limit number of results
+     */
+    limit(n) {
+        this._limit = n;
+        return this;
+    }
+
+    /**
+     * Skip first n results
+     */
+    skip(n) {
+        this._skip = n;
+        return this;
+    }
+
+    /**
+     * Sort results
+     */
+    orderBy(field, order = 'asc') {
+        this.sortOptions = { by: field, order };
+        return this;
+    }
+
+    /**
+     * Execute query and return results
+     */
+    execute() {
+        let results = this.eventFilter.applyFilter(this.events, this.filters);
+
+        if (this.sortOptions) {
+            results = this.eventFilter.sortEvents(results, this.sortOptions);
+        }
+
+        if (this._skip !== null) {
+            results = results.slice(this._skip);
+        }
+
+        if (this._limit !== null) {
+            results = results.slice(0, this._limit);
+        }
+
+        return results;
+    }
+
+    /**
+     * Execute query and return first result
+     */
+    first() {
+        const results = this.execute();
+        return results.length > 0 ? results[0] : null;
+    }
+
+    /**
+     * Execute query and return count
+     */
+    count() {
+        return this.execute().length;
+    }
+
+    /**
+     * Execute query and group results
+     */
+    groupBy(field) {
+        const results = this.execute();
+        return this.eventFilter.groupEvents(results, field);
+    }
+}