wttp-core
Version:
Core contracts, interfaces, and TypeScript types for the Web3 Transfer Protocol (WTTP).
154 lines • 6.31 kB
TypeScript
/**
* Interface for the result of URL preprocessing operations
* @internal
*/
interface ProcessedURL {
/** The URL string with alias removed, safe for native URL constructor */
processedUrl: string;
/** The extracted alias/chain identifier from the port position */
extractedAlias: string;
}
/**
* Extended URL class that supports string aliases in the port position
*
* wURL (wide URL) extends the native URL class to handle scenarios where the port position
* contains non-numeric values like blockchain chain identifiers, environment names, or other aliases.
*
* Key features:
* - Maintains 100% compatibility with native URL behavior
* - Supports aliases like "mainnet", "sepolia", or large chain IDs (>65535) in port position
* - Preserves all URL operations (relative resolution, property access, etc.)
* - Custom toString() that displays the alias instead of processed port
* - IPv6 address support with alias extraction
*
* @example
* ```typescript
* // Standard URL with valid port
* const url1 = new wURL('https://api.example.com:8080/data');
* console.log(url1.port); // "8080"
* console.log(url1.alias); // "8080"
*
* // URL with chain ID alias
* const url2 = new wURL('wttp://contract.eth:11155111/api');
* console.log(url2.port); // "" (empty, invalid for native URL)
* console.log(url2.alias); // "11155111"
*
* // URL with string alias
* const url3 = new wURL('https://api.example.com:mainnet/users');
* console.log(url3.alias); // "mainnet"
* console.log(url3.toString()); // "https://api.example.com:mainnet/users"
*
* // Relative URL resolution with alias inheritance
* const base = new wURL('wttp://example.com:sepolia/base/');
* const relative = new wURL('../api/data', base);
* console.log(relative.alias); // "sepolia" (inherited from base)
* ```
*/
export declare class wURL extends URL {
/**
* The alias/chain identifier extracted from the port position
*
* This property stores the original value from the port position, whether it's:
* - A valid port number (≤65535): alias equals port
* - An invalid large number (>65535): alias stores the full number
* - A string identifier: alias stores the string value
*
* @example
* ```typescript
* const url = new wURL('https://api.example.com:mainnet/data');
* console.log(url.alias); // "mainnet"
*
* const chainUrl = new wURL('wttp://contract.eth:11155111/api');
* console.log(chainUrl.alias); // "11155111"
* ```
*/
alias: string;
/**
* Creates a new wURL instance
*
* @param url - The URL string, URL object, or wURL object to parse
* @param base - Optional base URL for resolving relative URLs
*
* @throws {Error} When the URL is invalid or malformed
* @throws {Error} When IPv6 format is invalid
* @throws {Error} When alias format contains too many colons
*
* @example
* ```typescript
* // Absolute URLs
* const url1 = new wURL('https://example.com:mainnet/api');
* const url2 = new wURL('wttp://contract.eth:11155111/data');
*
* // Relative URLs with base
* const base = new wURL('https://api.example.com:staging/v1/');
* const endpoint = new wURL('users/profile', base);
* console.log(endpoint.alias); // "staging" (inherited from base)
*
* // IPv6 with alias
* const ipv6 = new wURL('https://[::1]:development/local');
* console.log(ipv6.alias); // "development"
* ```
*/
constructor(url: string | URL | wURL, base?: string | URL | wURL);
/**
* Returns the string representation of the URL with alias displayed
*
* When the alias differs from the port, this method replaces the port
* in the URL string with the alias for display purposes.
*
* @returns The URL string with alias in the port position
*
* @example
* ```typescript
* const url = new wURL('https://api.example.com:mainnet/data');
* console.log(url.toString()); // "https://api.example.com:mainnet/data"
* console.log(url.href); // "https://api.example.com/data" (native URL)
*
* const validPort = new wURL('https://api.example.com:8080/data');
* console.log(validPort.toString()); // "https://api.example.com:8080/data"
* ```
*/
toString(): string;
/**
* Preprocesses a URL to extract alias and make it compatible with native URL constructor
*
* This static method handles the complex logic of:
* - Detecting relative vs absolute URLs
* - Parsing port vs alias in the authority section
* - Handling IPv6 addresses with brackets
* - Extracting aliases while preserving URL structure
* - Creating URL strings safe for native URL constructor
*
* @param url - The URL to preprocess
* @param base - Optional base URL (currently unused but kept for API consistency)
* @returns Object containing the processed URL and extracted alias
*
* @throws {Error} When the URL is invalid
* @throws {Error} When IPv6 format is malformed
* @throws {Error} When authority contains too many colons (ambiguous parsing)
*
* @internal This method is primarily for internal use but exposed for testing
*
* @example
* ```typescript
* // Valid port - returned as-is
* wURL.preprocessUrl('https://example.com:8080/path');
* // Returns: { processedUrl: 'https://example.com:8080/path', extractedAlias: '8080' }
*
* // Invalid large port - alias extracted, port removed
* wURL.preprocessUrl('wttp://contract.eth:11155111/api');
* // Returns: { processedUrl: 'wttp://contract.eth/api', extractedAlias: '11155111' }
*
* // String alias - extracted and removed
* wURL.preprocessUrl('https://api.example.com:mainnet/data');
* // Returns: { processedUrl: 'https://api.example.com/data', extractedAlias: 'mainnet' }
*
* // IPv6 with alias
* wURL.preprocessUrl('https://[::1]:development/local');
* // Returns: { processedUrl: 'https://[::1]/local', extractedAlias: 'development' }
* ```
*/
static preprocessUrl(url: string | URL | wURL, base?: string | URL | wURL): ProcessedURL;
}
export {};
//# sourceMappingURL=wurl.d.ts.map