@sschepis/magazine 0.1.0

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@sschepis/magazine",
+  "version": "0.1.0",
+  "description": "A decentralized library for Ethereum event logging, syncing, and querying using ethers.js and GunDB",
+  "type": "module",
+  "main": "./dist/magazine.umd.js",
+  "module": "./dist/magazine.es.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/magazine.es.js",
+      "require": "./dist/magazine.cjs.js",
+      "default": "./dist/magazine.umd.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ethereum",
+    "events",
+    "blockchain",
+    "indexer",
+    "gun",
+    "gundb",
+    "decentralized",
+    "ethers",
+    "web3",
+    "event-log",
+    "smart-contract"
+  ],
+  "author": "Sebastian Schepis",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sschepis/magazine.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sschepis/magazine/issues"
+  },
+  "homepage": "https://github.com/sschepis/magazine#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "kill $(lsof -t -i:8545) &> /dev/null; npx hardhat node & (sleep 5 && npx hardhat test && kill $!)",
+    "test:unit": "npx mocha test/unit.test.cjs --timeout 10000",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@nomicfoundation/hardhat-chai-matchers": "^2.1.0",
+    "@nomicfoundation/hardhat-ethers": "^3.1.0",
+    "@nomicfoundation/hardhat-network-helpers": "^1.1.0",
+    "@nomicfoundation/hardhat-toolbox": "^6.1.0",
+    "chai": "^4.3.7",
+    "chai-as-promised": "^8.0.1",
+    "hardhat": "^2.26.1",
+    "mocha": "^10.2.0",
+    "sinon": "^21.0.0",
+    "vite": "^4.1.0"
+  },
+  "dependencies": {
+    "ethers": "^6.0.8",
+    "gun": "^0.2020.1239",
+    "pako": "^2.1.0"
+  }
+}

package/src/components/ConfigManager.js

@@ -0,0 +1,202 @@
+import Logger from './Logger.js';
+import ConfigSchema from './ConfigSchema.js';
+
+/**
+ * ConfigManager - Handles configuration validation and management using ConfigSchema
+ * 
+ * @class ConfigManager
+ * @description Provides comprehensive configuration validation, management, and documentation
+ * using a formal schema-based approach for better error handling and developer experience.
+ */
+export default class ConfigManager {
+    /**
+     * Create a ConfigManager instance
+     * @param {Object} config - Configuration object to validate and manage
+     * @throws {Error} If configuration validation fails
+     */
+    constructor(config) {
+        this.schema = new ConfigSchema();
+        
+        // Initialize logger with basic config for validation logging
+        this.logger = new Logger({
+            context: 'ConfigManager',
+            level: config?.logLevel || 'info'
+        });
+        
+        this.logger.debug('Initializing ConfigManager with schema validation', { 
+            config: this._sanitizeConfig(config) 
+        });
+        
+        // Validate and process configuration using schema
+        const validationResult = this.validateConfig(config);
+        
+        if (!validationResult.valid) {
+            const errorMessage = this._formatValidationErrors(validationResult.errors);
+            this.logger.error('Configuration validation failed', { 
+                errors: validationResult.errors,
+                warnings: validationResult.warnings 
+            });
+            throw new Error(`Configuration validation failed:\n${errorMessage}`);
+        }
+        
+        // Log validation warnings if any
+        if (validationResult.warnings.length > 0) {
+            this.logger.warn('Configuration validation warnings', { 
+                warnings: validationResult.warnings 
+            });
+        }
+        
+        // Use validated configuration
+        this.config = validationResult.validated;
+        
+        this.logger.info('ConfigManager initialized successfully', {
+            name: this.config.name,
+            address: this.config.address,
+            networkId: this.config.networkId,
+            maxRetries: this.config.maxRetries,
+            retryDelay: this.config.retryDelay,
+            timeout: this.config.timeout,
+            warningsCount: validationResult.warnings.length
+        });
+    }
+
+    /**
+     * Sanitize config for logging (remove sensitive data)
+     * @private
+     * @param {Object} config - Configuration object to sanitize
+     * @returns {Object} Sanitized configuration object
+     */
+    _sanitizeConfig(config) {
+        if (!config) return config;
+        const sanitized = { ...config };
+        // Remove potentially sensitive information
+        if (sanitized.gun) {
+            sanitized.gun = { ...sanitized.gun };
+            delete sanitized.gun.peers; // May contain sensitive URLs
+        }
+        return sanitized;
+    }
+
+    /**
+     * Validate configuration using ConfigSchema
+     * @param {Object} config - Configuration object to validate
+     * @returns {Object} Validation result with validated config
+     */
+    validateConfig(config) {
+        if (!config || typeof config !== 'object') {
+            return {
+                valid: false,
+                errors: [{
+                    field: 'config',
+                    type: 'required',
+                    message: 'Configuration must be a non-null object'
+                }],
+                warnings: [],
+                validated: {}
+            };
+        }
+        
+        return this.schema.validate(config);
+    }
+
+    /**
+     * Format validation errors into a readable string
+     * @private
+     * @param {Array} errors - Array of validation errors
+     * @returns {string} Formatted error message
+     */
+    _formatValidationErrors(errors) {
+        return errors.map(error => `  - ${error.field}: ${error.message}`).join('\n');
+    }
+
+    /**
+     * Get schema documentation
+     * @returns {Object} Schema documentation object
+     */
+    getSchemaDocumentation() {
+        return this.schema.getDocumentation();
+    }
+
+    /**
+     * Generate example configuration
+     * @param {Object} options - Generation options
+     * @returns {Object} Example configuration object
+     */
+    generateExampleConfig(options = {}) {
+        return this.schema.generateExample(options);
+    }
+
+    /**
+     * Validate a configuration object without creating an instance
+     * @static
+     * @param {Object} config - Configuration to validate
+     * @returns {Object} Validation result
+     */
+    static validateConfiguration(config) {
+        const schema = new ConfigSchema();
+        return schema.validate(config);
+    }
+
+    /**
+     * Validate block number parameters
+     * @param {number} blockNumber - Block number to validate
+     * @param {string} paramName - Parameter name for error messages
+     * @throws {Error} If block number is invalid
+     */
+    validateBlockNumber(blockNumber, paramName = 'blockNumber') {
+        if (!Number.isInteger(blockNumber) || blockNumber < 0) {
+            throw new Error(`${paramName} must be a non-negative integer`);
+        }
+    }
+
+    /**
+     * Validate options object for API methods
+     * @param {Object} options - Options object to validate
+     * @param {Array} allowedKeys - Array of allowed option keys
+     * @returns {Object} Validated options object
+     * @throws {Error} If options are invalid
+     */
+    validateOptions(options, allowedKeys = []) {
+        if (options !== undefined && (typeof options !== 'object' || options === null)) {
+            throw new Error('Options must be an object');
+        }
+        
+        if (options && allowedKeys.length > 0) {
+            const invalidKeys = Object.keys(options).filter(key => !allowedKeys.includes(key));
+            if (invalidKeys.length > 0) {
+                throw new Error(`Invalid option keys: ${invalidKeys.join(', ')}. Allowed: ${allowedKeys.join(', ')}`);
+            }
+        }
+        
+        return options || {};
+    }
+
+    /**
+     * Get configuration value by key
+     * @param {string} key - Configuration key
+     * @returns {*} Configuration value
+     */
+    get(key) {
+        return this.config[key];
+    }
+
+    /**
+     * Get all configuration
+     * @returns {Object} Complete configuration object
+     */
+    getAll() {
+        return { ...this.config };
+    }
+
+    /**
+     * Get retry options for network operations
+     * @returns {Object} Retry configuration object
+     */
+    getRetryOptions() {
+        return {
+            maxRetries: this.config.maxRetries,
+            retryDelay: this.config.retryDelay,
+            timeout: this.config.timeout
+        };
+    }
+}