@sschepis/magazine 0.1.0

package/src/index.js

@@ -0,0 +1,571 @@
+// magazine - a decentralized library for ethereum event logging
+// magazine uses gun.js to store events in a decentralized manner
+// events are stored in a graph structure, where each event is a node
+// ethers.js is used to interact with the ethereum blockchain
+// gun.js is used to store events in a decentralized manner
+// 
+// Usage:
+// 1. create a new magazine
+// 2. sync history from the blockchain to the magazine
+// 3. publish the magazine
+// 4. subscribe to the magazine
+// 5. read events from the magazine
+
+// Import required libraries and components
+import ConfigManager from './components/ConfigManager.js';
+import NetworkManager from './components/NetworkManager.js';
+import EventStore from './components/EventStore.js';
+import EventSyncer from './components/EventSyncer.js';
+import EventMetadata from './components/EventMetadata.js';
+import DebugUtils from './components/DebugUtils.js';
+import DataTransformer from './components/DataTransformer.js';
+import Logger from './components/Logger.js';
+
+// Define Magazine class
+export default class Magazine {
+    constructor(config) {
+        // Initialize configuration manager and validate config
+        this.configManager = new ConfigManager(config);
+        const validatedConfig = this.configManager.getAll();
+        
+        // Initialize logger
+        this.logger = new Logger({
+            context: 'Magazine',
+            level: validatedConfig.logLevel || 'info'
+        });
+        
+        this.logger.info('Initializing Magazine', {
+            name: validatedConfig.name,
+            address: validatedConfig.address,
+            networkId: validatedConfig.networkId
+        });
+        
+        // Initialize retry operation as a shared utility
+        this.retryOptions = this.configManager.getRetryOptions();
+        
+        // Initialize modular components with dependency injection
+        this.networkManager = new NetworkManager(validatedConfig, this.retryOperation.bind(this));
+        this.eventStore = new EventStore(validatedConfig.gun, this.retryOperation.bind(this));
+        this.eventSyncer = new EventSyncer(
+            this.networkManager,
+            this.eventStore,
+            this.configManager,
+            this.retryOperation.bind(this)
+        );
+        
+        // Initialize EventMetadata component
+        this.eventMetadata = new EventMetadata(this.networkManager, this.logger);
+        
+        // Initialize DebugUtils component
+        this.debugUtils = new DebugUtils(this, this.logger);
+        
+        // Initialize DataTransformer component
+        this.dataTransformer = new DataTransformer(
+            this.eventStore.getGunInstance(),
+            {
+                logLevel: validatedConfig.logLevel,
+                enableAutoTransform: validatedConfig.enableAutoTransform !== false
+            }
+        );
+        
+        // Expose configuration for backward compatibility
+        this.name = validatedConfig.name;
+        this.address = validatedConfig.address;
+        this.networkId = validatedConfig.networkId;
+        this.abi = validatedConfig.abi;
+        
+        this.logger.info('Magazine initialized successfully', {
+            name: this.name,
+            address: this.address,
+            networkId: this.networkId,
+            eventCount: Object.keys(this.networkManager.eventsByTopic).length,
+            componentCount: 6,
+            debugModeEnabled: this.debugUtils.isDebugMode(),
+            dataTransformerEnabled: true
+        });
+    }
+
+    // Get configuration manager for advanced configuration access
+    getConfigManager() {
+        return this.configManager;
+    }
+
+    // Get network manager for advanced network operations
+    getNetworkManager() {
+        return this.networkManager;
+    }
+
+    // Get event store for advanced storage operations
+    getEventStore() {
+        return this.eventStore;
+    }
+
+    // Get event syncer for advanced synchronization operations
+    getEventSyncer() {
+        return this.eventSyncer;
+    }
+
+    // Get logger for external logging operations
+    getLogger() {
+        return this.logger;
+    }
+
+    // Set log level dynamically
+    setLogLevel(level) {
+        this.logger.setLevel(level);
+        this.logger.info('Log level updated', { newLevel: level });
+    }
+
+    // Retry wrapper for async operations
+    async retryOperation(operation, context = '') {
+        const { maxRetries, retryDelay, timeout } = this.retryOptions;
+        let lastError;
+        
+        this.logger.debug('Starting retry operation', { context, maxRetries, timeout });
+        
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                // Add timeout to the operation
+                const timeoutPromise = new Promise((_, reject) =>
+                    setTimeout(() => reject(new Error(`Operation timeout: ${context}`)), timeout)
+                );
+                
+                const result = await Promise.race([operation(), timeoutPromise]);
+                
+                if (attempt > 1) {
+                    this.logger.info('Retry operation succeeded', {
+                        context,
+                        attempt,
+                        maxRetries
+                    });
+                }
+                
+                return result;
+            } catch (error) {
+                lastError = error;
+                
+                this.logger.warn('Retry operation failed', {
+                    context,
+                    attempt,
+                    maxRetries,
+                    error: error.message
+                });
+                
+                if (attempt < maxRetries) {
+                    const delay = retryDelay * Math.pow(2, attempt - 1); // Exponential backoff
+                    this.logger.debug('Retrying operation', {
+                        context,
+                        delay: `${delay}ms`,
+                        nextAttempt: attempt + 1
+                    });
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                } else {
+                    this.logger.error('Retry operation exhausted', {
+                        context,
+                        totalAttempts: maxRetries,
+                        finalError: error.message,
+                        stack: error.stack
+                    });
+                }
+            }
+        }
+        
+        throw lastError;
+    }
+
+    // Start syncing events from the blockchain to the magazine
+    startSync() {
+        this.logger.info('Starting automatic sync');
+        this.stopSync();
+        
+        this.syncInterval = setInterval(async () => {
+            try {
+                await this.syncEvents();
+            } catch (error) {
+                this.logger.error('Automatic sync error', {
+                    error: error.message,
+                    stack: error.stack
+                });
+                // Continue syncing despite errors
+            }
+        }, 5000);
+        
+        // Initial sync
+        this.syncEvents().catch(error => {
+            this.logger.error('Initial sync error', {
+                error: error.message,
+                stack: error.stack
+            });
+        });
+        
+        this.logger.info('Automatic sync started', { interval: '5000ms' });
+    }
+
+    /**
+     * Start real-time event streaming (requires WebSocket provider)
+     */
+    startRealtimeSync() {
+        return this.eventSyncer.startRealtimeSync();
+    }
+
+    /**
+     * Stop real-time event streaming
+     */
+    stopRealtimeSync() {
+        return this.eventSyncer.stopRealtimeSync();
+    }
+
+    /**
+     * Destroy the magazine instance, stopping sync and cleaning up listeners
+     */
+    destroy() {
+        this.stopSync();
+        this.stopRealtimeSync();
+        this.eventStore.destroy();
+        this.logger.info('Magazine instance destroyed');
+    }
+
+    // Stop syncing events from the blockchain to the magazine
+    stopSync() {
+        if (this.syncInterval) {
+            this.logger.info('Stopping automatic sync');
+            clearInterval(this.syncInterval);
+            this.syncInterval = undefined;
+        }
+    }
+
+    // Sync events from the blockchain to the magazine - delegates to EventSyncer
+    async syncEvents() {
+        return this.eventSyncer.syncEvents();
+    }
+
+    // Sync events from a specific block range
+    async syncEventsFromRange(fromBlock, toBlock) {
+        return this.eventSyncer.syncEventsFromRange(fromBlock, toBlock);
+    }
+
+    // Sync events from a specific transaction
+    async syncEventsFromTransaction(txHash) {
+        return this.eventSyncer.syncEventsFromTransaction(txHash);
+    }
+
+    // Get sync status information
+    async getSyncStatus() {
+        return this.eventSyncer.getSyncStatus();
+    }
+
+    // Get the start block number for syncing events - delegates to EventStore
+    async getStartBlockNumber() {
+        return this.eventStore.getStartBlockNumber();
+    }
+
+    // Set the start block number for syncing events - delegates to EventStore
+    async setStartBlockNumber(startBlockNumber) {
+        this.configManager.validateBlockNumber(startBlockNumber, 'startBlockNumber');
+        return this.eventStore.setStartBlockNumber(startBlockNumber);
+    }
+
+    // Get events by name with optional filtering
+    async getEvents(eventName, filter = {}) {
+        // Use the new filtering system
+        const result = await this.getAllEvents({
+            filter: { ...filter, eventName }
+        });
+        return result.data;
+    }
+
+    // Get all events with optional filtering and pagination
+    async getAllEvents(options = {}) {
+        return this.eventStore.getAllEvents(options);
+    }
+
+    /**
+     * Query events using fluent API
+     * @returns {Promise<Object>} Query builder
+     * @example
+     * const results = await magazine.query()
+     *   .eventName('Transfer')
+     *   .blockRange(1000, 2000)
+     *   .where('value', { gte: 1000 })
+     *   .orderBy('blockNumber', 'desc')
+     *   .execute();
+     */
+    async query() {
+        return this.eventStore.query();
+    }
+
+    /**
+     * Get events by transaction hash
+     * @param {string} transactionHash - Transaction hash to search for
+     * @returns {Promise<Array>} Events from the transaction
+     */
+    async getEventsByTransactionHash(transactionHash) {
+        if (!transactionHash || typeof transactionHash !== 'string') {
+            throw new Error('Transaction hash must be a non-empty string');
+        }
+        return this.eventStore.getEventsByTransactionHash(transactionHash);
+    }
+
+    /**
+     * Get events by block number
+     * @param {number} blockNumber - Block number to search for
+     * @returns {Promise<Array>} Events from the block
+     */
+    async getEventsByBlockNumber(blockNumber) {
+        if (!Number.isInteger(blockNumber) || blockNumber < 0) {
+            throw new Error('Block number must be a non-negative integer');
+        }
+        return this.eventStore.getEventsByBlockNumber(blockNumber);
+    }
+
+    /**
+     * Create async iterator for events
+     * @param {Object} options - Iterator options
+     * @param {Object} options.filter - Filter criteria
+     * @param {Object} options.sort - Sort options
+     * @param {number} options.pageSize - Items per iteration batch
+     * @returns {AsyncIterator} Async iterator for events
+     * @example
+     * for await (const event of magazine.iterateEvents({ pageSize: 50 })) {
+     *   console.log(event);
+     * }
+     */
+    async *iterateEvents(options = {}) {
+        yield* this.eventStore.iterateEvents(options);
+    }
+
+    // Get network information
+    async getNetworkInfo() {
+        return this.networkManager.getNetworkInfo();
+    }
+
+    // Validate network and contract
+    async validateNetwork() {
+        return this.networkManager.validateNetwork();
+    }
+
+    // Get latest block number
+    async getLatestBlockNumber() {
+        return this.networkManager.getLatestBlockNumber();
+    }
+
+    // Publish the magazine to the decentralized network
+    async publish(options = {}) {
+        const validatedOptions = this.configManager.validateOptions(options, ['alias', 'url']);
+        
+        // Validate specific option values
+        if (validatedOptions.alias && (typeof validatedOptions.alias !== 'string' || validatedOptions.alias.trim().length === 0)) {
+            throw new Error('alias must be a non-empty string');
+        }
+        
+        if (validatedOptions.url) {
+            if (typeof validatedOptions.url !== 'string') {
+                throw new Error('url must be a string');
+            }
+            try {
+                new URL(validatedOptions.url);
+            } catch {
+                throw new Error('url must be a valid URL');
+            }
+        }
+        
+        const alias = validatedOptions.alias ? validatedOptions.alias : this.name.toLowerCase().replace(/\s/g, '-');
+        const url = validatedOptions.url ? validatedOptions.url : `https://gunjs.herokuapp.com/gun`;
+
+        const magazineData = {
+            name: this.name,
+            address: this.address,
+            networkId: this.networkId,
+            abi: this.abi,
+        };
+
+        return this.eventStore.publishMagazine(alias, magazineData, url);
+    }
+
+    // Subscribe to a magazine on the decentralized network
+    static async subscribe(magazineId, config) {
+        // Validate parameters
+        if (!magazineId || typeof magazineId !== 'string') {
+            throw new Error('magazineId must be a non-empty string');
+        }
+        
+        if (!config || typeof config !== 'object') {
+            throw new Error('config must be an object');
+        }
+        
+        // Validate required config fields for subscription
+        const requiredFields = ['gun'];
+        for (const field of requiredFields) {
+            if (!config[field]) {
+                throw new Error(`Config field '${field}' is required for subscription`);
+            }
+        }
+
+        // Create a temporary event store for subscription
+        const tempEventStore = new EventStore(config.gun, () => {});
+        return tempEventStore.subscribeMagazine(magazineId);
+    }
+
+    // Read events from the magazine - delegates to EventStore
+    on(eventName, callback) {
+        if (typeof callback !== 'function') {
+            throw new Error('callback must be a function');
+        }
+        const gunInstance = this.eventStore.getGunInstance();
+        const eventNode = gunInstance.get('events').get(eventName);
+        eventNode.map().on(callback);
+    }
+
+    /**
+     * Health check endpoint - performs system health checks
+     * @returns {Promise<Object>} Health check results
+     */
+    async healthCheck() {
+        return this.debugUtils.healthCheck();
+    }
+
+    /**
+     * Get performance metrics
+     * @returns {Promise<Object>} Performance metrics
+     */
+    async getPerformanceMetrics() {
+        return this.debugUtils.getPerformanceReport();
+    }
+
+    /**
+     * Export debug information
+     * @param {Object} options - Export options
+     * @returns {Promise<Object>} Debug information
+     */
+    async exportDebugInfo(options = {}) {
+        return this.debugUtils.exportDebugData();
+    }
+
+    /**
+     * Enable or disable debug mode
+     * @param {boolean} enabled - Whether to enable debug mode
+     */
+    setDebugMode(enabled) {
+        this.debugUtils.setDebugMode(enabled);
+    }
+
+    /**
+     * Check if debug mode is enabled
+     * @returns {boolean} Debug mode status
+     */
+    isDebugMode() {
+        return this.debugUtils.isDebugMode();
+    }
+
+    /**
+     * Get configuration schema documentation
+     * @returns {Object} Schema documentation
+     */
+    getConfigSchema() {
+        return this.configManager.getSchemaDocumentation();
+    }
+
+    /**
+     * Generate example configuration
+     * @param {Object} options - Generation options
+     * @returns {Object} Example configuration
+     */
+    static generateExampleConfig(options = {}) {
+        const configManager = new ConfigManager({
+            name: 'temp',
+            address: '0x0000000000000000000000000000000000000000',
+            abi: [],
+            provider: 'http://localhost:8545',
+            networkId: 1
+        });
+        return configManager.generateExampleConfig(options);
+    }
+
+    /**
+     * Validate configuration without creating an instance
+     * @static
+     * @param {Object} config - Configuration to validate
+     * @returns {Object} Validation result
+     */
+    static validateConfig(config) {
+        return ConfigManager.validateConfiguration(config);
+    }
+
+    /**
+     * Get compression statistics from the event store
+     * @returns {Promise<Object>} Compression stats
+     */
+    async getCompressionStats() {
+        return this.eventStore.getCompressionStats();
+    }
+
+    // === Data Transformation API ===
+
+    /**
+     * Create or get a data model for structured storage
+     * @param {string} name - Model name
+     * @param {Object} schema - Model schema definition
+     * @param {Object} options - Model options
+     * @returns {Object} DataModel instance
+     */
+    model(name, schema, options = {}) {
+        return this.dataTransformer.model(name, schema, options);
+    }
+
+    /**
+     * Register an event transformer that converts blockchain events to model data
+     * @param {string} eventName - Event name to transform
+     * @param {string} modelName - Target model name
+     * @param {Function} transformFn - Transformation function
+     */
+    registerTransformer(eventName, modelName, transformFn) {
+        return this.dataTransformer.registerTransformer(eventName, modelName, transformFn);
+    }
+
+    /**
+     * Get a registered data model
+     * @param {string} name - Model name
+     * @returns {Object} DataModel instance
+     */
+    getModel(name) {
+        return this.dataTransformer.getModel(name);
+    }
+
+    /**
+     * Transform an event using registered transformers
+     * @param {Object} event - Blockchain event to transform
+     * @returns {Promise<Object|null>} Transformed data or null
+     */
+    async transformEvent(event) {
+        return this.dataTransformer.transformEvent(event);
+    }
+
+    /**
+     * Get data transformation statistics
+     * @returns {Object} Transformation stats
+     */
+    getTransformationStats() {
+        return this.dataTransformer.getStats();
+    }
+
+    /**
+     * Get all registered models
+     * @returns {Map} Map of model name to DataModel instance
+     */
+    getModels() {
+        return this.dataTransformer.getModels();
+    }
+}
+
+// Named exports for advanced usage
+export { default as ConfigManager } from './components/ConfigManager.js';
+export { default as NetworkManager } from './components/NetworkManager.js';
+export { default as EventStore } from './components/EventStore.js';
+export { default as EventSyncer } from './components/EventSyncer.js';
+export { default as EventMetadata } from './components/EventMetadata.js';
+export { default as DebugUtils } from './components/DebugUtils.js';
+export { default as DataTransformer, ValidationError, ModelError, DataModel, AggregationPipeline, SchemaMigration } from './components/DataTransformer.js';
+export { default as EventFilter } from './components/EventFilter.js';
+export { default as DataCompressor } from './components/DataCompressor.js';
+export { default as Paginator, PaginationHelper } from './components/Paginator.js';
+export { default as Logger } from './components/Logger.js';