0
# Web & Browser
1

2
Browser-specific utilities for URL parsing, cookie management, navigation, and browser detection. Essential for web development, browser compatibility, and client-side data management in web applications.
3

4
## Capabilities
5

6
### URL Operations
7

8
Parse and manipulate URLs with comprehensive component extraction.
9

10
```javascript { .api }
11
/**
12
 * Parse URL into its components
13
 * @param url - URL string to parse
14
 * @returns Parsed URL object with all components
15
 */
16
function parseUrl(url: string): ParsedUrl;
17

18
interface ParsedUrl {
19
  /** Full URL */
20
  href: string;
21
  /** Protocol (http:, https:, etc.) */
22
  protocol: string;
23
  /** Hostname */
24
  hostname: string;
25
  /** Port number */
26
  port: string;
27
  /** Host (hostname:port) */
28
  host: string;
29
  /** Pathname */
30
  pathname: string;
31
  /** Query string (including ?) */
32
  search: string;
33
  /** Fragment/hash (including #) */
34
  hash: string;
35
  /** Origin (protocol + host) */
36
  origin: string;
37
}
38

39
/**
40
 * Serialize object to query string
41
 * @param obj - Object to serialize
42
 * @param options - Serialization options
43
 * @returns Query string
44
 */
45
function serialize(obj: any, options?: SerializeOptions): string;
46

47
/**
48
 * Parse query string to object
49
 * @param str - Query string to parse
50
 * @param options - Parsing options
51
 * @returns Parsed object
52
 */
53
function unserialize(str: string, options?: SerializeOptions): any;
54

55
interface SerializeOptions {
56
  /** Whether to encode URI components (default: true) */
57
  encode?: boolean;
58
  /** Custom separator (default: '&') */
59
  separator?: string;
60
  /** Custom assignment operator (default: '=') */
61
  assignment?: string;
62
}
63
```
64

65
### Cookie Management
66

67
Comprehensive cookie manipulation utilities for client-side storage.
68

69
```javascript { .api }
70
/**
71
 * Get cookie value by name
72
 * @param name - Cookie name
73
 * @returns Cookie value or undefined
74
 */
75
function cookie(name: string): string | undefined;
76

77
/**
78
 * Set cookie with value and options
79
 * @param name - Cookie name
80
 * @param value - Cookie value
81
 * @param options - Cookie options
82
 * @returns Cookie value
83
 */
84
function cookie(name: string, value: any, options?: CookieOptions): string;
85

86
/**
87
 * Get all cookies as object
88
 * @returns Object with all cookies
89
 */
90
function cookie(): { [name: string]: string };
91

92
interface CookieOptions {
93
  /** Expiration in days (default: session cookie) */
94
  expires?: number;
95
  /** Cookie path (default: '/') */
96
  path?: string;
97
  /** Cookie domain */
98
  domain?: string;
99
  /** Secure flag (HTTPS only) */
100
  secure?: boolean;
101
  /** HttpOnly flag (server-side only) */
102
  httpOnly?: boolean;
103
  /** SameSite policy */
104
  sameSite?: 'Strict' | 'Lax' | 'None';
105
}
106
```
107

108
### Navigation & Location
109

110
Browser navigation and location utilities.
111

112
```javascript { .api }
113
/**
114
 * Navigate to URL
115
 * @param url - URL to navigate to
116
 * @param replace - Whether to replace current history entry (default: false)
117
 */
118
function locat(url: string, replace?: boolean): void;
119

120
/**
121
 * Get base URL of current page
122
 * @returns Base URL string
123
 */
124
function getBaseURL(): string;
125
```
126

127
### Browser Detection
128

129
Detect browser type, version, and capabilities.
130

131
```javascript { .api }
132
/**
133
 * Get comprehensive browser information
134
 * @returns Browser information object
135
 */
136
function browse(): BrowserInfo;
137

138
interface BrowserInfo {
139
  /** Browser name */
140
  name: string;
141
  /** Browser version */
142
  version: string;
143
  /** Major version number */
144
  majorVersion: number;
145
  /** Full user agent string */
146
  userAgent: string;
147
  /** Operating system */
148
  os: string;
149
  /** Device type */
150
  device: string;
151
  /** Whether browser is mobile */
152
  isMobile: boolean;
153
  /** Whether browser is tablet */
154
  isTablet: boolean;
155
  /** Whether browser is desktop */
156
  isDesktop: boolean;
157
  /** Specific browser flags */
158
  isChrome: boolean;
159
  isFirefox: boolean;
160
  isSafari: boolean;
161
  isEdge: boolean;
162
  isIE: boolean;
163
  isOpera: boolean;
164
}
165
```
166

167
**Usage Examples:**
168

169
```javascript
170
import { parseUrl, serialize, unserialize, cookie, locat, getBaseURL, browse } from 'xe-utils';
171

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

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

184
// Query string operations
185
const params = {
186
  page: 1,
187
  limit: 10,
188
  sort: 'name',
189
  filters: ['active', 'verified']
190
};
191

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

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

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

206
// Cookie management
207
// Set cookies
208
cookie('username', 'alice');
209
cookie('theme', 'dark', { expires: 30 }); // Expires in 30 days
210
cookie('session', 'abc123', { 
211
  expires: 1, 
212
  path: '/', 
213
  secure: true,
214
  sameSite: 'Strict'
215
});
216

217
// Get cookies
218
console.log(cookie('username')); // 'alice'
219
console.log(cookie('theme')); // 'dark'
220

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

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

228
// Navigation
229
function navigateToPage(path) {
230
  const baseUrl = getBaseURL();
231
  const fullUrl = baseUrl + path;
232
  locat(fullUrl);
233
}
234

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

239
// Usage
240
navigateToPage('/dashboard');
241
navigateAndReplace('/login');
242

243
// Browser detection
244
const browserInfo = browse();
245
console.log(browserInfo.name); // 'Chrome', 'Firefox', 'Safari', etc.
246
console.log(browserInfo.version); // '91.0.4472.124'
247
console.log(browserInfo.majorVersion); // 91
248
console.log(browserInfo.os); // 'Windows', 'macOS', 'Linux', etc.
249
console.log(browserInfo.isMobile); // true/false
250

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

256
if (browserInfo.isMobile) {
257
  // Load mobile-specific resources
258
  console.log('Loading mobile UI');
259
} else {
260
  // Load desktop resources
261
  console.log('Loading desktop UI');
262
}
263

264
// Practical examples
265
class URLManager {
266
  constructor() {
267
    this.baseUrl = getBaseURL();
268
  }
269
  
270
  buildApiUrl(endpoint, params = {}) {
271
    const queryString = serialize(params);
272
    return `${this.baseUrl}/api${endpoint}${queryString ? '?' + queryString : ''}`;
273
  }
274
  
275
  parseCurrentUrl() {
276
    return parseUrl(window.location.href);
277
  }
278
  
279
  updateQueryParams(newParams) {
280
    const current = this.parseCurrentUrl();
281
    const existingParams = unserialize(current.search.substring(1));
282
    const merged = { ...existingParams, ...newParams };
283
    const newQuery = serialize(merged);
284
    const newUrl = `${current.pathname}?${newQuery}${current.hash}`;
285
    locat(newUrl, true);
286
  }
287
}
288

289
class CookieManager {
290
  setUserPreferences(prefs) {
291
    cookie('userPrefs', JSON.stringify(prefs), { 
292
      expires: 365,
293
      path: '/',
294
      sameSite: 'Lax'
295
    });
296
  }
297
  
298
  getUserPreferences() {
299
    const prefs = cookie('userPrefs');
300
    return prefs ? JSON.parse(prefs) : {};
301
  }
302
  
303
  clearUserData() {
304
    const allCookies = cookie();
305
    Object.keys(allCookies).forEach(name => {
306
      if (name.startsWith('user')) {
307
        cookie(name, '', { expires: -1 });
308
      }
309
    });
310
  }
311
}
312

313
class BrowserCompatibility {
314
  constructor() {
315
    this.browser = browse();
316
  }
317
  
318
  supportsModernFeatures() {
319
    // Check for modern browser features
320
    return !(this.browser.isIE || 
321
            (this.browser.isChrome && this.browser.majorVersion < 60) ||
322
            (this.browser.isFirefox && this.browser.majorVersion < 55));
323
  }
324
  
325
  loadPolyfills() {
326
    if (!this.supportsModernFeatures()) {
327
      console.log('Loading polyfills for older browser');
328
      // Load polyfills
329
    }
330
  }
331
  
332
  getOptimalImageFormat() {
333
    if (this.browser.isChrome && this.browser.majorVersion >= 80) {
334
      return 'webp';
335
    } else if (this.browser.isFirefox && this.browser.majorVersion >= 65) {
336
      return 'webp';
337
    } else {
338
      return 'jpg';
339
    }
340
  }
341
}
342

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

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

350
const compatibility = new BrowserCompatibility();
351
if (!compatibility.supportsModernFeatures()) {
352
  compatibility.loadPolyfills();
353
}
354
```