web3-error-helper
Version:
> 🛠️ Turn confusing Web3 errors into clear, human-friendly messages for developers and users alike.
255 lines (254 loc) • 7.44 kB
JavaScript
;
/**
* Custom chain registry for managing blockchain network configurations
*
* This module provides a registry system for managing custom blockchain networks
* and their associated error mappings. It allows runtime registration of chains
* with their specific error patterns and fallback messages.
*/
Object.defineProperty(exports, "__esModule", { value: true });
exports.customChainRegistry = void 0;
exports.registerCustomChain = registerCustomChain;
exports.unregisterCustomChain = unregisterCustomChain;
exports.getCustomChain = getCustomChain;
exports.getAllCustomChains = getAllCustomChains;
exports.hasCustomChain = hasCustomChain;
exports.clearCustomChains = clearCustomChains;
exports.getCustomChains = getCustomChains;
exports.isCustomChain = isCustomChain;
/**
* In-memory registry for custom chain configurations
*/
class CustomChainRegistry {
chains = new Map();
/**
* Register a custom chain configuration
*
* @param config - The chain configuration to register
* @throws Error if chainId is already registered
*
* @example
* ```typescript
* const customChain: CustomChainConfig = {
* chainId: 'my-custom-chain',
* name: 'My Custom Chain',
* errorMappings: [
* { pattern: 'custom error', message: 'Custom error message' }
* ],
* customFallbacks: {
* generic: 'Custom chain error occurred'
* }
* };
*
* registry.register(customChain);
* ```
*/
register(config) {
if (this.chains.has(config.chainId)) {
throw new Error(`Chain '${config.chainId}' is already registered`);
}
this.validateConfig(config);
this.chains.set(config.chainId, { ...config });
}
/**
* Unregister a custom chain
*
* @param chainId - The chain identifier to unregister
* @returns true if the chain was removed, false if it wasn't found
*
* @example
* ```typescript
* const removed = registry.unregister('my-custom-chain');
* console.log(removed); // true if removed, false if not found
* ```
*/
unregister(chainId) {
return this.chains.delete(chainId);
}
/**
* Get a custom chain configuration
*
* @param chainId - The chain identifier to retrieve
* @returns The chain configuration or undefined if not found
*
* @example
* ```typescript
* const config = registry.get('my-custom-chain');
* if (config) {
* console.log(`Found chain: ${config.name}`);
* }
* ```
*/
get(chainId) {
return this.chains.get(chainId);
}
/**
* Get all registered custom chains
*
* @returns Array of all registered chain configurations
*
* @example
* ```typescript
* const allChains = registry.getAll();
* console.log(`Registered ${allChains.length} custom chains`);
* ```
*/
getAll() {
return Array.from(this.chains.values());
}
/**
* Check if a chain is registered
*
* @param chainId - The chain identifier to check
* @returns true if the chain is registered, false otherwise
*
* @example
* ```typescript
* if (registry.has('my-custom-chain')) {
* console.log('Chain is registered');
* }
* ```
*/
has(chainId) {
return this.chains.has(chainId);
}
/**
* Clear all registered custom chains
*
* @example
* ```typescript
* registry.clear();
* console.log('All custom chains cleared');
* ```
*/
clear() {
this.chains.clear();
}
/**
* Get error mappings for a specific chain
*
* @param chainId - The chain identifier
* @returns Array of error mappings for the chain
*/
getErrorMappings(chainId) {
const config = this.get(chainId);
return config?.errorMappings || [];
}
/**
* Get custom fallback messages for a specific chain
*
* @param chainId - The chain identifier
* @returns Custom fallback messages or undefined
*/
getCustomFallbacks(chainId) {
const config = this.get(chainId);
return config?.customFallbacks;
}
/**
* Validate a chain configuration
*
* @param config - The configuration to validate
* @throws Error if the configuration is invalid
*/
validateConfig(config) {
if (!config.chainId || typeof config.chainId !== 'string') {
throw new Error('chainId must be a non-empty string');
}
if (!config.name || typeof config.name !== 'string') {
throw new Error('name must be a non-empty string');
}
if (!Array.isArray(config.errorMappings)) {
throw new Error('errorMappings must be an array');
}
// Validate error mappings
config.errorMappings.forEach((mapping, index) => {
if (!mapping.pattern || typeof mapping.pattern !== 'string') {
throw new Error(`errorMappings[${index}].pattern must be a non-empty string`);
}
if (!mapping.message || typeof mapping.message !== 'string') {
throw new Error(`errorMappings[${index}].message must be a non-empty string`);
}
});
}
}
// Global registry instance
exports.customChainRegistry = new CustomChainRegistry();
/**
* Register a custom chain configuration
*
* @param config - The chain configuration to register
*
* @example
* ```typescript
* import { registerCustomChain } from './chain-registry';
*
* registerCustomChain({
* chainId: 'my-custom-chain',
* name: 'My Custom Chain',
* errorMappings: [
* { pattern: 'custom error', message: 'Custom error message' }
* ]
* });
* ```
*/
function registerCustomChain(config) {
exports.customChainRegistry.register(config);
}
/**
* Unregister a custom chain
*
* @param chainId - The chain identifier to unregister
* @returns true if the chain was removed, false if it wasn't found
*/
function unregisterCustomChain(chainId) {
return exports.customChainRegistry.unregister(chainId);
}
/**
* Get a custom chain configuration
*
* @param chainId - The chain identifier to retrieve
* @returns The chain configuration or undefined if not found
*/
function getCustomChain(chainId) {
return exports.customChainRegistry.get(chainId);
}
/**
* Get all registered custom chains
*
* @returns Array of all registered chain configurations
*/
function getAllCustomChains() {
return exports.customChainRegistry.getAll();
}
/**
* Check if a custom chain is registered
*
* @param chainId - The chain identifier to check
* @returns true if the chain is registered, false otherwise
*/
function hasCustomChain(chainId) {
return exports.customChainRegistry.has(chainId);
}
/**
* Clear all registered custom chains
*/
function clearCustomChains() {
exports.customChainRegistry.clear();
}
/**
* Get custom chain identifiers only
*
* @returns Array of custom chain identifiers
*/
function getCustomChains() {
return exports.customChainRegistry.getAll().map(config => config.chainId);
}
/**
* Check if a chain is custom
*
* @param chainId - The chain identifier to check
* @returns true if the chain is a custom registered chain
*/
function isCustomChain(chainId) {
return exports.customChainRegistry.has(chainId);
}