Web & Browser

/**
 * Parse URL into its components
 * @param url - URL string to parse
 * @returns Parsed URL object with all components
 */
function parseUrl(url: string): ParsedUrl;

interface ParsedUrl {
  /** Full URL */
  href: string;
  /** Protocol (http:, https:, etc.) */
  protocol: string;
  /** Hostname */
  hostname: string;
  /** Port number */
  port: string;
  /** Host (hostname:port) */
  host: string;
  /** Pathname */
  pathname: string;
  /** Query string (including ?) */
  search: string;
  /** Fragment/hash (including #) */
  hash: string;
  /** Origin (protocol + host) */
  origin: string;
}

/**
 * Serialize object to query string
 * @param obj - Object to serialize
 * @param options - Serialization options
 * @returns Query string
 */
function serialize(obj: any, options?: SerializeOptions): string;

/**
 * Parse query string to object
 * @param str - Query string to parse
 * @param options - Parsing options
 * @returns Parsed object
 */
function unserialize(str: string, options?: SerializeOptions): any;

interface SerializeOptions {
  /** Whether to encode URI components (default: true) */
  encode?: boolean;
  /** Custom separator (default: '&') */
  separator?: string;
  /** Custom assignment operator (default: '=') */
  assignment?: string;
}

/**
 * Get cookie value by name
 * @param name - Cookie name
 * @returns Cookie value or undefined
 */
function cookie(name: string): string | undefined;

/**
 * Set cookie with value and options
 * @param name - Cookie name
 * @param value - Cookie value
 * @param options - Cookie options
 * @returns Cookie value
 */
function cookie(name: string, value: any, options?: CookieOptions): string;

/**
 * Get all cookies as object
 * @returns Object with all cookies
 */
function cookie(): { [name: string]: string };

interface CookieOptions {
  /** Expiration in days (default: session cookie) */
  expires?: number;
  /** Cookie path (default: '/') */
  path?: string;
  /** Cookie domain */
  domain?: string;
  /** Secure flag (HTTPS only) */
  secure?: boolean;
  /** HttpOnly flag (server-side only) */
  httpOnly?: boolean;
  /** SameSite policy */
  sameSite?: 'Strict' | 'Lax' | 'None';
}

/**
 * Navigate to URL
 * @param url - URL to navigate to
 * @param replace - Whether to replace current history entry (default: false)
 */
function locat(url: string, replace?: boolean): void;

/**
 * Get base URL of current page
 * @returns Base URL string
 */
function getBaseURL(): string;

/**
 * Get comprehensive browser information
 * @returns Browser information object
 */
function browse(): BrowserInfo;

interface BrowserInfo {
  /** Browser name */
  name: string;
  /** Browser version */
  version: string;
  /** Major version number */
  majorVersion: number;
  /** Full user agent string */
  userAgent: string;
  /** Operating system */
  os: string;
  /** Device type */
  device: string;
  /** Whether browser is mobile */
  isMobile: boolean;
  /** Whether browser is tablet */
  isTablet: boolean;
  /** Whether browser is desktop */
  isDesktop: boolean;
  /** Specific browser flags */
  isChrome: boolean;
  isFirefox: boolean;
  isSafari: boolean;
  isEdge: boolean;
  isIE: boolean;
  isOpera: boolean;
}

import { parseUrl, serialize, unserialize, cookie, locat, getBaseURL, browse } from 'xe-utils';

// URL parsing
const url = 'https://api.example.com:8080/users?page=1&limit=10#section1';
const parsed = parseUrl(url);

console.log(parsed.protocol); // 'https:'
console.log(parsed.hostname); // 'api.example.com'
console.log(parsed.port); // '8080'
console.log(parsed.pathname); // '/users'
console.log(parsed.search); // '?page=1&limit=10'
console.log(parsed.hash); // '#section1'
console.log(parsed.origin); // 'https://api.example.com:8080'

// Query string operations
const params = {
  page: 1,
  limit: 10,
  sort: 'name',
  filters: ['active', 'verified']
};

const queryString = serialize(params);
console.log(queryString); // 'page=1&limit=10&sort=name&filters=active&filters=verified'

const parsed_params = unserialize('name=Alice&age=25&active=true');
console.log(parsed_params); // { name: 'Alice', age: '25', active: 'true' }

// Custom serialization
const customQuery = serialize(params, {
  separator: ';',
  assignment: ':',
  encode: false
});
console.log(customQuery); // 'page:1;limit:10;sort:name;filters:active;filters:verified'

// Cookie management
// Set cookies
cookie('username', 'alice');
cookie('theme', 'dark', { expires: 30 }); // Expires in 30 days
cookie('session', 'abc123', { 
  expires: 1, 
  path: '/', 
  secure: true,
  sameSite: 'Strict'
});

// Get cookies
console.log(cookie('username')); // 'alice'
console.log(cookie('theme')); // 'dark'

// Get all cookies
const allCookies = cookie();
console.log(allCookies); // { username: 'alice', theme: 'dark', session: 'abc123' }

// Remove cookie (set expires to past date)
cookie('username', '', { expires: -1 });

// Navigation
function navigateToPage(path) {
  const baseUrl = getBaseURL();
  const fullUrl = baseUrl + path;
  locat(fullUrl);
}

function navigateAndReplace(url) {
  locat(url, true); // Replace current history entry
}

// Usage
navigateToPage('/dashboard');
navigateAndReplace('/login');

// Browser detection
const browserInfo = browse();
console.log(browserInfo.name); // 'Chrome', 'Firefox', 'Safari', etc.
console.log(browserInfo.version); // '91.0.4472.124'
console.log(browserInfo.majorVersion); // 91
console.log(browserInfo.os); // 'Windows', 'macOS', 'Linux', etc.
console.log(browserInfo.isMobile); // true/false

// Conditional behavior based on browser
if (browserInfo.isIE && browserInfo.majorVersion < 11) {
  console.log('Please upgrade your browser');
}

if (browserInfo.isMobile) {
  // Load mobile-specific resources
  console.log('Loading mobile UI');
} else {
  // Load desktop resources
  console.log('Loading desktop UI');
}

// Practical examples
class URLManager {
  constructor() {
    this.baseUrl = getBaseURL();
  }
  
  buildApiUrl(endpoint, params = {}) {
    const queryString = serialize(params);
    return `${this.baseUrl}/api${endpoint}${queryString ? '?' + queryString : ''}`;
  }
  
  parseCurrentUrl() {
    return parseUrl(window.location.href);
  }
  
  updateQueryParams(newParams) {
    const current = this.parseCurrentUrl();
    const existingParams = unserialize(current.search.substring(1));
    const merged = { ...existingParams, ...newParams };
    const newQuery = serialize(merged);
    const newUrl = `${current.pathname}?${newQuery}${current.hash}`;
    locat(newUrl, true);
  }
}

class CookieManager {
  setUserPreferences(prefs) {
    cookie('userPrefs', JSON.stringify(prefs), { 
      expires: 365,
      path: '/',
      sameSite: 'Lax'
    });
  }
  
  getUserPreferences() {
    const prefs = cookie('userPrefs');
    return prefs ? JSON.parse(prefs) : {};
  }
  
  clearUserData() {
    const allCookies = cookie();
    Object.keys(allCookies).forEach(name => {
      if (name.startsWith('user')) {
        cookie(name, '', { expires: -1 });
      }
    });
  }
}

class BrowserCompatibility {
  constructor() {
    this.browser = browse();
  }
  
  supportsModernFeatures() {
    // Check for modern browser features
    return !(this.browser.isIE || 
            (this.browser.isChrome && this.browser.majorVersion < 60) ||
            (this.browser.isFirefox && this.browser.majorVersion < 55));
  }
  
  loadPolyfills() {
    if (!this.supportsModernFeatures()) {
      console.log('Loading polyfills for older browser');
      // Load polyfills
    }
  }
  
  getOptimalImageFormat() {
    if (this.browser.isChrome && this.browser.majorVersion >= 80) {
      return 'webp';
    } else if (this.browser.isFirefox && this.browser.majorVersion >= 65) {
      return 'webp';
    } else {
      return 'jpg';
    }
  }
}

// Usage
const urlManager = new URLManager();
const apiUrl = urlManager.buildApiUrl('/users', { page: 1, limit: 20 });

const cookieManager = new CookieManager();
cookieManager.setUserPreferences({ theme: 'dark', language: 'en' });

const compatibility = new BrowserCompatibility();
if (!compatibility.supportsModernFeatures()) {
  compatibility.loadPolyfills();
}